@intentius/chant 0.46.0 → 0.50.0

package/src/deep-observation.ts

@@ -266,6 +266,20 @@ export interface DeepNormalizationHooks {
    * reads as permanent drift.
    */
   unresolved?(node: DeepNode): boolean;
+  /**
+   * Return true when this value is secret material the diff must never hold —
+   * it is collapsed to {@link MASKED} on BOTH sides (the hook runs over the
+   * declared and the live tree alike), so presence and key names still
+   * classify while values never reach a diff row, a log line, or a snapshot.
+   *
+   * The pass masks by key name on its own ({@link isSensitiveKey}); this hook
+   * exists for the lexicons whose secret-bearing paths are structural rather
+   * than name-shaped — a Kubernetes Secret's `data` carries arbitrary key
+   * names (`app.conf`), and #1365 decision 6 draws the hard line: drift on a
+   * secret observes presence, declared key-set, and metadata — never a value
+   * or a value-derived hash.
+   */
+  mask?(node: DeepNode): boolean;
 }
 
 /** Everything the pass needs besides the tree itself. */
@@ -405,6 +419,9 @@ export function normalizeDeepProperties(
 
   const normalizeValue = (value: unknown, path: string, pattern: string, key: string): unknown => {
     if (isSensitiveKey(key)) return MASKED;
+    // The lexicon's structural mask — same collapse, path-shaped rather than
+    // key-named (a k8s Secret's `data.*` no matter what the key is called).
+    if (hooks?.mask?.(nodeOf(path, pattern, key, value))) return MASKED;
     // A value the lexicon says cannot be known without deploying — an
     // expression-string reference — collapses exactly like a class-instance
     // intrinsic does below.

package/src/discovery/collect.ts

@@ -34,6 +34,15 @@ function stackPrefix(file: string, buildRoot: string | undefined): string {
   return segments.map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join("");
 }
 
+/**
+ * Whole-entity origin for a declarable a file exported directly (chant #1443).
+ * A composite's members get theirs from `expandComposite`, which knows the
+ * composite and the instance; a direct export has nothing between the source
+ * file and the resource. Merged key-by-key, so a path the fold path already
+ * attributed to a build parameter is not overwritten.
+ */
+const AUTHORED_ROOT: EntityProvenance["paths"] = { "": { kind: "authored" } };
+
 /** One entity to be placed into the map, produced by {@link enumerateEntries}. */
 interface PendingEntry {
   /** The un-disambiguated map key this entity would take (export name, indexed
@@ -73,12 +82,12 @@ function enumerateEntries(
     for (const [rawName, value] of sortedExports) {
       const name = exportKey(rawName, file);
       if (isDeclarable(value)) {
-        entries.push({ bareKey: name, value, file, provenance: { sourceFile: file } });
+        entries.push({ bareKey: name, value, file, provenance: { sourceFile: file, paths: AUTHORED_ROOT } });
       } else if (Array.isArray(value)) {
         for (let i = 0; i < value.length; i++) {
           const item = value[i];
           if (isDeclarable(item)) {
-            entries.push({ bareKey: `${name}_${i}`, value: item, file, provenance: { sourceFile: file } });
+            entries.push({ bareKey: `${name}_${i}`, value: item, file, provenance: { sourceFile: file, paths: AUTHORED_ROOT } });
           } else if (isCompositeInstance(item)) {
             const indexedName = `${name}_${i}`;
             for (const [expandedName, entity] of expandComposite(indexedName, item)) {

package/src/discovery/fold-import.test.ts

@@ -9,6 +9,7 @@ import { isCompositeInstance } from "../composite";
 import { isAttrRefLike } from "../utils";
 import { isIntrinsic } from "../intrinsic";
 import { params as sharedParams } from "../params";
+import { getPathProvenance } from "../provenance";
 import type { AttrRef } from "../attrref";
 import type { IntrinsicDef } from "../lexicon";
 
@@ -1153,6 +1154,59 @@ describe("tryFoldFile — build-time parameters (chant #1064)", () => {
 
     setBuildParams({});
   });
+
+  // chant #1443 — fold substitutes `params.<name>` away, so the emitted value
+  // is a literal and unattributable. These record which parameters the
+  // AUTHORED expression read, before that happens.
+  test("a folded resource records which build parameters each of its paths reads", async () => {
+    await writeResourceDefs();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { params } from ${JSON.stringify(paramsPath)};
+        const suffix = params.env === "prod" ? "" : "-dev";
+        export const bucket = new Bucket({
+          name: \`assets\${suffix}\`,
+          fixed: "never-moves",
+          nested: { region: params.region },
+        });
+      `,
+    );
+
+    const session = createFoldSession([], { env: "prod", region: "us-east-1" });
+    const result = await tryFoldFile(file, [], session);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const [, entity] = result.entities[0];
+    expect(getPathProvenance(entity as object)).toEqual({
+      name: { kind: "build-param", params: ["env"] },
+      "nested.region": { kind: "build-param", params: ["region"] },
+    });
+  });
+
+  test("a folded resource that reads no parameter records no path origins", async () => {
+    await writeResourceDefs();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { params } from ${JSON.stringify(paramsPath)};
+        export const other = params.env;
+        export const bucket = new Bucket({ name: "static" });
+      `,
+    );
+
+    const result = await tryFoldFile(file, [], createFoldSession([], { env: "prod" }));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const entity = result.entities.find(([name]) => name === "bucket")![1];
+    expect(getPathProvenance(entity as object)).toBeUndefined();
+  });
 });
 
 /**

package/src/discovery/fold-import.ts

@@ -22,6 +22,7 @@ import {
   type FoldedIntrinsic,
   type FoldedHelperCall,
   type SymbolicValue,
+  type FoldedCompositeStepCall,
 } from "../fold/fold";
 import { isChantOwnedSpecifier, isFoldableHelperName } from "../fold/foldable-helpers";
 import {
@@ -37,7 +38,9 @@ import {
   SUPPORTED_UNARY_OPERATORS,
 } from "../fold/subset";
 import { importModule } from "./import";
-import type { IntrinsicDef } from "../lexicon";
+import { collectParamDependencies } from "./param-deps";
+import { setPathProvenance } from "../provenance";
+import { intrinsicCallFoldsEagerly, type IntrinsicDef } from "../lexicon";
 import type { BuildParamValue } from "../build-params";
 
 /**
@@ -1096,19 +1099,25 @@ function activeLexiconPackage(specifier: string, lexiconPackages: ReadonlySet<st
  * and intrinsic functions; the only thing new is that a plain DATA export is
  * now reachable too.
  *
- * Callable exports are deliberately excluded. A lexicon's functions — its
+ * Callable exports are otherwise excluded. A lexicon's functions — its
  * resource classes, composite factories, intrinsic implementations — already
  * have dedicated resolution paths that know how to INVOKE them
  * (`resolveResourceEntity`, `resolveCallExpression`, `reviveFoldedValue`), and
- * binding them as plain identifier values here would widen what folds in ways
- * this issue neither needs nor measured: none of the references #1063 exists
- * to unblock (`Azure`, `GCP`, `S3Actions`, gitlab's `CI`) is a function.
+ * binding an arbitrary one as a plain identifier value here would widen what
+ * folds in unmeasured ways. The one exception (chant #1966) is a function its
+ * lexicon registered with {@link IntrinsicDef.foldsEagerly} — the same
+ * per-name, lexicon-declared opt-in `foldsAsCall` is for an intrinsic's
+ * envelope-and-revive form, admitting this one because `fold()`
+ * (../fold/fold.ts) needs to CALL it eagerly — synchronously, before
+ * revival — to support a lexicon's own string-building helpers used inline
+ * (`matrix("os").toString()`, `` `${inputs("x")}` ``), where an envelope
+ * would still be a plain object when the enclosing template folds.
  *
  * Returns `undefined` — never throws — for a package that isn't an active
- * lexicon, an export the package doesn't have, a callable export, or an
- * import that fails. The binding is then simply absent from `externals`,
- * exactly as before, and `fold()`'s ordinary "unresolved identifier" failure
- * still fires if the name is actually referenced.
+ * lexicon, an export the package doesn't have, a non-admitted callable
+ * export, or an import that fails. The binding is then simply absent from
+ * `externals`, exactly as before, and `fold()`'s ordinary "unresolved
+ * identifier" failure still fires if the name is actually referenced.
  */
 async function resolveActiveLexiconExport(
   binding: ImportBinding,
@@ -1133,7 +1142,10 @@ async function resolveActiveLexiconExport(
 
   if (!(binding.imported in mod)) return undefined;
   const value = mod[binding.imported];
-  if (typeof value === "function") return undefined;
+  if (typeof value === "function") {
+    const eager = session.intrinsics.some((i) => i.name === binding.imported && intrinsicCallFoldsEagerly(i));
+    if (!eager) return undefined;
+  }
   return { value };
 }
 
@@ -1415,19 +1427,19 @@ async function resolveImportedCall(
 }
 
 /**
- * Arm 2 — import the module the callee came from and call it, in this process.
- * Unchanged from #1022 in both behavior and ORDER (refusal, resolve, import,
- * callable check, arguments, call); #1023 only factored it out so the
- * interpretation arm above can fall back into it.
- *
- * @param args - Already-evaluated arguments, when the caller has them.
+ * Arm 2 — import the module the callee came from and call it, in this
+ * process, given ALREADY-RESOLVED argument values. Factored out of
+ * {@link invokeImportedCallee} (chant #1174) so a caller with no raw
+ * `ts.CallExpression` node — {@link resolveCompositeCall}, the nested-value
+ * counterpart to {@link resolveCallExpression} — can reach the identical
+ * refusal/resolve/import/callable-check/call sequence #1022 established,
+ * without inventing a second copy of it.
  */
-async function invokeImportedCallee(
-  node: ts.CallExpression,
+async function invokeResolvedCallee(
   calleeName: string,
   binding: ImportBinding,
   ctx: ResolveCtx,
-  args?: readonly unknown[],
+  args: readonly unknown[],
 ): Promise<unknown> {
   // chant #1093 — THE gap this check exists for. Invoking the callee runs
   // project code (the factory body, and its whole module's top level) in the
@@ -1473,12 +1485,67 @@ async function invokeImportedCallee(
     throw cheapError(`"${binding.imported}" from "${binding.specifier}" is not a function`);
   }
 
-  const callArgs = args ?? (await resolveCallArguments(node, calleeName, ctx));
-
   executionCounts.factoryInvocations += 1;
   if (isProjectFileSpecifier(binding.specifier)) executionCounts.projectFactoryInvocations += 1;
 
-  return (Fn as (...fnArgs: unknown[]) => unknown)(...callArgs);
+  return (Fn as (...fnArgs: unknown[]) => unknown)(...args);
+}
+
+/**
+ * Arm 2's original entry point — a raw call-expression node in hand. Resolves
+ * arguments (unless the caller already has them) and delegates to
+ * {@link invokeResolvedCallee}. Unchanged from #1022 in both behavior and
+ * ORDER (refusal, resolve, import, callable check, arguments, call); #1023
+ * factored the body out once already, #1174 a second time.
+ *
+ * @param args - Already-evaluated arguments, when the caller has them.
+ */
+async function invokeImportedCallee(
+  node: ts.CallExpression,
+  calleeName: string,
+  binding: ImportBinding,
+  ctx: ResolveCtx,
+  args?: readonly unknown[],
+): Promise<unknown> {
+  const callArgs = args ?? (await resolveCallArguments(node, calleeName, ctx));
+  return invokeResolvedCallee(calleeName, binding, ctx, callArgs);
+}
+
+/**
+ * Resolve a composite-factory call used as a NESTED value — chant #1174's
+ * `<Identifier>(...).step` idiom ({@link FoldedCompositeStepCall}) — given
+ * its callee NAME and already-REVIVED argument values. The nested-value
+ * counterpart to {@link resolveCallExpression}, which the top-level
+ * declarator path (`export const x = Checkout({...})`) already used: the
+ * raw `ts.CallExpression` node isn't needed here because
+ * {@link resolveInterpretableFactory} only needs the import `binding`, and
+ * {@link interpretCompositeFactory}/{@link invokeResolvedCallee} only need
+ * the resolved argument values — which `fold()`'s envelope already folded
+ * and {@link reviveFoldedValue} has already revived by the time this runs.
+ *
+ * Same two arms, same order, as the top-level path: interpret a project-file
+ * registered `Composite` (chant #1023) when its body qualifies, otherwise
+ * import and invoke for real — which is the arm every lexicon-package
+ * composite (`Checkout`, `SetupNode`, …) always takes, exactly as it does
+ * today for a top-level `export const x = Checkout({...})`. An unbound
+ * callee name throws the same "function call as a value" message `fold()`
+ * itself would have, for a caller with no `FoldedCompositeStepCall` special
+ * case to fall into.
+ */
+async function resolveCompositeCall(calleeName: string, args: readonly unknown[], ctx: ResolveCtx): Promise<unknown> {
+  const binding = ctx.imports.get(calleeName);
+  if (!binding) throw cheapError(`unresolved identifier: ${calleeName}`);
+
+  const factory = await resolveInterpretableFactory(binding, ctx);
+  if (factory) {
+    const interpreted = await interpretCompositeFactory(factory, args, ctx);
+    if (interpreted) return interpreted.value;
+    // Declined — falls through to arm 2 with the SAME arguments, so a nested
+    // composite-call argument (or a live cross-file reference) is not
+    // resolved a second time. Identical discipline to `resolveImportedCall`.
+  }
+
+  return invokeResolvedCallee(calleeName, binding, ctx, args);
 }
 
 /**
@@ -2502,6 +2569,24 @@ async function reviveFoldedValue(value: FoldedValue, ctx: ResolveCtx, requireLiv
     return reviveHelperCall(value as FoldedHelperCall, ctx);
   }
 
+  if ("__compositeStep" in value) {
+    // chant #1174 — `<Identifier>(...).step`, see {@link FoldedCompositeStepCall}.
+    // Arguments revive with `requireLiveRefs: false` — the same rule
+    // `resolveCallArguments` applies to a NON-helper callee's arguments
+    // (a composite factory stores its props, it doesn't inspect them the way
+    // an intrinsic/helper does), so a `{__attrRef}` among them stays the
+    // symbolic envelope the composite's own resource construction resolves
+    // by name, exactly as a top-level resource's props would.
+    const call = value as FoldedCompositeStepCall;
+    const revivedArgs: unknown[] = [];
+    for (const a of call.args) revivedArgs.push(await reviveFoldedValue(a, ctx, false));
+    const result = await resolveCompositeCall(call.__compositeStep, revivedArgs, ctx);
+    if (!isIndexableObject(result)) {
+      throw cheapError(`composite call \`${call.__compositeStep}(...)\` did not resolve to an object with a "step" member`);
+    }
+    return (result as Record<string, unknown>).step;
+  }
+
   if ("__attrRef" in value) {
     if (requireLiveRefs) {
       throw cheapError(
@@ -2889,6 +2974,46 @@ async function constructFoldedResource(
  * performs unconditionally for the same file, and through the same
  * already-memoized `importModule`.
  */
+/**
+ * The local names this file bound to the build's parameter object (chant
+ * #1443). Object identity against {@link FoldSession.buildParams}, which
+ * `buildExternals` substituted directly, so an unrelated import that happens to
+ * be called `params` is not mistaken for it.
+ */
+function paramLocalNames(ctx: ResolveCtx): Set<string> {
+  const out = new Set<string>();
+  const buildParams = ctx.session.buildParams;
+  if (!buildParams) return out;
+  for (const [name, value] of ctx.externals) {
+    if (value === buildParams) out.add(name);
+  }
+  return out;
+}
+
+/**
+ * chant #1443 — record which build parameters each of a resource's authored
+ * property expressions reads, before fold substitutes them away. Best-effort
+ * and additive: a file with no `params` import, or a constructor called with no
+ * object literal, records nothing.
+ */
+function stampParamDependencies(entity: unknown, node: ts.NewExpression, ctx: ResolveCtx): void {
+  if (typeof entity !== "object" || entity === null) return;
+  const paramLocals = paramLocalNames(ctx);
+  if (paramLocals.size === 0) return;
+  // The same argument `foldResource` treats as props: the first object literal.
+  let propsArg: ts.ObjectLiteralExpression | undefined;
+  for (const argument of node.arguments ?? []) {
+    if (ts.isObjectLiteralExpression(argument)) {
+      propsArg = argument;
+      break;
+    }
+  }
+  if (!propsArg) return;
+  for (const [path, origin] of Object.entries(collectParamDependencies(propsArg, ctx.consts, paramLocals))) {
+    setPathProvenance(entity, path, origin);
+  }
+}
+
 async function preresolveResourceConsts(ctx: ResolveCtx): Promise<Map<ts.Expression, unknown>> {
   const built = new Map<ts.Expression, unknown>();
   for (const [name, initializer] of ctx.consts) {
@@ -2896,6 +3021,7 @@ async function preresolveResourceConsts(ctx: ResolveCtx): Promise<Map<ts.Express
     try {
       const spec = foldResource(initializer, ctx.consts, ctx.intrinsics, ctx.externals);
       const instance = await constructFoldedResource(spec, ctx, false);
+      stampParamDependencies(instance, initializer, ctx);
       built.set(initializer, instance);
       ctx.externals.set(name, instance);
     } catch {
@@ -2933,6 +3059,7 @@ async function resolveResourceEntity(
 
   try {
     const entity = (await instantiateFoldedResource(spec.__resource, ctorArgs, ctx, ` for "${name}"`)) as Declarable;
+    stampParamDependencies(entity, node, ctx);
     return { ok: true, entity };
   } catch (err) {
     return { ok: false, reason: err instanceof Error ? err.message : String(err) };
@@ -3552,22 +3679,21 @@ export async function tryFoldFile(
  * so the exact same forced-taint safety net still applies to that remaining
  * boundary, unchanged.
  */
-export async function planFoldTaint(
-  files: readonly string[],
-  wouldFold: ReadonlyMap<string, boolean>,
-  liveSources?: ReadonlyMap<string, ReadonlySet<string>>,
-): Promise<Set<string>> {
+/**
+ * file -> set of OTHER files in `files` that it relatively imports OR
+ * re-exports from, regardless of that file's own fold outcome. Extracted
+ * from {@link planFoldTaint} (chant #1083) so a second consumer — the fold
+ * blocker dominator ranking (`./fold-rank.ts`) — can walk the exact same
+ * project-file edges instead of re-parsing every file with its own
+ * specifier-resolution logic. chant #1020 — this counts a namespace import
+ * (`import * as ns from "./x"`, previously skipped — see `collectImports`)
+ * and a re-export (`export { x } from "./y"`, which `collectImports` never
+ * saw at all, since it only looks at `import` declarations): both are real
+ * cross-file value dependencies fold's own resolution follows, so both need
+ * the same edge an ordinary named import already gets.
+ */
+export async function buildProjectImportEdges(files: readonly string[]): Promise<Map<string, Set<string>>> {
   const fileSet = new Set(files);
-
-  // file -> set of OTHER discovered files it relatively imports OR re-exports
-  // from, regardless of that file's own fold outcome (taint needs the full
-  // edge set to propagate transitively). chant #1020 — this now ALSO counts
-  // a namespace import (`import * as ns from "./x"`, previously skipped —
-  // see `collectImports`) and a re-export (`export { x } from "./y"`, which
-  // `collectImports` never saw at all, since it only looks at `import`
-  // declarations): both are real cross-file value dependencies my own new
-  // resolution follows, so both need the same identity guarantee an
-  // ordinary named import already got.
   const edges = new Map<string, Set<string>>();
   for (const file of files) {
     const targets = new Set<string>();
@@ -3600,10 +3726,24 @@ export async function planFoldTaint(
     } catch {
       // Unreadable/unparseable — no edges contributed; tryFoldFile's own
       // top-level catch already turns this into a "run" decision for the
-      // file itself, which is enough to seed it as tainted below.
+      // file itself, which is enough to seed it as tainted below (or, for
+      // the dominator ranking, leaves it a childless node).
     }
     edges.set(file, targets);
   }
+  return edges;
+}
+
+export async function planFoldTaint(
+  files: readonly string[],
+  wouldFold: ReadonlyMap<string, boolean>,
+  liveSources?: ReadonlyMap<string, ReadonlySet<string>>,
+): Promise<Set<string>> {
+  const fileSet = new Set(files);
+
+  // file -> set of OTHER discovered files it relatively imports OR re-exports
+  // from — see {@link buildProjectImportEdges}.
+  const edges = await buildProjectImportEdges(files);
 
   // chant #1044 — reverse edges: consumed-file -> the folded files that
   // captured its objects. Same taint set, same fixpoint walk; see this

package/src/discovery/fold-rank.test.ts

@@ -0,0 +1,197 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, writeFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { rankFoldBlockers, toCollapsedFormat } from "./fold-rank";
+import type { FoldDecision } from "./index";
+
+describe("rankFoldBlockers", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-fold-rank-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  function run(file: string, reason = "unresolved identifier"): FoldDecision {
+    return { file, mode: "run", reason };
+  }
+  function folded(file: string): FoldDecision {
+    return { file, mode: "fold", resourceCount: 1 };
+  }
+  function reverseTaintedDecision(file: string, reason: string): FoldDecision {
+    return { file, mode: "run", reason, reverseTainted: true };
+  }
+
+  test("a chain — one root-cause blocker retains every file behind it", async () => {
+    // a.ts <- b.ts <- c.ts (b imports a, c imports b); all three fall back to run.
+    const a = join(testDir, "a.ts");
+    const b = join(testDir, "b.ts");
+    const c = join(testDir, "c.ts");
+    await writeFile(a, `export const a = process.env.X;`);
+    await writeFile(b, `import { a } from "./a";\nexport const b = a;`);
+    await writeFile(c, `import { b } from "./b";\nexport const c = b;`);
+
+    const result = await rankFoldBlockers([run(a), run(b), run(c)]);
+
+    expect(result.totalBlocked).toBe(3);
+    const byFile = new Map(result.blockers.map((x) => [x.file, x]));
+    expect(byFile.get(a)).toMatchObject({ retained: 3, topLevel: true });
+    expect(byFile.get(b)).toMatchObject({ retained: 2, topLevel: false, dominatedBy: a });
+    expect(byFile.get(c)).toMatchObject({ retained: 1, topLevel: false, dominatedBy: b });
+
+    // Ranked descending by retained count — the root cause comes first.
+    expect(result.blockers.map((x) => x.file)).toEqual([a, b, c]);
+  });
+
+  test("a diamond — a single root cause reached two ways is not double-counted", async () => {
+    // root.ts <- {left.ts, right.ts} <- both.ts (both.ts imports BOTH left and right).
+    const root = join(testDir, "root.ts");
+    const left = join(testDir, "left.ts");
+    const right = join(testDir, "right.ts");
+    const both = join(testDir, "both.ts");
+    await writeFile(root, `export const root = process.env.X;`);
+    await writeFile(left, `import { root } from "./root";\nexport const left = root;`);
+    await writeFile(right, `import { root } from "./root";\nexport const right = root;`);
+    await writeFile(
+      both,
+      `import { left } from "./left";\nimport { right } from "./right";\nexport const both = left + right;`,
+    );
+
+    const result = await rankFoldBlockers([run(root), run(left), run(right), run(both)]);
+
+    expect(result.totalBlocked).toBe(4);
+    const rootBlocker = result.blockers.find((x) => x.file === root)!;
+    // root retains ALL FOUR files — left, right, and "both" reached via
+    // either path — not eight (double-counted through the diamond).
+    expect(rootBlocker.retained).toBe(4);
+    expect(rootBlocker.topLevel).toBe(true);
+
+    const bothBlocker = result.blockers.find((x) => x.file === both)!;
+    expect(bothBlocker.retained).toBe(1);
+
+    // Conservation: top-level blockers' retained counts sum to totalBlocked.
+    const topLevelSum = result.blockers.filter((x) => x.topLevel).reduce((s, x) => s + x.retained, 0);
+    expect(topLevelSum).toBe(result.totalBlocked);
+  });
+
+  test("two independent blockers — a shared dependent is not credited to either", async () => {
+    // x.ts and y.ts fail independently (no relation to each other).
+    // both.ts imports both, and needs BOTH fixed to fold — so it is its
+    // own top-level entry, inflating neither x's nor y's retained count.
+    const x = join(testDir, "x.ts");
+    const y = join(testDir, "y.ts");
+    const both = join(testDir, "both.ts");
+    await writeFile(x, `export const x = process.env.X;`);
+    await writeFile(y, `export const y = process.env.Y;`);
+    await writeFile(both, `import { x } from "./x";\nimport { y } from "./y";\nexport const both = x + y;`);
+
+    const result = await rankFoldBlockers([run(x), run(y), run(both)]);
+
+    expect(result.totalBlocked).toBe(3);
+    const byFile = new Map(result.blockers.map((b) => [b.file, b]));
+    expect(byFile.get(x)).toMatchObject({ retained: 1, topLevel: true });
+    expect(byFile.get(y)).toMatchObject({ retained: 1, topLevel: true });
+    // "both" is dominated by neither x nor y alone — it becomes its own
+    // top-level entry rather than inflating either blocker.
+    expect(byFile.get(both)).toMatchObject({ retained: 1, topLevel: true });
+
+    const topLevelSum = result.blockers.filter((b) => b.topLevel).reduce((s, b) => s + b.retained, 0);
+    expect(topLevelSum).toBe(3);
+  });
+
+  test("a reverse-tainted file is reported separately and never enters the tree", async () => {
+    const blocker = join(testDir, "blocker.ts");
+    const wouldFold = join(testDir, "would-fold.ts");
+    await writeFile(blocker, `import { p } from "./would-fold";\nexport const b = p + process.env.X;`);
+    await writeFile(wouldFold, `export const p = "fine";`);
+
+    const decisions: FoldDecision[] = [
+      run(blocker),
+      reverseTaintedDecision(
+        wouldFold,
+        "would fold in isolation, but a file that imports it (directly or transitively) falls back to run — folding independently would create a duplicate, non-identical instance",
+      ),
+    ];
+
+    const result = await rankFoldBlockers(decisions);
+
+    expect(result.totalBlocked).toBe(1);
+    expect(result.blockers.map((b) => b.file)).toEqual([blocker]);
+    expect(result.reverseTainted).toEqual([
+      {
+        file: wouldFold,
+        reason:
+          "would fold in isolation, but a file that imports it (directly or transitively) falls back to run — folding independently would create a duplicate, non-identical instance",
+      },
+    ]);
+  });
+
+  test("fold-mode files are excluded from the tree entirely", async () => {
+    const okFile = join(testDir, "ok.ts");
+    const badFile = join(testDir, "bad.ts");
+    await writeFile(okFile, `export const ok = 1;`);
+    await writeFile(badFile, `export const bad = process.env.X;`);
+
+    const result = await rankFoldBlockers([folded(okFile), run(badFile)]);
+
+    expect(result.totalBlocked).toBe(1);
+    expect(result.blockers.map((b) => b.file)).toEqual([badFile]);
+  });
+
+  test("retained counts are conserved across a mixed graph (chain + independent leaf)", async () => {
+    const a = join(testDir, "a.ts");
+    const b = join(testDir, "b.ts");
+    const leaf = join(testDir, "leaf.ts");
+    await writeFile(a, `export const a = process.env.X;`);
+    await writeFile(b, `import { a } from "./a";\nexport const b = a;`);
+    await writeFile(leaf, `export const leaf = process.env.Y;`); // unrelated second root cause
+
+    const result = await rankFoldBlockers([run(a), run(b), run(leaf)]);
+
+    expect(result.totalBlocked).toBe(3);
+    const topLevelSum = result.blockers.filter((x) => x.topLevel).reduce((s, x) => s + x.retained, 0);
+    expect(topLevelSum).toBe(3);
+    // a.ts ranks ahead of leaf.ts (retains 2 vs 1) — sorted descending.
+    expect(result.blockers[0].file).toBe(a);
+    expect(result.blockers[0].retained).toBe(2);
+  });
+});
+
+describe("toCollapsedFormat", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-fold-rank-collapsed-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("emits one weighted line per file, folding to retained counts under a shared root frame", async () => {
+    const a = join(testDir, "a.ts");
+    const b = join(testDir, "b.ts");
+    await writeFile(a, `export const a = process.env.X;`);
+    await writeFile(b, `import { a } from "./a";\nexport const b = a;`);
+
+    const result = await rankFoldBlockers([
+      { file: a, mode: "run", reason: "r" },
+      { file: b, mode: "run", reason: "r" },
+    ]);
+    const lines = toCollapsedFormat(result, { relativeTo: testDir });
+
+    expect(lines.sort()).toEqual(["fold;a.ts 1", "fold;a.ts;b.ts 1"].sort());
+
+    // Every line for a's own subtree (its own line, plus every line whose
+    // stack is prefixed by it) sums to a's retained count.
+    const aPrefixCount = lines.filter((l) => l.startsWith("fold;a.ts")).length;
+    const aBlocker = result.blockers.find((x) => x.file === a)!;
+    expect(aPrefixCount).toBe(aBlocker.retained);
+  });
+});