The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as Effect from "effect/Effect"; |
| 2 | import * as FileSystem from "effect/FileSystem"; |
| 3 | import * as Path from "effect/Path"; |
| 4 | import type { PlatformError } from "effect/PlatformError"; |
| 5 | import picomatch from "picomatch"; |
| 6 | import { convertPathToPattern, glob } from "tinyglobby"; |
| 7 | import { dotAlchemyDirectory } from "../AlchemyContext.ts"; |
| 8 | import { |
| 9 | combineIgnoreRules, |
| 10 | type IgnoreRules, |
| 11 | listFileSystemDirectory, |
| 12 | parseIgnoreRules, |
| 13 | walkIgnoring, |
| 14 | } from "../Util/Ignore.ts"; |
| 15 | import { isPathWithin } from "../Util/isPathWithin.ts"; |
| 16 | import { initialCwd } from "../Util/Node.ts"; |
| 17 | import { sha256, sha256Object } from "../Util/sha256.ts"; |
| 18 | |
| 19 | /** |
| 20 | * Controls which files are included in the content hash that determines |
| 21 | * whether a build needs to re-run. |
| 22 | * |
| 23 | * By default (no options), every non-gitignored file in the working directory |
| 24 | * is hashed, plus the nearest package-manager lockfile. Provide explicit |
| 25 | * `include`/`exclude` globs to narrow the scope when the default is too broad. |
| 26 | */ |
| 27 | export interface MemoOptions { |
| 28 | /** |
| 29 | * Glob patterns of files to hash. Paths are relative to the working |
| 30 | * directory and may reach outside it with `../` segments — useful in a |
| 31 | * monorepo where the build consumes sibling workspace packages that the |
| 32 | * default (files under the working directory) does not cover. |
| 33 | * |
| 34 | * Note: providing `include` (or `exclude`) flips the {@link lockfile} |
| 35 | * default to `false` — pair it with `lockfile: true` to keep rebuilding |
| 36 | * when dependencies change. |
| 37 | * |
| 38 | * @default ["**\/*"] (all files, filtered by `exclude`) |
| 39 | * @example ["src/**", "package.json", "tsconfig.json"] |
| 40 | * @example ["**\/*", "../env/src/**"] (also rebuild when a sibling workspace package changes) |
| 41 | */ |
| 42 | include?: string[]; |
| 43 | /** |
| 44 | * Glob patterns to exclude from hashing. Paths are relative to the working directory. |
| 45 | * |
| 46 | * @default gitignore rules collected from the working directory up to the repo root |
| 47 | */ |
| 48 | exclude?: string[]; |
| 49 | /** |
| 50 | * Whether to include the nearest package-manager lockfile (`bun.lock`, |
| 51 | * `package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`) in the hash, |
| 52 | * even when it lives above the working directory (e.g. monorepo root). |
| 53 | * |
| 54 | * @default true when both `include` and `exclude` are unset; false otherwise |
| 55 | */ |
| 56 | lockfile?: boolean; |
| 57 | } |
| 58 | |
| 59 | interface ResolvedMemoOptions { |
| 60 | cwd: string; |
| 61 | include: string[]; |
| 62 | /** Explicit exclude globs; when unset, `gitignore` decides instead. */ |
| 63 | exclude: string[] | undefined; |
| 64 | /** The `.gitignore` rules from `cwd` up to the repository root. */ |
| 65 | gitignore: IgnoreRules | undefined; |
| 66 | lockfile: boolean; |
| 67 | } |
| 68 | |
| 69 | /** |
| 70 | * Internal service that resolves memo options, lists matching files, and |
| 71 | * produces a single SHA-256 content hash. Constructed as an Effect so it |
| 72 | * can access the platform `FileSystem` and `Path` services. |
| 73 | */ |
| 74 | const Memo = Effect.gen(function* () { |
| 75 | const fs = yield* FileSystem.FileSystem; |
| 76 | const path = yield* Path.Path; |
| 77 | const runtimeBase = process.cwd(); |
| 78 | const dotAlchemy = yield* dotAlchemyDirectory; |
| 79 | |
| 80 | const findUp = Effect.fn(function* ( |
| 81 | cwd: string, |
| 82 | filenames: string[], |
| 83 | ): Effect.fn.Return<string | undefined, PlatformError> { |
| 84 | const [file] = yield* Effect.filter( |
| 85 | filenames.map((filename) => path.join(cwd, filename)), |
| 86 | fs.exists, |
| 87 | { concurrency: "unbounded" }, |
| 88 | ); |
| 89 | if (file) { |
| 90 | return file; |
| 91 | } |
| 92 | const parent = path.dirname(cwd); |
| 93 | if (parent === cwd) { |
| 94 | return undefined; |
| 95 | } |
| 96 | return yield* findUp(parent, filenames); |
| 97 | }); |
| 98 | |
| 99 | /** |
| 100 | * Each `.gitignore` from `cwd` up to the repository root, anchored to its |
| 101 | * own directory. Rules that exclude `cwd` itself (a project inside an |
| 102 | * ignored folder) do not hide its files. |
| 103 | */ |
| 104 | const readGitIgnoreScopes = Effect.fn(function* ( |
| 105 | cwd: string, |
| 106 | directory = cwd, |
| 107 | ): Effect.fn.Return<Array<IgnoreRules>, PlatformError> { |
| 108 | const scope = yield* fs.readFileString(path.join(directory, ".gitignore")).pipe( |
| 109 | Effect.map((content) => [ |
| 110 | parseIgnoreRules(content, "gitignore", { |
| 111 | prefix: path.relative(directory, cwd).replaceAll("\\", "/"), |
| 112 | }), |
| 113 | ]), |
| 114 | Effect.catchIf( |
| 115 | (error) => error._tag === "PlatformError" && error.reason._tag === "NotFound", |
| 116 | () => Effect.succeed([]), |
| 117 | ), |
| 118 | ); |
| 119 | const parent = path.dirname(directory); |
| 120 | if (parent === directory || (yield* fs.exists(path.join(directory, ".git")))) { |
| 121 | return scope; |
| 122 | } |
| 123 | return [...(yield* readGitIgnoreScopes(cwd, parent)), ...scope]; |
| 124 | }); |
| 125 | |
| 126 | const resolveMemoOptions = Effect.fn(function* ( |
| 127 | cwd: string | undefined, |
| 128 | options: MemoOptions, |
| 129 | ): Effect.fn.Return<ResolvedMemoOptions, PlatformError> { |
| 130 | // Anchored: a live `process.cwd()` read can race a concurrent tool's |
| 131 | // transient chdir (see Util/Node.ts `initialCwd`). |
| 132 | const resolvedCwd = path.resolve(initialCwd, cwd ?? "."); |
| 133 | return { |
| 134 | cwd: resolvedCwd, |
| 135 | // Normalize absolute include patterns to cwd-relative ones so matched |
| 136 | // keys (and therefore the memo hash) stay free of machine-specific |
| 137 | // path prefixes. |
| 138 | include: (options.include ?? ["**/*"]).map((pattern) => |
| 139 | path.isAbsolute(pattern) |
| 140 | ? path.relative(resolvedCwd, pattern).replaceAll("\\", "/") |
| 141 | : pattern, |
| 142 | ), |
| 143 | exclude: options.exclude, |
| 144 | gitignore: |
| 145 | options.exclude === undefined |
| 146 | ? combineIgnoreRules("gitignore", [ |
| 147 | parseIgnoreRules([".git"], "gitignore"), |
| 148 | ...(yield* readGitIgnoreScopes(resolvedCwd)), |
| 149 | ]) |
| 150 | : undefined, |
| 151 | lockfile: options.lockfile ?? !(options.exclude || options.include), |
| 152 | }; |
| 153 | }); |
| 154 | |
| 155 | /** |
| 156 | * Files under `cwd` that the `.gitignore` rules keep, matched against |
| 157 | * `include`. Excluded directories (e.g. `node_modules`) are never read. |
| 158 | * Include patterns reaching outside `cwd` (`../env/src/**`) are globbed |
| 159 | * separately, as they lie outside the walked tree. |
| 160 | */ |
| 161 | const listGitTrackedCandidates = Effect.fn(function* ( |
| 162 | options: ResolvedMemoOptions, |
| 163 | gitignore: IgnoreRules, |
| 164 | ): Effect.fn.Return<string[], PlatformError, FileSystem.FileSystem | Path.Path> { |
| 165 | const inside = options.include.filter((pattern) => !pattern.startsWith("../")); |
| 166 | const outside = options.include.filter((pattern) => pattern.startsWith("../")); |
| 167 | const matches = picomatch(inside, { dot: true }); |
| 168 | const entries = yield* walkIgnoring({ |
| 169 | list: yield* listFileSystemDirectory(options.cwd), |
| 170 | rules: gitignore, |
| 171 | }); |
| 172 | const files = yield* Effect.filter( |
| 173 | entries.filter((entry) => entry.type !== "Directory" && matches(entry.path)), |
| 174 | // Like tinyglobby, keep symlinks that resolve to files. |
| 175 | (entry) => |
| 176 | entry.type === "File" |
| 177 | ? Effect.succeed(true) |
| 178 | : fs.stat(path.join(options.cwd, entry.path)).pipe( |
| 179 | Effect.map((info) => info.type === "File"), |
| 180 | Effect.orElseSucceed(() => false), |
| 181 | ), |
| 182 | ); |
| 183 | const external = |
| 184 | outside.length === 0 |
| 185 | ? [] |
| 186 | : yield* Effect.promise(() => |
| 187 | glob(outside, { |
| 188 | cwd: options.cwd, |
| 189 | onlyFiles: true, |
| 190 | expandDirectories: false, |
| 191 | dot: true, |
| 192 | }), |
| 193 | ); |
| 194 | return [...files.map((entry) => entry.path), ...external]; |
| 195 | }); |
| 196 | |
| 197 | const listFiles = Effect.fn(function* ( |
| 198 | options: ResolvedMemoOptions, |
| 199 | ): Effect.fn.Return<string[], PlatformError, FileSystem.FileSystem | Path.Path> { |
| 200 | // Explicitly hashing a generated artifact still hashes its contents. |
| 201 | const excludeRuntime = !isPathWithin(dotAlchemy, options.cwd, runtimeBase); |
| 202 | const [files, lockfile] = yield* Effect.all( |
| 203 | [ |
| 204 | options.gitignore === undefined |
| 205 | ? Effect.promise(() => |
| 206 | glob(options.include, { |
| 207 | cwd: options.cwd, |
| 208 | ignore: [ |
| 209 | ...(options.exclude ?? []), |
| 210 | ...(excludeRuntime |
| 211 | ? [`${convertPathToPattern(path.resolve(runtimeBase, dotAlchemy))}/**`] |
| 212 | : []), |
| 213 | ], |
| 214 | onlyFiles: true, |
| 215 | expandDirectories: false, |
| 216 | dot: true, |
| 217 | }), |
| 218 | ) |
| 219 | : listGitTrackedCandidates(options, options.gitignore), |
| 220 | options.lockfile |
| 221 | ? findUp(options.cwd, [ |
| 222 | "bun.lock", |
| 223 | "bun.lockb", |
| 224 | "package-lock.json", |
| 225 | "pnpm-lock.yaml", |
| 226 | "yarn.lock", |
| 227 | ]).pipe( |
| 228 | Effect.map((lockfile) => |
| 229 | lockfile ? path.relative(options.cwd, lockfile) : undefined, |
| 230 | ), |
| 231 | ) |
| 232 | : Effect.undefined, |
| 233 | ], |
| 234 | { concurrency: "unbounded" }, |
| 235 | ); |
| 236 | if (lockfile && !files.includes(lockfile)) { |
| 237 | files.push(lockfile); |
| 238 | } |
| 239 | // Absolute include patterns produce absolute matches; normalize them to |
| 240 | // cwd-relative (like the lockfile above) so `hashFiles` resolves them |
| 241 | // correctly and machine-specific path prefixes never leak into the hash. |
| 242 | return files |
| 243 | .filter( |
| 244 | (file) => |
| 245 | !excludeRuntime || |
| 246 | !isPathWithin(dotAlchemy, path.resolve(options.cwd, file), runtimeBase), |
| 247 | ) |
| 248 | .map((file) => (path.isAbsolute(file) ? path.relative(options.cwd, file) : file)) |
| 249 | .sort(); |
| 250 | }); |
| 251 | |
| 252 | const hashFiles = Effect.fn(function* ( |
| 253 | cwd: string, |
| 254 | files: string[], |
| 255 | ): Effect.fn.Return<string, PlatformError> { |
| 256 | const hashes = yield* Effect.forEach( |
| 257 | files, |
| 258 | (file) => |
| 259 | fs.readFile(path.join(cwd, file)).pipe( |
| 260 | Effect.flatMap(sha256), |
| 261 | Effect.map((hash) => `${file}:${hash}`), |
| 262 | ), |
| 263 | { concurrency: "unbounded" }, |
| 264 | ); |
| 265 | return yield* sha256Object(hashes); |
| 266 | }); |
| 267 | |
| 268 | return { |
| 269 | resolveMemoOptions, |
| 270 | listFiles, |
| 271 | hashFiles, |
| 272 | }; |
| 273 | }); |
| 274 | |
| 275 | /** |
| 276 | * Produces a deterministic SHA-256 hash of all files matched by the given |
| 277 | * memo options. The hash changes if and only if the content of the matched |
| 278 | * files changes, making it suitable for cache-busting build outputs. |
| 279 | */ |
| 280 | export const hashDirectory = Effect.fn(function* (props: { |
| 281 | cwd?: string; |
| 282 | memo?: MemoOptions; |
| 283 | }): Effect.fn.Return<string, PlatformError, FileSystem.FileSystem | Path.Path> { |
| 284 | const service = yield* Memo; |
| 285 | const resolvedOptions = yield* service.resolveMemoOptions(props.cwd, props.memo ?? {}); |
| 286 | const files = yield* service.listFiles(resolvedOptions); |
| 287 | const hash = yield* service.hashFiles(resolvedOptions.cwd, files); |
| 288 | return hash; |
| 289 | }); |