@suss/extractor 0.35.1 → 0.36.0

package/dist/index.cjs

@@ -48,6 +48,7 @@ __export(index_exports, {
   assembleSummary: () => assembleSummary,
   assessConfidence: () => assessConfidence,
   buildUngatedExtractionReport: () => buildUngatedExtractionReport,
+  callSiteKey: () => callSiteKey,
   chosenCacheRoot: () => chosenCacheRoot,
   commonDirectoryOf: () => commonDirectoryOf,
   composeWrappers: () => composeWrappers,
@@ -59,23 +60,28 @@ __export(index_exports, {
   createCodeHasher: () => createCodeHasher,
   createPackTallies: () => createPackTallies,
   createTimer: () => createTimer,
+  describeMissingPath: () => describeMissingPath,
   detectGaps: () => detectGaps,
   effectToIR: () => effectToIR,
+  effectsFiringOn: () => effectsFiringOn,
   emptyTally: () => emptyTally,
   enumerateOrDegrade: () => enumerateOrDegrade,
   enumerateStructuredPaths: () => enumerateStructuredPaths,
   evaluatePackHealth: () => evaluatePackHealth,
   extractionCacheDirFor: () => extractionCacheDirFor,
   extractionConfigStamp: () => extractionConfigStamp,
+  firesOn: () => firesOn,
   firstWrittenReading: () => firstWrittenReading,
   formatPackHealth: () => formatPackHealth,
   guardsHoldOn: () => guardsHoldOn,
   helperPathsOnVariables: () => helperPathsOnVariables,
   httpRouteDiscovery: () => httpRouteDiscovery,
   isListedTestFile: () => isListedTestFile,
+  libraryEnvReadMarker: () => libraryEnvReadMarker,
   liveRecordFor: () => liveRecordFor,
   makeIgnoredDirectory: () => makeIgnoredDirectory,
   makeTransitionId: () => makeTransitionId,
+  mapFolderFor: () => mapFolderFor,
   mapReading: () => mapReading,
   markReturnsAsExitCode: () => markReturnsAsExitCode,
   matchesTestFileName: () => matchesTestFileName,
@@ -83,10 +89,13 @@ __export(index_exports, {
   moduleInitStructure: () => moduleInitStructure,
   moduleOfFile: () => moduleOfFile,
   noopTimer: () => noopTimer,
+  numberRepeatedCallSites: () => numberRepeatedCallSites,
   ownersWhereWritten: () => ownersWhereWritten,
   packConfigCheck: () => packConfigCheck,
   packGradients: () => packGradients,
+  packPathCheck: () => packPathCheck,
   paramToInput: () => paramToInput,
+  placeTerminals: () => placeTerminals,
   processCodeHasher: () => processCodeHasher,
   projectFileStamp: () => projectFileStamp,
   rawConditionToPredicate: () => rawConditionToPredicate,
@@ -104,6 +113,7 @@ __export(index_exports, {
   stampMayMissAWrite: () => stampMayMissAWrite,
   stampModuleImports: () => stampModuleImports,
   stampModules: () => stampModules,
+  statementSites: () => statementSites,
   storageSystemOption: () => storageSystemOption,
   summaryCountsByPack: () => summaryCountsByPack,
   tallyUnit: () => tallyUnit,
@@ -117,8 +127,8 @@ __export(index_exports, {
   writtenReading: () => writtenReading
 });
 module.exports = __toCommonJS(index_exports);
-var import_node_crypto7 = require("crypto");
-var import_behavioral_ir8 = require("@suss/behavioral-ir");
+var import_node_crypto8 = require("crypto");
+var import_behavioral_ir10 = require("@suss/behavioral-ir");
 
 // src/contractStatusGaps.ts
 var import_behavioral_ir = require("@suss/behavioral-ir");
@@ -271,27 +281,66 @@ function mergeInputReads(derived, syntactic) {
   return [...found.values()];
 }
 
-// src/composeWrappers.ts
+// src/callSiteGroup.ts
+var import_node_crypto = require("crypto");
 var import_behavioral_ir2 = require("@suss/behavioral-ir");
+function callSiteKey(effect) {
+  const callee = calleeOf(effect);
+  const written = callee === void 0 ? effect : { ...effect, callee: (0, import_behavioral_ir2.normalizeCalleeText)(callee) };
+  const hash = (0, import_node_crypto.createHash)("sha1").update((0, import_behavioral_ir2.effectKey)(written)).digest("hex").slice(0, 7);
+  return callee === void 0 ? hash : `${(0, import_behavioral_ir2.normalizeCalleeText)(callee)}:${hash}`;
+}
+function calleeOf(effect) {
+  return effect.type === "interaction" || effect.type === "invocation" ? effect.callee : void 0;
+}
+function numberRepeatedCallSites(sites) {
+  const taken = /* @__PURE__ */ new Map();
+  return sites.map((entries) => {
+    const ids = /* @__PURE__ */ new Map();
+    for (const key of new Set(
+      entries.flatMap((entry) => groupIdOf(entry.effect))
+    )) {
+      const count = (taken.get(key) ?? 0) + 1;
+      taken.set(key, count);
+      ids.set(key, count === 1 ? key : `${key}#${count}`);
+    }
+    return entries.map((entry) => ({
+      ...entry,
+      effect: withGroupId(entry.effect, ids)
+    }));
+  });
+}
+function groupIdOf(effect) {
+  return effect.type === "interaction" && effect.groupId !== void 0 ? [effect.groupId] : [];
+}
+function withGroupId(effect, ids) {
+  if (effect.type !== "interaction" || effect.groupId === void 0) {
+    return effect;
+  }
+  return { ...effect, groupId: ids.get(effect.groupId) ?? effect.groupId };
+}
+
+// src/composeWrappers.ts
+var import_behavioral_ir3 = require("@suss/behavioral-ir");
 function composeWrappers(summaries, options = {}) {
-  const chain = (0, import_behavioral_ir2.wrapperIndex)(summaries);
+  const chain = (0, import_behavioral_ir3.wrapperIndex)(summaries);
   const keepGaps = options.gapHandling !== "silent";
   return summaries.map((summary) => composeOne(summary, chain, keepGaps));
 }
 function composeOne(summary, chain, keepGaps) {
-  const recorded = (0, import_behavioral_ir2.readWrapperMetadata)(summary);
+  const recorded = (0, import_behavioral_ir3.readWrapperMetadata)(summary);
   const applied = recorded?.applied ?? [];
   const covering = applied.filter(
     (reference) => coversUnit(reference, summary)
   );
   const narrowed = covering.length === applied.length ? summary : {
     ...summary,
-    metadata: (0, import_behavioral_ir2.withWrapperMetadata)(summary.metadata, {
+    metadata: (0, import_behavioral_ir3.withWrapperMetadata)(summary.metadata, {
       applied: covering
     })
   };
   const wrappers = covering.flatMap((reference) => {
-    const found = (0, import_behavioral_ir2.wrapperFor)(chain, reference);
+    const found = (0, import_behavioral_ir3.wrapperFor)(chain, reference);
     return found === void 0 ? [] : [{ reference, summary: found }];
   });
   if (wrappers.length === 0) {
@@ -356,8 +405,8 @@ function settledUncaught(transitions, wrappers) {
 function markedCaught(transition) {
   return {
     ...transition,
-    metadata: (0, import_behavioral_ir2.withWrapperMetadata)(transition.metadata, {
-      ...(0, import_behavioral_ir2.readWrapperMetadata)(transition),
+    metadata: (0, import_behavioral_ir3.withWrapperMetadata)(transition.metadata, {
+      ...(0, import_behavioral_ir3.readWrapperMetadata)(transition),
       caught: true
     })
   };
@@ -470,9 +519,9 @@ function catchMatch(reference, thrown) {
   return unread || reference.mayCatchAny === true ? "maybe" : "no";
 }
 function withContractStatusGaps(summary, composed, handled) {
-  const contract = (0, import_behavioral_ir2.readHttpMetadata)(summary)?.declaredContract;
+  const contract = (0, import_behavioral_ir3.readHttpMetadata)(summary)?.declaredContract;
   const binding = summary.identity.boundaryBinding;
-  if (contract === void 0 || binding !== null && !(0, import_behavioral_ir2.exchangesHttpResponses)(binding)) {
+  if (contract === void 0 || binding !== null && !(0, import_behavioral_ir3.exchangesHttpResponses)(binding)) {
     return summary.gaps;
   }
   const declared = {
@@ -497,12 +546,12 @@ function coversUnit(reference, summary) {
     return true;
   }
   const binding = summary.identity.boundaryBinding;
-  return binding !== null && (0, import_behavioral_ir2.withinScope)(binding, reference.scope);
+  return binding !== null && (0, import_behavioral_ir3.withinScope)(binding, reference.scope);
 }
 function attribute(transitions, reference, catchUncertain = false) {
   return transitions.map((transition) => ({
     ...transition,
-    metadata: (0, import_behavioral_ir2.withWrapperMetadata)(transition.metadata, {
+    metadata: (0, import_behavioral_ir3.withWrapperMetadata)(transition.metadata, {
       from: reference,
       ...catchUncertain ? { catchUncertain } : {}
     })
@@ -570,6 +619,22 @@ function modulesStamp(modules) {
 // src/effectGuards.ts
 var keyOf = (condition) => `${condition.polarity}:${condition.sourceText}`;
 var opposite = (condition) => `${condition.polarity === "positive" ? "negative" : "positive"}:${condition.sourceText}`;
+function firesOn(site, branch) {
+  const loop = branch.loopAround;
+  if (loop !== void 0 && site.line >= loop.start && site.line <= loop.end) {
+    return true;
+  }
+  if (!guardsHoldOn(site.preconditions, branch.conditions)) {
+    return false;
+  }
+  return runsBefore(
+    site.cleansUpFrom ?? site.line,
+    branch.terminal.location.end
+  );
+}
+function effectsFiringOn(placed, branch) {
+  return placed.filter((one) => firesOn(one.site, branch)).map((one) => one.effect);
+}
 function guardsHoldOn(preconditions, conditions) {
   if (preconditions === void 0 || preconditions.length === 0) {
     return true;
@@ -585,14 +650,14 @@ function runsBefore(effectLine, terminalEndLine) {
 
 // src/exitCode.ts
 var import_node_path2 = __toESM(require("path"), 1);
-var import_behavioral_ir3 = require("@suss/behavioral-ir");
+var import_behavioral_ir4 = require("@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 : import_node_path2.default.resolve(workspaceRoot, summary.location.file);
     markExitCodeFrom(
       summary,
-      span !== void 0 && returnsTheCode.has((0, import_behavioral_ir3.declarationKey)(file, span))
+      span !== void 0 && returnsTheCode.has((0, import_behavioral_ir4.declarationKey)(file, span))
     );
   }
 }
@@ -619,7 +684,7 @@ function markExitCodeFrom(summary, marked) {
 }
 
 // src/helperHandOff.ts
-var import_behavioral_ir4 = require("@suss/behavioral-ir");
+var import_behavioral_ir5 = require("@suss/behavioral-ir");
 var MAX_HELPER_PATHS = 16;
 function throughHelper(branch, at, helperBranches) {
   return helperBranches.map((helper) => {
@@ -637,16 +702,21 @@ function throughHelper(branch, at, helperBranches) {
         isDefault: branch.isDefault && helper.isDefault
       };
     }
+    const { loopAround, ...rest } = branch;
     return {
-      ...branch,
+      ...rest,
       ...reads,
       conditions,
       terminal: { ...helper.terminal, location: at },
       location: at,
+      ...loopAround !== void 0 && within(at, loopAround) ? { loopAround } : {},
       isDefault: false
     };
   });
 }
+function within(inner, outer) {
+  return inner.start >= outer.start && inner.end <= outer.end;
+}
 function mergeReadShapes(a, b) {
   if (a === null || b === null) {
     return a ?? b;
@@ -664,12 +734,11 @@ function mergeReadShapes(a, b) {
 function splitAtHandOffs(branch, sites, from = 0) {
   for (let index = from; index < sites.length; index++) {
     const site = sites[index];
-    const reached = site.alwaysRuns === true || runsBefore(site.line, branch.terminal.location.end);
-    if (!reached || !guardsHoldOn(site.preconditions, branch.conditions)) {
+    if (!firesOn(site, branch)) {
       continue;
     }
     return throughHelper(branch, site.at, site.helper).flatMap(
-      (path10) => path10.terminal === branch.terminal ? splitAtHandOffs(path10, sites, index + 1) : [path10]
+      (path11) => path11.terminal === branch.terminal ? splitAtHandOffs(path11, sites, index + 1) : [path11]
     );
   }
   return [branch];
@@ -685,7 +754,7 @@ function helperPathsOnVariables(helperBranches, passed) {
   const variables = new Set(passed.values());
   const testsWhatItGot = renamed.some(
     (branch) => branch.conditions.some(
-      (condition) => condition.structured !== null && (0, import_behavioral_ir4.predicateRefs)(condition.structured).some(
+      (condition) => condition.structured !== null && (0, import_behavioral_ir5.predicateRefs)(condition.structured).some(
         (ref) => variables.has(rootName(ref) ?? "")
       )
     )
@@ -707,7 +776,7 @@ function onCallerVariables(predicate, passed) {
     }
     return ref;
   };
-  return (0, import_behavioral_ir4.replacePredicateRefs)(predicate, rename);
+  return (0, import_behavioral_ir5.replacePredicateRefs)(predicate, rename);
 }
 function rootName(ref) {
   if (ref.type === "derived") {
@@ -716,6 +785,34 @@ function rootName(ref) {
   return ref.type === "dependency" ? ref.name : null;
 }
 
+// src/libraryEnvReads.ts
+var import_behavioral_ir6 = require("@suss/behavioral-ir");
+function libraryEnvReadMarker(recognition, declared, importer) {
+  return {
+    kind: "library",
+    location: { file: importer, range: { start: 0, end: 0 }, exportName: null },
+    identity: {
+      name: `${declared.module} env reads`,
+      exportPath: null,
+      boundaryBinding: (0, import_behavioral_ir6.functionCallBinding)({
+        transport: "in-process",
+        recognition
+      })
+    },
+    inputs: [],
+    transitions: [],
+    gaps: [],
+    confidence: { source: "declared", level: "high" },
+    metadata: {
+      libraryEnvReads: {
+        module: declared.module,
+        ...declared.prefixes !== void 0 ? { prefixes: declared.prefixes } : {},
+        ...declared.names !== void 0 ? { names: declared.names } : {}
+      }
+    }
+  };
+}
+
 // src/moduleImports.ts
 function stampModuleImports(summaries, importsOf2) {
   const byFile = /* @__PURE__ */ new Map();
@@ -969,7 +1066,7 @@ var configuredCallOption = import_zod.z.object({
 }).strict();
 
 // src/paths/enumeratePaths.ts
-var import_behavioral_ir5 = require("@suss/behavioral-ir");
+var import_behavioral_ir7 = require("@suss/behavioral-ir");
 var MAX_PATHS = 256;
 var UnmodeledFlow = class extends Error {
 };
@@ -1013,12 +1110,12 @@ var loopCompletedCond = (headerText, exit) => fixedCond(
   exit === "throw" ? "earlyThrow" : "earlyReturn"
 );
 var catchEntryCond = () => fixedCond(
-  { sourceText: import_behavioral_ir5.CATCH_ENTRY_TEXT, expression: null },
+  { sourceText: import_behavioral_ir7.CATCH_ENTRY_TEXT, expression: null },
   "positive",
   "catchBlock"
 );
-function classify(path10, home, isAncestorOrSelf) {
-  return path10.map((cond) => {
+function classify(path11, home, isAncestorOrSelf) {
+  return path11.map((cond) => {
     if (cond.branchStmt === null) {
       return cond.info;
     }
@@ -1090,9 +1187,9 @@ function limitOpenPaths(paths) {
     );
   }
 }
-function recordTerminal(ctx, terminal, home, path10) {
+function recordTerminal(ctx, terminal, home, path11) {
   chargeBudget(ctx.state);
-  const info = classify(path10, home, ctx.isAncestorOrSelf);
+  const info = classify(path11, home, ctx.isAncestorOrSelf);
   const existing = ctx.state.byTerminal.get(terminal) ?? [];
   existing.push(info);
   ctx.state.byTerminal.set(terminal, existing);
@@ -1103,15 +1200,15 @@ function containsTerminal(ctx, stmt) {
   }
   return childrenOf(stmt).some((child) => containsTerminal(ctx, child));
 }
-function stepIf(stmt, path10, ctx) {
+function stepIf(stmt, path11, ctx) {
   const thenExit = exitKindOfList(stmt.thenBody);
   const elseExit = stmt.elseBody === null ? null : exitKindOfList(stmt.elseBody);
   const thenPath = [
-    ...path10,
+    ...path11,
     branchCond(stmt, stmt.condition, "positive", elseExit)
   ];
   const elsePath = [
-    ...path10,
+    ...path11,
     branchCond(
       stmt,
       stmt.condition,
@@ -1128,7 +1225,7 @@ function stepIf(stmt, path10, ctx) {
   }
   return out;
 }
-function stepSwitch(stmt, path10, ctx) {
+function stepSwitch(stmt, path11, ctx) {
   const out = [];
   const negations = [];
   let defaultRanBody = false;
@@ -1138,7 +1235,7 @@ function stepSwitch(stmt, path10, ctx) {
     if (hasStrayBreak(group.body)) {
       throw new UnmodeledFlow("non-trailing break in switch clause");
     }
-    const groupPath = group.condition === null ? [...path10, ...negations] : [...path10, fixedCond(group.condition, "positive", "explicit")];
+    const groupPath = group.condition === null ? [...path11, ...negations] : [...path11, fixedCond(group.condition, "positive", "explicit")];
     const conts = enumerate(ctx, group.body, groupPath);
     if (conts.length > 0) {
       if (!group.hasTrailingBreak && !fallthroughSafe) {
@@ -1155,24 +1252,24 @@ function stepSwitch(stmt, path10, ctx) {
     }
   }
   if (!defaultRanBody) {
-    out.push([...path10, ...negations]);
+    out.push([...path11, ...negations]);
   }
   return out;
 }
-function stepLoop(stmt, path10, ctx) {
+function stepLoop(stmt, path11, ctx) {
   const bodyExit = exitKindOfList(stmt.body);
   if (containsTerminal(ctx, stmt)) {
     enumerate(ctx, stmt.body, [
-      ...path10,
+      ...path11,
       loopIterationCond(stmt.condition.sourceText)
     ]);
   }
   if (bodyExit !== null) {
-    return [[...path10, loopCompletedCond(stmt.condition.sourceText, bodyExit)]];
+    return [[...path11, loopCompletedCond(stmt.condition.sourceText, bodyExit)]];
   }
-  return [path10];
+  return [path11];
 }
-function stepTry(stmt, path10, ctx) {
+function stepTry(stmt, path11, ctx) {
   if (stmt.finallyBody !== null) {
     const finallyHasTerminal = stmt.finallyBody.some(
       (s) => containsTerminal(ctx, s)
@@ -1182,22 +1279,22 @@ function stepTry(stmt, path10, ctx) {
     }
   }
   const out = [];
-  out.push(...enumerate(ctx, stmt.tryBody, path10));
+  out.push(...enumerate(ctx, stmt.tryBody, path11));
   if (stmt.catchBody !== null) {
-    const catchPath = [...path10, catchEntryCond()];
+    const catchPath = [...path11, catchEntryCond()];
     out.push(...enumerate(ctx, stmt.catchBody, catchPath));
   }
   return out;
 }
-function stepExit(stmt, path10, ctx) {
+function stepExit(stmt, path11, ctx) {
   const collector = ctx.state.callbackExits[ctx.state.callbackExits.length - 1];
   if (collector !== void 0 && (stmt.exit === "return" || stmt.exit === "throw")) {
-    collector.push(path10);
+    collector.push(path11);
   }
   return [];
 }
-function stepOpaque(_stmt, path10, _ctx) {
-  return [path10];
+function stepOpaque(_stmt, path11, _ctx) {
+  return [path11];
 }
 var stepHandlers = {
   if: stepIf,
@@ -1207,20 +1304,20 @@ var stepHandlers = {
   exit: stepExit,
   opaque: stepOpaque
 };
-function stepCallback(ctx, body, path10) {
+function stepCallback(ctx, body, path11) {
   const exits = [];
   ctx.state.callbackExits.push(exits);
   let fellThrough;
   try {
-    fellThrough = enumerate(ctx, body, path10);
+    fellThrough = enumerate(ctx, body, path11);
   } finally {
     ctx.state.callbackExits.pop();
   }
   const out = [...fellThrough, ...exits];
-  return out.length === 0 ? [path10] : out;
+  return out.length === 0 ? [path11] : out;
 }
-function stepStatement(ctx, stmt, path10) {
-  let paths = [path10];
+function stepStatement(ctx, stmt, path11) {
+  let paths = [path11];
   for (const body of stmt.callbacks ?? []) {
     paths = paths.flatMap((each) => stepCallback(ctx, body, each));
     limitOpenPaths(paths);
@@ -1307,8 +1404,8 @@ function enumerate(ctx, stmts, prefix) {
   let frontiers = [[...prefix]];
   for (const stmt of stmts) {
     const nextFrontiers = [];
-    for (const path10 of mergeRejoined(frontiers, ctx.keepsArms)) {
-      nextFrontiers.push(...stepStatement(ctx, stmt, path10));
+    for (const path11 of mergeRejoined(frontiers, ctx.keepsArms)) {
+      nextFrontiers.push(...stepStatement(ctx, stmt, path11));
     }
     frontiers = nextFrontiers;
     limitOpenPaths(frontiers);
@@ -1332,6 +1429,39 @@ function buildParentMap(statements) {
   }
   return parentOf;
 }
+function placeTerminals(input, parentOf = buildParentMap(input.statements)) {
+  const placement = /* @__PURE__ */ new Map();
+  for (const [home, terminals] of input.terminalsByStmt) {
+    const placed = placementOf(home, parentOf);
+    if (placed.loopAround === void 0 && placed.cleansUpFrom === void 0) {
+      continue;
+    }
+    for (const terminal of terminals) {
+      placement.set(terminal, placed);
+    }
+  }
+  return placement;
+}
+function placementOf(home, parentOf) {
+  let loopAround = home.kind === "loop" ? home.lines : void 0;
+  let cleansUpFrom;
+  let child = home;
+  let parent = parentOf.get(home) ?? null;
+  while (parent !== null) {
+    if (parent.kind === "loop" && parent.lines !== void 0) {
+      loopAround = parent.lines;
+    }
+    if (parent.kind === "try" && parent.lines !== void 0 && (parent.finallyBody ?? []).includes(child)) {
+      cleansUpFrom = parent.lines.start;
+    }
+    child = parent;
+    parent = parentOf.get(parent) ?? null;
+  }
+  return {
+    ...loopAround === void 0 ? {} : { loopAround: { start: loopAround.start, end: loopAround.end } },
+    ...cleansUpFrom === void 0 ? {} : { cleansUpFrom }
+  };
+}
 function enumerateStructuredPaths(input) {
   const parentOf = buildParentMap(input.statements);
   const isAncestorOrSelf = (a, b) => {
@@ -1357,11 +1487,15 @@ function enumerateStructuredPaths(input) {
     isAncestorOrSelf
   };
   const continuations = withRejoined(enumerate(ctx, input.statements, []));
-  for (const path10 of continuations) {
+  for (const path11 of continuations) {
     chargeBudget(state);
-    state.fallthrough.push(classify(path10, null, isAncestorOrSelf));
+    state.fallthrough.push(classify(path11, null, isAncestorOrSelf));
   }
-  return { byTerminal: state.byTerminal, fallthrough: state.fallthrough };
+  return {
+    byTerminal: state.byTerminal,
+    fallthrough: state.fallthrough,
+    placement: placeTerminals(input, parentOf)
+  };
 }
 function enumerateOrDegrade(input, terminals) {
   try {
@@ -1381,9 +1515,28 @@ function enumerateOrDegrade(input, terminals) {
     for (const terminal of terminals) {
       byTerminal.set(terminal, [[marker]]);
     }
-    return { byTerminal, fallthrough: [[marker]], degraded: reason };
+    return {
+      byTerminal,
+      fallthrough: [[marker]],
+      placement: placeTerminals(input),
+      degraded: reason
+    };
   }
 }
+function enumerateCallStatements(input, terminals) {
+  const placement = placeTerminals(input);
+  const enumerable = new Map(
+    [...input.terminalsByStmt].filter(
+      ([, found]) => found.every(
+        (terminal) => placement.get(terminal)?.cleansUpFrom === void 0
+      )
+    )
+  );
+  return {
+    ...enumerateOrDegrade({ ...input, terminalsByStmt: enumerable }, terminals),
+    placement
+  };
+}
 function reasonToDegrade(error) {
   if (error instanceof PathBudgetExceeded) {
     return error.message === "" ? "path budget exceeded" : error.message;
@@ -1402,8 +1555,8 @@ function sharedGatingConditions(paths, readPredicate) {
     return [];
   }
   const shared = new Set(first.map(keyOf2));
-  for (const path10 of rest) {
-    const here = new Set(path10.map(keyOf2));
+  for (const path11 of rest) {
+    const here = new Set(path11.map(keyOf2));
     for (const value of shared) {
       if (!here.has(value)) {
         shared.delete(value);
@@ -1521,6 +1674,43 @@ function walkDescendants(root, carried, childrenOf2, visitor) {
   }
 }
 
+// src/paths/statementSites.ts
+function statementSites(nodes, reading) {
+  const statements = new IdMap();
+  const statementOfNode = new IdMap();
+  for (const node of nodes) {
+    const written = reading.statementOf(node);
+    if (written === null) {
+      continue;
+    }
+    const statement = statements.get(written) ?? written;
+    statements.set(statement, statement);
+    statementOfNode.set(node, statement);
+  }
+  const terminals = [...statements].map(([statement]) => statement);
+  const enumerated = enumerateCallStatements(
+    reading.lower(terminals),
+    terminals
+  );
+  const pathsTo = (node) => {
+    const statement = statementOfNode.get(node);
+    return statement === void 0 ? void 0 : enumerated.byTerminal.get(statement);
+  };
+  const siteOf = (node, preconditions) => {
+    const statement = statementOfNode.get(node);
+    return {
+      line: reading.firstLine(statement ?? node),
+      preconditions,
+      cleansUpFrom: statement === void 0 ? void 0 : enumerated.placement.get(statement)?.cleansUpFrom
+    };
+  };
+  return {
+    pathsTo,
+    siteOf,
+    plainSiteOf: (node) => siteOf(node, sharedGatingConditions(pathsTo(node)))
+  };
+}
+
 // src/projectRoot.ts
 var import_node_path3 = __toESM(require("path"), 1);
 function commonDirectoryOf(files) {
@@ -1669,13 +1859,13 @@ function quoted(text, key) {
 }
 
 // src/adapterStamp.ts
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 var import_node_fs3 = __toESM(require("fs"), 1);
 var import_node_path5 = __toESM(require("path"), 1);
 var import_node_url = require("url");
 
 // src/codeHash.ts
-var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("crypto");
 var import_node_fs2 = __toESM(require("fs"), 1);
 var import_node_module = require("module");
 var import_node_path4 = __toESM(require("path"), 1);
@@ -1721,7 +1911,7 @@ function createCodeHasher() {
     if (files.length === 0) {
       return "";
     }
-    const hash = (0, import_node_crypto.createHash)("sha256");
+    const hash = (0, import_node_crypto2.createHash)("sha256");
     for (const file of files) {
       hash.update(read.get(file)?.digest ?? "");
     }
@@ -1738,7 +1928,7 @@ function readCodeFile(file) {
     return null;
   }
   return {
-    digest: (0, import_node_crypto.createHash)("sha256").update(text).digest("hex"),
+    digest: (0, import_node_crypto2.createHash)("sha256").update(text).digest("hex"),
     imports: importsOf(file, text.toString("utf8"))
   };
 }
@@ -1896,7 +2086,7 @@ function computeContentHash(paths) {
   if (paths.length === 0) {
     return "";
   }
-  const hash = (0, import_node_crypto2.createHash)("sha256");
+  const hash = (0, import_node_crypto3.createHash)("sha256");
   for (const file of paths) {
     try {
       hash.update(import_node_fs3.default.readFileSync(file));
@@ -1910,7 +2100,7 @@ function projectFileStamp(paths) {
   if (paths.length === 0) {
     return "none";
   }
-  const hash = (0, import_node_crypto2.createHash)("sha256");
+  const hash = (0, import_node_crypto3.createHash)("sha256");
   for (const file of [...paths].sort()) {
     hash.update(file);
     hash.update("\0");
@@ -1945,13 +2135,13 @@ function runDigest(packsDigest, packs, files) {
 }
 
 // src/cache.ts
-var import_node_crypto5 = require("crypto");
+var import_node_crypto6 = require("crypto");
 var import_promises2 = __toESM(require("fs/promises"), 1);
 var import_node_path8 = __toESM(require("path"), 1);
 var import_files3 = require("@suss/behavioral-ir/files");
 
 // src/cacheIndex.ts
-var import_behavioral_ir6 = require("@suss/behavioral-ir");
+var import_behavioral_ir8 = require("@suss/behavioral-ir");
 var import_files = require("@suss/behavioral-ir/files");
 function entriesOf(units) {
   const boundaries = [];
@@ -1968,7 +2158,7 @@ function entriesOf(units) {
     if (own !== null) {
       add(
         keyOf3(own),
-        import_behavioral_ir6.BOUNDARY_ROLE[summary.kind] === "provider" ? "serves" : "calls"
+        import_behavioral_ir8.BOUNDARY_ROLE[summary.kind] === "provider" ? "serves" : "calls"
       );
     }
     const spellings = /* @__PURE__ */ new Set();
@@ -2046,14 +2236,14 @@ function writeStoreIndex(file, index) {
 }
 function keyOf3(binding) {
   try {
-    return (0, import_behavioral_ir6.displayLabel)(binding);
+    return (0, import_behavioral_ir8.displayLabel)(binding);
   } catch {
     return null;
   }
 }
 
 // src/cacheShards.ts
-var import_node_crypto3 = require("crypto");
+var import_node_crypto4 = require("crypto");
 var import_node_fs4 = __toESM(require("fs"), 1);
 var import_node_path6 = __toESM(require("path"), 1);
 var import_files2 = require("@suss/behavioral-ir/files");
@@ -2115,7 +2305,7 @@ function namesIn(dir) {
 }
 function writeOnce(root, value) {
   const pieces = [...(0, import_files2.documentPieces)(value)];
-  const hash = (0, import_node_crypto3.createHash)("sha256");
+  const hash = (0, import_node_crypto4.createHash)("sha256");
   for (const piece of pieces) {
     hash.update(piece);
   }
@@ -2219,7 +2409,7 @@ function copyOfJson(value) {
 }
 
 // src/cacheStamps.ts
-var import_node_crypto4 = require("crypto");
+var import_node_crypto5 = require("crypto");
 var import_promises = __toESM(require("fs/promises"), 1);
 var RECENT_CHANGE_MS = 2e3;
 function stampMayMissAWrite(stat, statAt) {
@@ -2309,7 +2499,7 @@ function reusableHash(prior, stamp) {
 async function hashFile(filePath) {
   try {
     const content = await import_promises.default.readFile(filePath);
-    return (0, import_node_crypto4.createHash)("sha256").update(content).digest("hex").slice(0, 16);
+    return (0, import_node_crypto5.createHash)("sha256").update(content).digest("hex").slice(0, 16);
   } catch {
     return null;
   }
@@ -2765,7 +2955,7 @@ function entryDirFor(cacheDir, input) {
     input.adapterPacksDigest,
     input.configPath ?? ""
   ].join(" ");
-  const name = (0, import_node_crypto5.createHash)("sha256").update(key).digest("hex").slice(0, 16);
+  const name = (0, import_node_crypto6.createHash)("sha256").update(key).digest("hex").slice(0, 16);
   return import_node_path8.default.join(cacheDir, `${ENTRY_PREFIX}${name}`);
 }
 function isEntryDir(name) {
@@ -2839,7 +3029,7 @@ async function readManifest2(manifestPath) {
 }
 
 // src/cacheLocation.ts
-var import_node_crypto6 = require("crypto");
+var import_node_crypto7 = require("crypto");
 var import_node_fs6 = __toESM(require("fs"), 1);
 var import_node_path9 = __toESM(require("path"), 1);
 var CACHE_DIR_ENV = "SUSS_CACHE_DIR";
@@ -2858,7 +3048,7 @@ function realPathOrSelf(dir) {
   }
 }
 function projectKey(projectDir) {
-  return (0, import_node_crypto6.createHash)("sha256").update(realPathOrSelf(import_node_path9.default.resolve(projectDir))).digest("hex").slice(0, 16);
+  return (0, import_node_crypto7.createHash)("sha256").update(realPathOrSelf(import_node_path9.default.resolve(projectDir))).digest("hex").slice(0, 16);
 }
 function extractionCacheDirFor(projectDir) {
   const root = chosenCacheRoot();
@@ -2867,6 +3057,13 @@ function extractionCacheDirFor(projectDir) {
   }
   return import_node_path9.default.join(root, "cache", projectKey(projectDir));
 }
+function mapFolderFor(projectDir) {
+  const root = chosenCacheRoot();
+  if (root === null) {
+    return import_node_path9.default.join(projectDir, ".suss");
+  }
+  return import_node_path9.default.join(root, "map", projectKey(projectDir));
+}
 function liveRecordFor(projectDir) {
   const root = chosenCacheRoot();
   if (root === null) {
@@ -2876,7 +3073,7 @@ function liveRecordFor(projectDir) {
 }
 
 // src/extractionReport.ts
-var import_behavioral_ir7 = require("@suss/behavioral-ir");
+var import_behavioral_ir9 = require("@suss/behavioral-ir");
 var emptyTally = () => ({
   candidateFiles: 0,
   unitsDiscovered: 0,
@@ -2926,7 +3123,7 @@ function summaryCountsByPack(summaries) {
     }
     const entry = counts.get(recognition) ?? emptyCounts();
     entry.bound += 1;
-    if (import_behavioral_ir7.BOUNDARY_ROLE[summary.kind] === "provider") {
+    if (import_behavioral_ir9.BOUNDARY_ROLE[summary.kind] === "provider") {
       entry.providers += 1;
     }
     if (summary.transitions.length > 0) {
@@ -3015,6 +3212,7 @@ var KeptParses = class {
 };
 
 // src/packHealth.ts
+var import_node_path10 = __toESM(require("path"), 1);
 function stagesOf(funnel) {
   const stages = [];
   const gateSaysSomething = funnel.gates.length > 0 && funnel.unresolvedGates.length === 0;
@@ -3162,6 +3360,30 @@ function packConfigCheck(needs) {
     }))
   };
 }
+function describeMissingPath(missing) {
+  const where = `${missing.option} is ${missing.value} in ${missing.configFile}`;
+  if (import_node_path10.default.isAbsolute(missing.value)) {
+    return {
+      problem: `${where}, and nothing exists there.`,
+      fix: `Set ${missing.option} to a path that exists.`
+    };
+  }
+  return {
+    problem: `${where}, and nothing exists at ${missing.resolved}. A relative path is read against the config file, not the project.`,
+    fix: missing.inProject === void 0 ? `Set ${missing.option} to an absolute path, or move the config file into the project.` : `Set ${missing.option} to ${missing.inProject} in the config file, or move the config file into the project.`
+  };
+}
+function packPathCheck(missing) {
+  return {
+    name: "every path a pack config gives exists",
+    code: "no-path",
+    audience: "run",
+    violations: missing.map((one) => {
+      const { problem, fix } = describeMissingPath(one);
+      return { label: one.pack, detail: `${problem} ${fix}` };
+    })
+  };
+}
 function evaluatePackHealth(report) {
   const gradients = packGradients(report);
   return [
@@ -3314,7 +3536,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_crypto7.createHash)("sha1").update(conditionSig).digest("hex").slice(0, 7);
+  const conditionHash = (0, import_node_crypto8.createHash)("sha1").update(conditionSig).digest("hex").slice(0, 7);
   return `${functionName}:${terminal.kind}:${statusKey}:${conditionHash}`;
 }
 function collapseReading(table, reading) {
@@ -3383,17 +3605,17 @@ function effectsOfBranch(branch) {
     ...branch.effects.map(effectToIR),
     ...branch.extraEffects ?? []
   ];
-  return (0, import_behavioral_ir8.foldRepeatedEffects)(effects.map(withNormalizedCallee));
+  return (0, import_behavioral_ir10.foldRepeatedEffects)(effects.map(withNormalizedCallee));
 }
 function provenanceOf(raw, effects) {
   if (raw.length === 0) {
     return [];
   }
-  const positionOf = new Map(effects.map((one, at) => [(0, import_behavioral_ir8.effectKey)(one), at]));
+  const positionOf = new Map(effects.map((one, at) => [(0, import_behavioral_ir10.effectKey)(one), at]));
   const bySlot = /* @__PURE__ */ new Map();
   const said = /* @__PURE__ */ new Map();
   for (const one of raw) {
-    const effect = positionOf.get((0, import_behavioral_ir8.effectKey)(withNormalizedCallee(one.effect)));
+    const effect = positionOf.get((0, import_behavioral_ir10.effectKey)(withNormalizedCallee(one.effect)));
     if (effect === void 0) {
       continue;
     }
@@ -3425,7 +3647,7 @@ function withNormalizedCallee(effect) {
   if (effect.callee === void 0) {
     return effect;
   }
-  return { ...effect, callee: (0, import_behavioral_ir8.normalizeCalleeText)(effect.callee) };
+  return { ...effect, callee: (0, import_behavioral_ir10.normalizeCalleeText)(effect.callee) };
 }
 function assembleSummary(raw, options = DEFAULT_OPTIONS) {
   const transitions = raw.branches.map((rawBranch) => {
@@ -3490,28 +3712,31 @@ function buildMetadata(raw) {
   let metadata = {};
   const http = buildHttpMetadataValue(raw);
   if (http !== null) {
-    metadata = (0, import_behavioral_ir8.withHttpMetadata)(metadata, http);
+    metadata = (0, import_behavioral_ir10.withHttpMetadata)(metadata, http);
   }
   const graphql = buildGraphqlMetadataValue(raw);
   if (graphql !== null) {
-    metadata = (0, import_behavioral_ir8.withGraphqlMetadata)(metadata, graphql);
+    metadata = (0, import_behavioral_ir10.withGraphqlMetadata)(metadata, graphql);
   }
   if (raw.sourceDocumentLabel !== void 0) {
-    metadata = (0, import_behavioral_ir8.withSourceDocumentMetadata)(metadata, {
+    metadata = (0, import_behavioral_ir10.withSourceDocumentMetadata)(metadata, {
       label: raw.sourceDocumentLabel
     });
   }
   if (raw.mount !== void 0) {
-    metadata = (0, import_behavioral_ir8.withMountMetadata)(metadata, raw.mount);
+    metadata = (0, import_behavioral_ir10.withMountMetadata)(metadata, raw.mount);
   }
   if (raw.wrappers !== void 0 && raw.wrappers.length > 0) {
-    metadata = (0, import_behavioral_ir8.withWrapperMetadata)(metadata, { applied: raw.wrappers });
+    metadata = (0, import_behavioral_ir10.withWrapperMetadata)(metadata, { applied: raw.wrappers });
   }
   if (raw.requestSpelling !== void 0) {
-    metadata = (0, import_behavioral_ir8.withRequestSpellingMetadata)(metadata, raw.requestSpelling);
+    metadata = (0, import_behavioral_ir10.withRequestSpellingMetadata)(metadata, raw.requestSpelling);
   }
   if (raw.test !== void 0) {
-    metadata = (0, import_behavioral_ir8.withTestMetadata)(metadata, raw.test);
+    metadata = (0, import_behavioral_ir10.withTestMetadata)(metadata, raw.test);
+  }
+  if (raw.packMetadata !== void 0) {
+    metadata = { ...metadata, ...raw.packMetadata };
   }
   return Object.keys(metadata).length > 0 ? metadata : null;
 }
@@ -3564,13 +3789,19 @@ function buildGraphqlMetadataValue(raw) {
   if (raw.graphqlUnresolvedDocument !== void 0) {
     graphql.unresolvedDocument = raw.graphqlUnresolvedDocument;
   }
+  if (raw.graphqlClient !== void 0) {
+    graphql.client = raw.graphqlClient;
+  }
+  if (raw.graphqlUnresolvedClient !== void 0) {
+    graphql.unresolvedClient = raw.graphqlUnresolvedClient;
+  }
   return Object.keys(graphql).length > 0 ? graphql : null;
 }
 function answersWithHttpResponses(raw) {
   if (raw.boundaryBinding === null || raw.boundaryBinding === void 0) {
     return true;
   }
-  return (0, import_behavioral_ir8.exchangesHttpResponses)(raw.boundaryBinding);
+  return (0, import_behavioral_ir10.exchangesHttpResponses)(raw.boundaryBinding);
 }
 function detectGaps(raw, transitions, options) {
   if (options.gapHandling === "silent") {
@@ -3755,7 +3986,10 @@ var effectConverters = {
   stateChange: (e) => ({ type: "stateChange", variable: e.variable })
 };
 function effectToIR(effect) {
-  return effectConverters[effect.type](effect);
+  const converted = effectConverters[effect.type](
+    effect
+  );
+  return effect.location === void 0 ? converted : { ...converted, location: effect.location };
 }
 function paramToInput(param) {
   return {
@@ -3787,6 +4021,7 @@ function paramToInput(param) {
   assembleSummary,
   assessConfidence,
   buildUngatedExtractionReport,
+  callSiteKey,
   chosenCacheRoot,
   commonDirectoryOf,
   composeWrappers,
@@ -3798,23 +4033,28 @@ function paramToInput(param) {
   createCodeHasher,
   createPackTallies,
   createTimer,
+  describeMissingPath,
   detectGaps,
   effectToIR,
+  effectsFiringOn,
   emptyTally,
   enumerateOrDegrade,
   enumerateStructuredPaths,
   evaluatePackHealth,
   extractionCacheDirFor,
   extractionConfigStamp,
+  firesOn,
   firstWrittenReading,
   formatPackHealth,
   guardsHoldOn,
   helperPathsOnVariables,
   httpRouteDiscovery,
   isListedTestFile,
+  libraryEnvReadMarker,
   liveRecordFor,
   makeIgnoredDirectory,
   makeTransitionId,
+  mapFolderFor,
   mapReading,
   markReturnsAsExitCode,
   matchesTestFileName,
@@ -3822,10 +4062,13 @@ function paramToInput(param) {
   moduleInitStructure,
   moduleOfFile,
   noopTimer,
+  numberRepeatedCallSites,
   ownersWhereWritten,
   packConfigCheck,
   packGradients,
+  packPathCheck,
   paramToInput,
+  placeTerminals,
   processCodeHasher,
   projectFileStamp,
   rawConditionToPredicate,
@@ -3843,6 +4086,7 @@ function paramToInput(param) {
   stampMayMissAWrite,
   stampModuleImports,
   stampModules,
+  statementSites,
   storageSystemOption,
   summaryCountsByPack,
   tallyUnit,