@intentius/chant 0.80.0 → 0.81.0

package/src/discovery/walk.test.ts

@@ -0,0 +1,263 @@
+import { afterEach, describe, expect, test } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative } from "node:path";
+import { walkDiscovery, workspaceMemberDirs, type DiscoveryWalker } from "./walk";
+import { findInfraFiles } from "./files";
+import { discoverOps } from "../op/discover";
+import type { DiscoveryGlobs } from "../config";
+import { auditCommand } from "../cli/commands/audit";
+
+/**
+ * chant#2527: one discovery walk. Every walker skips dot-directories, `dist`
+ * and git-ignored paths, stops at child projects inside a project, reads
+ * every child project outside one, and lets `include` re-admit what it skips.
+ */
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+function tree(files: Record<string, string>, opts: { git?: boolean } = {}): string {
+  const root = mkdtempSync(join(tmpdir(), "chant-2527-"));
+  dirs.push(root);
+  for (const [path, body] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), body);
+  }
+  if (opts.git) execFileSync("git", ["init", "-q"], { cwd: root });
+  return root;
+}
+
+const WALKERS: DiscoveryWalker[] = ["source", "lint", "components", "ops", "audit"];
+
+function walk(walker: DiscoveryWalker, root: string, globs?: Partial<DiscoveryGlobs>): string[] {
+  return walkDiscovery({
+    walker,
+    root,
+    accept: (name) => name.endsWith(".ts"),
+    globs: globs ? { root, exclude: [], include: [], ...globs } : undefined,
+  })
+    .map((f) => relative(root, f).split("\\").join("/"))
+    .sort();
+}
+
+describe("the rules every walker shares (#2527)", () => {
+  test.each(WALKERS)("%s skips dot-directories, dist and node_modules", (walker) => {
+    const root = tree({
+      "a.ts": "",
+      ".cache/b.ts": "",
+      "dist/c.ts": "",
+      "src/dist/d.ts": "",
+      "node_modules/x/e.ts": "",
+      ".github/f.ts": "",
+    });
+    const expected = walker === "audit" ? [".github/f.ts", "a.ts"] : ["a.ts"];
+    expect(walk(walker, root)).toEqual(expected);
+  });
+
+  test.each(WALKERS)("%s skips git-ignored paths, nested .gitignore included", (walker) => {
+    const root = tree(
+      {
+        ".gitignore": "vendor/\n",
+        "a.ts": "",
+        "vendor/b.ts": "",
+        "pkg/.gitignore": "gen.ts\n",
+        "pkg/gen.ts": "",
+        "pkg/keep.ts": "",
+      },
+      { git: true },
+    );
+    expect(walk(walker, root)).toEqual(["a.ts", "pkg/keep.ts"]);
+  });
+
+  test("a scan root that is itself ignored is read", () => {
+    const root = tree({ ".gitignore": "/carveout/\n", "carveout/src/main.ts": "" }, { git: true });
+    const src = join(root, "carveout", "src");
+    expect(walk("lint", src)).toEqual(["main.ts"]);
+  });
+
+  test("a tree outside git is read without ignore rules", () => {
+    const root = tree({ ".gitignore": "*.ts\n", "a.ts": "" });
+    expect(walk("source", root)).toEqual(["a.ts"]);
+  });
+});
+
+describe("child projects (#2527)", () => {
+  const files = {
+    "chant.config.ts": "export default {};\n",
+    "main.ts": "",
+    "east/chant.config.ts": "export default {};\n",
+    "east/e.ts": "",
+    "west/chant.config.json": JSON.stringify({ lexicons: ["aws"] }),
+    "west/w.ts": "",
+    "lintonly/chant.config.json": JSON.stringify({ rules: { COR004: "off" } }),
+    "lintonly/l.ts": "",
+  };
+
+  test.each(WALKERS)("inside a project, %s stops at every child project, .json configs included, and not at a lint-only fragment", (walker) => {
+    const root = tree(files);
+    expect(walk(walker, root)).toEqual(["chant.config.ts", "lintonly/l.ts", "main.ts"]);
+  });
+
+  test("the first-config quirk is gone: no child project is read as the project's own source", () => {
+    const root = tree({ "chant.config.ts": "export default {};\n", "src/chant.config.ts": "export default {};\n", "src/a.ts": "", "zz/chant.config.ts": "export default {};\n", "zz/b.ts": "" });
+    expect(walk("source", root)).toEqual(["chant.config.ts"]);
+  });
+
+  test.each(["source", "components", "lint"] as DiscoveryWalker[])("outside a project, %s reads every child project", (walker) => {
+    const root = tree({ "package.json": "{}", "a/chant.config.ts": "", "a/x.ts": "", "b/chant.config.ts": "", "b/y.ts": "" });
+    expect(walk(walker, root)).toEqual(["a/chant.config.ts", "a/x.ts", "b/chant.config.ts", "b/y.ts"]);
+  });
+
+  test("Op discovery stops at child projects even with no config at its root", () => {
+    const root = tree({ "package.json": "{}", "a/chant.config.ts": "", "a/x.ts": "", "top.ts": "" });
+    expect(walk("ops", root)).toEqual(["top.ts"]);
+  });
+
+  test("discoverOps from a configless git root does not collect a sibling project's Ops", async () => {
+    const root = tree(
+      {
+        "ops/local.op.ts": `export default { props: { name: "local", phases: [] } };\n`,
+        "sibling/chant.config.json": JSON.stringify({ lexicons: ["aws"] }),
+        "sibling/ops/theirs.op.ts": `export default { props: { name: "theirs", phases: [] } };\n`,
+      },
+      { git: true },
+    );
+    const { ops, errors } = await discoverOps({ cwd: root });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()]).toEqual(["local"]);
+  });
+});
+
+describe("include and exclude (#2519, #2527)", () => {
+  test("include re-admits a dot-directory, dist, an ignored path and a child project", () => {
+    const root = tree(
+      {
+        "chant.config.ts": "export default {};\n",
+        ".gitignore": "gen/\n",
+        ".cache/a.ts": "",
+        "dist/b.ts": "",
+        "gen/c.ts": "",
+        "stack/chant.config.ts": "",
+        "stack/d.ts": "",
+        "main.ts": "",
+      },
+      { git: true },
+    );
+    expect(walk("source", root)).toEqual(["chant.config.ts", "main.ts"]);
+    expect(walk("source", root, { include: [".cache", "dist/b.ts", "gen", "stack"] })).toEqual([
+      ".cache/a.ts",
+      "chant.config.ts",
+      "dist/b.ts",
+      "gen/c.ts",
+      "main.ts",
+      "stack/chant.config.ts",
+      "stack/d.ts",
+    ]);
+  });
+
+  test("an include below a skipped directory reads only what it names there", () => {
+    const root = tree({ ".tool/keep/a.ts": "", ".tool/drop/b.ts": "", ".tool/c.ts": "" });
+    expect(walk("source", root, { include: [".tool/keep/**"] })).toEqual([".tool/keep/a.ts"]);
+  });
+
+  test("exclude drops files, include wins over it, and include never reaches node_modules", () => {
+    const root = tree({ "ops/run.ts": "", "ops/stack.ts": "", "node_modules/x/a.ts": "", "main.ts": "" });
+    expect(walk("ops", root, { exclude: ["ops"], include: ["ops/stack.ts", "node_modules"] })).toEqual(["main.ts", "ops/stack.ts"]);
+  });
+
+  test("findInfraFiles reads include from the project config", async () => {
+    const root = tree({
+      "chant.config.json": JSON.stringify({ lexicons: ["aws"], include: ["src"] }),
+      "src/chant.config.ts": "export default { lint: {} };\n",
+      "src/a.ts": "",
+    });
+    const files = (await findInfraFiles(root)).map((f) => relative(root, f)).sort();
+    expect(files).toEqual(["src/a.ts", "src/chant.config.ts"]);
+  });
+});
+
+describe("workspace members and groups (#2525 rule 3, read by #2534's reader)", () => {
+  test("nothing is excluded without a workspace declaration", async () => {
+    const root = tree({ "chant.config.json": JSON.stringify({ lexicons: ["aws"] }), "members/a/x.ts": "" }, { git: true });
+    expect(await workspaceMemberDirs(root)).toEqual([]);
+  });
+
+  test("with chant.workspace.json, member directories below the scan root leave the walk", async () => {
+    const root = tree(
+      {
+        "chant.workspace.json": JSON.stringify({
+          name: "w",
+          schema: 1,
+          members: [
+            { name: "root", dir: ".", kind: "chant" },
+            { name: "a", dir: "members/a", kind: "chant" },
+          ],
+        }),
+        "main.ts": "",
+        "members/a/x.ts": "",
+        "members/b/y.ts": "",
+      },
+      { git: true },
+    );
+    const excludeDirs = await workspaceMemberDirs(root);
+    expect(excludeDirs.map((d) => relative(root, d))).toEqual(["members/a"]);
+    const files = walkDiscovery({ walker: "source", root, accept: (n) => n.endsWith(".ts"), excludeDirs, globs: { root, exclude: [], include: ["members"] } });
+    expect(files.map((f) => relative(root, f)).sort()).toEqual(["main.ts", "members/b/y.ts"]);
+    // Scanned from inside the member, the member is the project and is read.
+    expect(await workspaceMemberDirs(join(root, "members", "a"))).toEqual([]);
+  });
+
+  test("an example group's matches leave the walk too, and a .jsonc declaration counts", async () => {
+    const root = tree(
+      {
+        "chant.workspace.jsonc": `{
+          // groups are read through #2534's declaration reader
+          "name": "w",
+          "schema": 1,
+          "members": [
+            { "name": "root", "dir": ".", "kind": "chant" },
+            { "name": "examples", "kind": "examples", "glob": "examples/*" },
+          ],
+        }`,
+        "main.ts": "",
+        "examples/one/chant.config.ts": "export default {};",
+        "examples/one/x.ts": "",
+        "examples/notes/readme.ts": "",
+      },
+      { git: true },
+    );
+    const excludeDirs = await workspaceMemberDirs(root);
+    // `examples/notes` holds no chant project, so the group leaves it alone.
+    expect(excludeDirs.map((d) => relative(root, d))).toEqual(["examples/one"]);
+  });
+
+  test("chant audit at the workspace root leaves members out", async () => {
+    const root = tree(
+      {
+        "chant.workspace.json": JSON.stringify({
+          name: "w",
+          schema: 1,
+          members: [
+            { name: "root", dir: ".", kind: "chant" },
+            { name: "a", dir: "members/a", kind: "chant" },
+          ],
+        }),
+        "terraform.tfstate": "{}",
+        "members/a/terraform.tfstate": "{}",
+      },
+      { git: true },
+    );
+    // No lexicons: TF023 still runs, and its paths show what the walk read.
+    const result = await auditCommand({ path: root, format: "json", plugins: [] });
+    expect(result.findings.filter((f) => f.checkId === "TF023").map((f) => f.file)).toEqual(["terraform.tfstate"]);
+  });
+
+  test("a declaration that fails to read excludes nothing", async () => {
+    const root = tree({ "chant.workspace.json": "{ not json", "members/a/x.ts": "" }, { git: true });
+    expect(await workspaceMemberDirs(root)).toEqual([]);
+  });
+});

package/src/discovery/walk.ts

@@ -0,0 +1,334 @@
+/**
+ * The one discovery walk (chant#2527).
+ *
+ * Every command that decides which files chant reads walks the tree here:
+ * source discovery (`./files.ts`'s `findInfraFiles`, behind build, graph,
+ * list, explain and lexicon detection), `chant lint`, component discovery,
+ * Op discovery and the `chant audit` walk. They used to have five walkers
+ * with five sets of rules. v0.80.0 warned about every file whose status the
+ * convergence changes (#2571), and this module is that convergence. It is on
+ * #2525's level-0 exception list.
+ *
+ * The rules, for every walker:
+ *
+ * - `node_modules` and `.git` are never entered.
+ * - Dot-directories are skipped. The audit walk keeps `.github` and
+ *   `.forgejo`, which hold the CI files it audits.
+ * - `dist` is skipped.
+ * - Git-ignored paths are skipped, nested `.gitignore` files, `.git/info/exclude`
+ *   and the global excludes file included, the way git itself decides. Only
+ *   paths below the scan root are asked about: when the scan root is itself
+ *   ignored, nothing under it is dropped for being ignored, so building or
+ *   linting an ignored directory still reads it.
+ * - When the scan root is inside a chant project, a child directory holding a
+ *   project config is a boundary and is not entered. A `chant.config.json`
+ *   holding only lint keys is a fragment, not a project config, and is not a
+ *   boundary. A `chant.config.ts` always is one, since telling a lint-only one
+ *   apart would mean running it. When the scan root is outside every project,
+ *   every child project is read. Op discovery always stops at child projects
+ *   below its root.
+ * - The project's `exclude` globs (#2519) drop what they match, and its
+ *   `include` globs re-admit what `exclude` or any rule above would skip.
+ *   `node_modules`, `.git` and workspace members are the exceptions: include
+ *   never re-admits them.
+ * - Workspace members and group matches leave the root project's walk
+ *   (#2525 rule 3), and only when a workspace declaration exists. Without one nothing is loaded and
+ *   nothing is excluded; see {@link workspaceMemberDirs}.
+ *
+ * The walk is synchronous: the audit walk it replaced was, and the glob and
+ * ignore facts are gathered once before it starts.
+ */
+
+import { execFileSync } from "node:child_process";
+import { closeSync, existsSync, openSync, readdirSync, readSync, statSync, type Dirent } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+// @ts-ignore — picomatch has no types declaration
+import picomatch from "picomatch";
+import { findProjectConfig, findWorkspaceRoot } from "../project-root";
+import { isLintOnlyFragment, type DiscoveryGlobs } from "../config";
+
+/** The commands that walk the tree. */
+export type DiscoveryWalker = "source" | "lint" | "components" | "ops" | "audit";
+
+/** Dot-directories the audit walk enters anyway, since they hold the CI files it audits. */
+export const AUDIT_DOT_DIRS: ReadonlySet<string> = new Set([".github", ".forgejo"]);
+
+/** Directories no rule and no glob ever lets the walk into. */
+const NEVER_ENTER = new Set(["node_modules", ".git"]);
+
+/** One walk: which walker, where from, which files it wants, and the facts only some walkers have. */
+export interface WalkOptions {
+  walker: DiscoveryWalker;
+  /** The directory the walk starts from. Joined onto, never resolved, so relative roots give relative paths. */
+  root: string;
+  /**
+   * Which files the walker wants, by name and full path. Called only for a
+   * file every rule above has let through, so a marker check here reads only
+   * files that could be returned.
+   */
+  accept: (name: string, fullPath: string) => boolean;
+  /**
+   * The project's discovery globs. Omitted, none apply. Callers that can load
+   * the project config resolve them with `resolveDiscoveryGlobs`.
+   */
+  globs?: DiscoveryGlobs;
+  /** Sort each directory's entries by name. The audit walk does, for a stable limit. */
+  sorted?: boolean;
+  /** Follow symlinked directories and files. `chant lint` always did; the others never did. */
+  followSymlinks?: boolean;
+  /**
+   * The audit walk's file limit. Every file the walk takes counts, accepted or
+   * not; `truncated` is set once a file past the limit is met.
+   */
+  limit?: { max: number; truncated: boolean };
+  /**
+   * Called for a dot-directory the walk skips. Returning true takes the
+   * directory's own path as a file without entering it (the audit walk's
+   * `.terraform`, which TF023 reports by its presence).
+   */
+  takeSkippedDir?: (name: string, fullPath: string) => boolean;
+  /**
+   * Paths the git-ignore rule leaves alone, to be judged by the caller. The
+   * audit walk keeps Terraform state paths for TF023, which has its own
+   * `.gitignore` reading.
+   */
+  keepIgnored?: (fullPath: string) => boolean;
+  /** Directories that leave this walk, absolute. See {@link workspaceMemberDirs}. */
+  excludeDirs?: readonly string[];
+}
+
+// ── Globs ────────────────────────────────────────────────────────────────────
+
+/** A project's `exclude` and `include` globs, compiled against the config's directory. */
+interface CompiledGlobs {
+  /** True when an `exclude` pattern matches the path or a directory above it. */
+  excluded(full: string): boolean;
+  /** True when an `include` pattern matches the path or a directory above it. */
+  included(full: string): boolean;
+  /** True when some `include` pattern names a path strictly below directory `full`. */
+  includeBelow(full: string): boolean;
+}
+
+/** Path parts below `home`, or undefined for `home` itself or a path outside it. */
+function partsBelow(home: string, full: string): string[] | undefined {
+  const rel = relative(home, resolve(full));
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return undefined;
+  return rel.split(sep);
+}
+
+function compileGlobs(globs: DiscoveryGlobs | undefined): CompiledGlobs | undefined {
+  if (!globs || (globs.exclude.length === 0 && globs.include.length === 0)) return undefined;
+  const home = resolve(globs.root);
+  const matcher = (patterns: string[]): ((full: string) => boolean) => {
+    if (patterns.length === 0) return () => false;
+    const match: (p: string) => boolean = picomatch(patterns, { dot: true });
+    return (full) => {
+      const parts = partsBelow(home, full);
+      return parts !== undefined && parts.some((_, i) => match(parts.slice(0, i + 1).join("/")));
+    };
+  };
+  // The literal directory part of each include pattern: `.cache/keep/**`
+  // gives `.cache/keep`. The walk enters a skipped directory on the way to it.
+  const bases = globs.include.map((p) => (picomatch.scan(p) as { base: string }).base).filter((b) => b !== "");
+  return {
+    excluded: matcher(globs.exclude),
+    included: matcher(globs.include),
+    includeBelow: (full) => {
+      const parts = partsBelow(home, full);
+      if (parts === undefined) return false;
+      const rel = parts.join("/");
+      return bases.some((b) => b.startsWith(`${rel}/`));
+    },
+  };
+}
+
+// ── Git ──────────────────────────────────────────────────────────────────────
+
+/**
+ * The untracked paths git ignores under `root`, absolute, with fully ignored
+ * directories listed once. One `git ls-files` call. A tree outside git, a
+ * missing `git`, or a root that is itself ignored yields an empty set: ignore
+ * rules are asked only about paths below the scan root.
+ */
+export function gitIgnoredBelow(root: string): Set<string> {
+  let out: string;
+  try {
+    out = execFileSync("git", ["ls-files", "-z", "--others", "--ignored", "--exclude-standard", "--directory"], {
+      cwd: root,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 256 * 1024 * 1024,
+    });
+  } catch {
+    return new Set();
+  }
+  const ignored = new Set<string>();
+  const abs = resolve(root);
+  for (const entry of out.split("\0")) {
+    if (entry === "") continue;
+    const rel = entry.endsWith("/") ? entry.slice(0, -1) : entry;
+    // `./` (or `.`): the scan root is itself ignored.
+    if (rel === "." || rel === "") return new Set();
+    ignored.add(join(abs, rel));
+  }
+  return ignored;
+}
+
+// ── Boundaries ───────────────────────────────────────────────────────────────
+
+/** A directory that holds a project config: `chant.config.ts`, or a `chant.config.json` that is not a lint-only fragment. */
+export function isProjectBoundary(dir: string): boolean {
+  if (existsSync(join(dir, "chant.config.ts"))) return true;
+  const json = join(dir, "chant.config.json");
+  return existsSync(json) && !isLintOnlyFragment(json);
+}
+
+/** Whether child projects end the walk from `root`: always for Ops, otherwise when `root` is inside a project. */
+export function childProjectsAreBoundaries(walker: DiscoveryWalker, root: string): boolean {
+  return walker === "ops" || findProjectConfig(root).configPath !== undefined;
+}
+
+// ── Workspace members ────────────────────────────────────────────────────────
+
+/**
+ * The directories a workspace declaration moves out of the root project's
+ * discovery (#2525 rule 3), absolute and strictly below `root`, or none:
+ * every member's directory but the root's, and every group match
+ * (`rootExclusions` in `../workspace/declaration.ts`).
+ *
+ * Level 0 pays for `findWorkspaceRoot`, which only tests whether a
+ * `chant.workspace.json` or `.jsonc` exists from `root` up to the git root,
+ * and loads nothing. Only when a declaration is found are the workspace
+ * modules loaded to read it. A declaration that fails to read excludes
+ * nothing here; `chant workspace ls` is where its errors are reported. This
+ * is the only place discovery asks about workspaces; the walkers pass the
+ * result as `excludeDirs`.
+ */
+export async function workspaceMemberDirs(root: string): Promise<string[]> {
+  const found = findWorkspaceRoot(root);
+  if (!found) return [];
+  const start = resolve(root);
+  const [{ readDeclaration, resolveGroups, rootExclusions }, { workingTree }] = await Promise.all([
+    import("../workspace/declaration"),
+    import("../workspace/tree"),
+  ]);
+  let dirs: string[];
+  try {
+    const tree = workingTree(found.dir);
+    const declaration = readDeclaration(tree);
+    dirs = rootExclusions(declaration, resolveGroups(declaration, tree)).map((e) => resolve(found.dir, e.dir));
+  } catch {
+    return [];
+  }
+  return dirs.filter((d) => partsBelow(start, d) !== undefined);
+}
+
+// ── Markers ──────────────────────────────────────────────────────────────────
+
+/** The first `bytes` of a file as UTF-8, or "" when it can't be read. */
+export function readHead(file: string, bytes: number): string {
+  let fd: number | undefined;
+  try {
+    fd = openSync(file, "r");
+    const buf = Buffer.alloc(bytes);
+    const n = readSync(fd, buf, 0, bytes, 0);
+    return buf.toString("utf8", 0, n);
+  } catch {
+    return "";
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+// ── The walk ─────────────────────────────────────────────────────────────────
+
+/** Walk `opts.root` under the rules in the module doc and return the files `accept` took. */
+export function walkDiscovery(opts: WalkOptions): string[] {
+  const out: string[] = [];
+  const globs = compileGlobs(opts.globs);
+  const ignored = gitIgnoredBelow(opts.root);
+  const boundaries = childProjectsAreBoundaries(opts.walker, opts.root);
+  const excludeDirs = new Set((opts.excludeDirs ?? []).map((d) => resolve(d)));
+  const dotDirsKept = opts.walker === "audit" ? AUDIT_DOT_DIRS : new Set<string>();
+  const limit = opts.limit;
+
+  const isIgnored = (full: string): boolean => ignored.size > 0 && ignored.has(resolve(full));
+
+  /** Take a path; false once the limit is reached. */
+  const take = (full: string): boolean => {
+    if (limit && out.length >= limit.max) {
+      limit.truncated = true;
+      return false;
+    }
+    out.push(full);
+    return true;
+  };
+
+  const kind = (dir: string, e: Dirent): "dir" | "file" | undefined => {
+    if (e.isDirectory()) return "dir";
+    if (e.isFile()) return "file";
+    if (opts.followSymlinks && e.isSymbolicLink()) {
+      try {
+        const s = statSync(join(dir, e.name));
+        return s.isDirectory() ? "dir" : s.isFile() ? "file" : undefined;
+      } catch {
+        return undefined;
+      }
+    }
+    return undefined;
+  };
+
+  /**
+   * Walk `dir`. `probing` is true below a directory a rule skipped that the
+   * walk entered only because an `include` pattern names something inside
+   * it: there, only what `include` matches is taken.
+   */
+  const walk = (dir: string, probing: boolean): boolean => {
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return true;
+    }
+    if (opts.sorted) entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const e of entries) {
+      if (limit?.truncated) return false;
+      const full = join(dir, e.name);
+      const type = kind(dir, e);
+      if (type === "dir") {
+        if (NEVER_ENTER.has(e.name) || excludeDirs.has(resolve(full))) continue;
+        const dotSkip = e.name.startsWith(".") && !dotDirsKept.has(e.name);
+        if (dotSkip && opts.takeSkippedDir?.(e.name, full)) {
+          if (!take(full)) return false;
+          continue;
+        }
+        const ruleSkip =
+          dotSkip ||
+          e.name === "dist" ||
+          (isIgnored(full) && !opts.keepIgnored?.(full)) ||
+          (boundaries && isProjectBoundary(full));
+        if (ruleSkip || probing) {
+          if (globs?.included(full)) {
+            if (!walk(full, false)) return false;
+          } else if (globs?.includeBelow(full)) {
+            if (!walk(full, true)) return false;
+          }
+          continue;
+        }
+        if (!walk(full, false)) return false;
+      } else if (type === "file") {
+        const skipped =
+          probing ||
+          (isIgnored(full) && !opts.keepIgnored?.(full)) ||
+          (globs?.excluded(full) ?? false);
+        if (skipped && !globs?.included(full)) continue;
+        if (!opts.accept(e.name, full)) continue;
+        if (!take(full)) return false;
+      }
+    }
+    return true;
+  };
+
+  walk(opts.root, false);
+  return out;
+}

package/src/effect-receipt.ts

@@ -38,7 +38,7 @@
  * `sha256:<hex>` like the build-ledger digests in ./lifecycle/build-ledger.ts).
  */
 
-import { createHash } from "node:crypto";
+import { contentDigest } from "./content-digest";
 import { DECLARABLE_MARKER, type Declarable } from "./declarable";
 import { isIntrinsic, type Intrinsic } from "./intrinsic";
 
@@ -293,7 +293,7 @@ function encodeCanonical(value: unknown, path: string, seen: Set<object>): strin
 }
 
 function sha256Digest(canonical: string): string {
-  return `sha256:${createHash("sha256").update(canonical, "utf8").digest("hex")}`;
+  return contentDigest(canonical);
 }
 
 // ─────────────────────────────────────────────────────────────────────────

package/src/graph-ir.ts

@@ -230,7 +230,10 @@ export interface IRExport {
 /** A cross-stack import this stack consumes — a `Parameter` fed from another
  * stack's output at deploy time. A viewer matches an import `name` to another
  * stack's export `name` to draw the cross-stack edge; the parameter's in-stack
- * consumers are ordinary `$ref` edges to `node` (#513). */
+ * consumers are ordinary `$ref` edges to `node` (#513). A reader that infers
+ * that match by name uses `joinKey()` from `./join-key.ts` and labels the edge
+ * `exact` or `folded`, the way `chant workspace graph` labels joins across
+ * members (#2539, ws-008). */
 export interface IRImport {
   /** Parameter name — the cross-stack handle (e.g. "clusterArn"). */
   name: string;

package/src/join-key.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "vitest";
+import { joinKey, joinLabel } from "./join-key";
+
+describe("joinKey (#2539, ws-008)", () => {
+  test("folds case and punctuation", () => {
+    for (const name of ["ClusterArn", "clusterArn", "cluster_arn", "cluster-arn", "CLUSTER.ARN", "Cluster Arn"]) {
+      expect(joinKey(name)).toBe("clusterarn");
+    }
+  });
+
+  test("keeps digits and letters outside ASCII", () => {
+    expect(joinKey("Subnet1")).toBe("subnet1");
+    expect(joinKey("Subnet1")).not.toBe(joinKey("Subnet2"));
+    expect(joinKey("Größe")).toBe("größe");
+  });
+
+  test("labels a join exact or folded, and says when names don't join", () => {
+    expect(joinLabel("ClusterArn", "ClusterArn")).toBe("exact");
+    expect(joinLabel("clusterArn", "ClusterArn")).toBe("folded");
+    expect(joinLabel("vpc_id", "VpcId")).toBe("folded");
+    expect(joinLabel("VpcId", "SubnetId")).toBeUndefined();
+    expect(joinLabel("", "")).toBeUndefined();
+    expect(joinLabel("--", "__")).toBeUndefined();
+  });
+});