@suss/extractor 0.33.1 → 0.34.0

package/dist/index.js

@@ -1,6 +1,7 @@
 // src/index.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import {
+  effectKey,
   exchangesHttpResponses as exchangesHttpResponses2,
   foldRepeatedEffects,
   normalizeCalleeText,
@@ -9,6 +10,7 @@ import {
   withMountMetadata,
   withRequestSpellingMetadata,
   withSourceDocumentMetadata,
+  withTestMetadata,
   withWrapperMetadata as withWrapperMetadata2
 } from "@suss/behavioral-ir";
 
@@ -281,6 +283,56 @@ function withDistinctIds(transitions) {
   });
 }
 
+// src/declaredModules.ts
+import fs from "fs";
+import path from "path";
+var MODULE_SURFACE_RECOGNITION = "modules";
+function settleModules(modules, candidates) {
+  return (modules ?? []).map((module) => ({
+    ...module,
+    public: module.public ?? candidates.map(
+      (one) => path.join(module.root, one.replace("{name}", module.name))
+    ).filter((file) => fs.existsSync(file))
+  }));
+}
+function isInside(file, root) {
+  const relative = path.relative(root, file);
+  return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function moduleOfFile(modules, file) {
+  const byPublicFile = modules.find((module) => module.public.includes(file));
+  if (byPublicFile !== void 0) {
+    return byPublicFile;
+  }
+  let deepest;
+  for (const module of modules) {
+    if (isInside(file, module.root) && (deepest === void 0 || module.root.length > deepest.root.length)) {
+      deepest = module;
+    }
+  }
+  return deepest;
+}
+function stampModules(summaries, modules, root) {
+  if (modules.length === 0) {
+    return;
+  }
+  for (const summary of summaries) {
+    const file = path.resolve(root ?? "", summary.location.file);
+    const module = moduleOfFile(modules, file);
+    if (module !== void 0) {
+      summary.location.module = module.name;
+    }
+  }
+}
+function modulesStamp(modules) {
+  if (modules === void 0 || modules.length === 0) {
+    return void 0;
+  }
+  return JSON.stringify(
+    modules.map((module) => [module.name, module.root, [...module.public]])
+  );
+}
+
 // src/effectGuards.ts
 var keyOf = (condition) => `${condition.polarity}:${condition.sourceText}`;
 var opposite = (condition) => `${condition.polarity === "positive" ? "negative" : "positive"}:${condition.sourceText}`;
@@ -297,6 +349,41 @@ function runsBefore(effectLine, terminalEndLine) {
   return effectLine <= terminalEndLine;
 }
 
+// src/exitCode.ts
+import path2 from "path";
+import { declarationKey } from "@suss/behavioral-ir";
+function markReturnsAsExitCode(summaries, returnsTheCode, workspaceRoot) {
+  for (const summary of summaries) {
+    const span = summary.location.span;
+    const file = workspaceRoot === void 0 ? summary.location.file : path2.resolve(workspaceRoot, summary.location.file);
+    markExitCodeFrom(
+      summary,
+      span !== void 0 && returnsTheCode.has(declarationKey(file, span))
+    );
+  }
+}
+function markExitCodeFrom(summary, marked) {
+  const process2 = summary.metadata?.process;
+  if (marked) {
+    summary.metadata = {
+      ...summary.metadata ?? {},
+      process: { ...process2 ?? {}, exitCodeFrom: "return" }
+    };
+    return;
+  }
+  if (process2 === void 0 || !("exitCodeFrom" in process2)) {
+    return;
+  }
+  const { exitCodeFrom: _dropped, ...rest } = process2;
+  const { process: _process, ...others } = summary.metadata ?? {};
+  const left = Object.keys(rest).length === 0 ? others : { ...others, process: rest };
+  if (Object.keys(left).length === 0) {
+    Reflect.deleteProperty(summary, "metadata");
+    return;
+  }
+  summary.metadata = left;
+}
+
 // src/moduleImports.ts
 function stampModuleImports(summaries, importsOf) {
   const byFile = /* @__PURE__ */ new Map();
@@ -373,8 +460,8 @@ function httpRouteDiscovery(opts) {
       registrationChain: [...opts.methods]
     },
     bindingExtraction: {
-      // `.all` registers every method, so it records "*", which the pairing
-      // engine treats as agreeing with any method at all.
+      // `.all` registers every method, so it records "*", which pairs with
+      // any method.
       method: {
         type: "fromRegistration",
         position: "methodName",
@@ -390,10 +477,9 @@ function httpRouteDiscovery(opts) {
   }
   return [
     ...calls,
-    // Routes registered in a loop over an array of specs, a shape
-    // registration-call discovery cannot see. The receiver comes from
-    // the same import declaration as the calls above, so a loop that
-    // never touches this library's routable is left alone.
+    // Routes registered in a loop over an array of specs, which the calls
+    // above cannot see. The receiver must come from the same import, so a
+    // loop that never touches this library's routable is left alone.
     {
       kind,
       match: {
@@ -540,7 +626,7 @@ var configuredCallOption = z.object({
   receiver: z.string(),
   /** Method that performs the send. */
   method: z.string(),
-  /** Argument index carrying the subject. */
+  /** Index of the argument that is the subject. */
   subjectArg: z.number(),
   /**
    * Which argument the message body is. Left out when the method has no
@@ -599,8 +685,8 @@ var catchEntryCond = () => fixedCond(
   "positive",
   "catchBlock"
 );
-function classify(path4, home, isAncestorOrSelf) {
-  return path4.map((cond) => {
+function classify(path6, home, isAncestorOrSelf) {
+  return path6.map((cond) => {
     if (cond.branchStmt === null) {
       return cond.info;
     }
@@ -665,9 +751,9 @@ function chargeBudget(state) {
     );
   }
 }
-function recordTerminal(ctx, terminal, home, path4) {
+function recordTerminal(ctx, terminal, home, path6) {
   chargeBudget(ctx.state);
-  const info = classify(path4, home, ctx.isAncestorOrSelf);
+  const info = classify(path6, home, ctx.isAncestorOrSelf);
   const existing = ctx.state.byTerminal.get(terminal) ?? [];
   existing.push(info);
   ctx.state.byTerminal.set(terminal, existing);
@@ -678,15 +764,15 @@ function containsTerminal(ctx, stmt) {
   }
   return childrenOf(stmt).some((child) => containsTerminal(ctx, child));
 }
-function stepIf(stmt, path4, ctx) {
+function stepIf(stmt, path6, ctx) {
   const thenExit = exitKindOfList(stmt.thenBody);
   const elseExit = stmt.elseBody === null ? null : exitKindOfList(stmt.elseBody);
   const thenPath = [
-    ...path4,
+    ...path6,
     branchCond(stmt, stmt.condition, "positive", elseExit)
   ];
   const elsePath = [
-    ...path4,
+    ...path6,
     branchCond(
       stmt,
       stmt.condition,
@@ -703,7 +789,7 @@ function stepIf(stmt, path4, ctx) {
   }
   return out;
 }
-function stepSwitch(stmt, path4, ctx) {
+function stepSwitch(stmt, path6, ctx) {
   const out = [];
   const negations = [];
   let defaultRanBody = false;
@@ -713,7 +799,7 @@ function stepSwitch(stmt, path4, ctx) {
     if (hasStrayBreak(group.body)) {
       throw new UnmodeledFlow("non-trailing break in switch clause");
     }
-    const groupPath = group.condition === null ? [...path4, ...negations] : [...path4, fixedCond(group.condition, "positive", "explicit")];
+    const groupPath = group.condition === null ? [...path6, ...negations] : [...path6, fixedCond(group.condition, "positive", "explicit")];
     const conts = enumerate(ctx, group.body, groupPath);
     if (conts.length > 0) {
       if (!group.hasTrailingBreak && !fallthroughSafe) {
@@ -730,24 +816,24 @@ function stepSwitch(stmt, path4, ctx) {
     }
   }
   if (!defaultRanBody) {
-    out.push([...path4, ...negations]);
+    out.push([...path6, ...negations]);
   }
   return out;
 }
-function stepLoop(stmt, path4, ctx) {
+function stepLoop(stmt, path6, ctx) {
   const bodyExit = exitKindOfList(stmt.body);
   if (containsTerminal(ctx, stmt)) {
     enumerate(ctx, stmt.body, [
-      ...path4,
+      ...path6,
       loopIterationCond(stmt.condition.sourceText)
     ]);
   }
   if (bodyExit !== null) {
-    return [[...path4, loopCompletedCond(stmt.condition.sourceText, bodyExit)]];
+    return [[...path6, loopCompletedCond(stmt.condition.sourceText, bodyExit)]];
   }
-  return [path4];
+  return [path6];
 }
-function stepTry(stmt, path4, ctx) {
+function stepTry(stmt, path6, ctx) {
   if (stmt.finallyBody !== null) {
     const finallyHasTerminal = stmt.finallyBody.some(
       (s) => containsTerminal(ctx, s)
@@ -757,22 +843,22 @@ function stepTry(stmt, path4, ctx) {
     }
   }
   const out = [];
-  out.push(...enumerate(ctx, stmt.tryBody, path4));
+  out.push(...enumerate(ctx, stmt.tryBody, path6));
   if (stmt.catchBody !== null) {
-    const catchPath = [...path4, catchEntryCond()];
+    const catchPath = [...path6, catchEntryCond()];
     out.push(...enumerate(ctx, stmt.catchBody, catchPath));
   }
   return out;
 }
-function stepExit(stmt, path4, ctx) {
+function stepExit(stmt, path6, ctx) {
   const collector = ctx.state.callbackExits[ctx.state.callbackExits.length - 1];
   if (collector !== void 0 && (stmt.exit === "return" || stmt.exit === "throw")) {
-    collector.push(path4);
+    collector.push(path6);
   }
   return [];
 }
-function stepOpaque(_stmt, path4, _ctx) {
-  return [path4];
+function stepOpaque(_stmt, path6, _ctx) {
+  return [path6];
 }
 var stepHandlers = {
   if: stepIf,
@@ -782,20 +868,20 @@ var stepHandlers = {
   exit: stepExit,
   opaque: stepOpaque
 };
-function stepCallback(ctx, body, path4) {
+function stepCallback(ctx, body, path6) {
   const exits = [];
   ctx.state.callbackExits.push(exits);
   let fellThrough;
   try {
-    fellThrough = enumerate(ctx, body, path4);
+    fellThrough = enumerate(ctx, body, path6);
   } finally {
     ctx.state.callbackExits.pop();
   }
   const out = [...fellThrough, ...exits];
-  return out.length === 0 ? [path4] : out;
+  return out.length === 0 ? [path6] : out;
 }
-function stepStatement(ctx, stmt, path4) {
-  let paths = [path4];
+function stepStatement(ctx, stmt, path6) {
+  let paths = [path6];
   for (const body of stmt.callbacks ?? []) {
     paths = paths.flatMap((each) => stepCallback(ctx, body, each));
   }
@@ -876,8 +962,8 @@ function enumerate(ctx, stmts, prefix) {
   let frontiers = [[...prefix]];
   for (const stmt of stmts) {
     const nextFrontiers = [];
-    for (const path4 of mergeRejoined(frontiers)) {
-      nextFrontiers.push(...stepStatement(ctx, stmt, path4));
+    for (const path6 of mergeRejoined(frontiers)) {
+      nextFrontiers.push(...stepStatement(ctx, stmt, path6));
     }
     frontiers = nextFrontiers;
     if (frontiers.length > MAX_PATHS) {
@@ -928,9 +1014,9 @@ function enumerateStructuredPaths(input) {
     isAncestorOrSelf
   };
   const continuations = withRejoined(enumerate(ctx, input.statements, []));
-  for (const path4 of continuations) {
+  for (const path6 of continuations) {
     chargeBudget(state);
-    state.fallthrough.push(classify(path4, null, isAncestorOrSelf));
+    state.fallthrough.push(classify(path6, null, isAncestorOrSelf));
   }
   return { byTerminal: state.byTerminal, fallthrough: state.fallthrough };
 }
@@ -973,8 +1059,8 @@ function sharedGatingConditions(paths, readPredicate) {
     return [];
   }
   const shared = new Set(first.map(keyOf2));
-  for (const path4 of rest) {
-    const here = new Set(path4.map(keyOf2));
+  for (const path6 of rest) {
+    const here = new Set(path6.map(keyOf2));
     for (const value of shared) {
       if (!here.has(value)) {
         shared.delete(value);
@@ -1004,7 +1090,7 @@ var IdSet = class {
   has(node) {
     return this.byKey.has(node.id);
   }
-  /** The node this set was built with, which is the caller's own handle for it. */
+  /** The wrapper that was added, which may be a different object from `node`. */
   get(node) {
     return this.byKey.get(node.id);
   }
@@ -1035,6 +1121,51 @@ var IdMap = class {
   }
 };
 
+// src/paths/nodeReads.ts
+var EnclosingNodes = class {
+  constructor(types) {
+    this.types = types;
+  }
+  types;
+  byTree = /* @__PURE__ */ new WeakMap();
+  /**
+   * The nearest ancestor of one of the types, or null when there is none.
+   * Every node passed on the way up has the same result, so each one is
+   * kept, and a later read from a sibling stops one step up.
+   */
+  of(node) {
+    const kept = this.keptFor(node.tree);
+    const known = kept.get(node.id);
+    if (known !== void 0) {
+      return known;
+    }
+    const passed = [node.id];
+    let current = node.parent;
+    while (current !== null && !this.types.has(current.type)) {
+      const above = kept.get(current.id);
+      if (above !== void 0) {
+        current = above;
+        break;
+      }
+      passed.push(current.id);
+      current = current.parent;
+    }
+    for (const id of passed) {
+      kept.set(id, current);
+    }
+    return current;
+  }
+  keptFor(tree) {
+    const known = this.byTree.get(tree);
+    if (known !== void 0) {
+      return known;
+    }
+    const fresh = /* @__PURE__ */ new Map();
+    this.byTree.set(tree, fresh);
+    return fresh;
+  }
+};
+
 // src/paths/nodeWalk.ts
 var SKIP_CHILDREN = /* @__PURE__ */ Symbol("skipChildren");
 function walkDescendants(root, carried, visitor) {
@@ -1051,23 +1182,23 @@ function walkDescendants(root, carried, visitor) {
 }
 
 // src/projectRoot.ts
-import path from "path";
+import path3 from "path";
 function commonDirectoryOf(files) {
-  const absolute = files.filter((f) => path.isAbsolute(f));
+  const absolute = files.filter((f) => path3.isAbsolute(f));
   const first = absolute[0];
   if (first === void 0) {
     return void 0;
   }
-  let shared = path.dirname(first).split(path.sep);
+  let shared = path3.dirname(first).split(path3.sep);
   for (const file of absolute.slice(1)) {
-    const parts = path.dirname(file).split(path.sep);
+    const parts = path3.dirname(file).split(path3.sep);
     let i = 0;
     while (i < shared.length && i < parts.length && shared[i] === parts[i]) {
       i += 1;
     }
     shared = shared.slice(0, i);
   }
-  const joined = shared.join(path.sep);
+  const joined = shared.join(path3.sep);
   return joined.length > 1 ? joined : void 0;
 }
 
@@ -1124,11 +1255,79 @@ function valueToReadFurtherFrom(reading) {
   return reading.kind === "written" ? reading.value : null;
 }
 
+// src/testFiles.ts
+function isListedTestFile(file, listed) {
+  if (listed === void 0) {
+    return true;
+  }
+  const whole = withForwardSlashes(file);
+  return listed.some((entry) => {
+    const tail = withForwardSlashes(entry).replace(/^\.\//, "");
+    return whole === tail || whole.endsWith(`/${tail}`);
+  });
+}
+function matchesTestFileName(file, patterns) {
+  const base = withForwardSlashes(file).split("/").pop() ?? "";
+  return patterns.some((pattern) => globToRegExp(pattern).test(base));
+}
+function globToRegExp(pattern) {
+  const escaped = pattern.split("*").map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+  return new RegExp(`^${escaped}$`);
+}
+function withForwardSlashes(file) {
+  return file.replace(/\\/g, "/");
+}
+
+// src/valueSources.ts
+var QUOTED_LENGTH = 80;
+function sourceRefsOf(leaves, spelling) {
+  const refs = [];
+  const said = /* @__PURE__ */ new Set();
+  for (const leaf of leaves) {
+    const ref = convertedFrom(refOf(leaf, spelling), leaf.conversions);
+    const spelled = JSON.stringify(ref);
+    if (!said.has(spelled)) {
+      said.add(spelled);
+      refs.push(ref);
+    }
+  }
+  return refs;
+}
+function convertedFrom(ref, conversions) {
+  return conversions.reduceRight(
+    (from, method) => ({
+      type: "derived",
+      from,
+      derivation: { type: "methodCall", method, args: [] }
+    }),
+    ref
+  );
+}
+function refOf(leaf, spelling) {
+  const whole = leaf.computedAt === null;
+  const input = whole ? spelling.inputOf(leaf) : null;
+  if (input !== null) {
+    return input;
+  }
+  if (whole && leaf.end.is === "written" && leaf.path.length === 0) {
+    const literal = spelling.literalAt(leaf.key);
+    if (literal !== void 0) {
+      return { type: "literal", value: literal };
+    }
+  }
+  const at = leaf.computedAt ?? leaf.key;
+  return { type: "unresolved", sourceText: quoted(spelling.textAt(at), at) };
+}
+function quoted(text, key) {
+  const written = (text ?? key.slice(key.lastIndexOf("#") + 1)).replace(/\s+/g, " ").trim();
+  return written.length <= QUOTED_LENGTH ? written : `${written.slice(0, QUOTED_LENGTH - 3)}...`;
+}
+
 // src/adapterStamp.ts
 import { createHash } from "crypto";
-import fs from "fs";
+import fs2 from "fs";
 import { createRequire } from "module";
-import path2 from "path";
+import path4 from "path";
 import { fileURLToPath } from "url";
 var ANALYSIS_PACKAGES = [
   "@suss/extractor",
@@ -1170,16 +1369,16 @@ function createAdapterStamp(config) {
 function readAdapterCodeStamp(moduleUrl) {
   try {
     const selfPath = fileURLToPath(moduleUrl);
-    const hash = computeDistHashFrom(path2.dirname(selfPath));
+    const hash = computeDistHashFrom(path4.dirname(selfPath));
     return hash.length > 0 ? { kind: "bundle", hash } : SOURCE_STAMP;
   } catch {
     return SOURCE_STAMP;
   }
 }
 function computeDistHashFrom(dir) {
-  const candidates = [path2.join(dir, "index.js"), path2.join(dir, "index.cjs")];
+  const candidates = [path4.join(dir, "index.js"), path4.join(dir, "index.cjs")];
   for (const candidate of candidates) {
-    if (!fs.existsSync(candidate)) {
+    if (!fs2.existsSync(candidate)) {
       continue;
     }
     return computeContentHash([candidate, ...analysisBundles()]);
@@ -1193,7 +1392,7 @@ function computeContentHash(paths) {
   const hash = createHash("sha256");
   for (const file of paths) {
     try {
-      hash.update(fs.readFileSync(file));
+      hash.update(fs2.readFileSync(file));
     } catch {
       return "";
     }
@@ -1209,13 +1408,29 @@ function projectFileStamp(paths) {
     hash.update(file);
     hash.update("\0");
     try {
-      hash.update(fs.readFileSync(file));
+      hash.update(fs2.readFileSync(file));
     } catch {
       hash.update("absent");
     }
   }
   return hash.digest("hex").slice(0, 16);
 }
+function extractionConfigStamp(config) {
+  const parts = [
+    ["gapHandling", config.gapHandling ?? "permissive"],
+    ["includeReachable", optionalText(config.includeReachable)],
+    ["workspaceRoot", config.workspaceRoot],
+    ["projectRoot", config.projectRoot],
+    ["importRoots", config.importRoots?.join(path4.delimiter)],
+    ["modules", modulesStamp(config.modules)]
+  ];
+  return parts.flatMap(
+    ([name, value]) => value === void 0 ? [] : [`${name}=${value}`]
+  ).join(",");
+}
+function optionalText(value) {
+  return value === void 0 ? void 0 : String(value);
+}
 function runDigest(packsDigest, packs, files) {
   const inputs = packs.flatMap((pack) => pack.discoveryInputs?.(files) ?? []);
   return `${packsDigest}|reads:${projectFileStamp(inputs)}`;
@@ -1233,10 +1448,118 @@ function analysisBundles() {
 }
 
 // src/cache.ts
+import { createHash as createHash3 } from "crypto";
+import fs4 from "fs/promises";
+import path5 from "path";
+
+// src/cacheStamps.ts
 import { createHash as createHash2 } from "crypto";
-import fs2 from "fs/promises";
-import path3 from "path";
-var SCHEMA_VERSION = "7";
+import fs3 from "fs/promises";
+var RECENT_CHANGE_MS = 2e3;
+function stampMayMissAWrite(stat, statAt) {
+  return Math.max(stat.mtimeMs, stat.ctimeMs) > statAt - RECENT_CHANGE_MS;
+}
+async function startRun(files, configPath) {
+  const startedAt = Date.now();
+  const config = configPath === void 0 ? null : await statAtStart(configPath);
+  const stats = await Promise.all(files.map(statAtStart));
+  stats.sort(
+    (a, b) => a.stamp.path < b.stamp.path ? -1 : a.stamp.path > b.stamp.path ? 1 : 0
+  );
+  return {
+    startedAt,
+    config: config?.ctimeMs === null ? null : config,
+    files: stats,
+    hashes: /* @__PURE__ */ new Map()
+  };
+}
+async function statAtStart(filePath) {
+  try {
+    const stat = await fs3.stat(filePath);
+    return {
+      stamp: { path: filePath, mtimeMs: stat.mtimeMs, size: stat.size },
+      ctimeMs: stat.ctimeMs
+    };
+  } catch {
+    return { stamp: { path: filePath, mtimeMs: -1, size: -1 }, ctimeMs: null };
+  }
+}
+async function hashOf(run, filePath) {
+  const known = run.hashes.get(filePath);
+  if (known !== void 0) {
+    return known;
+  }
+  const hash = await hashFile(filePath);
+  run.hashes.set(filePath, hash);
+  return hash;
+}
+async function hashRecentChanges(run) {
+  const recent = [...run.config === null ? [] : [run.config], ...run.files].filter(
+    (file) => file.ctimeMs !== null && stampMayMissAWrite(
+      { mtimeMs: file.stamp.mtimeMs, ctimeMs: file.ctimeMs },
+      run.startedAt
+    )
+  ).map((file) => file.stamp.path);
+  await Promise.all(recent.map((filePath) => hashOf(run, filePath)));
+}
+async function stillMatches(stored, found, run) {
+  if (!fileStampEquals(stored, found)) {
+    return false;
+  }
+  if (stored === null || stored.verifyHash !== true) {
+    return true;
+  }
+  return await hashOf(run, stored.path) === stored.contentHash;
+}
+async function filesStillMatch(stored, run) {
+  if (stored.length !== run.files.length || !stored.every((s, i) => fileStampEquals(s, run.files[i]?.stamp ?? null))) {
+    return false;
+  }
+  const checks = await Promise.all(
+    stored.map((s, i) => stillMatches(s, run.files[i]?.stamp ?? null, run))
+  );
+  return checks.every(Boolean);
+}
+async function recordedStamp(start, run, prior) {
+  if (start.ctimeMs === null) {
+    return start.stamp;
+  }
+  const filePath = start.stamp.path;
+  const now = await fs3.stat(filePath).catch(() => null);
+  if (now === null || now.mtimeMs !== start.stamp.mtimeMs || now.size !== start.stamp.size || now.ctimeMs !== start.ctimeMs) {
+    return null;
+  }
+  const atStart = { mtimeMs: start.stamp.mtimeMs, ctimeMs: start.ctimeMs };
+  if (stampMayMissAWrite(atStart, run.startedAt)) {
+    const readBefore = run.hashes.get(filePath);
+    return readBefore === void 0 || readBefore === null ? null : { ...start.stamp, contentHash: readBefore, verifyHash: true };
+  }
+  const hash = run.hashes.get(filePath) ?? reusableHash(prior, start.stamp) ?? await hashFile(filePath);
+  return hash === null ? start.stamp : { ...start.stamp, contentHash: hash };
+}
+function reusableHash(prior, stamp) {
+  return prior !== void 0 && prior.verifyHash !== true && fileStampEquals(prior, stamp) ? prior.contentHash : void 0;
+}
+async function hashFile(filePath) {
+  try {
+    const content = await fs3.readFile(filePath);
+    return createHash2("sha256").update(content).digest("hex").slice(0, 16);
+  } catch {
+    return null;
+  }
+}
+function fileStampEquals(a, b) {
+  if (a === null && b === null) {
+    return true;
+  }
+  if (a === null || b === null) {
+    return false;
+  }
+  return a.path === b.path && a.mtimeMs === b.mtimeMs && a.size === b.size;
+}
+
+// src/cache.ts
+var SCHEMA_VERSION = "9";
 var MAX_ENTRIES = 2;
 var ENTRY_PREFIX = "key-";
 var ENTRY_DIR_NAME = new RegExp(`^${ENTRY_PREFIX}[0-9a-f]{16}$`);
@@ -1253,56 +1576,88 @@ function createCacheLayer(cacheDir) {
       }
     };
   }
+  const manifests = new ManifestReads();
+  const runs = /* @__PURE__ */ new WeakMap();
+  const runFor = async (input) => runs.get(input) ?? await startRun(input.files, input.configPath);
+  const lookupWith = async (input, run) => {
+    const entryDir = entryDirFor(cacheDir, input);
+    const manifest = await manifests.readAtRunStart(
+      path5.join(entryDir, "manifest.json")
+    );
+    if (manifest === null) {
+      return missDiag(await describeAbsentEntry(cacheDir));
+    }
+    if (!await stillMatches(
+      manifest.configStamp,
+      run.config?.stamp ?? null,
+      run
+    )) {
+      return missDiag("config-changed");
+    }
+    if (!await filesStillMatch(manifest.files, run)) {
+      return missDiag("files-changed");
+    }
+    await markUsed(entryDir);
+    manifests.forget();
+    return {
+      kind: "hit",
+      summaries: manifest.summaries,
+      diagnostic: { kind: "hit" }
+    };
+  };
   return {
     async tryHit(input) {
       const result = await this.lookup(input);
       return result.kind === "hit" ? result.summaries : null;
     },
     async lookup(input) {
-      const entryDir = entryDirFor(cacheDir, input);
-      const manifest = await readManifest(
-        path3.join(entryDir, "manifest.json")
-      );
-      if (manifest === null) {
-        return missDiag(await describeAbsentEntry(cacheDir));
+      const run = await startRun(input.files, input.configPath);
+      runs.set(input, run);
+      const result = await lookupWith(input, run);
+      if (result.kind === "miss") {
+        await hashRecentChanges(run);
       }
-      const currentConfigStamp = await stampConfigFile(input.configPath);
-      if (!fileStampEquals(manifest.configStamp, currentConfigStamp)) {
-        return missDiag("config-changed");
-      }
-      const currentFiles = await resolveFileStamps(input);
-      if (!fileStampsEqual(manifest.files, currentFiles)) {
-        return missDiag("files-changed");
-      }
-      await markUsed(entryDir);
-      return {
-        kind: "hit",
-        summaries: manifest.summaries,
-        diagnostic: { kind: "hit" }
-      };
+      return result;
     },
     async plan(input) {
       const entryDir = entryDirFor(cacheDir, input);
-      const manifest = await readManifest(
-        path3.join(entryDir, "manifest.json")
+      const manifest = await manifests.readAgain(
+        path5.join(entryDir, "manifest.json")
       );
       if (manifest === null || manifest.roots === void 0 || manifest.rootMeta === void 0 || manifest.owners === void 0) {
         return null;
       }
-      const currentConfigStamp = await stampConfigFile(input.configPath);
-      if (!fileStampEquals(manifest.configStamp, currentConfigStamp)) {
+      const run = await runFor(input);
+      if (!await stillMatches(
+        manifest.configStamp,
+        run.config?.stamp ?? null,
+        run
+      )) {
         return null;
       }
       await markUsed(entryDir);
-      return buildPlan(manifest, await resolveFileStamps(input));
+      return buildPlan(manifest, run);
     },
     async write(input, summaries, attribution) {
       const entryDir = entryDirFor(cacheDir, input);
-      const previous = await readManifest(
-        path3.join(entryDir, "manifest.json")
+      const previous = await manifests.readAgain(
+        path5.join(entryDir, "manifest.json")
       );
-      const configStamp = await stampConfigFile(input.configPath);
-      const files = await hashStamps(await resolveFileStamps(input), previous);
+      manifests.forget();
+      const known = runs.get(input);
+      const run = known ?? await runFor(input);
+      if (known === void 0) {
+        await hashRecentChanges(run);
+      }
+      runs.delete(input);
+      const configStamp = run.config === null ? null : await recordedStamp(run.config, run, void 0);
+      const prior = new Map((previous?.files ?? []).map((f) => [f.path, f]));
+      const recorded = await Promise.all(
+        run.files.map(
+          (file) => recordedStamp(file, run, prior.get(file.stamp.path))
+        )
+      );
+      const files = recorded.filter((stamp) => stamp !== null);
       const manifest = {
         schemaVersion: SCHEMA_VERSION,
         adapterPacksDigest: input.adapterPacksDigest,
@@ -1311,19 +1666,20 @@ function createCacheLayer(cacheDir) {
         summaries,
         ...attribution === void 0 ? {} : encodeAttribution(attribution)
       };
-      await fs2.mkdir(entryDir, { recursive: true });
-      await fs2.writeFile(
-        path3.join(entryDir, "manifest.json"),
+      await fs4.mkdir(entryDir, { recursive: true });
+      await fs4.writeFile(
+        path5.join(entryDir, "manifest.json"),
         JSON.stringify(manifest)
       );
       await evictOldEntries(cacheDir, entryDir);
     }
   };
 }
-async function buildPlan(manifest, currentStamps) {
+async function buildPlan(manifest, run) {
   const stored = new Map(manifest.files.map((f) => [f.path, f]));
-  const current = new Map(currentStamps.map((f) => [f.path, f]));
+  const current = new Map(run.files.map((f) => [f.stamp.path, f.stamp]));
   const changed = /* @__PURE__ */ new Set();
+  const added = /* @__PURE__ */ new Set();
   const removed = /* @__PURE__ */ new Set();
   for (const p of stored.keys()) {
     if (!current.has(p)) {
@@ -1335,17 +1691,20 @@ async function buildPlan(manifest, currentStamps) {
     const before = stored.get(p);
     if (before === void 0) {
       changed.add(p);
+      added.add(p);
     } else if (!fileStampEquals(before, stamp)) {
       if (before.contentHash === void 0) {
         changed.add(p);
       } else {
         toVerify.push(p);
       }
+    } else if (before.verifyHash === true) {
+      toVerify.push(p);
     }
   }
   await Promise.all(
     toVerify.map(async (p) => {
-      const hash = await hashFile(p);
+      const hash = await hashOf(run, p);
       if (hash === null || hash !== stored.get(p)?.contentHash) {
         changed.add(p);
       }
@@ -1354,6 +1713,10 @@ async function buildPlan(manifest, currentStamps) {
   const roots = /* @__PURE__ */ new Map();
   const rootNames = manifest.roots ?? [];
   const depPaths = manifest.depPaths ?? [];
+  const pathsOf = (ids) => ids.flatMap((d) => {
+    const p = depPaths[d];
+    return p === void 0 ? [] : [p];
+  });
   let rootsDeclined = 0;
   rootNames.forEach((rootPath, i) => {
     const meta = manifest.rootMeta?.[i];
@@ -1366,35 +1729,54 @@ async function buildPlan(manifest, currentStamps) {
     roots.set(rootPath, {
       path: rootPath,
       cacheable: meta.cacheable,
-      deps: meta.deps.flatMap((d) => {
-        const p = depPaths[d];
-        return p === void 0 ? [] : [p];
-      }),
+      deps: pathsOf(meta.deps),
       claims: meta.claims,
       meta: meta.meta,
-      packs: meta.packs
+      packs: meta.packs,
+      ...meta.imports === void 0 ? {} : { imports: pathsOf(meta.imports) }
     });
   });
+  const unchanged = (filePath, deps) => current.has(filePath) && !changed.has(filePath) && !deps.some((d) => changed.has(d) || removed.has(d));
   const validRoots = /* @__PURE__ */ new Set();
   for (const [rootPath, record] of roots) {
-    if (!record.cacheable || !current.has(rootPath)) {
-      continue;
+    if (record.cacheable && unchanged(rootPath, record.deps)) {
+      validRoots.add(rootPath);
     }
-    if (changed.has(rootPath)) {
-      continue;
+  }
+  const units = (manifest.units ?? []).flatMap((stored2) => {
+    const file = depPaths[stored2.file];
+    return file === void 0 ? [] : [
+      {
+        key: stored2.key,
+        file,
+        deps: pathsOf(stored2.deps),
+        data: stored2.data
+      }
+    ];
+  });
+  const validUnits = /* @__PURE__ */ new Map();
+  for (const unit of units) {
+    if (unchanged(unit.file, unit.deps)) {
+      validUnits.set(unit.key, unit);
     }
-    const depMoved = record.deps.some((d) => changed.has(d) || removed.has(d));
-    if (!depMoved) {
-      validRoots.add(rootPath);
+  }
+  const resolvedImports = /* @__PURE__ */ new Map();
+  if (added.size === 0 && removed.size === 0) {
+    for (const [rootPath, record] of roots) {
+      if (record.imports !== void 0 && !changed.has(rootPath)) {
+        resolvedImports.set(rootPath, record.imports);
+      }
     }
   }
   const owners = manifest.owners ?? [];
   return {
     changed,
     removed,
+    resolvedImports,
     roots,
     validRoots,
     rootsDeclined,
+    validUnits,
     reuse(valid) {
       const summaries = [];
       const reusedOwners = [];
@@ -1421,7 +1803,8 @@ async function buildPlan(manifest, currentStamps) {
             const p = rootNames[o];
             return p === void 0 ? [] : [p];
           })
-        )
+        ),
+        units
       };
     }
   };
@@ -1446,7 +1829,8 @@ function encodeAttribution(attribution) {
     deps: r.deps.map(depIdOf),
     claims: r.claims,
     meta: r.meta,
-    packs: r.packs
+    packs: r.packs,
+    ...r.imports === void 0 ? {} : { imports: r.imports.map(depIdOf) }
   }));
   const owners = attribution.owners.map(
     (ownerPaths) => ownerPaths.flatMap((p) => {
@@ -1454,32 +1838,23 @@ function encodeAttribution(attribution) {
       return i === void 0 ? [] : [i];
     })
   );
-  return { roots, rootMeta, depPaths, owners };
-}
-async function hashStamps(stamps, previous) {
-  const before = new Map((previous?.files ?? []).map((f) => [f.path, f]));
-  return Promise.all(
-    stamps.map(async (stamp) => {
-      const prior = before.get(stamp.path);
-      if (prior !== void 0 && prior.contentHash !== void 0 && fileStampEquals(prior, stamp)) {
-        return { ...stamp, contentHash: prior.contentHash };
-      }
-      const contentHash = await hashFile(stamp.path);
-      return contentHash === null ? stamp : { ...stamp, contentHash };
-    })
-  );
-}
-async function hashFile(filePath) {
-  try {
-    const content = await fs2.readFile(filePath);
-    return createHash2("sha256").update(content).digest("hex").slice(0, 16);
-  } catch {
-    return null;
-  }
+  const units = attribution.units?.map((unit) => ({
+    key: unit.key,
+    file: depIdOf(unit.file),
+    deps: unit.deps.map(depIdOf),
+    data: unit.data
+  }));
+  return {
+    roots,
+    rootMeta,
+    depPaths,
+    owners,
+    ...units === void 0 ? {} : { units }
+  };
 }
 async function describeAbsentEntry(cacheDir) {
   try {
-    const entries = await fs2.readdir(cacheDir, { withFileTypes: true });
+    const entries = await fs4.readdir(cacheDir, { withFileTypes: true });
     return entries.some((e) => e.isDirectory() && isEntryDir(e.name)) ? "key-changed" : "no-manifest";
   } catch {
     return "no-manifest";
@@ -1491,8 +1866,8 @@ function entryDirFor(cacheDir, input) {
     input.adapterPacksDigest,
     input.configPath ?? ""
   ].join(" ");
-  const name = createHash2("sha256").update(key).digest("hex").slice(0, 16);
-  return path3.join(cacheDir, `${ENTRY_PREFIX}${name}`);
+  const name = createHash3("sha256").update(key).digest("hex").slice(0, 16);
+  return path5.join(cacheDir, `${ENTRY_PREFIX}${name}`);
 }
 function isEntryDir(name) {
   return ENTRY_DIR_NAME.test(name);
@@ -1500,24 +1875,24 @@ function isEntryDir(name) {
 async function markUsed(entryDir) {
   const now = /* @__PURE__ */ new Date();
   try {
-    await fs2.utimes(entryDir, now, now);
+    await fs4.utimes(entryDir, now, now);
   } catch {
   }
 }
 async function evictOldEntries(cacheDir, keepDir) {
   try {
-    await fs2.rm(path3.join(cacheDir, "manifest.json"), { force: true });
-    const entries = await fs2.readdir(cacheDir, { withFileTypes: true });
+    await fs4.rm(path5.join(cacheDir, "manifest.json"), { force: true });
+    const entries = await fs4.readdir(cacheDir, { withFileTypes: true });
     const dirs = await Promise.all(
       entries.filter((e) => e.isDirectory() && isEntryDir(e.name)).map(async (e) => {
-        const dir = path3.join(cacheDir, e.name);
-        const stat = await fs2.stat(dir);
+        const dir = path5.join(cacheDir, e.name);
+        const stat = await fs4.stat(dir);
         return { dir, mtimeMs: stat.mtimeMs };
       })
     );
     const doomed = dirs.filter((d) => d.dir !== keepDir).sort((a, b) => b.mtimeMs - a.mtimeMs).slice(MAX_ENTRIES - 1);
     await Promise.all(
-      doomed.map((d) => fs2.rm(d.dir, { recursive: true, force: true }))
+      doomed.map((d) => fs4.rm(d.dir, { recursive: true, force: true }))
     );
   } catch {
   }
@@ -1528,51 +1903,41 @@ function missDiag(reason) {
     diagnostic: { kind: "miss", missReason: reason }
   };
 }
-async function readManifest(manifestPath) {
+var ManifestReads = class {
+  last = null;
+  async readAtRunStart(manifestPath) {
+    const stamp = await manifestStamp(manifestPath);
+    const manifest = await readManifest(manifestPath);
+    this.last = { path: manifestPath, stamp, manifest };
+    return manifest;
+  }
+  async readAgain(manifestPath) {
+    const last = this.last;
+    if (last !== null && last.path === manifestPath && last.stamp !== null && last.stamp === await manifestStamp(manifestPath)) {
+      return last.manifest;
+    }
+    return await this.readAtRunStart(manifestPath);
+  }
+  forget() {
+    this.last = null;
+  }
+};
+async function manifestStamp(manifestPath) {
   try {
-    const raw = await fs2.readFile(manifestPath, "utf-8");
-    return JSON.parse(raw);
+    const stat = await fs4.stat(manifestPath);
+    return `${stat.ino}:${stat.mtimeMs}:${stat.size}`;
   } catch {
     return null;
   }
 }
-async function stampConfigFile(configPath) {
-  if (configPath === void 0) {
-    return null;
-  }
+async function readManifest(manifestPath) {
   try {
-    const stat = await fs2.stat(configPath);
-    return { path: configPath, mtimeMs: stat.mtimeMs, size: stat.size };
+    const raw = await fs4.readFile(manifestPath, "utf-8");
+    return JSON.parse(raw);
   } catch {
     return null;
   }
 }
-async function resolveFileStamps(input) {
-  const stamped = await Promise.all(
-    input.files.map(async (p) => {
-      try {
-        const stat = await fs2.stat(p);
-        return { path: p, mtimeMs: stat.mtimeMs, size: stat.size };
-      } catch {
-        return { path: p, mtimeMs: -1, size: -1 };
-      }
-    })
-  );
-  stamped.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
-  return stamped;
-}
-function fileStampsEqual(a, b) {
-  return a.length === b.length && a.every((s, i) => fileStampEquals(s, b[i]));
-}
-function fileStampEquals(a, b) {
-  if (a === null && b === null) {
-    return true;
-  }
-  if (a === null || b === null) {
-    return false;
-  }
-  return a.path === b.path && a.mtimeMs === b.mtimeMs && a.size === b.size;
-}
 
 // src/extractionReport.ts
 import { BOUNDARY_ROLE } from "@suss/behavioral-ir";
@@ -1681,6 +2046,38 @@ function firstEmptyUngatedStage(packs, filesWalked) {
   return "assembly";
 }
 
+// src/keptParses.ts
+var KeptParses = class {
+  constructor(release = () => {
+  }) {
+    this.release = release;
+  }
+  release;
+  byFile = /* @__PURE__ */ new Map();
+  async parse(file, source, make) {
+    const kept = this.byFile.get(file);
+    if (kept !== void 0 && kept.source === source) {
+      return kept.value;
+    }
+    const value = await make(source);
+    if (kept !== void 0) {
+      this.release(kept.value);
+    }
+    this.byFile.set(file, { source, value });
+    return value;
+  }
+  /** Lets go of every file not in this run. */
+  keepOnly(files) {
+    const wanted = new Set(files);
+    for (const [file, kept] of this.byFile) {
+      if (!wanted.has(file)) {
+        this.release(kept.value);
+        this.byFile.delete(file);
+      }
+    }
+  }
+};
+
 // src/packHealth.ts
 function stagesOf(funnel) {
   const stages = [];
@@ -1727,8 +2124,8 @@ function funnelDrops(packs) {
 function recognizersWithNoUnits(packs) {
   return packs.filter(
     (funnel) => funnel.recognizes && !funnel.discovers && funnel.gates.length > 0 && funnel.unresolvedGates.length === 0 && funnel.candidateFiles > 0 && funnel.unitsInGatedFiles === 0 && // The closure walks a recognizer-only pack's gated exports as
-    // roots, so effects recognized there mean the run worked and
-    // the missing framework pack costs attribution, not existence.
+    // roots, so effects recognized there mean the run worked and only
+    // the framework pack's attribution is missing.
     funnel.effectsRecognized === 0
   ).map((funnel) => ({
     label: funnel.pack,
@@ -1970,7 +2367,7 @@ function makeTransitionId(functionName, branch) {
   const { terminal } = branch;
   const statusKey = terminal.statusCode === null ? "none" : terminal.statusCode.type === "literal" ? String(terminal.statusCode.value) : `dyn:${terminal.statusCode.sourceText}`;
   const conditionSig = branch.conditions.map((c) => `${c.polarity}:${c.sourceText}`).join(";");
-  const conditionHash = createHash3("sha1").update(conditionSig).digest("hex").slice(0, 7);
+  const conditionHash = createHash4("sha1").update(conditionSig).digest("hex").slice(0, 7);
   return `${functionName}:${terminal.kind}:${statusKey}:${conditionHash}`;
 }
 function collapseReading(table, reading) {
@@ -2040,6 +2437,39 @@ function effectsOfBranch(branch) {
   ];
   return foldRepeatedEffects(effects.map(withNormalizedCallee));
 }
+function provenanceOf(raw, effects) {
+  if (raw.length === 0) {
+    return [];
+  }
+  const positionOf = new Map(effects.map((one, at) => [effectKey(one), at]));
+  const bySlot = /* @__PURE__ */ new Map();
+  const said = /* @__PURE__ */ new Map();
+  for (const one of raw) {
+    const effect = positionOf.get(effectKey(withNormalizedCallee(one.effect)));
+    if (effect === void 0) {
+      continue;
+    }
+    const slotKey = `${effect}\0${one.slot}\0${one.name}`;
+    let entry = bySlot.get(slotKey);
+    let seen = said.get(slotKey);
+    if (entry === void 0 || seen === void 0) {
+      entry = { at: { slot: one.slot, effect, name: one.name }, from: [] };
+      seen = /* @__PURE__ */ new Set();
+      bySlot.set(slotKey, entry);
+      said.set(slotKey, seen);
+    }
+    for (const source of one.from) {
+      const spelled = JSON.stringify(source);
+      if (!seen.has(spelled)) {
+        seen.add(spelled);
+        entry.from.push(source);
+      }
+    }
+  }
+  return [...bySlot.values()].sort(
+    (a, b) => a.at.effect - b.at.effect || a.at.slot.localeCompare(b.at.slot) || a.at.name.localeCompare(b.at.name)
+  );
+}
 function withNormalizedCallee(effect) {
   if (effect.type !== "invocation" && effect.type !== "interaction") {
     return effect;
@@ -2055,17 +2485,22 @@ function assembleSummary(raw, options = DEFAULT_OPTIONS) {
     const conditions = branch.conditions.map(
       rawConditionToPredicate
     );
+    const effects = effectsOfBranch(branch);
     const transition = {
       id: makeTransitionId(raw.identity.name, branch),
       conditions,
       output: terminalToOutput(branch.terminal),
-      effects: effectsOfBranch(branch),
+      effects,
       location: branch.location,
       isDefault: branch.isDefault
     };
     if (branch.expectedInput != null) {
       transition.expectedInput = branch.expectedInput;
     }
+    const provenance = provenanceOf(branch.provenance ?? [], effects);
+    if (provenance.length > 0) {
+      transition.provenance = provenance;
+    }
     return transition;
   });
   const gaps = detectGaps(raw, transitions, options);
@@ -2127,6 +2562,9 @@ function buildMetadata(raw) {
   if (raw.requestSpelling !== void 0) {
     metadata = withRequestSpellingMetadata(metadata, raw.requestSpelling);
   }
+  if (raw.test !== void 0) {
+    metadata = withTestMetadata(metadata, raw.test);
+  }
   return Object.keys(metadata).length > 0 ? metadata : null;
 }
 function buildHttpMetadataValue(raw) {
@@ -2270,18 +2708,27 @@ function bodyToShape(body) {
   }
   return null;
 }
+function statusValueRef(code) {
+  if (code === null) {
+    return null;
+  }
+  return code.type === "literal" ? { type: "literal", value: code.value } : { type: "unresolved", sourceText: code.sourceText };
+}
 var terminalConverters = {
   response: (t) => {
-    const statusCode = t.statusCode ? t.statusCode.type === "literal" ? { type: "literal", value: t.statusCode.value } : { type: "unresolved", sourceText: t.statusCode.sourceText } : null;
     const body = bodyToShape(t.body);
-    return { type: "response", statusCode, body, headers: {} };
+    return {
+      type: "response",
+      statusCode: statusValueRef(t.statusCode),
+      body,
+      headers: {}
+    };
   },
   throw: (t) => {
     if (t.statusCode && t.producesResponse === true) {
-      const statusCode = t.statusCode.type === "literal" ? { type: "literal", value: t.statusCode.value } : { type: "unresolved", sourceText: t.statusCode.sourceText };
       return {
         type: "response",
-        statusCode,
+        statusCode: statusValueRef(t.statusCode),
         body: bodyToShape(t.body),
         headers: {}
       };
@@ -2309,7 +2756,8 @@ var terminalConverters = {
     type: "return",
     value: bodyToShape(t.body)
   }),
-  void: (_t) => ({ type: "void" })
+  void: (_t) => ({ type: "void" }),
+  exit: (t) => ({ type: "exit", code: statusValueRef(t.statusCode) })
 };
 function terminalToOutput(terminal) {
   return terminalConverters[terminal.kind](terminal);
@@ -2352,14 +2800,18 @@ function paramToInput(param) {
     name: param.name,
     position: param.position,
     role: param.role,
+    ...param.field === void 0 ? {} : { field: param.field },
     shape: param.typeText ? { type: "ref", name: param.typeText } : null
   };
 }
 export {
+  EnclosingNodes,
   IdMap,
   IdSet,
+  KeptParses,
   MAX_ENTRIES,
   MAX_PATHS,
+  MODULE_SURFACE_RECOGNITION,
   PathBudgetExceeded,
   SKIP_CHILDREN,
   UnmodeledFlow,
@@ -2384,13 +2836,18 @@ export {
   enumerateOrDegrade,
   enumerateStructuredPaths,
   evaluatePackHealth,
+  extractionConfigStamp,
   firstWrittenReading,
   formatPackHealth,
   guardsHoldOn,
   httpRouteDiscovery,
+  isListedTestFile,
   makeTransitionId,
   mapReading,
+  markReturnsAsExitCode,
+  matchesTestFileName,
   moduleInitStructure,
+  moduleOfFile,
   noopTimer,
   packGradients,
   paramToInput,
@@ -2402,8 +2859,12 @@ export {
   runDigest,
   runsBefore,
   scopeOption,
+  settleModules,
   sharedGatingConditions,
+  sourceRefsOf,
+  stampMayMissAWrite,
   stampModuleImports,
+  stampModules,
   storageSystemOption,
   summaryCountsByPack,
   tallyUnit,