sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ Command/ Memo.ts

import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Path from "effect/Path";
import type { PlatformError } from "effect/PlatformError";
import picomatch from "picomatch";
import { convertPathToPattern, glob } from "tinyglobby";
import { dotAlchemyDirectory } from "../AlchemyContext.ts";
import {
  combineIgnoreRules,
  type IgnoreRules,
  listFileSystemDirectory,
  parseIgnoreRules,
  walkIgnoring,
} from "../Util/Ignore.ts";
import { isPathWithin } from "../Util/isPathWithin.ts";
import { initialCwd } from "../Util/Node.ts";
import { sha256, sha256Object } from "../Util/sha256.ts";

/**
 * Controls which files are included in the content hash that determines
 * whether a build needs to re-run.
 *
 * By default (no options), every non-gitignored file in the working directory
 * is hashed, plus the nearest package-manager lockfile. Provide explicit
 * `include`/`exclude` globs to narrow the scope when the default is too broad.
 */
export interface MemoOptions {
  /**
   * Glob patterns of files to hash. Paths are relative to the working
   * directory and may reach outside it with `../` segments — useful in a
   * monorepo where the build consumes sibling workspace packages that the
   * default (files under the working directory) does not cover.
   *
   * Note: providing `include` (or `exclude`) flips the {@link lockfile}
   * default to `false` — pair it with `lockfile: true` to keep rebuilding
   * when dependencies change.
   *
   * @default ["**\/*"] (all files, filtered by `exclude`)
   * @example ["src/**", "package.json", "tsconfig.json"]
   * @example ["**\/*", "../env/src/**"] (also rebuild when a sibling workspace package changes)
   */
  include?: string[];
  /**
   * Glob patterns to exclude from hashing. Paths are relative to the working directory.
   *
   * @default gitignore rules collected from the working directory up to the repo root
   */
  exclude?: string[];
  /**
   * Whether to include the nearest package-manager lockfile (`bun.lock`,
   * `package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`) in the hash,
   * even when it lives above the working directory (e.g. monorepo root).
   *
   * @default true when both `include` and `exclude` are unset; false otherwise
   */
  lockfile?: boolean;
}

interface ResolvedMemoOptions {
  cwd: string;
  include: string[];
  /** Explicit exclude globs; when unset, `gitignore` decides instead. */
  exclude: string[] | undefined;
  /** The `.gitignore` rules from `cwd` up to the repository root. */
  gitignore: IgnoreRules | undefined;
  lockfile: boolean;
}

/**
 * Internal service that resolves memo options, lists matching files, and
 * produces a single SHA-256 content hash. Constructed as an Effect so it
 * can access the platform `FileSystem` and `Path` services.
 */
const Memo = Effect.gen(function* () {
  const fs = yield* FileSystem.FileSystem;
  const path = yield* Path.Path;
  const runtimeBase = process.cwd();
  const dotAlchemy = yield* dotAlchemyDirectory;

  const findUp = Effect.fn(function* (
    cwd: string,
    filenames: string[],
  ): Effect.fn.Return<string | undefined, PlatformError> {
    const [file] = yield* Effect.filter(
      filenames.map((filename) => path.join(cwd, filename)),
      fs.exists,
      { concurrency: "unbounded" },
    );
    if (file) {
      return file;
    }
    const parent = path.dirname(cwd);
    if (parent === cwd) {
      return undefined;
    }
    return yield* findUp(parent, filenames);
  });

  /**
   * Each `.gitignore` from `cwd` up to the repository root, anchored to its
   * own directory. Rules that exclude `cwd` itself (a project inside an
   * ignored folder) do not hide its files.
   */
  const readGitIgnoreScopes = Effect.fn(function* (
    cwd: string,
    directory = cwd,
  ): Effect.fn.Return<Array<IgnoreRules>, PlatformError> {
    const scope = yield* fs.readFileString(path.join(directory, ".gitignore")).pipe(
      Effect.map((content) => [
        parseIgnoreRules(content, "gitignore", {
          prefix: path.relative(directory, cwd).replaceAll("\\", "/"),
        }),
      ]),
      Effect.catchIf(
        (error) => error._tag === "PlatformError" && error.reason._tag === "NotFound",
        () => Effect.succeed([]),
      ),
    );
    const parent = path.dirname(directory);
    if (parent === directory || (yield* fs.exists(path.join(directory, ".git")))) {
      return scope;
    }
    return [...(yield* readGitIgnoreScopes(cwd, parent)), ...scope];
  });

  const resolveMemoOptions = Effect.fn(function* (
    cwd: string | undefined,
    options: MemoOptions,
  ): Effect.fn.Return<ResolvedMemoOptions, PlatformError> {
    // Anchored: a live `process.cwd()` read can race a concurrent tool's
    // transient chdir (see Util/Node.ts `initialCwd`).
    const resolvedCwd = path.resolve(initialCwd, cwd ?? ".");
    return {
      cwd: resolvedCwd,
      // Normalize absolute include patterns to cwd-relative ones so matched
      // keys (and therefore the memo hash) stay free of machine-specific
      // path prefixes.
      include: (options.include ?? ["**/*"]).map((pattern) =>
        path.isAbsolute(pattern)
          ? path.relative(resolvedCwd, pattern).replaceAll("\\", "/")
          : pattern,
      ),
      exclude: options.exclude,
      gitignore:
        options.exclude === undefined
          ? combineIgnoreRules("gitignore", [
              parseIgnoreRules([".git"], "gitignore"),
              ...(yield* readGitIgnoreScopes(resolvedCwd)),
            ])
          : undefined,
      lockfile: options.lockfile ?? !(options.exclude || options.include),
    };
  });

  /**
   * Files under `cwd` that the `.gitignore` rules keep, matched against
   * `include`. Excluded directories (e.g. `node_modules`) are never read.
   * Include patterns reaching outside `cwd` (`../env/src/**`) are globbed
   * separately, as they lie outside the walked tree.
   */
  const listGitTrackedCandidates = Effect.fn(function* (
    options: ResolvedMemoOptions,
    gitignore: IgnoreRules,
  ): Effect.fn.Return<string[], PlatformError, FileSystem.FileSystem | Path.Path> {
    const inside = options.include.filter((pattern) => !pattern.startsWith("../"));
    const outside = options.include.filter((pattern) => pattern.startsWith("../"));
    const matches = picomatch(inside, { dot: true });
    const entries = yield* walkIgnoring({
      list: yield* listFileSystemDirectory(options.cwd),
      rules: gitignore,
    });
    const files = yield* Effect.filter(
      entries.filter((entry) => entry.type !== "Directory" && matches(entry.path)),
      // Like tinyglobby, keep symlinks that resolve to files.
      (entry) =>
        entry.type === "File"
          ? Effect.succeed(true)
          : fs.stat(path.join(options.cwd, entry.path)).pipe(
              Effect.map((info) => info.type === "File"),
              Effect.orElseSucceed(() => false),
            ),
    );
    const external =
      outside.length === 0
        ? []
        : yield* Effect.promise(() =>
            glob(outside, {
              cwd: options.cwd,
              onlyFiles: true,
              expandDirectories: false,
              dot: true,
            }),
          );
    return [...files.map((entry) => entry.path), ...external];
  });

  const listFiles = Effect.fn(function* (
    options: ResolvedMemoOptions,
  ): Effect.fn.Return<string[], PlatformError, FileSystem.FileSystem | Path.Path> {
    // Explicitly hashing a generated artifact still hashes its contents.
    const excludeRuntime = !isPathWithin(dotAlchemy, options.cwd, runtimeBase);
    const [files, lockfile] = yield* Effect.all(
      [
        options.gitignore === undefined
          ? Effect.promise(() =>
              glob(options.include, {
                cwd: options.cwd,
                ignore: [
                  ...(options.exclude ?? []),
                  ...(excludeRuntime
                    ? [`${convertPathToPattern(path.resolve(runtimeBase, dotAlchemy))}/**`]
                    : []),
                ],
                onlyFiles: true,
                expandDirectories: false,
                dot: true,
              }),
            )
          : listGitTrackedCandidates(options, options.gitignore),
        options.lockfile
          ? findUp(options.cwd, [
              "bun.lock",
              "bun.lockb",
              "package-lock.json",
              "pnpm-lock.yaml",
              "yarn.lock",
            ]).pipe(
              Effect.map((lockfile) =>
                lockfile ? path.relative(options.cwd, lockfile) : undefined,
              ),
            )
          : Effect.undefined,
      ],
      { concurrency: "unbounded" },
    );
    if (lockfile && !files.includes(lockfile)) {
      files.push(lockfile);
    }
    // Absolute include patterns produce absolute matches; normalize them to
    // cwd-relative (like the lockfile above) so `hashFiles` resolves them
    // correctly and machine-specific path prefixes never leak into the hash.
    return files
      .filter(
        (file) =>
          !excludeRuntime ||
          !isPathWithin(dotAlchemy, path.resolve(options.cwd, file), runtimeBase),
      )
      .map((file) => (path.isAbsolute(file) ? path.relative(options.cwd, file) : file))
      .sort();
  });

  const hashFiles = Effect.fn(function* (
    cwd: string,
    files: string[],
  ): Effect.fn.Return<string, PlatformError> {
    const hashes = yield* Effect.forEach(
      files,
      (file) =>
        fs.readFile(path.join(cwd, file)).pipe(
          Effect.flatMap(sha256),
          Effect.map((hash) => `${file}:${hash}`),
        ),
      { concurrency: "unbounded" },
    );
    return yield* sha256Object(hashes);
  });

  return {
    resolveMemoOptions,
    listFiles,
    hashFiles,
  };
});

/**
 * Produces a deterministic SHA-256 hash of all files matched by the given
 * memo options. The hash changes if and only if the content of the matched
 * files changes, making it suitable for cache-busting build outputs.
 */
export const hashDirectory = Effect.fn(function* (props: {
  cwd?: string;
  memo?: MemoOptions;
}): Effect.fn.Return<string, PlatformError, FileSystem.FileSystem | Path.Path> {
  const service = yield* Memo;
  const resolvedOptions = yield* service.resolveMemoOptions(props.cwd, props.memo ?? {});
  const files = yield* service.listFiles(resolvedOptions);
  const hash = yield* service.hashFiles(resolvedOptions.cwd, files);
  return hash;
});