@suss/extractor 0.19.0 → 0.21.0

package/dist/index.js

@@ -4,7 +4,9 @@ import {
   exchangesHttpResponses,
   withGraphqlMetadata,
   withHttpMetadata,
-  withSourceDocumentMetadata
+  withMountMetadata,
+  withSourceDocumentMetadata,
+  withWrapperMetadata as withWrapperMetadata2
 } from "@suss/behavioral-ir";
 
 // src/inputReads.ts
@@ -97,80 +99,12 @@ function mergeInputReads(derived, syntactic) {
   return [...found.values()];
 }
 
-// src/packHelpers.ts
-function httpRouteDiscovery(opts) {
-  const kind = opts.kind ?? "handler";
-  const calls = opts.importNames.map((importName) => ({
-    kind,
-    match: {
-      type: "registrationCall",
-      importModule: opts.importModule,
-      importName,
-      registrationChain: [...opts.methods]
-    },
-    bindingExtraction: {
-      // `.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: "fromArgument", position: 0 }
-    },
-    ...opts.mount !== void 0 ? { mount: opts.mount } : {},
-    requiresImport: [opts.importModule]
-  }));
-  if (opts.importNames.length === 0) {
-    return calls;
-  }
-  return [
-    ...calls,
-    // Routes registered in a loop over an array of specs, a shape
-    // registration-call discovery cannot see. The receiver comes from
-    // the same import declaration as the calls above, so a loop that
-    // never touches this library's routable is left alone.
-    {
-      kind,
-      match: {
-        type: "registrationLoop",
-        elementShape: LOOP_ELEMENT_SHAPE,
-        receiver: {
-          importModule: opts.importModule,
-          importNames: [...opts.importNames]
-        }
-      },
-      requiresImport: [opts.importModule]
-    }
-  ];
-}
-var LOOP_ELEMENT_SHAPE = {
-  methodKey: "method",
-  pathKey: "path",
-  handlerKey: "handler"
-};
-function registrationHelperDiscovery(helpers, kind = "handler") {
-  return helpers.map((helper) => ({
-    kind,
-    match: {
-      type: "registrationTemplate",
-      helperName: helper.helperName,
-      ...helper.importModule !== void 0 ? { importModule: helper.importModule } : {},
-      registrations: helper.registrations.map((one) => ({ ...one }))
-    }
-  }));
-}
-function unwrapJsonStringify(body) {
-  if (body === null || typeof body !== "object") {
-    return body;
-  }
-  const candidate = body;
-  if (candidate.kind !== "call" || candidate.callee !== "JSON.stringify") {
-    return body;
-  }
-  const inner = candidate.args?.[0];
-  return inner ?? body;
-}
+// src/composeWrappers.ts
+import {
+  readWrapperMetadata,
+  withinScope,
+  withWrapperMetadata
+} from "@suss/behavioral-ir";
 
 // src/paths/enumeratePaths.ts
 import { CATCH_ENTRY_TEXT } from "@suss/behavioral-ir";
@@ -587,23 +521,372 @@ function reasonToDegrade(error) {
   return null;
 }
 
-// src/paths/gatingConditions.ts
+// src/composeWrappers.ts
+var BUDGET_GAP = {
+  type: "unreadOutcome",
+  conditions: [],
+  consequence: "unknown",
+  description: `Composing the wrappers registered around this unit would have gone past the path budget of ${MAX_PATHS}, so what each of them produces is reported beside this unit's own outcomes rather than under the conditions that reach it`
+};
+function composeWrappers(summaries) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const summary of summaries) {
+    const key = summaryKey(summary.location.file, summary.identity.name);
+    if (!byKey.has(key)) {
+      byKey.set(key, summary);
+    }
+  }
+  return summaries.map((summary) => composeOne(summary, byKey));
+}
+function summaryKey(file, name) {
+  return `${file}::${name}`;
+}
+function composeOne(summary, byKey) {
+  const recorded = readWrapperMetadata(summary);
+  const applied = recorded?.applied ?? [];
+  const covering = applied.filter(
+    (reference) => coversUnit(reference, summary)
+  );
+  const narrowed = covering.length === applied.length ? summary : {
+    ...summary,
+    metadata: withWrapperMetadata(summary.metadata, {
+      applied: covering
+    })
+  };
+  const wrappers = covering.flatMap((reference) => {
+    const found = byKey.get(summaryKey(reference.file, reference.name));
+    return found === void 0 ? [] : [{ reference, summary: found }];
+  });
+  if (wrappers.length === 0) {
+    return narrowed;
+  }
+  let composition = {
+    transitions: summary.transitions,
+    degraded: false
+  };
+  for (const wrapper of [...wrappers].reverse()) {
+    if (wrapper.reference.onThrow === true) {
+      continue;
+    }
+    composition = merge(composition, applyWrapper(wrapper, composition));
+  }
+  for (const wrapper of wrappers) {
+    if (wrapper.reference.onThrow !== true) {
+      continue;
+    }
+    composition = merge(composition, applyThrowWrapper(wrapper, composition));
+  }
+  if (composition.transitions === summary.transitions) {
+    return narrowed;
+  }
+  return {
+    ...narrowed,
+    transitions: withDistinctIds(composition.transitions),
+    gaps: composition.degraded ? [...summary.gaps, BUDGET_GAP] : summary.gaps
+  };
+}
+function merge(before, step) {
+  return {
+    transitions: step.transitions,
+    degraded: before.degraded || step.degraded
+  };
+}
+function coversUnit(reference, summary) {
+  if (reference.scope === void 0) {
+    return true;
+  }
+  const binding = summary.identity.boundaryBinding;
+  return binding !== null && withinScope(binding, reference.scope);
+}
+function applyWrapper(wrapper, inner) {
+  const shortCircuits = attribute(
+    wrapper.summary.transitions.filter((t) => t.output.type !== "delegate"),
+    wrapper.reference
+  );
+  const passThroughs = wrapper.summary.transitions.filter(
+    (t) => t.output.type === "delegate"
+  );
+  if (passThroughs.length === 0 || shortCircuits.length + passThroughs.length * inner.transitions.length > MAX_PATHS) {
+    return {
+      transitions: [...shortCircuits, ...inner.transitions],
+      degraded: passThroughs.length > 0
+    };
+  }
+  const continued = passThroughs.flatMap(
+    (passThrough) => inner.transitions.map((transition) => splice(passThrough, transition))
+  );
+  return { transitions: [...shortCircuits, ...continued], degraded: false };
+}
+function applyThrowWrapper(wrapper, inner) {
+  const thrown = inner.transitions.filter((t) => t.output.type === "throw");
+  if (thrown.length === 0) {
+    return inner;
+  }
+  const rest = inner.transitions.filter((t) => t.output.type !== "throw");
+  const handled = wrapper.summary.transitions;
+  if (rest.length + thrown.length * handled.length > MAX_PATHS) {
+    return {
+      transitions: [
+        ...inner.transitions,
+        ...attribute(handled, wrapper.reference)
+      ],
+      degraded: true
+    };
+  }
+  const composed = thrown.flatMap(
+    (transition) => attribute(
+      handled.map((handler) => splice(transition, handler)),
+      wrapper.reference
+    )
+  );
+  return { transitions: [...rest, ...composed], degraded: false };
+}
+function splice(outer, inner) {
+  return {
+    ...inner,
+    id: `${inner.id}:via:${outer.id}`,
+    conditions: [...outer.conditions, ...inner.conditions],
+    effects: [...outer.effects, ...inner.effects],
+    isDefault: outer.isDefault && inner.isDefault
+  };
+}
+function attribute(transitions, reference) {
+  return transitions.map((transition) => ({
+    ...transition,
+    metadata: withWrapperMetadata(transition.metadata, { from: reference })
+  }));
+}
+function withDistinctIds(transitions) {
+  const seen = /* @__PURE__ */ new Map();
+  return transitions.map((transition) => {
+    const taken = seen.get(transition.id);
+    seen.set(transition.id, (taken ?? 0) + 1);
+    return taken === void 0 ? transition : { ...transition, id: `${transition.id}#${taken + 1}` };
+  });
+}
+
+// src/effectGuards.ts
 var keyOf = (condition) => `${condition.polarity}:${condition.sourceText}`;
+var opposite = (condition) => `${condition.polarity === "positive" ? "negative" : "positive"}:${condition.sourceText}`;
+function guardsHoldOn(preconditions, conditions) {
+  if (preconditions === void 0 || preconditions.length === 0) {
+    return true;
+  }
+  const onBranch = new Set(conditions.map(keyOf));
+  return preconditions.every(
+    (precondition) => !onBranch.has(opposite(precondition))
+  );
+}
+function runsBefore(effectLine, terminalEndLine) {
+  return effectLine <= terminalEndLine;
+}
+
+// src/packHelpers.ts
+function httpRouteDiscovery(opts) {
+  const kind = opts.kind ?? "handler";
+  const calls = opts.importNames.map((importName) => ({
+    kind,
+    match: {
+      type: "registrationCall",
+      importModule: opts.importModule,
+      importName,
+      registrationChain: [...opts.methods]
+    },
+    bindingExtraction: {
+      // `.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: "fromArgument", position: 0 }
+    },
+    ...opts.mount !== void 0 ? { mount: opts.mount } : {},
+    requiresImport: [opts.importModule]
+  }));
+  if (opts.importNames.length === 0) {
+    return calls;
+  }
+  return [
+    ...calls,
+    // Routes registered in a loop over an array of specs, a shape
+    // registration-call discovery cannot see. The receiver comes from
+    // the same import declaration as the calls above, so a loop that
+    // never touches this library's routable is left alone.
+    {
+      kind,
+      match: {
+        type: "registrationLoop",
+        elementShape: LOOP_ELEMENT_SHAPE,
+        receiver: {
+          importModule: opts.importModule,
+          importNames: [...opts.importNames]
+        }
+      },
+      requiresImport: [opts.importModule]
+    }
+  ];
+}
+function wrapperDiscovery(opts) {
+  return opts.importNames.flatMap(
+    (importName) => opts.wraps.map((wraps) => ({
+      kind: opts.kind ?? "middleware",
+      match: {
+        type: "registrationCall",
+        importModule: opts.importModule,
+        importName,
+        registrationChain: []
+      },
+      wraps: { ...wraps },
+      requiresImport: [opts.importModule]
+    }))
+  );
+}
+var LOOP_ELEMENT_SHAPE = {
+  methodKey: "method",
+  pathKey: "path",
+  handlerKey: "handler"
+};
+function registrationHelperDiscovery(helpers, kind = "handler") {
+  return helpers.map((helper) => ({
+    kind,
+    match: {
+      type: "registrationTemplate",
+      helperName: helper.helperName,
+      ...helper.importModule !== void 0 ? { importModule: helper.importModule } : {},
+      ...helper.subject !== void 0 ? { subject: helper.subject } : {},
+      registrations: helper.registrations.map((one) => ({ ...one }))
+    }
+  }));
+}
+function routeHelperIndex(opts) {
+  const methods = new Set(
+    opts.methods.map(
+      (method) => method.startsWith(".") ? method.slice(1) : method
+    )
+  );
+  return {
+    find: { by: "subject" },
+    declare: (helpers) => ({
+      discovery: registrationHelperDiscovery(
+        helpers.flatMap((helper) => routesRegisteredBy(helper, methods, opts)),
+        opts.kind ?? "handler"
+      )
+    })
+  };
+}
+function routesRegisteredBy(helper, methods, opts) {
+  const registrations = [];
+  let subjectArgument;
+  for (const sink of helper.sinks) {
+    const registration = routeRegisteredBy(helper, sink, methods);
+    if (registration === null) {
+      continue;
+    }
+    registrations.push(registration);
+    if (sink.receiver.as === "parameter") {
+      subjectArgument = sink.receiver.position;
+    }
+  }
+  if (registrations.length === 0 || subjectArgument === void 0) {
+    return [];
+  }
+  return [
+    {
+      helperName: helper.name,
+      importModule: helper.file,
+      subject: {
+        argument: subjectArgument,
+        importModule: opts.importModule,
+        importNames: [...opts.importNames]
+      },
+      registrations
+    }
+  ];
+}
+function routeRegisteredBy(helper, sink, methods) {
+  if (sink.method === null || !methods.has(sink.method)) {
+    return null;
+  }
+  const { receiver } = sink;
+  if (receiver.as !== "parameter" || receiver.property !== void 0 || !helper.subjectParameters.includes(receiver.position)) {
+    return null;
+  }
+  const pathTemplate = sink.arguments[0];
+  const handler = sink.arguments[sink.arguments.length - 1];
+  if (sink.arguments.length < 2 || pathTemplate === void 0 || pathTemplate.as !== "text" || handler === void 0) {
+    return null;
+  }
+  const handlerArg = handlerSlot(handler);
+  return handlerArg === null ? null : {
+    // `.all` registers every method, which the pairing engine
+    // spells as a wildcard.
+    method: sink.method === "all" ? "*" : sink.method.toUpperCase(),
+    pathTemplate: pathTemplate.text,
+    handlerArg
+  };
+}
+function handlerSlot(value) {
+  if (value.as !== "parameter") {
+    return null;
+  }
+  return value.property === void 0 ? `{${value.position}}` : `{${value.position}}.${value.property}`;
+}
+function unwrapJsonStringify(body) {
+  if (body === null || typeof body !== "object") {
+    return body;
+  }
+  const candidate = body;
+  if (candidate.kind !== "call" || candidate.callee !== "JSON.stringify") {
+    return body;
+  }
+  const inner = candidate.args?.[0];
+  return inner ?? body;
+}
+
+// src/packOptions.ts
+import { z } from "zod";
+var storageSystemOption = z.enum([
+  "postgresql",
+  "mysql",
+  "sqlite"
+]);
+var scopeOption = z.string();
+var configuredCallOption = z.object({
+  /** Module that declares the receiver's type. */
+  module: z.string(),
+  /** Type name of the receiver, as exported from that module. */
+  receiver: z.string(),
+  /** Method that performs the send. */
+  method: z.string(),
+  /** Argument index carrying the subject. */
+  subjectArg: z.number(),
+  /**
+   * Which argument the message body is. Left out when the method has no
+   * single body argument, as a batch method taking a list of entries
+   * does, and then no body is reported.
+   */
+  bodyArg: z.number().optional()
+}).strict();
+
+// src/paths/gatingConditions.ts
+var keyOf2 = (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));
+  const shared = new Set(first.map(keyOf2));
   for (const path of rest) {
-    const here = new Set(path.map(keyOf));
+    const here = new Set(path.map(keyOf2));
     for (const value of shared) {
       if (!here.has(value)) {
         shared.delete(value);
       }
     }
   }
-  return first.filter((condition) => shared.has(keyOf(condition))).map((condition) => ({
+  return first.filter((condition) => shared.has(keyOf2(condition))).map((condition) => ({
     sourceText: condition.sourceText,
     structured: readPredicate === void 0 || condition.expression === null ? null : readPredicate(condition.expression),
     polarity: condition.polarity,
@@ -657,6 +940,21 @@ var IdMap = class {
   }
 };
 
+// src/paths/nodeWalk.ts
+var SKIP_CHILDREN = /* @__PURE__ */ Symbol("skipChildren");
+function walkDescendants(root, carried, visitor) {
+  for (const child of root.namedChildren) {
+    if (child === null) {
+      continue;
+    }
+    visitor.at(child, carried);
+    const inner = visitor.into(child, carried);
+    if (inner !== SKIP_CHILDREN) {
+      walkDescendants(child, inner, visitor);
+    }
+  }
+}
+
 // src/reading.ts
 function writtenReading(value, range) {
   return { kind: "written", value, range };
@@ -823,6 +1121,7 @@ function assembleSummary(raw, options = DEFAULT_OPTIONS) {
     location: {
       file: raw.identity.file,
       range: raw.identity.range,
+      ...raw.identity.span !== void 0 ? { span: raw.identity.span } : {},
       exportName: raw.identity.exportName
     },
     identity: {
@@ -856,6 +1155,12 @@ function buildMetadata(raw) {
       label: raw.sourceDocumentLabel
     });
   }
+  if (raw.mount !== void 0) {
+    metadata = withMountMetadata(metadata, raw.mount);
+  }
+  if (raw.wrappers !== void 0 && raw.wrappers.length > 0) {
+    metadata = withWrapperMetadata2(metadata, { applied: raw.wrappers });
+  }
   return Object.keys(metadata).length > 0 ? metadata : null;
 }
 function buildHttpMetadataValue(raw) {
@@ -1118,27 +1423,39 @@ function paramToInput(param) {
 export {
   IdMap,
   IdSet,
+  MAX_PATHS,
   PathBudgetExceeded,
+  SKIP_CHILDREN,
   UnmodeledFlow,
   absentReading,
   ambiguousReading,
   andThenReading,
   assembleSummary,
   assessConfidence,
+  composeWrappers,
+  configuredCallOption,
   detectGaps,
   effectToIR,
   enumerateOrDegrade,
   enumerateStructuredPaths,
   firstWrittenReading,
+  guardsHoldOn,
   httpRouteDiscovery,
   makeTransitionId,
   mapReading,
   paramToInput,
+  rawConditionToPredicate,
   registrationHelperDiscovery,
+  routeHelperIndex,
+  runsBefore,
+  scopeOption,
   sharedGatingConditions,
+  storageSystemOption,
   terminalToOutput,
   unreadableReading,
   unwrapJsonStringify,
   valueToReadFurtherFrom,
+  walkDescendants,
+  wrapperDiscovery,
   writtenReading
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/extractor",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "type": "module",
   "description": "Framework-agnostic extraction pipeline that turns raw extractions into suss behavioral summaries.",
   "keywords": [
@@ -45,7 +45,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.19.0"
+    "@suss/behavioral-ir": "0.21.0",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "tsup": "*",