@suss/extractor 0.21.0 → 0.22.0

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -22,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   IdMap: () => IdMap,
   IdSet: () => IdSet,
+  MAX_ENTRIES: () => MAX_ENTRIES,
   MAX_PATHS: () => MAX_PATHS,
   PathBudgetExceeded: () => PathBudgetExceeded,
   SKIP_CHILDREN: () => SKIP_CHILDREN,
@@ -31,25 +42,44 @@ __export(index_exports, {
   andThenReading: () => andThenReading,
   assembleSummary: () => assembleSummary,
   assessConfidence: () => assessConfidence,
+  buildUngatedExtractionReport: () => buildUngatedExtractionReport,
   composeWrappers: () => composeWrappers,
+  computeContentHash: () => computeContentHash,
+  computeDistHashFrom: () => computeDistHashFrom,
   configuredCallOption: () => configuredCallOption,
+  createAdapterStamp: () => createAdapterStamp,
+  createCacheLayer: () => createCacheLayer,
+  createPackTallies: () => createPackTallies,
+  createTimer: () => createTimer,
   detectGaps: () => detectGaps,
   effectToIR: () => effectToIR,
+  emptyTally: () => emptyTally,
   enumerateOrDegrade: () => enumerateOrDegrade,
   enumerateStructuredPaths: () => enumerateStructuredPaths,
+  evaluatePackHealth: () => evaluatePackHealth,
   firstWrittenReading: () => firstWrittenReading,
+  formatPackHealth: () => formatPackHealth,
   guardsHoldOn: () => guardsHoldOn,
   httpRouteDiscovery: () => httpRouteDiscovery,
   makeTransitionId: () => makeTransitionId,
   mapReading: () => mapReading,
+  moduleInitStructure: () => moduleInitStructure,
+  noopTimer: () => noopTimer,
+  packGradients: () => packGradients,
   paramToInput: () => paramToInput,
+  projectFileStamp: () => projectFileStamp,
   rawConditionToPredicate: () => rawConditionToPredicate,
+  recordPackFailure: () => recordPackFailure,
   registrationHelperDiscovery: () => registrationHelperDiscovery,
   routeHelperIndex: () => routeHelperIndex,
+  runDigest: () => runDigest,
   runsBefore: () => runsBefore,
   scopeOption: () => scopeOption,
   sharedGatingConditions: () => sharedGatingConditions,
+  stampModuleImports: () => stampModuleImports,
   storageSystemOption: () => storageSystemOption,
+  summaryCountsByPack: () => summaryCountsByPack,
+  tallyUnit: () => tallyUnit,
   terminalToOutput: () => terminalToOutput,
   unreadableReading: () => unreadableReading,
   unwrapJsonStringify: () => unwrapJsonStringify,
@@ -59,8 +89,8 @@ __export(index_exports, {
   writtenReading: () => writtenReading
 });
 module.exports = __toCommonJS(index_exports);
-var import_node_crypto = require("crypto");
-var import_behavioral_ir3 = require("@suss/behavioral-ir");
+var import_node_crypto3 = require("crypto");
+var import_behavioral_ir4 = require("@suss/behavioral-ir");
 
 // src/inputReads.ts
 function inputReadsOf(args) {
@@ -204,8 +234,8 @@ var catchEntryCond = () => fixedCond(
   "positive",
   "catchBlock"
 );
-function classify(path, home, isAncestorOrSelf) {
-  return path.map((cond) => {
+function classify(path3, home, isAncestorOrSelf) {
+  return path3.map((cond) => {
     if (cond.branchStmt === null) {
       return cond.info;
     }
@@ -270,9 +300,9 @@ function chargeBudget(state) {
     );
   }
 }
-function recordTerminal(ctx, terminal, home, path) {
+function recordTerminal(ctx, terminal, home, path3) {
   chargeBudget(ctx.state);
-  const info = classify(path, home, ctx.isAncestorOrSelf);
+  const info = classify(path3, home, ctx.isAncestorOrSelf);
   const existing = ctx.state.byTerminal.get(terminal) ?? [];
   existing.push(info);
   ctx.state.byTerminal.set(terminal, existing);
@@ -283,15 +313,15 @@ function containsTerminal(ctx, stmt) {
   }
   return childrenOf(stmt).some((child) => containsTerminal(ctx, child));
 }
-function stepIf(stmt, path, ctx) {
+function stepIf(stmt, path3, ctx) {
   const thenExit = exitKindOfList(stmt.thenBody);
   const elseExit = stmt.elseBody === null ? null : exitKindOfList(stmt.elseBody);
   const thenPath = [
-    ...path,
+    ...path3,
     branchCond(stmt, stmt.condition, "positive", elseExit)
   ];
   const elsePath = [
-    ...path,
+    ...path3,
     branchCond(
       stmt,
       stmt.condition,
@@ -308,7 +338,7 @@ function stepIf(stmt, path, ctx) {
   }
   return out;
 }
-function stepSwitch(stmt, path, ctx) {
+function stepSwitch(stmt, path3, ctx) {
   const out = [];
   const negations = [];
   let defaultRanBody = false;
@@ -318,7 +348,7 @@ function stepSwitch(stmt, path, ctx) {
     if (hasStrayBreak(group.body)) {
       throw new UnmodeledFlow("non-trailing break in switch clause");
     }
-    const groupPath = group.condition === null ? [...path, ...negations] : [...path, fixedCond(group.condition, "positive", "explicit")];
+    const groupPath = group.condition === null ? [...path3, ...negations] : [...path3, fixedCond(group.condition, "positive", "explicit")];
     const conts = enumerate(ctx, group.body, groupPath);
     if (conts.length > 0) {
       if (!group.hasTrailingBreak && !fallthroughSafe) {
@@ -335,24 +365,24 @@ function stepSwitch(stmt, path, ctx) {
     }
   }
   if (!defaultRanBody) {
-    out.push([...path, ...negations]);
+    out.push([...path3, ...negations]);
   }
   return out;
 }
-function stepLoop(stmt, path, ctx) {
+function stepLoop(stmt, path3, ctx) {
   const bodyExit = exitKindOfList(stmt.body);
   if (containsTerminal(ctx, stmt)) {
     enumerate(ctx, stmt.body, [
-      ...path,
+      ...path3,
       loopIterationCond(stmt.condition.sourceText)
     ]);
   }
   if (bodyExit !== null) {
-    return [[...path, loopCompletedCond(stmt.condition.sourceText, bodyExit)]];
+    return [[...path3, loopCompletedCond(stmt.condition.sourceText, bodyExit)]];
   }
-  return [path];
+  return [path3];
 }
-function stepTry(stmt, path, ctx) {
+function stepTry(stmt, path3, ctx) {
   if (stmt.finallyBody !== null) {
     const finallyHasTerminal = stmt.finallyBody.some(
       (s) => containsTerminal(ctx, s)
@@ -362,22 +392,22 @@ function stepTry(stmt, path, ctx) {
     }
   }
   const out = [];
-  out.push(...enumerate(ctx, stmt.tryBody, path));
+  out.push(...enumerate(ctx, stmt.tryBody, path3));
   if (stmt.catchBody !== null) {
-    const catchPath = [...path, catchEntryCond()];
+    const catchPath = [...path3, catchEntryCond()];
     out.push(...enumerate(ctx, stmt.catchBody, catchPath));
   }
   return out;
 }
-function stepExit(stmt, path, ctx) {
+function stepExit(stmt, path3, ctx) {
   const collector = ctx.state.callbackExits[ctx.state.callbackExits.length - 1];
   if (collector !== void 0 && (stmt.exit === "return" || stmt.exit === "throw")) {
-    collector.push(path);
+    collector.push(path3);
   }
   return [];
 }
-function stepOpaque(_stmt, path, _ctx) {
-  return [path];
+function stepOpaque(_stmt, path3, _ctx) {
+  return [path3];
 }
 var stepHandlers = {
   if: stepIf,
@@ -387,20 +417,20 @@ var stepHandlers = {
   exit: stepExit,
   opaque: stepOpaque
 };
-function stepCallback(ctx, body, path) {
+function stepCallback(ctx, body, path3) {
   const exits = [];
   ctx.state.callbackExits.push(exits);
   let fellThrough;
   try {
-    fellThrough = enumerate(ctx, body, path);
+    fellThrough = enumerate(ctx, body, path3);
   } finally {
     ctx.state.callbackExits.pop();
   }
   const out = [...fellThrough, ...exits];
-  return out.length === 0 ? [path] : out;
+  return out.length === 0 ? [path3] : out;
 }
-function stepStatement(ctx, stmt, path) {
-  let paths = [path];
+function stepStatement(ctx, stmt, path3) {
+  let paths = [path3];
   for (const body of stmt.callbacks ?? []) {
     paths = paths.flatMap((each) => stepCallback(ctx, body, each));
   }
@@ -481,8 +511,8 @@ function enumerate(ctx, stmts, prefix) {
   let frontiers = [[...prefix]];
   for (const stmt of stmts) {
     const nextFrontiers = [];
-    for (const path of mergeRejoined(frontiers)) {
-      nextFrontiers.push(...stepStatement(ctx, stmt, path));
+    for (const path3 of mergeRejoined(frontiers)) {
+      nextFrontiers.push(...stepStatement(ctx, stmt, path3));
     }
     frontiers = nextFrontiers;
     if (frontiers.length > MAX_PATHS) {
@@ -533,9 +563,9 @@ function enumerateStructuredPaths(input) {
     isAncestorOrSelf
   };
   const continuations = withRejoined(enumerate(ctx, input.statements, []));
-  for (const path of continuations) {
+  for (const path3 of continuations) {
     chargeBudget(state);
-    state.fallthrough.push(classify(path, null, isAncestorOrSelf));
+    state.fallthrough.push(classify(path3, null, isAncestorOrSelf));
   }
   return { byTerminal: state.byTerminal, fallthrough: state.fallthrough };
 }
@@ -730,6 +760,70 @@ function runsBefore(effectLine, terminalEndLine) {
   return effectLine <= terminalEndLine;
 }
 
+// src/moduleImports.ts
+function stampModuleImports(summaries, importsOf) {
+  const byFile = /* @__PURE__ */ new Map();
+  for (const summary of summaries) {
+    const file = summary.location.file;
+    if (!byFile.has(file)) {
+      const found = importsOf(file);
+      byFile.set(
+        file,
+        found === void 0 ? void 0 : [...new Set(found)].sort()
+      );
+    }
+    const imports = byFile.get(file);
+    if (imports === void 0) {
+      continue;
+    }
+    summary.metadata = {
+      ...summary.metadata ?? {},
+      moduleImports: imports
+    };
+  }
+}
+
+// src/moduleInit.ts
+function moduleInitStructure(options) {
+  const { name, file, range, effects } = options;
+  return {
+    identity: {
+      name,
+      kind: "module-init",
+      file,
+      range,
+      exportName: null,
+      exportPath: null
+    },
+    boundaryBinding: null,
+    parameters: [],
+    branches: [
+      {
+        conditions: [],
+        terminal: {
+          kind: "void",
+          statusCode: null,
+          body: null,
+          exceptionType: null,
+          message: null,
+          component: null,
+          renderTree: null,
+          delegateTarget: null,
+          emitEvent: null,
+          location: range
+        },
+        effects: [],
+        extraEffects: effects,
+        location: range,
+        isDefault: true
+      }
+    ],
+    unmatchedReturns: 0,
+    dependencyCalls: [],
+    declaredContract: null
+  };
+}
+
 // src/packHelpers.ts
 function httpRouteDiscovery(opts) {
   const kind = opts.kind ?? "handler";
@@ -927,8 +1021,8 @@ function sharedGatingConditions(paths, readPredicate) {
     return [];
   }
   const shared = new Set(first.map(keyOf2));
-  for (const path of rest) {
-    const here = new Set(path.map(keyOf2));
+  for (const path3 of rest) {
+    const here = new Set(path3.map(keyOf2));
     for (const value of shared) {
       if (!here.has(value)) {
         shared.delete(value);
@@ -1057,6 +1151,841 @@ function valueToReadFurtherFrom(reading) {
   return reading.kind === "written" ? reading.value : null;
 }
 
+// src/adapterStamp.ts
+var import_node_crypto = require("crypto");
+var import_node_fs = __toESM(require("fs"), 1);
+var import_node_module = require("module");
+var import_node_path = __toESM(require("path"), 1);
+var import_node_url = require("url");
+var import_meta = {};
+var ANALYSIS_PACKAGES = [
+  "@suss/extractor",
+  "@suss/resolution",
+  "@suss/datalog",
+  "@suss/behavioral-ir"
+];
+var SOURCE_STAMP = { kind: "source" };
+function createAdapterStamp(config) {
+  let cachedCodeStamp = null;
+  let saidWhyNoCache = false;
+  function codeStamp() {
+    if (cachedCodeStamp !== null) {
+      return cachedCodeStamp;
+    }
+    cachedCodeStamp = readAdapterCodeStamp(config.moduleUrl);
+    return cachedCodeStamp;
+  }
+  function packsDigest(packVersions) {
+    const sortedPacks = [...packVersions].map((p) => `${p.name}@${p.version ?? "unset"}`).sort();
+    const stamp = codeStamp();
+    const adapterStamp = stamp.kind === "bundle" ? `adapter@${config.version}+${stamp.hash}` : `adapter@${config.version}+source`;
+    return `${adapterStamp}|${sortedPacks.join(",")}`;
+  }
+  function declineWhenRunFromSource(cacheDir) {
+    if (cacheDir === null || codeStamp().kind === "bundle") {
+      return cacheDir;
+    }
+    if (!saidWhyNoCache) {
+      saidWhyNoCache = true;
+      process.stderr.write(
+        "[suss] extraction cache off: this process loaded the adapter from source, where nothing can tell one build of it from another. Run the built adapter to cache.\n"
+      );
+    }
+    return null;
+  }
+  return { codeStamp, packsDigest, declineWhenRunFromSource };
+}
+function readAdapterCodeStamp(moduleUrl) {
+  try {
+    const selfPath = (0, import_node_url.fileURLToPath)(moduleUrl);
+    const hash = computeDistHashFrom(import_node_path.default.dirname(selfPath));
+    return hash.length > 0 ? { kind: "bundle", hash } : SOURCE_STAMP;
+  } catch {
+    return SOURCE_STAMP;
+  }
+}
+function computeDistHashFrom(dir) {
+  const candidates = [import_node_path.default.join(dir, "index.js"), import_node_path.default.join(dir, "index.cjs")];
+  for (const candidate of candidates) {
+    if (!import_node_fs.default.existsSync(candidate)) {
+      continue;
+    }
+    return computeContentHash([candidate, ...analysisBundles()]);
+  }
+  return "";
+}
+function computeContentHash(paths) {
+  if (paths.length === 0) {
+    return "";
+  }
+  const hash = (0, import_node_crypto.createHash)("sha256");
+  for (const file of paths) {
+    try {
+      hash.update(import_node_fs.default.readFileSync(file));
+    } catch {
+      return "";
+    }
+  }
+  return hash.digest("hex").slice(0, 16);
+}
+function projectFileStamp(paths) {
+  if (paths.length === 0) {
+    return "none";
+  }
+  const hash = (0, import_node_crypto.createHash)("sha256");
+  for (const file of [...paths].sort()) {
+    hash.update(file);
+    hash.update("\0");
+    try {
+      hash.update(import_node_fs.default.readFileSync(file));
+    } catch {
+      hash.update("absent");
+    }
+  }
+  return hash.digest("hex").slice(0, 16);
+}
+function runDigest(packsDigest, packs, files) {
+  const inputs = packs.flatMap((pack) => pack.discoveryInputs?.(files) ?? []);
+  return `${packsDigest}|reads:${projectFileStamp(inputs)}`;
+}
+function analysisBundles() {
+  const require2 = (0, import_node_module.createRequire)(import_meta.url);
+  const found = [];
+  for (const name of ANALYSIS_PACKAGES) {
+    try {
+      found.push(require2.resolve(name));
+    } catch {
+    }
+  }
+  return found;
+}
+
+// src/cache.ts
+var import_node_crypto2 = require("crypto");
+var import_promises = __toESM(require("fs/promises"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
+var SCHEMA_VERSION = "7";
+var MAX_ENTRIES = 2;
+var ENTRY_PREFIX = "key-";
+var ENTRY_DIR_NAME = new RegExp(`^${ENTRY_PREFIX}[0-9a-f]{16}$`);
+function createCacheLayer(cacheDir) {
+  if (cacheDir === null) {
+    return {
+      tryHit: async () => null,
+      lookup: async () => ({
+        kind: "miss",
+        diagnostic: { kind: "miss", missReason: "no-manifest" }
+      }),
+      plan: async () => null,
+      write: async () => {
+      }
+    };
+  }
+  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(
+        import_node_path2.default.join(entryDir, "manifest.json")
+      );
+      if (manifest === null) {
+        return missDiag(await describeAbsentEntry(cacheDir));
+      }
+      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" }
+      };
+    },
+    async plan(input) {
+      const entryDir = entryDirFor(cacheDir, input);
+      const manifest = await readManifest(
+        import_node_path2.default.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)) {
+        return null;
+      }
+      await markUsed(entryDir);
+      return buildPlan(manifest, await resolveFileStamps(input));
+    },
+    async write(input, summaries, attribution) {
+      const entryDir = entryDirFor(cacheDir, input);
+      const previous = await readManifest(
+        import_node_path2.default.join(entryDir, "manifest.json")
+      );
+      const configStamp = await stampConfigFile(input.configPath);
+      const files = await hashStamps(await resolveFileStamps(input), previous);
+      const manifest = {
+        schemaVersion: SCHEMA_VERSION,
+        adapterPacksDigest: input.adapterPacksDigest,
+        configStamp,
+        files,
+        summaries,
+        ...attribution === void 0 ? {} : encodeAttribution(attribution)
+      };
+      await import_promises.default.mkdir(entryDir, { recursive: true });
+      await import_promises.default.writeFile(
+        import_node_path2.default.join(entryDir, "manifest.json"),
+        JSON.stringify(manifest)
+      );
+      await evictOldEntries(cacheDir, entryDir);
+    }
+  };
+}
+async function buildPlan(manifest, currentStamps) {
+  const stored = new Map(manifest.files.map((f) => [f.path, f]));
+  const current = new Map(currentStamps.map((f) => [f.path, f]));
+  const changed = /* @__PURE__ */ new Set();
+  const removed = /* @__PURE__ */ new Set();
+  for (const p of stored.keys()) {
+    if (!current.has(p)) {
+      removed.add(p);
+    }
+  }
+  const toVerify = [];
+  for (const [p, stamp] of current) {
+    const before = stored.get(p);
+    if (before === void 0) {
+      changed.add(p);
+    } else if (!fileStampEquals(before, stamp)) {
+      if (before.contentHash === void 0) {
+        changed.add(p);
+      } else {
+        toVerify.push(p);
+      }
+    }
+  }
+  await Promise.all(
+    toVerify.map(async (p) => {
+      const hash = await hashFile(p);
+      if (hash === null || hash !== stored.get(p)?.contentHash) {
+        changed.add(p);
+      }
+    })
+  );
+  const roots = /* @__PURE__ */ new Map();
+  const rootNames = manifest.roots ?? [];
+  const depPaths = manifest.depPaths ?? [];
+  let rootsDeclined = 0;
+  rootNames.forEach((rootPath, i) => {
+    const meta = manifest.rootMeta?.[i];
+    if (meta === void 0) {
+      return;
+    }
+    if (!meta.cacheable) {
+      rootsDeclined += 1;
+    }
+    roots.set(rootPath, {
+      path: rootPath,
+      cacheable: meta.cacheable,
+      deps: meta.deps.flatMap((d) => {
+        const p = depPaths[d];
+        return p === void 0 ? [] : [p];
+      }),
+      claims: meta.claims,
+      meta: meta.meta,
+      packs: meta.packs
+    });
+  });
+  const validRoots = /* @__PURE__ */ new Set();
+  for (const [rootPath, record] of roots) {
+    if (!record.cacheable || !current.has(rootPath)) {
+      continue;
+    }
+    if (changed.has(rootPath)) {
+      continue;
+    }
+    const depMoved = record.deps.some((d) => changed.has(d) || removed.has(d));
+    if (!depMoved) {
+      validRoots.add(rootPath);
+    }
+  }
+  const owners = manifest.owners ?? [];
+  return {
+    changed,
+    removed,
+    roots,
+    validRoots,
+    rootsDeclined,
+    reuse(valid) {
+      const summaries = [];
+      const reusedOwners = [];
+      manifest.summaries.forEach((summary, i) => {
+        const ownerPaths = (owners[i] ?? []).flatMap((o) => {
+          const p = rootNames[o];
+          return p === void 0 ? [] : [p];
+        });
+        if (ownerPaths.some((p) => valid.has(p))) {
+          summaries.push(summary);
+          reusedOwners.push(ownerPaths.filter((p) => valid.has(p)));
+        }
+      });
+      return { summaries, owners: reusedOwners };
+    },
+    allSummaries() {
+      return manifest.summaries;
+    },
+    attribution() {
+      return {
+        roots: [...roots.values()],
+        owners: owners.map(
+          (ownerIds) => ownerIds.flatMap((o) => {
+            const p = rootNames[o];
+            return p === void 0 ? [] : [p];
+          })
+        )
+      };
+    }
+  };
+}
+function encodeAttribution(attribution) {
+  const roots = attribution.roots.map((r) => r.path);
+  const rootIndex = new Map(roots.map((p, i) => [p, i]));
+  const depIndex = /* @__PURE__ */ new Map();
+  const depPaths = [];
+  const depIdOf = (p) => {
+    const existing = depIndex.get(p);
+    if (existing !== void 0) {
+      return existing;
+    }
+    const id = depPaths.length;
+    depPaths.push(p);
+    depIndex.set(p, id);
+    return id;
+  };
+  const rootMeta = attribution.roots.map((r) => ({
+    cacheable: r.cacheable,
+    deps: r.deps.map(depIdOf),
+    claims: r.claims,
+    meta: r.meta,
+    packs: r.packs
+  }));
+  const owners = attribution.owners.map(
+    (ownerPaths) => ownerPaths.flatMap((p) => {
+      const i = rootIndex.get(p);
+      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 import_promises.default.readFile(filePath);
+    return (0, import_node_crypto2.createHash)("sha256").update(content).digest("hex").slice(0, 16);
+  } catch {
+    return null;
+  }
+}
+async function describeAbsentEntry(cacheDir) {
+  try {
+    const entries = await import_promises.default.readdir(cacheDir, { withFileTypes: true });
+    return entries.some((e) => e.isDirectory() && isEntryDir(e.name)) ? "key-changed" : "no-manifest";
+  } catch {
+    return "no-manifest";
+  }
+}
+function entryDirFor(cacheDir, input) {
+  const key = [
+    SCHEMA_VERSION,
+    input.adapterPacksDigest,
+    input.configPath ?? ""
+  ].join(" ");
+  const name = (0, import_node_crypto2.createHash)("sha256").update(key).digest("hex").slice(0, 16);
+  return import_node_path2.default.join(cacheDir, `${ENTRY_PREFIX}${name}`);
+}
+function isEntryDir(name) {
+  return ENTRY_DIR_NAME.test(name);
+}
+async function markUsed(entryDir) {
+  const now = /* @__PURE__ */ new Date();
+  try {
+    await import_promises.default.utimes(entryDir, now, now);
+  } catch {
+  }
+}
+async function evictOldEntries(cacheDir, keepDir) {
+  try {
+    await import_promises.default.rm(import_node_path2.default.join(cacheDir, "manifest.json"), { force: true });
+    const entries = await import_promises.default.readdir(cacheDir, { withFileTypes: true });
+    const dirs = await Promise.all(
+      entries.filter((e) => e.isDirectory() && isEntryDir(e.name)).map(async (e) => {
+        const dir = import_node_path2.default.join(cacheDir, e.name);
+        const stat = await import_promises.default.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) => import_promises.default.rm(d.dir, { recursive: true, force: true }))
+    );
+  } catch {
+  }
+}
+function missDiag(reason) {
+  return {
+    kind: "miss",
+    diagnostic: { kind: "miss", missReason: reason }
+  };
+}
+async function readManifest(manifestPath) {
+  try {
+    const raw = await import_promises.default.readFile(manifestPath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function stampConfigFile(configPath) {
+  if (configPath === void 0) {
+    return null;
+  }
+  try {
+    const stat = await import_promises.default.stat(configPath);
+    return { path: configPath, mtimeMs: stat.mtimeMs, size: stat.size };
+  } catch {
+    return null;
+  }
+}
+async function resolveFileStamps(input) {
+  const stamped = await Promise.all(
+    input.files.map(async (p) => {
+      try {
+        const stat = await import_promises.default.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
+var import_behavioral_ir3 = require("@suss/behavioral-ir");
+var emptyTally = () => ({
+  candidateFiles: 0,
+  unitsDiscovered: 0,
+  unitsInGatedFiles: 0,
+  effectsRecognized: 0,
+  unitsClaimed: 0,
+  selfCollisions: 0,
+  summariesProduced: 0,
+  failures: [],
+  helpersMatched: /* @__PURE__ */ new Set()
+});
+function recordPackFailure(tally, failure) {
+  const message = failure.error instanceof Error ? failure.error.message : String(failure.error);
+  tally?.failures.push({
+    hook: failure.hook,
+    file: failure.file,
+    message
+  });
+  return `[suss] pack "${failure.pack}" threw from ${failure.hook} while reading ${failure.file}: ${message}
+`;
+}
+function createPackTallies(packs) {
+  const tallies = /* @__PURE__ */ new Map();
+  for (const pack of packs) {
+    tallies.set(pack.name, emptyTally());
+  }
+  return tallies;
+}
+function tallyUnit(tallies, recognition) {
+  const tally = recognition === void 0 ? void 0 : tallies.get(recognition);
+  if (tally === void 0) {
+    return;
+  }
+  tally.unitsDiscovered += 1;
+  tally.summariesProduced += 1;
+}
+var emptyCounts = () => ({
+  bound: 0,
+  providers: 0,
+  withBehavior: 0
+});
+function summaryCountsByPack(summaries) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const summary of summaries) {
+    const recognition = summary.identity.boundaryBinding?.recognition;
+    if (recognition === void 0 || recognition === null) {
+      continue;
+    }
+    const entry = counts.get(recognition) ?? emptyCounts();
+    entry.bound += 1;
+    if (import_behavioral_ir3.BOUNDARY_ROLE[summary.kind] === "provider") {
+      entry.providers += 1;
+    }
+    if (summary.transitions.length > 0) {
+      entry.withBehavior += 1;
+    }
+    counts.set(recognition, entry);
+  }
+  return counts;
+}
+function buildUngatedExtractionReport(args) {
+  const bySummary = summaryCountsByPack(args.summaries);
+  const packFunnels = args.packs.map((pack) => {
+    const tally = args.tallies.get(pack.name) ?? emptyTally();
+    const counted = bySummary.get(pack.name) ?? emptyCounts();
+    return {
+      pack: pack.name,
+      version: pack.version,
+      discovers: pack.discovers,
+      recognizes: false,
+      gates: [],
+      unresolvedGates: [],
+      candidateFiles: args.filesWalked,
+      unitsDiscovered: tally.unitsDiscovered,
+      unitsInGatedFiles: 0,
+      effectsRecognized: 0,
+      unitsClaimed: tally.unitsDiscovered,
+      selfCollisions: 0,
+      summariesProduced: tally.summariesProduced,
+      failures: tally.failures,
+      helpersUnmatched: [],
+      summariesBound: counted.bound,
+      providerSummaries: counted.providers,
+      summariesWithBehavior: counted.withBehavior,
+      declarations: null
+    };
+  });
+  return {
+    filesInProject: null,
+    filesWalked: args.filesWalked,
+    packs: packFunnels,
+    summaries: args.summaries.length,
+    filesWithUnreadableExports: [],
+    reassignedNamesUnstated: 0,
+    emptyStage: args.summaries.length === 0 ? firstEmptyUngatedStage(packFunnels, args.filesWalked) : null
+  };
+}
+function firstEmptyUngatedStage(packs, filesWalked) {
+  if (filesWalked === 0) {
+    return "candidateFiles";
+  }
+  if (packs.every((p) => p.unitsDiscovered === 0)) {
+    return "discovery";
+  }
+  return "assembly";
+}
+
+// src/packHealth.ts
+function stagesOf(funnel) {
+  const stages = [];
+  const gateSaysSomething = funnel.gates.length > 0 && funnel.unresolvedGates.length === 0;
+  if (funnel.recognizes && !funnel.discovers && gateSaysSomething) {
+    stages.push({
+      from: { count: funnel.unitsInGatedFiles, name: "unit bodies" },
+      to: { count: funnel.effectsRecognized, name: "effects" }
+    });
+  }
+  if (funnel.discovers && gateSaysSomething) {
+    stages.push({
+      from: { count: funnel.candidateFiles, name: "source files" },
+      to: { count: funnel.unitsDiscovered, name: "units" }
+    });
+  }
+  stages.push(
+    {
+      from: { count: funnel.unitsClaimed, name: "units" },
+      to: { count: funnel.summariesBound, name: "summaries" }
+    },
+    {
+      from: { count: funnel.summariesBound, name: "summaries" },
+      to: { count: funnel.summariesWithBehavior, name: "transitions" }
+    }
+  );
+  return stages;
+}
+function funnelDrops(packs) {
+  const violations = [];
+  for (const funnel of packs) {
+    for (const stage of stagesOf(funnel)) {
+      if (stage.from.count === 0 || stage.to.count > 0) {
+        continue;
+      }
+      violations.push({
+        label: funnel.pack,
+        detail: `${stage.from.count} ${stage.from.name} -> 0 ${stage.to.name}`
+      });
+    }
+  }
+  return violations;
+}
+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.
+    funnel.effectsRecognized === 0
+  ).map((funnel) => ({
+    label: funnel.pack,
+    detail: `${funnel.candidateFiles} gated files, and no pack in this run discovered a unit in them. ${funnel.pack} reads calls inside units another pack finds, so add the pack that finds this project's handlers (-f express, -f fastify, ...), or run suss init to work out which.`
+  }));
+}
+function helpersThatMatchedNothing(packs) {
+  return packs.flatMap(
+    (funnel) => funnel.helpersUnmatched.map((helper) => ({
+      label: funnel.pack,
+      detail: `${helper} matched no call in this run, so whatever it registers is missing. suss read that helper out of the project and then failed to match a call to it, which is a bug in suss rather than in your code.`
+    }))
+  );
+}
+function unversionedPacks(packs) {
+  return packs.filter((funnel) => funnel.version === null).map((funnel) => ({
+    label: funnel.pack,
+    detail: "no version declared"
+  }));
+}
+function selfCollisions(packs) {
+  return packs.filter((funnel) => funnel.selfCollisions > 0).map((funnel) => ({
+    label: funnel.pack,
+    detail: `${funnel.selfCollisions} ${funnel.selfCollisions === 1 ? "unit" : "units"} matched twice, second dropped`
+  }));
+}
+function threwWhileReading(packs) {
+  return packs.filter((funnel) => funnel.failures.length > 0).map((funnel) => {
+    const first = funnel.failures[0];
+    const rest = funnel.failures.length - 1;
+    const alsoIn = rest > 0 ? ` (+${rest} more)` : "";
+    return {
+      label: funnel.pack,
+      detail: `${first.hook} on ${first.file}${alsoIn}: ${first.message}`
+    };
+  });
+}
+function packGradients(report) {
+  const gradients = [];
+  for (const funnel of report.packs) {
+    if (funnel.declarations === null) {
+      continue;
+    }
+    gradients.push(gradientOf(funnel.pack, funnel.declarations.declarations));
+  }
+  return gradients;
+}
+function gradientOf(pack, declarations) {
+  const gradient = {
+    pack,
+    dataLinks: 0,
+    functionLinks: [],
+    astLinks: [],
+    withoutExample: []
+  };
+  for (const declaration of declarations) {
+    gradient.dataLinks += declaration.dataLinks;
+    for (const question of declaration.functionLinks) {
+      gradient.functionLinks.push(`${declaration.name}.${question}`);
+    }
+    for (const question of declaration.astLinks) {
+      gradient.astLinks.push(`${declaration.name}.${question}`);
+    }
+    if (declaration.example === null) {
+      gradient.withoutExample.push(declaration.name);
+    }
+  }
+  return gradient;
+}
+function opaqueLinks(gradients) {
+  return gradients.filter((gradient) => gradient.functionLinks.length > 0).map((gradient) => ({
+    label: gradient.pack,
+    detail: `${gradient.functionLinks.join(", ")} (${gradient.dataLinks} data)`
+  }));
+}
+function reachesTheSyntaxTree(gradients) {
+  return gradients.filter((gradient) => gradient.astLinks.length > 0).map((gradient) => ({
+    label: gradient.pack,
+    detail: gradient.astLinks.join(", ")
+  }));
+}
+function undocumentedDeclarations(gradients) {
+  return gradients.filter((gradient) => gradient.withoutExample.length > 0).map((gradient) => ({
+    label: gradient.pack,
+    detail: gradient.withoutExample.join(", ")
+  }));
+}
+function evaluatePackHealth(report) {
+  const gradients = packGradients(report);
+  return [
+    {
+      name: "no pack throws while it reads",
+      code: "threw",
+      audience: "run",
+      violations: threwWhileReading(report.packs)
+    },
+    {
+      name: "no pack finds something and records nothing",
+      code: "no-output",
+      audience: "run",
+      violations: funnelDrops(report.packs)
+    },
+    {
+      name: "no pack collides with itself",
+      code: "double-match",
+      audience: "run",
+      violations: selfCollisions(report.packs)
+    },
+    {
+      name: "every recognizer had units to look inside",
+      code: "no-units",
+      audience: "run",
+      violations: recognizersWithNoUnits(report.packs)
+    },
+    {
+      name: "every registration helper the run read matched a call",
+      code: "no-helper",
+      audience: "run",
+      violations: helpersThatMatchedNothing(report.packs)
+    },
+    {
+      name: "every pack declares a version",
+      code: "no-version",
+      audience: "pack",
+      violations: unversionedPacks(report.packs)
+    },
+    {
+      name: "every link a declared pack states is data",
+      code: "fn-link",
+      audience: "pack",
+      violations: opaqueLinks(gradients)
+    },
+    {
+      name: "no declared pack reads the syntax tree",
+      code: "ast-link",
+      audience: "pack",
+      violations: reachesTheSyntaxTree(gradients)
+    },
+    {
+      name: "every declaration states an example",
+      code: "no-example",
+      audience: "pack",
+      violations: undocumentedDeclarations(gradients)
+    }
+  ];
+}
+function formatPackHealth(checks, audiences) {
+  const fired = checks.filter(
+    (check) => check.violations.length > 0 && audiences.includes(check.audience)
+  );
+  if (fired.length === 0) {
+    return "";
+  }
+  const rows = fired.flatMap(
+    (check) => check.violations.map((violation) => ({
+      code: check.code,
+      pack: violation.label,
+      detail: violation.detail
+    }))
+  );
+  const codeWidth = Math.max(...rows.map((row) => row.code.length));
+  const packWidth = Math.max(...rows.map((row) => row.pack.length));
+  const lines = ["", `Pack health (${rows.length}):`];
+  for (const row of rows) {
+    lines.push(
+      `  ${row.code.padEnd(codeWidth)}  ${row.pack.padEnd(packWidth)}  ${row.detail}`
+    );
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/timing.ts
+function createTimer() {
+  const phases = /* @__PURE__ */ new Map();
+  const start = performance.now();
+  function record(label, deltaMs) {
+    const existing = phases.get(label);
+    if (existing === void 0) {
+      phases.set(label, { durationMs: deltaMs, calls: 1 });
+    } else {
+      existing.durationMs += deltaMs;
+      existing.calls += 1;
+    }
+  }
+  return {
+    time(label, fn) {
+      const t0 = performance.now();
+      try {
+        return fn();
+      } finally {
+        record(label, performance.now() - t0);
+      }
+    },
+    async timeAsync(label, fn) {
+      const t0 = performance.now();
+      try {
+        return await fn();
+      } finally {
+        record(label, performance.now() - t0);
+      }
+    },
+    report() {
+      const totalMs = performance.now() - start;
+      const ordered = [...phases.entries()].map(([label, s]) => ({
+        label,
+        durationMs: s.durationMs,
+        calls: s.calls
+      })).sort((a, b) => b.durationMs - a.durationMs);
+      return { totalMs, phases: ordered };
+    }
+  };
+}
+function noopTimer() {
+  return {
+    time(_label, fn) {
+      return fn();
+    },
+    async timeAsync(_label, fn) {
+      return fn();
+    },
+    report() {
+      return { totalMs: 0, phases: [] };
+    }
+  };
+}
+
 // src/index.ts
 function valuesOfOutput(output) {
   if (output.type === "response" && output.statusCode !== null) {
@@ -1069,7 +1998,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 = (0, import_node_crypto.createHash)("sha1").update(conditionSig).digest("hex").slice(0, 7);
+  const conditionHash = (0, import_node_crypto3.createHash)("sha1").update(conditionSig).digest("hex").slice(0, 7);
   return `${functionName}:${terminal.kind}:${statusKey}:${conditionHash}`;
 }
 function collapseReading(table, reading) {
@@ -1193,22 +2122,22 @@ function buildMetadata(raw) {
   let metadata = {};
   const http = buildHttpMetadataValue(raw);
   if (http !== null) {
-    metadata = (0, import_behavioral_ir3.withHttpMetadata)(metadata, http);
+    metadata = (0, import_behavioral_ir4.withHttpMetadata)(metadata, http);
   }
   const graphql = buildGraphqlMetadataValue(raw);
   if (graphql !== null) {
-    metadata = (0, import_behavioral_ir3.withGraphqlMetadata)(metadata, graphql);
+    metadata = (0, import_behavioral_ir4.withGraphqlMetadata)(metadata, graphql);
   }
   if (raw.sourceDocumentLabel !== void 0) {
-    metadata = (0, import_behavioral_ir3.withSourceDocumentMetadata)(metadata, {
+    metadata = (0, import_behavioral_ir4.withSourceDocumentMetadata)(metadata, {
       label: raw.sourceDocumentLabel
     });
   }
   if (raw.mount !== void 0) {
-    metadata = (0, import_behavioral_ir3.withMountMetadata)(metadata, raw.mount);
+    metadata = (0, import_behavioral_ir4.withMountMetadata)(metadata, raw.mount);
   }
   if (raw.wrappers !== void 0 && raw.wrappers.length > 0) {
-    metadata = (0, import_behavioral_ir3.withWrapperMetadata)(metadata, { applied: raw.wrappers });
+    metadata = (0, import_behavioral_ir4.withWrapperMetadata)(metadata, { applied: raw.wrappers });
   }
   return Object.keys(metadata).length > 0 ? metadata : null;
 }
@@ -1258,7 +2187,7 @@ function answersWithHttpResponses(raw) {
   if (raw.boundaryBinding === null || raw.boundaryBinding === void 0) {
     return true;
   }
-  return (0, import_behavioral_ir3.exchangesHttpResponses)(raw.boundaryBinding);
+  return (0, import_behavioral_ir4.exchangesHttpResponses)(raw.boundaryBinding);
 }
 function detectGaps(raw, transitions, options) {
   if (options.gapHandling === "silent") {
@@ -1473,6 +2402,7 @@ function paramToInput(param) {
 0 && (module.exports = {
   IdMap,
   IdSet,
+  MAX_ENTRIES,
   MAX_PATHS,
   PathBudgetExceeded,
   SKIP_CHILDREN,
@@ -1482,25 +2412,44 @@ function paramToInput(param) {
   andThenReading,
   assembleSummary,
   assessConfidence,
+  buildUngatedExtractionReport,
   composeWrappers,
+  computeContentHash,
+  computeDistHashFrom,
   configuredCallOption,
+  createAdapterStamp,
+  createCacheLayer,
+  createPackTallies,
+  createTimer,
   detectGaps,
   effectToIR,
+  emptyTally,
   enumerateOrDegrade,
   enumerateStructuredPaths,
+  evaluatePackHealth,
   firstWrittenReading,
+  formatPackHealth,
   guardsHoldOn,
   httpRouteDiscovery,
   makeTransitionId,
   mapReading,
+  moduleInitStructure,
+  noopTimer,
+  packGradients,
   paramToInput,
+  projectFileStamp,
   rawConditionToPredicate,
+  recordPackFailure,
   registrationHelperDiscovery,
   routeHelperIndex,
+  runDigest,
   runsBefore,
   scopeOption,
   sharedGatingConditions,
+  stampModuleImports,
   storageSystemOption,
+  summaryCountsByPack,
+  tallyUnit,
   terminalToOutput,
   unreadableReading,
   unwrapJsonStringify,