The best way to control Claude Code, Codex and more from any computer or phone
| 1 | /** |
| 2 | * INTERNAL — one implementation of ignore-file filtering for every place that |
| 3 | * walks a directory and skips what an ignore file excludes. |
| 4 | * |
| 5 | * Two dialects, because the tools they imitate disagree: |
| 6 | * |
| 7 | * - `gitignore` (`.gitignore`, `.assetsignore`): a pattern without a slash |
| 8 | * matches at any depth, and nothing below an excluded directory can be |
| 9 | * re-included. |
| 10 | * - `dockerignore` (`.dockerignore`, `<Dockerfile>.dockerignore`): patterns |
| 11 | * are rooted at the context, and a later `!` rule can re-include a path |
| 12 | * below an excluded directory. |
| 13 | * |
| 14 | * {@link walkIgnoring} lists a tree one level at a time and skips directories |
| 15 | * the rules prune, so an excluded `node_modules` is never read and an |
| 16 | * unreadable excluded folder never fails the walk. Directory symlinks are |
| 17 | * reported as links and never followed. |
| 18 | */ |
| 19 | |
| 20 | import createGitIgnore from "@alchemy.run/node-utils/ignore"; |
| 21 | import * as Effect from "effect/Effect"; |
| 22 | import * as FileSystem from "effect/FileSystem"; |
| 23 | import * as Path from "effect/Path"; |
| 24 | import * as Result from "effect/Result"; |
| 25 | |
| 26 | export type IgnoreDialect = "gitignore" | "dockerignore"; |
| 27 | |
| 28 | export interface IgnoreRules { |
| 29 | readonly dialect: IgnoreDialect; |
| 30 | /** |
| 31 | * Whether a path is excluded. Paths are relative to the directory the |
| 32 | * ignore file applies to and use `/` separators. |
| 33 | */ |
| 34 | readonly ignores: (relativePath: string, isDirectory?: boolean) => boolean; |
| 35 | /** |
| 36 | * Whether a directory and everything below it is excluded, so a walk can |
| 37 | * skip reading it. Conservative: `false` only costs a directory read. |
| 38 | */ |
| 39 | readonly prunes: (relativeDirectory: string) => boolean; |
| 40 | } |
| 41 | |
| 42 | /** Normalize to the `/`-separated, `./`-free form the matchers expect. */ |
| 43 | export const normalizeRelativePath = (value: string) => |
| 44 | value.replaceAll("\\", "/").replace(/^\.\/+/, ""); |
| 45 | |
| 46 | const splitLines = (content: string | ReadonlyArray<string>) => |
| 47 | typeof content === "string" ? content.replace(/^/, "").split(/\r?\n/) : content; |
| 48 | |
| 49 | export interface ParseIgnoreRulesOptions { |
| 50 | /** |
| 51 | * gitignore only: the walk root's path relative to the directory the |
| 52 | * ignore file sits in (e.g. `"packages/app"` for the repository root's |
| 53 | * `.gitignore` when walking `packages/app`). Rules see full paths, but |
| 54 | * only directories below the walk root can exclude their contents, so an |
| 55 | * ignore file that excludes the walk root itself still lets it be listed. |
| 56 | * @default "" |
| 57 | */ |
| 58 | readonly prefix?: string; |
| 59 | } |
| 60 | |
| 61 | /** Parse ignore-file content (or its lines) in the given dialect. */ |
| 62 | export const parseIgnoreRules = ( |
| 63 | content: string | ReadonlyArray<string>, |
| 64 | dialect: IgnoreDialect, |
| 65 | options: ParseIgnoreRulesOptions = {}, |
| 66 | ): IgnoreRules => |
| 67 | dialect === "gitignore" |
| 68 | ? parseGitIgnore(splitLines(content), options.prefix ?? "") |
| 69 | : parseDockerIgnore(splitLines(content)); |
| 70 | |
| 71 | /** Rules that exclude nothing. */ |
| 72 | export const noIgnoreRules = (dialect: IgnoreDialect): IgnoreRules => ({ |
| 73 | dialect, |
| 74 | ignores: () => false, |
| 75 | prunes: () => false, |
| 76 | }); |
| 77 | |
| 78 | // --------------------------------------------------------------------------- |
| 79 | // gitignore |
| 80 | // --------------------------------------------------------------------------- |
| 81 | |
| 82 | const parseGitIgnore = (lines: ReadonlyArray<string>, prefix: string): IgnoreRules => { |
| 83 | const matcher = createGitIgnore().add(lines); |
| 84 | const base = normalizeRelativePath(prefix).replace(/\/+$/, ""); |
| 85 | const full = (path: string) => (base.length === 0 ? path : `${base}/${path}`); |
| 86 | // Git's rule: a path is excluded when a parent directory is, otherwise by |
| 87 | // the last rule matching the path itself. The parent walk starts below the |
| 88 | // walk root; directory-only patterns need the trailing slash. |
| 89 | const ignores = (relativePath: string, isDirectory?: boolean) => { |
| 90 | const segments = normalizeRelativePath(relativePath).split("/").filter(Boolean); |
| 91 | for (let index = 0; index < segments.length; index++) { |
| 92 | const path = full(segments.slice(0, index + 1).join("/")); |
| 93 | const isLast = index === segments.length - 1; |
| 94 | const result = matcher.matches(isLast && !isDirectory ? path : `${path}/`); |
| 95 | if (isLast) return result.ignored; |
| 96 | if (result.ignored) return true; |
| 97 | } |
| 98 | return false; |
| 99 | }; |
| 100 | return { |
| 101 | dialect: "gitignore", |
| 102 | ignores, |
| 103 | // Git cannot re-include anything below an excluded directory. |
| 104 | prunes: (relativeDirectory) => ignores(relativeDirectory, true), |
| 105 | }; |
| 106 | }; |
| 107 | |
| 108 | // --------------------------------------------------------------------------- |
| 109 | // dockerignore (moby/patternmatcher semantics) |
| 110 | // --------------------------------------------------------------------------- |
| 111 | |
| 112 | interface DockerIgnoreRule { |
| 113 | ignored: boolean; |
| 114 | expression: RegExp; |
| 115 | /** The cleaned pattern is also needed when deciding whether a directory can be pruned. */ |
| 116 | pattern: string; |
| 117 | } |
| 118 | |
| 119 | const escapeRegExp = (value: string) => value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&"); |
| 120 | |
| 121 | const cleanDockerIgnorePath = (value: string) => { |
| 122 | const parts: string[] = []; |
| 123 | for (const part of value.split("/")) { |
| 124 | if (part.length === 0 || part === ".") continue; |
| 125 | if (part === "..") { |
| 126 | if (parts.length > 0 && parts.at(-1) !== "..") parts.pop(); |
| 127 | else parts.push(part); |
| 128 | } else { |
| 129 | parts.push(part); |
| 130 | } |
| 131 | } |
| 132 | return parts.join("/"); |
| 133 | }; |
| 134 | |
| 135 | /** Compile one line of Docker's ordered ignore-pattern form into a path matcher. */ |
| 136 | const compileDockerIgnoreRule = (raw: string): DockerIgnoreRule | undefined => { |
| 137 | if (raw.startsWith("#")) { |
| 138 | return undefined; |
| 139 | } |
| 140 | |
| 141 | let pattern = raw.trim(); |
| 142 | if (pattern.length === 0 || pattern === ".") { |
| 143 | return undefined; |
| 144 | } |
| 145 | |
| 146 | let ignored = true; |
| 147 | if (pattern.startsWith("\\!") || pattern.startsWith("\\#")) { |
| 148 | pattern = pattern.slice(1); |
| 149 | } else if (pattern.startsWith("!")) { |
| 150 | ignored = false; |
| 151 | pattern = pattern.slice(1).trim(); |
| 152 | } |
| 153 | |
| 154 | pattern = cleanDockerIgnorePath( |
| 155 | pattern |
| 156 | .replace(/^\.\/+/, "") |
| 157 | .replace(/^\/+/, "") |
| 158 | .replace(/\/+$/, ""), |
| 159 | ); |
| 160 | if (pattern.length === 0 || pattern === ".") { |
| 161 | return undefined; |
| 162 | } |
| 163 | |
| 164 | let body = ""; |
| 165 | for (let index = 0; index < pattern.length; index++) { |
| 166 | const char = pattern[index]; |
| 167 | if (char === "\\" && pattern[index + 1] !== undefined) { |
| 168 | body += escapeRegExp(pattern[++index]); |
| 169 | continue; |
| 170 | } |
| 171 | if (char === "*") { |
| 172 | if (pattern[index + 1] === "*") { |
| 173 | while (pattern[index + 1] === "*") { |
| 174 | index++; |
| 175 | } |
| 176 | if (pattern[index + 1] === "/") { |
| 177 | index++; |
| 178 | body += "(?:.*/)?"; |
| 179 | } else { |
| 180 | body += ".*"; |
| 181 | } |
| 182 | } else { |
| 183 | body += "[^/]*"; |
| 184 | } |
| 185 | continue; |
| 186 | } |
| 187 | if (char === "?") { |
| 188 | body += "[^/]"; |
| 189 | continue; |
| 190 | } |
| 191 | if (char === "[") { |
| 192 | const end = pattern.indexOf("]", index + 1); |
| 193 | if (end !== -1) { |
| 194 | const content = pattern.slice(index + 1, end); |
| 195 | const negated = content.startsWith("!") || content.startsWith("^"); |
| 196 | const members = negated ? content.slice(1) : content; |
| 197 | body += `[${negated ? "^" : ""}${members.replaceAll("\\", "\\\\")}]`; |
| 198 | index = end; |
| 199 | continue; |
| 200 | } |
| 201 | } |
| 202 | body += escapeRegExp(char); |
| 203 | } |
| 204 | |
| 205 | return { ignored, expression: new RegExp(`^${body}$`), pattern }; |
| 206 | }; |
| 207 | |
| 208 | /** A path matches a rule when it, or any of its parent directories, does. */ |
| 209 | const pathCandidates = (relativePath: string) => { |
| 210 | const segments = normalizeRelativePath(relativePath).split("/"); |
| 211 | return segments.map((_, index) => segments.slice(0, index + 1).join("/")); |
| 212 | }; |
| 213 | |
| 214 | /** Index of the last rule matching the path (or a parent), if any. */ |
| 215 | const matchingDockerRuleIndex = (relativePath: string, rules: ReadonlyArray<DockerIgnoreRule>) => { |
| 216 | const candidates = pathCandidates(relativePath); |
| 217 | let matching: number | undefined; |
| 218 | for (let index = 0; index < rules.length; index++) { |
| 219 | if (candidates.some((candidate) => rules[index].expression.test(candidate))) { |
| 220 | matching = index; |
| 221 | } |
| 222 | } |
| 223 | return matching; |
| 224 | }; |
| 225 | |
| 226 | const hasGlob = (segment: string) => /[*?[]/.test(segment); |
| 227 | |
| 228 | /** |
| 229 | * Return whether a negated rule could match the directory or any path below |
| 230 | * it. This is deliberately conservative: a false positive costs a directory |
| 231 | * read, while a false negative would drop a re-included path. |
| 232 | */ |
| 233 | const canDockerRuleMatchDescendant = (relativeDirectory: string, rule: DockerIgnoreRule) => { |
| 234 | const directory = normalizeRelativePath(relativeDirectory).split("/"); |
| 235 | const patternParts = rule.pattern.split("/"); |
| 236 | |
| 237 | // A recursive segment can bridge any number of directory levels, but the |
| 238 | // fixed prefix before it still has to reach this tree. For example, |
| 239 | // `ignored/keep/**` cannot re-include anything below `ignored/other`. |
| 240 | const recursiveIndex = patternParts.indexOf("**"); |
| 241 | if (recursiveIndex !== -1) { |
| 242 | for (let index = 0; index < recursiveIndex && index < directory.length; index++) { |
| 243 | const part = patternParts[index]; |
| 244 | if (!hasGlob(part) && part !== directory[index]) return false; |
| 245 | } |
| 246 | return true; |
| 247 | } |
| 248 | |
| 249 | // Docker patterns are rooted, so a fixed leading segment rules out any |
| 250 | // directory outside it: `!src` cannot re-include anything below `docs`. |
| 251 | const compared = Math.min(directory.length, patternParts.length); |
| 252 | for (let index = 0; index < compared; index++) { |
| 253 | const part = patternParts[index]; |
| 254 | if (!hasGlob(part) && part !== directory[index]) return false; |
| 255 | } |
| 256 | return true; |
| 257 | }; |
| 258 | |
| 259 | /** |
| 260 | * Find an ignore rule that excludes every descendant of a directory. Patterns |
| 261 | * such as `node_modules/**` do not match the directory entry itself, so they |
| 262 | * are recognized here to let the walker skip their contents. |
| 263 | */ |
| 264 | const descendantIgnoreRuleIndex = ( |
| 265 | relativeDirectory: string, |
| 266 | rules: ReadonlyArray<DockerIgnoreRule>, |
| 267 | ) => { |
| 268 | const matching = matchingDockerRuleIndex(relativeDirectory, rules); |
| 269 | let result = matching !== undefined && rules[matching].ignored ? matching : undefined; |
| 270 | |
| 271 | for (let index = 0; index < rules.length; index++) { |
| 272 | const rule = rules[index]; |
| 273 | if (!rule.ignored) continue; |
| 274 | if (rule.pattern === "**" && (result === undefined || index > result)) { |
| 275 | result = index; |
| 276 | continue; |
| 277 | } |
| 278 | if (!rule.pattern.endsWith("/**")) continue; |
| 279 | // Probe below the directory against the original expression, which |
| 280 | // keeps the pattern's slash scope: `foo/**` must not prune `bar`. |
| 281 | if (rule.expression.test(`${relativeDirectory}/__alchemy_prune_probe__`)) { |
| 282 | result = index; |
| 283 | } |
| 284 | } |
| 285 | return result; |
| 286 | }; |
| 287 | |
| 288 | const parseDockerIgnore = (lines: ReadonlyArray<string>): IgnoreRules => { |
| 289 | const rules = lines.flatMap((line) => { |
| 290 | const rule = compileDockerIgnoreRule(line); |
| 291 | return rule === undefined ? [] : [rule]; |
| 292 | }); |
| 293 | return { |
| 294 | dialect: "dockerignore", |
| 295 | // Docker strips trailing slashes, so directory-ness never matters. |
| 296 | ignores: (relativePath) => { |
| 297 | const matching = matchingDockerRuleIndex(relativePath, rules); |
| 298 | return matching !== undefined && rules[matching].ignored; |
| 299 | }, |
| 300 | prunes: (relativeDirectory) => { |
| 301 | const directory = normalizeRelativePath(relativeDirectory); |
| 302 | const ignoreIndex = descendantIgnoreRuleIndex(directory, rules); |
| 303 | if (ignoreIndex === undefined) return false; |
| 304 | // Only a later negation can make walking this directory necessary. |
| 305 | return !rules.some( |
| 306 | (rule, index) => |
| 307 | index > ignoreIndex && !rule.ignored && canDockerRuleMatchDescendant(directory, rule), |
| 308 | ); |
| 309 | }, |
| 310 | }; |
| 311 | }; |
| 312 | |
| 313 | // --------------------------------------------------------------------------- |
| 314 | // Walking |
| 315 | // --------------------------------------------------------------------------- |
| 316 | |
| 317 | export type WalkEntryType = "File" | "Directory" | "SymbolicLink" | "Other"; |
| 318 | |
| 319 | export interface WalkEntry { |
| 320 | /** Path relative to the walk root, `/`-separated. */ |
| 321 | readonly path: string; |
| 322 | readonly type: WalkEntryType; |
| 323 | } |
| 324 | |
| 325 | export interface WalkIgnoringOptions<E, R> { |
| 326 | /** |
| 327 | * List one directory (relative to the walk root, `""` for the root). Each |
| 328 | * child's type must describe the entry itself: a symlink is a |
| 329 | * `SymbolicLink`, never its target. |
| 330 | */ |
| 331 | readonly list: ( |
| 332 | relativeDirectory: string, |
| 333 | ) => Effect.Effect<ReadonlyArray<{ readonly name: string; readonly type: WalkEntryType }>, E, R>; |
| 334 | /** @default no rules */ |
| 335 | readonly rules?: IgnoreRules; |
| 336 | /** |
| 337 | * Paths always listed even when excluded (Docker always sends the |
| 338 | * Dockerfile and its ignore file). Their parent directories are never |
| 339 | * pruned. |
| 340 | */ |
| 341 | readonly force?: ReadonlyArray<string>; |
| 342 | } |
| 343 | |
| 344 | /** |
| 345 | * List every entry under a root that the rules keep, sorted by path. |
| 346 | * Directories are listed too (Docker sends empty directories). Excluded |
| 347 | * directories are only read when a later rule could re-include something |
| 348 | * below them; symlinked directories are listed as links and not followed. |
| 349 | */ |
| 350 | export const walkIgnoring = <E, R>({ |
| 351 | list, |
| 352 | rules, |
| 353 | force = [], |
| 354 | }: WalkIgnoringOptions<E, R>): Effect.Effect<WalkEntry[], E, R> => |
| 355 | Effect.gen(function* () { |
| 356 | const forced = force.map(normalizeRelativePath); |
| 357 | const isForced = (path: string) => forced.includes(path); |
| 358 | const hasForcedDescendant = (path: string) => |
| 359 | forced.some((forcedPath) => forcedPath.startsWith(`${path}/`)); |
| 360 | const keeps = (path: string, isDirectory: boolean) => |
| 361 | isForced(path) || rules === undefined || !rules.ignores(path, isDirectory); |
| 362 | |
| 363 | const entries: WalkEntry[] = []; |
| 364 | const pending = [""]; |
| 365 | while (pending.length > 0) { |
| 366 | const directory = pending.pop()!; |
| 367 | for (const child of yield* list(directory)) { |
| 368 | const path = directory.length === 0 ? child.name : `${directory}/${child.name}`; |
| 369 | if (child.type !== "Directory") { |
| 370 | if (keeps(path, false)) entries.push({ path, type: child.type }); |
| 371 | continue; |
| 372 | } |
| 373 | if ( |
| 374 | rules !== undefined && |
| 375 | !isForced(path) && |
| 376 | !hasForcedDescendant(path) && |
| 377 | rules.prunes(path) |
| 378 | ) { |
| 379 | continue; |
| 380 | } |
| 381 | if (keeps(path, true)) entries.push({ path, type: "Directory" }); |
| 382 | pending.push(path); |
| 383 | } |
| 384 | } |
| 385 | return entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)); |
| 386 | }); |
| 387 | |
| 388 | /** |
| 389 | * A {@link WalkIgnoringOptions.list} over the real file system rooted at |
| 390 | * `root`. Symlinks are probed before `stat`, which follows them. |
| 391 | */ |
| 392 | export const listFileSystemDirectory = Effect.fn(function* (root: string) { |
| 393 | const fs = yield* FileSystem.FileSystem; |
| 394 | const path = yield* Path.Path; |
| 395 | return Effect.fn(function* (relativeDirectory: string) { |
| 396 | const directory = path.join(root, relativeDirectory); |
| 397 | const names = yield* fs.readDirectory(directory); |
| 398 | return yield* Effect.forEach(names, (name) => |
| 399 | Effect.gen(function* () { |
| 400 | const fullPath = path.join(directory, name); |
| 401 | const link = yield* Effect.result(fs.readLink(fullPath)); |
| 402 | if (Result.isSuccess(link)) { |
| 403 | return { name, type: "SymbolicLink" as const }; |
| 404 | } |
| 405 | const info = yield* fs.stat(fullPath); |
| 406 | const type: WalkEntryType = |
| 407 | info.type === "File" || info.type === "Directory" ? info.type : "Other"; |
| 408 | return { name, type }; |
| 409 | }), |
| 410 | ); |
| 411 | }); |
| 412 | }); |
| 413 | |
| 414 | /** |
| 415 | * Combine rule sets, e.g. the `.gitignore` files from a working directory up |
| 416 | * to the repository root (each parsed with its own `prefix`). A path is |
| 417 | * excluded when any rule set excludes it. |
| 418 | */ |
| 419 | export const combineIgnoreRules = ( |
| 420 | dialect: IgnoreDialect, |
| 421 | rules: ReadonlyArray<IgnoreRules>, |
| 422 | ): IgnoreRules => ({ |
| 423 | dialect, |
| 424 | ignores: (relativePath, isDirectory) => |
| 425 | rules.some((rule) => rule.ignores(relativePath, isDirectory)), |
| 426 | prunes: (relativeDirectory) => rules.some((rule) => rule.prunes(relativeDirectory)), |
| 427 | }); |