@intentius/chant 0.46.0 → 0.50.0

package/src/discovery/fold-rank.ts

@@ -0,0 +1,346 @@
+import { relative } from "node:path";
+import { buildProjectImportEdges } from "./fold-import";
+import type { FoldDecision } from "./index";
+
+/**
+ * chant #1083 — rank fold blockers by dominator retained-count over the
+ * import graph discovery already builds.
+ *
+ * ## Why dominators, not a flat "files downstream of X" count
+ *
+ * The import graph is a DAG (occasionally cyclic, when project source
+ * itself has an import cycle), not a tree: a file can be reachable through
+ * several paths, so naively summing "files that import X, transitively"
+ * double-counts every diamond and the totals stop meaning anything. The
+ * fix is the same one heap snapshot tools use for object retained sizes
+ * (Cooper–Harvey–Kennedy immediate dominators, prior art: spicypath's
+ * `src/heap-dominators.js`, cited on chant #1083): file `d` dominates file
+ * `n` when every causal path to `n`'s failure passes through `d`. A file's
+ * retained count is then the size of its dominator subtree — the number of
+ * files that would fold if `d` folded — and every node lands in exactly one
+ * dominator subtree, so retained counts are conserved: they sum to the
+ * total across the tree's top-level blockers, with nothing counted twice
+ * through a diamond, and a file with two INDEPENDENT blockers (no common
+ * ancestor besides the synthetic root) inflates neither.
+ *
+ * ## One direction only
+ *
+ * This models FORWARD contagion only: file `n` fails to fold because one of
+ * its own imports, `d`, also fails — an unresolved cross-file reference.
+ * The edge direction for dominance purposes is therefore `d -> n` (the
+ * blocker points at what it blocks), which is the REVERSE of the literal
+ * import edge `n -> d` (n imports d).
+ *
+ * Fold has a second, opposite-direction rule (chant #1044, implemented in
+ * {@link import("./fold-import").planFoldTaint}): a file that WOULD fold
+ * fine in isolation is forced back to run anyway because some file that
+ * imports it (directly or transitively) itself runs — folding it
+ * independently would create a second, non-identical instance. That is
+ * contagion from importER to importEE, the opposite of the direction this
+ * tree models, and a dominator tree over import edges cannot express it: a
+ * fix to the "blocker" here wouldn't actually unblock the reverse-tainted
+ * file (it was never broken on its own terms), so crediting it would
+ * overstate the fix's blast radius. Every file discovery marked
+ * {@link FoldDecision.reverseTainted} is therefore excluded from the tree
+ * entirely and reported in {@link FoldRankResult.reverseTainted} instead —
+ * see chant #1083's re-scope comment.
+ */
+
+/** Sentinel "file path" for the synthetic dominator-tree root. Never a real file — file paths never contain NUL. */
+const ROOT = "\0chant-fold-rank-root\0";
+
+/** One node in the forward-contagion dominator tree — a `"run"`, non-reverse-tainted file. */
+export interface FoldBlocker {
+  /** Absolute source file path (matches {@link FoldDecision.file}). */
+  file: string;
+  /** Why THIS file itself falls back to run (its own {@link FoldDecision.reason}). */
+  reason?: string;
+  /**
+   * Number of files — including this one — that would fold if this file's
+   * own fold problem were fixed: this node's dominator-subtree size.
+   * Conserved: summing this field over every blocker with no closer
+   * dominator ({@link topLevel}) equals {@link FoldRankResult.totalBlocked}.
+   */
+  retained: number;
+  /** True when nothing else in the tree dominates this file more closely than the synthetic root — i.e. this file's own fold failure isn't explained by importing another blocker already in the tree. */
+  topLevel: boolean;
+  /** This file's immediate dominator's file path, or `undefined` for a {@link topLevel} blocker. */
+  dominatedBy?: string;
+}
+
+/** A `"run"` file held back only by the chant #1044 reverse rule — never part of the forward dominator tree (see this module's doc). */
+export interface FoldReverseTaintedFile {
+  file: string;
+  reason?: string;
+}
+
+export interface FoldRankResult {
+  /**
+   * Every forward-contagion blocker (a `"run"`, non-reverse-tainted file),
+   * sorted by {@link FoldBlocker.retained} descending, ties broken by file
+   * path for determinism. Includes every node in the tree, not just
+   * top-level ones — an intermediate hub file (e.g. a `params.ts` many
+   * others funnel through) is itself a meaningful blocker to rank.
+   */
+  blockers: FoldBlocker[];
+  /** `"run"` files excluded from the tree by the reverse rule (chant #1044) — see this module's doc. */
+  reverseTainted: FoldReverseTaintedFile[];
+  /** Total forward-blocked files considered ({@link blockers}.length). Top-level blockers' retained counts sum to exactly this. */
+  totalBlocked: number;
+}
+
+/**
+ * Compute immediate dominators for `nodes` over `edges` (blocker -> blocked,
+ * i.e. flowing in the CAUSAL direction, not the import direction), rooted at
+ * a synthetic {@link ROOT}. Handles a cyclic/irreducible graph correctly —
+ * Cooper–Harvey–Kennedy's iterative algorithm converges on any graph, not
+ * just reducible ones (this is exactly why it's the right tool here: an
+ * import graph can have cycles).
+ *
+ * `rootChildren` must already guarantee every node in `nodes` is reachable
+ * from {@link ROOT} via `rootChildren` + `edges` — see `rankFoldBlockers`'s
+ * two-phase root-selection below.
+ */
+function computeImmediateDominators(
+  nodes: readonly string[],
+  edges: ReadonlyMap<string, ReadonlySet<string>>,
+  rootChildren: ReadonlySet<string>,
+): Map<string, string> {
+  const succ = (n: string): ReadonlySet<string> => (n === ROOT ? rootChildren : edges.get(n) ?? new Set());
+
+  // Predecessors, including the synthetic ROOT edge into every root child.
+  const preds = new Map<string, Set<string>>();
+  for (const n of nodes) preds.set(n, new Set());
+  for (const [from, targets] of edges) {
+    for (const to of targets) {
+      if (!preds.has(to)) preds.set(to, new Set());
+      preds.get(to)!.add(from);
+    }
+  }
+  for (const rc of rootChildren) preds.get(rc)?.add(ROOT);
+
+  // Reverse-postorder numbering via one DFS from ROOT — every node in
+  // `nodes` must be reached (guaranteed by the caller's root selection).
+  const postorderNumber = new Map<string, number>();
+  const visited = new Set<string>([ROOT]);
+  let counter = 0;
+  const visitStack: Array<{ node: string; iter: Iterator<string> }> = [
+    { node: ROOT, iter: succ(ROOT).values() },
+  ];
+  while (visitStack.length > 0) {
+    const top = visitStack[visitStack.length - 1];
+    const next = top.iter.next();
+    if (next.done) {
+      postorderNumber.set(top.node, counter++);
+      visitStack.pop();
+      continue;
+    }
+    const child = next.value;
+    if (!visited.has(child)) {
+      visited.add(child);
+      visitStack.push({ node: child, iter: succ(child).values() });
+    }
+  }
+
+  const rpo = [...nodes, ROOT].filter((n) => postorderNumber.has(n));
+  rpo.sort((a, b) => postorderNumber.get(b)! - postorderNumber.get(a)!); // reverse postorder: highest number first
+
+  const idom = new Map<string, string>();
+  idom.set(ROOT, ROOT);
+
+  const intersect = (a: string, b: string): string => {
+    let finger1 = a;
+    let finger2 = b;
+    while (finger1 !== finger2) {
+      while (postorderNumber.get(finger1)! < postorderNumber.get(finger2)!) finger1 = idom.get(finger1)!;
+      while (postorderNumber.get(finger2)! < postorderNumber.get(finger1)!) finger2 = idom.get(finger2)!;
+    }
+    return finger1;
+  };
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const node of rpo) {
+      if (node === ROOT) continue;
+      let newIdom: string | undefined;
+      for (const p of preds.get(node) ?? []) {
+        if (!idom.has(p)) continue; // not yet processed this pass
+        newIdom = newIdom === undefined ? p : intersect(newIdom, p);
+      }
+      if (newIdom !== undefined && idom.get(node) !== newIdom) {
+        idom.set(node, newIdom);
+        changed = true;
+      }
+    }
+  }
+
+  idom.delete(ROOT);
+  return idom;
+}
+
+/**
+ * Rank fold blockers by dominator retained-count over the (forward-only)
+ * import graph among this build's `"run"`-mode files. See this module's doc
+ * for the model. `decisions` is expected to be a `--fold` build's complete
+ * {@link FoldDecision}[] — every discovered file, fold or run.
+ */
+export async function rankFoldBlockers(decisions: readonly FoldDecision[]): Promise<FoldRankResult> {
+  const allFiles = decisions.map((d) => d.file);
+  const reverseTainted = decisions
+    .filter((d) => d.mode === "run" && d.reverseTainted === true)
+    .map((d) => ({ file: d.file, reason: d.reason }))
+    .sort((a, b) => a.file.localeCompare(b.file));
+
+  const nodeDecisions = decisions.filter((d) => d.mode === "run" && d.reverseTainted !== true);
+  const reasonByFile = new Map(nodeDecisions.map((d) => [d.file, d.reason] as const));
+  const nodes = nodeDecisions.map((d) => d.file).sort((a, b) => a.localeCompare(b));
+  const nodeSet = new Set(nodes);
+
+  // file -> the OTHER discovered files it imports (real import direction).
+  const importEdges = await buildProjectImportEdges(allFiles);
+
+  // Cause graph, blocker -> blocked: importee -> importer, restricted to
+  // both endpoints being forward-tree nodes (a fold-mode or reverse-tainted
+  // file is neither a blocker nor blocked in this tree).
+  const causeEdges = new Map<string, Set<string>>();
+  for (const n of nodes) causeEdges.set(n, new Set());
+  for (const [importer, targets] of importEdges) {
+    if (!nodeSet.has(importer)) continue;
+    for (const target of targets) {
+      if (!nodeSet.has(target)) continue;
+      causeEdges.get(target)!.add(importer);
+    }
+  }
+
+  // Predecessor count, to find true root causes (a blocked file that is
+  // itself never blocked by another tree node).
+  const predCount = new Map<string, number>();
+  for (const n of nodes) predCount.set(n, 0);
+  for (const targets of causeEdges.values()) {
+    for (const t of targets) predCount.set(t, (predCount.get(t) ?? 0) + 1);
+  }
+
+  // Two-phase root selection, so every node is reachable from ROOT even
+  // across an import cycle with no external entry point (chant #1083's doc
+  // cites spicypath's dominators working over a graph that is "cyclic and
+  // irreducible" as the precedent this needs to match).
+  const rootChildren = new Set<string>();
+  const reached = new Set<string>();
+  const expandFrom = (start: string): void => {
+    if (reached.has(start)) return;
+    const stack = [start];
+    reached.add(start);
+    while (stack.length > 0) {
+      const cur = stack.pop()!;
+      for (const next of causeEdges.get(cur) ?? []) {
+        if (!reached.has(next)) {
+          reached.add(next);
+          stack.push(next);
+        }
+      }
+    }
+  };
+  for (const n of nodes) {
+    if (predCount.get(n) === 0) {
+      rootChildren.add(n);
+      expandFrom(n);
+    }
+  }
+  for (const n of nodes) {
+    if (!reached.has(n)) {
+      rootChildren.add(n);
+      expandFrom(n);
+    }
+  }
+
+  const idom = computeImmediateDominators(nodes, causeEdges, rootChildren);
+
+  // Dominator-tree children, to compute retained (subtree size) bottom-up.
+  const domChildren = new Map<string, string[]>();
+  for (const n of nodes) domChildren.set(n, []);
+  for (const [n, parent] of idom) {
+    if (parent !== ROOT) domChildren.get(parent)!.push(n);
+  }
+
+  const retained = new Map<string, number>();
+  const computeRetained = (n: string): number => {
+    const cached = retained.get(n);
+    if (cached !== undefined) return cached;
+    let size = 1;
+    for (const child of domChildren.get(n) ?? []) size += computeRetained(child);
+    retained.set(n, size);
+    return size;
+  };
+  for (const n of nodes) computeRetained(n);
+
+  const blockers: FoldBlocker[] = nodes.map((file) => {
+    const parent = idom.get(file);
+    const topLevel = parent === undefined || parent === ROOT;
+    return {
+      file,
+      reason: reasonByFile.get(file),
+      retained: retained.get(file)!,
+      topLevel,
+      dominatedBy: topLevel ? undefined : parent,
+    };
+  });
+  blockers.sort((a, b) => b.retained - a.retained || a.file.localeCompare(b.file));
+
+  return { blockers, reverseTainted, totalBlocked: nodes.length };
+}
+
+/** `file -> dominatedBy` lookup built from a {@link FoldRankResult}, for reconstructing a blocker's dominator-chain (used by {@link toCollapsedFormat}). */
+function dominatorChain(result: FoldRankResult, file: string): string[] {
+  const dominatedByFile = new Map(result.blockers.map((b) => [b.file, b.dominatedBy] as const));
+  const chain: string[] = [file];
+  let current: string | undefined = file;
+  const guard = new Set<string>([file]);
+  for (;;) {
+    const parent = dominatedByFile.get(current!);
+    if (parent === undefined) break;
+    if (guard.has(parent)) break; // defensive: never trust a cycle in the tree itself
+    chain.push(parent);
+    guard.add(parent);
+    current = parent;
+  }
+  return chain.reverse(); // top-level ancestor first, `file` last
+}
+
+/** A collapsed-format frame may not contain `;` (the frame separator) or a newline; sanitize rather than silently mis-render. */
+function sanitizeFrame(label: string): string {
+  return label.replace(/[\n\r]/g, " ").replace(/;/g, ",");
+}
+
+/**
+ * Export the dominator tree in Brendan Gregg collapsed stack format
+ * (`frame;frame;...;frame count`), weighted by retained count, so it opens
+ * in any flame or icicle graph viewer with no chant-specific tooling (the
+ * seam is the file format, per chant #1083's original scope).
+ *
+ * One line per blocker, `count` always `1`: each file's stack is the chain
+ * of dominators from the top-level blocker down to itself. Folding
+ * identical prefixes — what every collapsed-format consumer does — then
+ * reproduces each blocker's retained count as that prefix's total weight,
+ * with nothing double-counted through a diamond. `rootLabel` is a single
+ * synthetic top frame (default `"fold"`) so every top-level blocker renders
+ * under one shared root instead of the viewer showing several disconnected
+ * trees; pass `relativeTo` (typically the build's infra path) to shorten
+ * frame labels to project-relative paths.
+ */
+export function toCollapsedFormat(
+  result: FoldRankResult,
+  options?: { rootLabel?: string; relativeTo?: string },
+): string[] {
+  const rootLabel = options?.rootLabel ?? "fold";
+  const toLabel = (file: string): string =>
+    sanitizeFrame(options?.relativeTo ? relative(options.relativeTo, file) || file : file);
+
+  return result.blockers
+    .slice()
+    .sort((a, b) => a.file.localeCompare(b.file))
+    .map((blocker) => {
+      const chain = dominatorChain(result, blocker.file).map(toLabel);
+      return `${sanitizeFrame(rootLabel)};${chain.join(";")} 1`;
+    });
+}

package/src/discovery/index.ts

@@ -85,6 +85,21 @@ export interface FoldDecision {
   reason?: string;
   /** Number of entities the fold produced. Present only when `mode === "fold"`. */
   resourceCount?: number;
+  /**
+   * chant #1083 — true when this file's OWN fold attempt succeeded (it would
+   * fold cleanly in isolation) but it was forced to `"run"` anyway by
+   * {@link planFoldTaint}'s REVERSE rule (chant #1044): some other file that
+   * imports it, directly or transitively, itself falls back to run, so
+   * folding this one independently would create a duplicate, non-identical
+   * instance. Present only when `mode === "run"`.
+   *
+   * The fold-blocker dominator ranking (`./fold-rank.ts`) keys on this: a
+   * reverse-tainted file is not a forward-contagion blocker (fixing it
+   * unblocks nothing — it was never the cause), and the tree can't express
+   * the edge that DOES hold it back (an importer, not something it imports).
+   * It's reported in a separate bucket instead of a dominator subtree.
+   */
+  reverseTainted?: boolean;
 }
 
 /**
@@ -295,7 +310,7 @@ export async function discover(path: string, options?: DiscoveryOptions): Promis
       const reason = !folded.ok
         ? folded.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`;
-      foldDecisions.push({ file, mode: "run", reason });
+      foldDecisions.push({ file, mode: "run", reason, reverseTainted: folded.ok });
     }
 
     if (options?.sandbox) {

package/src/discovery/param-deps.test.ts

@@ -0,0 +1,118 @@
+import * as ts from "typescript";
+import { describe, expect, test } from "vitest";
+import { collectConsts } from "../fold/fold";
+import { collectParamDependencies } from "./param-deps";
+import type { PathOrigin } from "../provenance";
+
+/**
+ * Collect dependencies for the props of the file's single
+ * `export const x = new Type({...})`, which is the shape every case here uses.
+ */
+function depsOf(source: string, paramLocals = ["params"]): Record<string, PathOrigin> {
+  const file = ts.createSourceFile("fixture.ts", source, ts.ScriptTarget.Latest, true);
+  const consts = collectConsts(file);
+  let props: ts.ObjectLiteralExpression | undefined;
+  for (const statement of file.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    for (const decl of statement.declarationList.declarations) {
+      if (decl.name.getText() !== "x" || !decl.initializer) continue;
+      if (!ts.isNewExpression(decl.initializer)) continue;
+      for (const argument of decl.initializer.arguments ?? []) {
+        if (ts.isObjectLiteralExpression(argument)) {
+          props = argument;
+          break;
+        }
+      }
+    }
+  }
+  if (!props) throw new Error("fixture has no `const x = new Type({...})`");
+  return collectParamDependencies(props, consts, new Set(paramLocals));
+}
+
+const param = (...names: string[]): PathOrigin => ({ kind: "build-param", params: names });
+
+describe("collectParamDependencies", () => {
+  test("a direct read is attributed to its own path", () => {
+    expect(depsOf(`export const x = new Thing({ replicas: params.replicas, name: "fixed" });`)).toEqual({
+      replicas: param("replicas"),
+    });
+  });
+
+  test("nested object literals are descended into, dotted", () => {
+    const source = `export const x = new Thing({ spec: { template: { image: params.image } } });`;
+    expect(depsOf(source)).toEqual({ "spec.template.image": param("image") });
+  });
+
+  test("an expression is attributed to every parameter it can read, not to its value", () => {
+    const source = `export const x = new Thing({ replicas: params.tier === "prod" ? params.big : 1 });`;
+    expect(depsOf(source)).toEqual({ replicas: param("big", "tier") });
+  });
+
+  test("a parameter hoisted into a const is followed to the field that uses it", () => {
+    const source = [
+      `const replicas = params.tier === "prod" ? 5 : 1;`,
+      `export const x = new Thing({ replicas });`,
+    ].join("\n");
+    expect(depsOf(source)).toEqual({ replicas: param("tier") });
+  });
+
+  test("const chains are followed transitively, and a cycle terminates", () => {
+    const source = [
+      `const a = b;`,
+      `const b = \`\${params.region}-\${a}\`;`,
+      `export const x = new Thing({ zone: a });`,
+    ].join("\n");
+    expect(depsOf(source)).toEqual({ zone: param("region") });
+  });
+
+  test("template literals and calls are walked", () => {
+    const source = `export const x = new Thing({ bucket: \`\${params.env}-assets\`.toLowerCase() });`;
+    expect(depsOf(source)).toEqual({ bucket: param("env") });
+  });
+
+  test("an array is attributed whole, never per index", () => {
+    const source = `export const x = new Thing({ containers: [{ image: params.image }, { image: "sidecar" }] });`;
+    expect(depsOf(source)).toEqual({ containers: param("image") });
+  });
+
+  test("a spread is attributed to the object it spreads into", () => {
+    const source = [
+      `const base = { region: params.region };`,
+      `export const x = new Thing({ ...base, spec: { ...base, replicas: 1 } });`,
+    ].join("\n");
+    expect(depsOf(source)).toEqual({ "": param("region"), spec: param("region") });
+  });
+
+  test("bracket access with a literal key names the parameter", () => {
+    expect(depsOf(`export const x = new Thing({ zone: params["region"] });`)).toEqual({ zone: param("region") });
+  });
+
+  test("a property KEY that happens to match a const is not a reference", () => {
+    const source = [`const tier = params.tier;`, `export const x = new Thing({ spec: { tier: "fixed" } });`].join("\n");
+    expect(depsOf(source)).toEqual({});
+  });
+
+  test("a bare reference to the whole params object records nothing", () => {
+    // It names no single parameter; under-reporting is the safe direction.
+    expect(depsOf(`export const x = new Thing({ all: params });`)).toEqual({});
+  });
+
+  test("a file that never imported params records nothing", () => {
+    expect(depsOf(`export const x = new Thing({ replicas: params.replicas });`, [])).toEqual({});
+  });
+
+  test("the local name the import bound is what counts, not the word 'params'", () => {
+    const source = `export const x = new Thing({ replicas: p.replicas, other: params.replicas });`;
+    expect(depsOf(source, ["p"])).toEqual({ replicas: param("replicas") });
+  });
+
+  test("parameter names are sorted and de-duplicated", () => {
+    const source = `export const x = new Thing({ n: params.z + params.a + params.z });`;
+    expect(depsOf(source)).toEqual({ n: param("a", "z") });
+  });
+
+  test("a computed key is skipped rather than guessed at", () => {
+    const source = `export const x = new Thing({ [params.key]: 1, name: params.name });`;
+    expect(depsOf(source)).toEqual({ name: param("name") });
+  });
+});

package/src/discovery/param-deps.ts

@@ -0,0 +1,170 @@
+import * as ts from "typescript";
+import type { PathOrigin } from "../provenance";
+
+/**
+ * Which build parameters an authored props expression READS, per path (chant
+ * #1443) — the declared-side counterpart of `managed-fields.ts`'s per-path live
+ * `owners`.
+ *
+ * This is a syntactic dependency, not a value taint. Fold substitutes
+ * `params.<name>` before anything is emitted, so by output time the value is a
+ * literal and indistinguishable from one typed by hand; tainting the value
+ * through fold's evaluator would mean propagating a tag through every operator
+ * it supports, and one operator that forgot would produce silently wrong
+ * provenance. Recording which parameters the *expression* mentions cannot
+ * degrade that way: a shape this walk does not follow drops a dependency, it
+ * never invents one.
+ *
+ * It also answers the more useful question. For
+ * `replicas: params.tier === "prod" ? 5 : 1`, a taint reports that the value
+ * came from the literal `5` — true, and no help to anyone about to edit the
+ * field. The dependency reports that the field is governed by `tier`.
+ *
+ * Known under-reporting, all in the safe direction: destructured parameters
+ * (`const { tier } = params`) are not tracked, because `collectConsts` only
+ * records identifier bindings; a bare reference to the whole `params` object
+ * names no single parameter and records nothing; and the run path has no
+ * expression to walk at all.
+ *
+ * The one direction it can over-report is a local binding that shadows a
+ * top-level `const` of the same name, since names resolve against the file's
+ * consts without scope tracking. That reports a parameter the field could
+ * plausibly be governed by rather than one it definitely is, which is the
+ * failure the "could affect" reading is written to absorb.
+ */
+
+/** The property name a member declares, when it is a literal one. */
+function literalName(name: ts.PropertyName | undefined): string | undefined {
+  if (!name) return undefined;
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) return name.text;
+  return undefined;
+}
+
+/** Strip the wrappers that do not change what an initializer reads. */
+function unwrap(expr: ts.Expression): ts.Expression {
+  let current = expr;
+  for (;;) {
+    if (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isNonNullExpression(current)) {
+      current = current.expression;
+      continue;
+    }
+    return current;
+  }
+}
+
+/**
+ * Every parameter name `expr` reads, following this file's own top-level
+ * `const` bindings so a value hoisted into a local is still attributed
+ * (`const replicas = params.tier === "prod" ? 5 : 1` used as `replicas`).
+ */
+function readParams(
+  expr: ts.Expression,
+  consts: ReadonlyMap<string, ts.Expression>,
+  paramLocals: ReadonlySet<string>,
+  out: Set<string>,
+): void {
+  const followed = new Set<string>();
+
+  const visit = (node: ts.Node): void => {
+    if (ts.isPropertyAccessExpression(node)) {
+      if (ts.isIdentifier(node.expression) && paramLocals.has(node.expression.text)) {
+        out.add(node.name.text);
+        return;
+      }
+      visit(node.expression);
+      return;
+    }
+
+    if (ts.isElementAccessExpression(node)) {
+      if (ts.isIdentifier(node.expression) && paramLocals.has(node.expression.text)) {
+        if (ts.isStringLiteralLike(node.argumentExpression)) out.add(node.argumentExpression.text);
+      } else {
+        visit(node.expression);
+      }
+      visit(node.argumentExpression);
+      return;
+    }
+
+    if (ts.isIdentifier(node)) {
+      // A bare `params` names no single parameter — see the under-reporting
+      // note above.
+      if (paramLocals.has(node.text)) return;
+      const initializer = consts.get(node.text);
+      if (initializer && !followed.has(node.text)) {
+        followed.add(node.text);
+        visit(initializer);
+      }
+      return;
+    }
+
+    // A property KEY is not a reference; without this a nested `{ tier: 1 }`
+    // would resolve `tier` against `consts` and manufacture a dependency.
+    if (ts.isPropertyAssignment(node)) {
+      visit(node.initializer);
+      return;
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(expr);
+}
+
+/**
+ * Path → build-parameter origin for one resource's props object literal.
+ *
+ * Paths are dotted property names only, per `EntityProvenance.paths`: an object
+ * literal is descended into, and anything else — an array literal included — is
+ * attributed whole at its own path. An array's elements are deliberately not
+ * indexed, because an index-shaped key would not survive an element moving and
+ * would not match the `[#key]` addressing a diff uses.
+ *
+ * A spread is attributed to the object it spreads INTO, at that object's own
+ * path (the entity root for a top-level spread), since which keys it
+ * contributes is not knowable here.
+ */
+export function collectParamDependencies(
+  props: ts.ObjectLiteralExpression,
+  consts: ReadonlyMap<string, ts.Expression>,
+  paramLocals: ReadonlySet<string>,
+): Record<string, PathOrigin> {
+  const out: Record<string, PathOrigin> = {};
+  if (paramLocals.size === 0) return out;
+
+  const record = (path: string, expr: ts.Expression): void => {
+    const found = new Set<string>();
+    readParams(expr, consts, paramLocals, found);
+    if (found.size === 0) return;
+    const existing = out[path];
+    const merged =
+      existing && existing.kind === "build-param" ? new Set([...existing.params, ...found]) : found;
+    out[path] = { kind: "build-param", params: [...merged].sort() };
+  };
+
+  const walk = (object: ts.ObjectLiteralExpression, prefix: string): void => {
+    for (const member of object.properties) {
+      if (ts.isSpreadAssignment(member)) {
+        record(prefix, member.expression);
+        continue;
+      }
+      if (ts.isShorthandPropertyAssignment(member)) {
+        const key = member.name.text;
+        record(prefix ? `${prefix}.${key}` : key, member.name);
+        continue;
+      }
+      if (!ts.isPropertyAssignment(member)) continue;
+      const key = literalName(member.name);
+      if (key === undefined) continue;
+      const path = prefix ? `${prefix}.${key}` : key;
+      const initializer = unwrap(member.initializer);
+      if (ts.isObjectLiteralExpression(initializer)) {
+        walk(initializer, path);
+        continue;
+      }
+      record(path, member.initializer);
+    }
+  };
+
+  walk(props, "");
+  return out;
+}