@suss/extractor 0.3.2 → 0.4.0

package/dist/index.js

@@ -1,5 +1,10 @@
 // src/index.ts
 import { createHash } from "crypto";
+import {
+  exchangesHttpResponses,
+  withGraphqlMetadata,
+  withHttpMetadata
+} from "@suss/behavioral-ir";
 
 // src/inputReads.ts
 function inputReadsOf(args) {
@@ -93,13 +98,521 @@ function httpRouteDiscovery(opts) {
       registrationChain: [...opts.methods]
     },
     bindingExtraction: {
-      method: { type: "fromRegistration", position: "methodName" },
+      // `.all` registers every method, so it records "*", which the pairing
+      // engine treats as agreeing with any method at all.
+      method: {
+        type: "fromRegistration",
+        position: "methodName",
+        nameMap: { all: "*" }
+      },
       path: { type: "fromRegistration", position: 0 }
     },
+    ...opts.mount !== void 0 ? { mount: opts.mount } : {},
     requiresImport: [opts.importModule]
   }));
 }
 
+// src/paths/enumeratePaths.ts
+var MAX_PATHS = 256;
+var UnmodeledFlow = class extends Error {
+};
+var PathBudgetExceeded = class extends Error {
+};
+function branchCond(branchStmt, condition, polarity, oppositeExit) {
+  return {
+    info: {
+      sourceText: condition.sourceText,
+      polarity,
+      source: "explicit",
+      expression: condition.expression
+    },
+    branchStmt,
+    oppositeExit
+  };
+}
+function fixedCond(condition, polarity, source) {
+  return {
+    info: {
+      sourceText: condition.sourceText,
+      polarity,
+      source,
+      expression: condition.expression
+    },
+    branchStmt: null,
+    oppositeExit: null
+  };
+}
+var loopIterationCond = (headerText) => fixedCond(
+  { sourceText: `some iteration of: ${headerText}`, expression: null },
+  "positive",
+  "explicit"
+);
+var loopCompletedCond = (headerText, exit) => fixedCond(
+  {
+    sourceText: `loop exited via ${exit ?? "return"}: ${headerText}`,
+    expression: null
+  },
+  "negative",
+  exit === "throw" ? "earlyThrow" : "earlyReturn"
+);
+var catchEntryCond = () => fixedCond(
+  { sourceText: "catch", expression: null },
+  "positive",
+  "catchBlock"
+);
+function classify(path, home, isAncestorOrSelf) {
+  return path.map((cond) => {
+    if (cond.branchStmt === null) {
+      return cond.info;
+    }
+    const encloses = home !== null && isAncestorOrSelf(cond.branchStmt, home);
+    if (encloses || cond.info.polarity === "positive") {
+      return { ...cond.info, source: "explicit" };
+    }
+    const source = cond.oppositeExit === "throw" ? "earlyThrow" : "earlyReturn";
+    return { ...cond.info, source };
+  });
+}
+function childrenOf(stmt) {
+  if (stmt.kind === "if") {
+    return stmt.elseBody === null ? stmt.thenBody : [...stmt.thenBody, ...stmt.elseBody];
+  }
+  if (stmt.kind === "switch") {
+    return stmt.groups.flatMap((g) => g.body);
+  }
+  if (stmt.kind === "loop") {
+    return stmt.body;
+  }
+  if (stmt.kind === "try") {
+    return [
+      ...stmt.tryBody,
+      ...stmt.catchBody ?? [],
+      ...stmt.finallyBody ?? []
+    ];
+  }
+  return [];
+}
+function hasStrayBreak(nodes) {
+  return nodes.some((node) => {
+    if (node.kind === "exit" && node.exit === "break") {
+      return true;
+    }
+    if (node.kind === "switch" || node.kind === "loop") {
+      return false;
+    }
+    return hasStrayBreak(childrenOf(node));
+  });
+}
+function exitKindOfList(stmts) {
+  let sawReturn = false;
+  for (const stmt of stmts) {
+    if (stmt.exitKind === "throw") {
+      return "throw";
+    }
+    if (stmt.exitKind === "return") {
+      sawReturn = true;
+    }
+  }
+  return sawReturn ? "return" : null;
+}
+function chargeBudget(state) {
+  state.pathCount++;
+  if (state.pathCount > MAX_PATHS) {
+    throw new PathBudgetExceeded();
+  }
+}
+function recordTerminal(ctx, terminal, home, path) {
+  chargeBudget(ctx.state);
+  const info = classify(path, home, ctx.isAncestorOrSelf);
+  const existing = ctx.state.byTerminal.get(terminal) ?? [];
+  existing.push(info);
+  ctx.state.byTerminal.set(terminal, existing);
+}
+function containsTerminal(ctx, stmt) {
+  if ((ctx.terminalsByStmt.get(stmt)?.length ?? 0) > 0) {
+    return true;
+  }
+  return childrenOf(stmt).some((child) => containsTerminal(ctx, child));
+}
+function stepIf(stmt, path, ctx) {
+  const armsExit = stmt.exitKind !== null;
+  const armsHaveTerminals = containsTerminal(ctx, stmt);
+  if (!armsExit && !armsHaveTerminals) {
+    return [path];
+  }
+  const thenExit = exitKindOfList(stmt.thenBody);
+  const elseExit = stmt.elseBody === null ? null : exitKindOfList(stmt.elseBody);
+  const thenPath = [
+    ...path,
+    branchCond(stmt, stmt.condition, "positive", elseExit)
+  ];
+  const elsePath = [
+    ...path,
+    branchCond(stmt, stmt.condition, "negative", thenExit)
+  ];
+  const out = [];
+  out.push(...enumerate(ctx, stmt.thenBody, thenPath));
+  if (stmt.elseBody !== null) {
+    out.push(...enumerate(ctx, stmt.elseBody, elsePath));
+  } else {
+    out.push(elsePath);
+  }
+  return out;
+}
+function stepSwitch(stmt, path, ctx) {
+  const out = [];
+  const negations = [];
+  let defaultRanBody = false;
+  for (let i = 0; i < stmt.groups.length; i++) {
+    const group = stmt.groups[i];
+    const fallthroughSafe = i === stmt.groups.length - 1;
+    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 conts = enumerate(ctx, group.body, groupPath);
+    if (conts.length > 0) {
+      if (!group.hasTrailingBreak && !fallthroughSafe) {
+        throw new UnmodeledFlow("fallthrough into a non-empty switch clause");
+      }
+      out.push(...conts);
+    }
+    if (group.condition === null) {
+      defaultRanBody = true;
+    } else {
+      const exit = exitKindOfList(group.body);
+      const negationSource = exit === "throw" ? "earlyThrow" : exit === "return" ? "earlyReturn" : "explicit";
+      negations.push(fixedCond(group.condition, "negative", negationSource));
+    }
+  }
+  if (!defaultRanBody) {
+    out.push([...path, ...negations]);
+  }
+  return out;
+}
+function stepLoop(stmt, path, ctx) {
+  const bodyExit = exitKindOfList(stmt.body);
+  if (containsTerminal(ctx, stmt)) {
+    enumerate(ctx, stmt.body, [
+      ...path,
+      loopIterationCond(stmt.condition.sourceText)
+    ]);
+  }
+  if (bodyExit !== null) {
+    return [[...path, loopCompletedCond(stmt.condition.sourceText, bodyExit)]];
+  }
+  return [path];
+}
+function stepTry(stmt, path, ctx) {
+  if (stmt.finallyBody !== null) {
+    const finallyHasTerminal = stmt.finallyBody.some(
+      (s) => containsTerminal(ctx, s)
+    );
+    if (exitKindOfList(stmt.finallyBody) !== null || finallyHasTerminal) {
+      throw new UnmodeledFlow("finally block with exits or terminals");
+    }
+  }
+  const out = [];
+  out.push(...enumerate(ctx, stmt.tryBody, path));
+  if (stmt.catchBody !== null) {
+    const catchPath = [...path, catchEntryCond()];
+    out.push(...enumerate(ctx, stmt.catchBody, catchPath));
+  }
+  return out;
+}
+function stepExit(_stmt, _path, _ctx) {
+  return [];
+}
+function stepOpaque(_stmt, path, _ctx) {
+  return [path];
+}
+var stepHandlers = {
+  if: stepIf,
+  switch: stepSwitch,
+  loop: stepLoop,
+  try: stepTry,
+  exit: stepExit,
+  opaque: stepOpaque
+};
+function stepStatement(ctx, stmt, path) {
+  const ownTerminals = ctx.terminalsByStmt.get(stmt) ?? [];
+  for (const terminal of ownTerminals) {
+    recordTerminal(ctx, terminal, stmt, path);
+  }
+  const handler = stepHandlers[stmt.kind];
+  return handler(
+    stmt,
+    path,
+    ctx
+  );
+}
+function soleDisagreement(left, right) {
+  if (left.length !== right.length) {
+    return null;
+  }
+  let found = null;
+  for (let at = 0; at < left.length; at++) {
+    const one = left[at];
+    const other = right[at];
+    if (one === other) {
+      continue;
+    }
+    if (found !== null) {
+      return null;
+    }
+    if (one === void 0 || other === void 0 || one.branchStmt === null || one.branchStmt !== other.branchStmt || one.info.polarity === other.info.polarity) {
+      return null;
+    }
+    found = at;
+  }
+  return found;
+}
+function mergeRejoined(paths) {
+  let current = paths;
+  for (let round = 0; round < current.length; round++) {
+    const out = [];
+    const taken = /* @__PURE__ */ new Set();
+    let mergedAny = false;
+    for (let i = 0; i < current.length; i++) {
+      if (taken.has(i)) {
+        continue;
+      }
+      let combined = current[i];
+      for (let j = i + 1; j < current.length; j++) {
+        if (taken.has(j)) {
+          continue;
+        }
+        const at = soleDisagreement(combined, current[j]);
+        if (at === null) {
+          continue;
+        }
+        combined = [...combined.slice(0, at), ...combined.slice(at + 1)];
+        taken.add(j);
+        mergedAny = true;
+        break;
+      }
+      out.push(combined);
+    }
+    current = out;
+    if (!mergedAny) {
+      break;
+    }
+  }
+  return current;
+}
+function enumerate(ctx, stmts, prefix) {
+  let frontiers = [[...prefix]];
+  for (const stmt of stmts) {
+    const nextFrontiers = [];
+    for (const path of frontiers) {
+      nextFrontiers.push(...stepStatement(ctx, stmt, path));
+    }
+    frontiers = mergeRejoined(nextFrontiers);
+    if (frontiers.length > MAX_PATHS) {
+      throw new PathBudgetExceeded();
+    }
+    if (frontiers.length === 0) {
+      break;
+    }
+  }
+  return frontiers;
+}
+function buildParentMap(statements) {
+  const parentOf = /* @__PURE__ */ new Map();
+  const visit = (stmt, parent) => {
+    parentOf.set(stmt, parent);
+    for (const child of childrenOf(stmt)) {
+      visit(child, stmt);
+    }
+  };
+  for (const stmt of statements) {
+    visit(stmt, null);
+  }
+  return parentOf;
+}
+function enumerateStructuredPaths(input) {
+  const parentOf = buildParentMap(input.statements);
+  const isAncestorOrSelf = (a, b) => {
+    let current = b;
+    while (current !== null) {
+      if (current === a) {
+        return true;
+      }
+      current = parentOf.get(current) ?? null;
+    }
+    return false;
+  };
+  const state = {
+    byTerminal: /* @__PURE__ */ new Map(),
+    fallthrough: [],
+    pathCount: 0
+  };
+  const ctx = {
+    terminalsByStmt: input.terminalsByStmt,
+    state,
+    isAncestorOrSelf
+  };
+  const continuations = enumerate(ctx, input.statements, []);
+  for (const path of continuations) {
+    chargeBudget(state);
+    state.fallthrough.push(classify(path, null, isAncestorOrSelf));
+  }
+  return { byTerminal: state.byTerminal, fallthrough: state.fallthrough };
+}
+function enumerateOrDegrade(input, terminals) {
+  try {
+    return { ...enumerateStructuredPaths(input), degraded: null };
+  } catch (error) {
+    const reason = reasonToDegrade(error);
+    if (reason === null) {
+      throw error;
+    }
+    const marker = {
+      sourceText: `unmodeled control flow (${reason})`,
+      polarity: "positive",
+      source: "explicit",
+      expression: null
+    };
+    const byTerminal = /* @__PURE__ */ new Map();
+    for (const terminal of terminals) {
+      byTerminal.set(terminal, [[marker]]);
+    }
+    return { byTerminal, fallthrough: [[marker]], degraded: reason };
+  }
+}
+function reasonToDegrade(error) {
+  if (error instanceof PathBudgetExceeded) {
+    return "path budget exceeded";
+  }
+  if (error instanceof UnmodeledFlow) {
+    return error.message;
+  }
+  return null;
+}
+
+// src/paths/gatingConditions.ts
+var keyOf = (condition) => `${condition.polarity}:${condition.sourceText}`;
+function sharedGatingConditions(paths, readPredicate) {
+  const [first, ...rest] = paths ?? [];
+  if (first === void 0) {
+    return [];
+  }
+  const shared = new Set(first.map(keyOf));
+  for (const path of rest) {
+    const here = new Set(path.map(keyOf));
+    for (const value of shared) {
+      if (!here.has(value)) {
+        shared.delete(value);
+      }
+    }
+  }
+  return first.filter((condition) => shared.has(keyOf(condition))).map((condition) => ({
+    sourceText: condition.sourceText,
+    structured: readPredicate === void 0 || condition.expression === null ? null : readPredicate(condition.expression),
+    polarity: condition.polarity,
+    source: condition.source
+  }));
+}
+
+// src/paths/nodeIdentity.ts
+var IdSet = class {
+  byKey = /* @__PURE__ */ new Map();
+  constructor(nodes = []) {
+    for (const node of nodes) {
+      this.add(node);
+    }
+  }
+  add(node) {
+    this.byKey.set(node.id, node);
+    return this;
+  }
+  has(node) {
+    return this.byKey.has(node.id);
+  }
+  /** The node this set was built with, which is the caller's own handle for it. */
+  get(node) {
+    return this.byKey.get(node.id);
+  }
+  get size() {
+    return this.byKey.size;
+  }
+  [Symbol.iterator]() {
+    return this.byKey.values();
+  }
+};
+var IdMap = class {
+  entries = /* @__PURE__ */ new Map();
+  set(node, value) {
+    this.entries.set(node.id, [node, value]);
+    return this;
+  }
+  get(node) {
+    return this.entries.get(node.id)?.[1];
+  }
+  has(node) {
+    return this.entries.has(node.id);
+  }
+  get size() {
+    return this.entries.size;
+  }
+  [Symbol.iterator]() {
+    return this.entries.values();
+  }
+};
+
+// src/reading.ts
+function writtenReading(value, range) {
+  return { kind: "written", value, range };
+}
+var absentReading = { kind: "absent" };
+function unreadableReading(reason, range) {
+  return { kind: "unreadable", reason, range };
+}
+function ambiguousReading(candidates, reason, range) {
+  return { kind: "ambiguous", candidates, reason, range };
+}
+function dispatchReading(table, reading) {
+  return table[reading.kind](reading);
+}
+function mapReading(reading, f) {
+  const table = {
+    written: (r) => writtenReading(f(r.value), r.range),
+    absent: () => absentReading,
+    unreadable: (r) => unreadableReading(r.reason, r.range),
+    ambiguous: (r) => ambiguousReading(r.candidates.map(f), r.reason, r.range)
+  };
+  return dispatchReading(table, reading);
+}
+function andThenReading(reading, f) {
+  const table = {
+    written: (r) => f(r.value, r.range),
+    absent: () => absentReading,
+    unreadable: (r) => unreadableReading(r.reason, r.range),
+    ambiguous: (r) => ambiguousReading(
+      r.candidates.flatMap((candidate) => {
+        const next = f(candidate, r.range);
+        return next.kind === "written" ? [next.value] : [];
+      }),
+      r.reason,
+      r.range
+    )
+  };
+  return dispatchReading(table, reading);
+}
+function firstWrittenReading(readings) {
+  const written = readings.find((reading) => reading.kind === "written");
+  const chosen = written ?? readings.find((reading) => reading.kind !== "absent") ?? absentReading;
+  return {
+    reading: chosen,
+    passedOver: readings.filter(
+      (reading) => reading !== chosen && (reading.kind === "unreadable" || reading.kind === "ambiguous")
+    )
+  };
+}
+function valueToReadFurtherFrom(reading) {
+  return reading.kind === "written" ? reading.value : null;
+}
+
 // src/index.ts
 function valuesOfOutput(output) {
   if (output.type === "response" && output.statusCode !== null) {
@@ -115,8 +628,69 @@ function makeTransitionId(functionName, branch) {
   const conditionHash = createHash("sha1").update(conditionSig).digest("hex").slice(0, 7);
   return `${functionName}:${terminal.kind}:${statusKey}:${conditionHash}`;
 }
+function collapseReading(table, reading) {
+  return table[reading.kind](reading);
+}
+function claimedValue(defaulted) {
+  const table = {
+    written: (r) => r.value,
+    absent: () => defaulted.libraryDefault ?? null,
+    unreadable: () => null,
+    ambiguous: () => null
+  };
+  return collapseReading(table, defaulted.reading);
+}
+function unreadReasonOf(reading) {
+  const table = {
+    written: () => null,
+    absent: () => null,
+    unreadable: (r) => r.reason,
+    ambiguous: (r) => r.reason
+  };
+  return collapseReading(table, reading);
+}
+function bodyWithClaimedShape(terminal, reading) {
+  return {
+    typeText: terminal.body?.typeText ?? null,
+    shape: claimedValue(reading)
+  };
+}
+function branchWithCollapsedReadings(branch) {
+  const { statusCodeReading, bodyShapeReading } = branch;
+  if (statusCodeReading === void 0 && bodyShapeReading === void 0) {
+    return branch;
+  }
+  const status = statusCodeReading !== void 0 ? claimedValue(statusCodeReading) : null;
+  return {
+    ...branch,
+    terminal: {
+      ...branch.terminal,
+      ...statusCodeReading !== void 0 ? {
+        statusCode: status !== null ? { type: "literal", value: status } : null
+      } : {},
+      ...bodyShapeReading !== void 0 ? { body: bodyWithClaimedShape(branch.terminal, bodyShapeReading) } : {}
+    }
+  };
+}
+function readingsOfBranch(branch) {
+  return [
+    ...branch.bodyShapeReading !== void 0 ? [branch.bodyShapeReading.reading] : [],
+    ...branch.statusCodeReading !== void 0 ? [branch.statusCodeReading.reading] : []
+  ];
+}
+function unreadSentences(raw) {
+  const handedOver = [
+    ...raw.readings ?? [],
+    ...raw.branches.flatMap(readingsOfBranch)
+  ];
+  return [
+    ...raw.unreadBinding !== void 0 ? [raw.unreadBinding] : [],
+    ...handedOver.map(unreadReasonOf).filter((reason) => reason !== null)
+  ];
+}
 function assembleSummary(raw, options = DEFAULT_OPTIONS) {
-  const transitions = raw.branches.map((branch) => {
+  const transitions = raw.branches.map((rawBranch) => {
+    const branch = branchWithCollapsedReadings(rawBranch);
     const conditions = branch.conditions.map(
       rawConditionToPredicate
     );
@@ -153,6 +727,7 @@ function assembleSummary(raw, options = DEFAULT_OPTIONS) {
     },
     identity: {
       name: raw.identity.name,
+      ...raw.identity.nameKind !== void 0 ? { nameKind: raw.identity.nameKind } : {},
       exportPath: raw.identity.exportPath,
       boundaryBinding: raw.boundaryBinding ?? null,
       ...raw.deployableUnit !== void 0 ? { deployableUnit: raw.deployableUnit } : {}
@@ -167,21 +742,25 @@ function assembleSummary(raw, options = DEFAULT_OPTIONS) {
   };
 }
 function buildMetadata(raw) {
-  const metadata = {};
-  const http = buildHttpMetadata(raw);
+  let metadata = {};
+  const http = buildHttpMetadataValue(raw);
   if (http !== null) {
-    metadata.http = http;
+    metadata = withHttpMetadata(metadata, http);
   }
-  const graphql = buildGraphqlMetadata(raw);
+  const graphql = buildGraphqlMetadataValue(raw);
   if (graphql !== null) {
-    metadata.graphql = graphql;
+    metadata = withGraphqlMetadata(metadata, graphql);
   }
   return Object.keys(metadata).length > 0 ? metadata : null;
 }
-function buildHttpMetadata(raw) {
+function buildHttpMetadataValue(raw) {
   const http = {};
   if (raw.declaredContract !== null) {
-    http.declaredContract = raw.declaredContract;
+    http.declaredContract = {
+      framework: raw.declaredContract.framework,
+      responses: raw.declaredContract.responses,
+      provenance: raw.declaredContract.provenance ?? "independent"
+    };
   }
   if (raw.bodyAccessors !== void 0 && raw.bodyAccessors.length > 0) {
     http.bodyAccessors = raw.bodyAccessors;
@@ -191,7 +770,7 @@ function buildHttpMetadata(raw) {
   }
   return Object.keys(http).length > 0 ? http : null;
 }
-function buildGraphqlMetadata(raw) {
+function buildGraphqlMetadataValue(raw) {
   const graphql = {};
   if (raw.graphqlDocument !== void 0) {
     graphql.document = raw.graphqlDocument;
@@ -207,6 +786,12 @@ function buildGraphqlMetadata(raw) {
   }
   return Object.keys(graphql).length > 0 ? graphql : null;
 }
+function answersWithHttpResponses(raw) {
+  if (raw.boundaryBinding === null || raw.boundaryBinding === void 0) {
+    return true;
+  }
+  return exchangesHttpResponses(raw.boundaryBinding);
+}
 function detectGaps(raw, transitions, options) {
   if (options.gapHandling === "silent") {
     return [];
@@ -215,20 +800,18 @@ function detectGaps(raw, transitions, options) {
   if (raw.unmatchedReturns !== void 0 && raw.unmatchedReturns > 0) {
     const count = raw.unmatchedReturns;
     gaps.push({
-      // Not a contract violation: the handler may be answering
-      // correctly, in a shape nobody taught the pack.
       type: "unreadOutcome",
       conditions: [],
       consequence: "unknown",
       description: count === 1 ? "One return in this function matches none of the terminal shapes this pack looks for, so what it produces is not described here" : `${count} returns in this function match none of the terminal shapes this pack looks for, so what they produce is not described here`
     });
   }
-  if (raw.unreadBinding !== void 0) {
+  for (const sentence of unreadSentences(raw)) {
     gaps.push({
       type: "unreadOutcome",
       conditions: [],
       consequence: "unknown",
-      description: raw.unreadBinding
+      description: sentence
     });
   }
   const unreadBody = describeUnreadBody(raw);
@@ -240,7 +823,7 @@ function detectGaps(raw, transitions, options) {
       description: unreadBody
     });
   }
-  if (raw.declaredContract) {
+  if (raw.declaredContract && answersWithHttpResponses(raw)) {
     const producedStatuses = new Set(
       transitions.flatMap((t) => {
         if (t.output.type !== "response") {
@@ -419,12 +1002,27 @@ function paramToInput(param) {
   };
 }
 export {
+  IdMap,
+  IdSet,
+  PathBudgetExceeded,
+  UnmodeledFlow,
+  absentReading,
+  ambiguousReading,
+  andThenReading,
   assembleSummary,
   assessConfidence,
   detectGaps,
   effectToIR,
+  enumerateOrDegrade,
+  enumerateStructuredPaths,
+  firstWrittenReading,
   httpRouteDiscovery,
   makeTransitionId,
+  mapReading,
   paramToInput,
-  terminalToOutput
+  sharedGatingConditions,
+  terminalToOutput,
+  unreadableReading,
+  valueToReadFurtherFrom,
+  writtenReading
 };