@suss/extractor 0.22.3 → 0.23.0

package/README.md

@@ -75,11 +75,17 @@ What it does not read:
 
 - **Anything after the continuation returns.** A middleware that inspects the response on the way back out is read up to the `next()` call and no further.
 - **A wrapper whose continuation the pack does not declare, or whose call the walk cannot see.** Nothing says where control passes on, so the wrapper's outcomes are reported beside the unit's own rather than around them.
-- **A throw the walk never saw.** An error handler composes over the paths that end by throwing, so a route whose 500 comes from a call the walk could not follow still does not report 500.
+- **A throw the walk never saw.** An error handler composes over the paths that end by throwing, so a route whose 500 comes from a call the walk could not follow still does not report 500 as a transition. The contract comparison below is the one place that counts it anyway.
 - **Registration order against route order.** A wrapper registered after a route still composes into it.
 
 Composition multiplies paths, so it is capped by the same `MAX_PATHS` budget path enumeration uses. Past it the two sides are reported side by side and the unit gets a gap saying so.
 
+### The declared contract, compared again
+
+`assembleSummary` compares a route's declared responses against its own body and records a gap for each status declared but never produced, or produced but never declared. That runs before anything around the route is read, so a contract that declares the 401 the auth middleware returns was reported as declaring a status nothing produces, once per route.
+
+`composeWrappers` runs the same comparison over the composed transitions and replaces those gaps. A status a wrapper produces counts as produced, and one the contract leaves out is reported against the wrapper by name: "requireCaller, registered around this handler, produces status 429 which is not declared in the hono contract". An error handler's responses count as produced on every route it covers, whether or not a path through the route was seen to throw, since anything the route calls can throw at runtime. A run with `gapHandling: "silent"` gets no gaps from this step either.
+
 ## Which branch an effect belongs to
 
 An adapter finds the calls a body makes once, and it finds the branches separately. Something then has to say which branch each call runs on. `guardsHoldOn` and `runsBefore` in `effectGuards.ts` are that decision, and both adapters that make it call these rather than keeping a copy.

package/dist/index.cjs

@@ -90,7 +90,68 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 var import_node_crypto3 = require("crypto");
-var import_behavioral_ir4 = require("@suss/behavioral-ir");
+var import_behavioral_ir5 = require("@suss/behavioral-ir");
+
+// src/contractStatusGaps.ts
+var import_behavioral_ir = require("@suss/behavioral-ir");
+function contractStatusGaps(contract, transitions) {
+  const producers = producersByStatus(transitions);
+  const declared = new Set(contract.responses.map((r) => r.statusCode));
+  const gaps = [];
+  for (const status of declared) {
+    if (!producers.has(status)) {
+      gaps.push({
+        type: "unhandledCase",
+        conditions: [],
+        consequence: "frameworkDefault",
+        description: `Declared response ${status} is never produced by the handler`
+      });
+    }
+  }
+  for (const [status, wrappers] of producers) {
+    if (declared.has(status)) {
+      continue;
+    }
+    gaps.push({
+      type: "unhandledCase",
+      conditions: [],
+      consequence: "unknown",
+      description: `${producerOf(wrappers)} produces status ${status} which is not declared in the ${contract.framework} contract`
+    });
+  }
+  return gaps;
+}
+function producersByStatus(transitions) {
+  const producers = /* @__PURE__ */ new Map();
+  for (const transition of transitions) {
+    if (transition.output.type !== "response") {
+      continue;
+    }
+    const status = transition.output.statusCode;
+    if (status?.type !== "literal" || typeof status.value !== "number") {
+      continue;
+    }
+    const from = (0, import_behavioral_ir.readWrapperMetadata)(transition)?.from;
+    const seen = producers.get(status.value);
+    if (seen === void 0) {
+      producers.set(
+        status.value,
+        new Set(from === void 0 ? [] : [from.name])
+      );
+    } else if (from === void 0) {
+      seen.clear();
+    } else if (seen.size > 0) {
+      seen.add(from.name);
+    }
+  }
+  return producers;
+}
+function producerOf(wrappers) {
+  if (wrappers.size === 0) {
+    return "Handler";
+  }
+  return `${[...wrappers].sort().join(" and ")}, registered around this handler,`;
+}
 
 // src/inputReads.ts
 function inputReadsOf(args) {
@@ -183,10 +244,10 @@ function mergeInputReads(derived, syntactic) {
 }
 
 // src/composeWrappers.ts
-var import_behavioral_ir2 = require("@suss/behavioral-ir");
+var import_behavioral_ir3 = require("@suss/behavioral-ir");
 
 // src/paths/enumeratePaths.ts
-var import_behavioral_ir = require("@suss/behavioral-ir");
+var import_behavioral_ir2 = require("@suss/behavioral-ir");
 var MAX_PATHS = 256;
 var UnmodeledFlow = class extends Error {
 };
@@ -230,7 +291,7 @@ var loopCompletedCond = (headerText, exit) => fixedCond(
   exit === "throw" ? "earlyThrow" : "earlyReturn"
 );
 var catchEntryCond = () => fixedCond(
-  { sourceText: import_behavioral_ir.CATCH_ENTRY_TEXT, expression: null },
+  { sourceText: import_behavioral_ir2.CATCH_ENTRY_TEXT, expression: null },
   "positive",
   "catchBlock"
 );
@@ -607,7 +668,7 @@ var BUDGET_GAP = {
   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) {
+function composeWrappers(summaries, options = {}) {
   const byKey = /* @__PURE__ */ new Map();
   for (const summary of summaries) {
     const key = summaryKey(summary.location.file, summary.identity.name);
@@ -615,20 +676,21 @@ function composeWrappers(summaries) {
       byKey.set(key, summary);
     }
   }
-  return summaries.map((summary) => composeOne(summary, byKey));
+  const keepGaps = options.gapHandling !== "silent";
+  return summaries.map((summary) => composeOne(summary, byKey, keepGaps));
 }
 function summaryKey(file, name) {
   return `${file}::${name}`;
 }
-function composeOne(summary, byKey) {
-  const recorded = (0, import_behavioral_ir2.readWrapperMetadata)(summary);
+function composeOne(summary, byKey, keepGaps) {
+  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
     })
   };
@@ -655,14 +717,45 @@ function composeOne(summary, byKey) {
     }
     composition = merge(composition, applyThrowWrapper(wrapper, composition));
   }
-  if (composition.transitions === summary.transitions) {
+  const transitions = composition.transitions === summary.transitions ? summary.transitions : withDistinctIds(composition.transitions);
+  if (!keepGaps) {
+    return { ...narrowed, transitions };
+  }
+  const gaps = withContractStatusGaps(summary, transitions, wrappers);
+  if (transitions === summary.transitions && gaps === summary.gaps) {
     return narrowed;
   }
   return {
     ...narrowed,
-    transitions: withDistinctIds(composition.transitions),
-    gaps: composition.degraded ? [...summary.gaps, BUDGET_GAP] : summary.gaps
+    transitions,
+    gaps: composition.degraded ? [...gaps, BUDGET_GAP] : gaps
+  };
+}
+function withContractStatusGaps(summary, composed, wrappers) {
+  const contract = (0, import_behavioral_ir3.readHttpMetadata)(summary)?.declaredContract;
+  const binding = summary.identity.boundaryBinding;
+  if (contract === void 0 || binding !== null && !(0, import_behavioral_ir3.exchangesHttpResponses)(binding)) {
+    return summary.gaps;
+  }
+  const declared = {
+    framework: contract.framework ?? "declared",
+    responses: contract.responses
   };
+  const stale = new Set(
+    contractStatusGaps(declared, summary.transitions).map(gapKey)
+  );
+  const onThrow = wrappers.filter((wrapper) => wrapper.reference.onThrow === true).flatMap(
+    (wrapper) => attribute(wrapper.summary.transitions, wrapper.reference)
+  );
+  const gaps = [
+    ...summary.gaps.filter((gap) => !stale.has(gapKey(gap))),
+    ...contractStatusGaps(declared, [...composed, ...onThrow])
+  ];
+  const unchanged = gaps.length === summary.gaps.length && gaps.every((gap, i) => gapKey(gap) === gapKey(summary.gaps[i]));
+  return unchanged ? summary.gaps : gaps;
+}
+function gapKey(gap) {
+  return `${gap.type}|${gap.description}`;
 }
 function merge(before, step) {
   return {
@@ -675,7 +768,7 @@ 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 applyWrapper(wrapper, inner) {
   const shortCircuits = attribute(
@@ -732,7 +825,7 @@ function splice(outer, inner) {
 function attribute(transitions, reference) {
   return transitions.map((transition) => ({
     ...transition,
-    metadata: (0, import_behavioral_ir2.withWrapperMetadata)(transition.metadata, { from: reference })
+    metadata: (0, import_behavioral_ir3.withWrapperMetadata)(transition.metadata, { from: reference })
   }));
 }
 function withDistinctIds(transitions) {
@@ -1603,7 +1696,7 @@ function fileStampEquals(a, b) {
 }
 
 // src/extractionReport.ts
-var import_behavioral_ir3 = require("@suss/behavioral-ir");
+var import_behavioral_ir4 = require("@suss/behavioral-ir");
 var emptyTally = () => ({
   candidateFiles: 0,
   unitsDiscovered: 0,
@@ -1654,7 +1747,7 @@ function summaryCountsByPack(summaries) {
     }
     const entry = counts.get(recognition) ?? emptyCounts();
     entry.bound += 1;
-    if (import_behavioral_ir3.BOUNDARY_ROLE[summary.kind] === "provider") {
+    if (import_behavioral_ir4.BOUNDARY_ROLE[summary.kind] === "provider") {
       entry.providers += 1;
     }
     if (summary.transitions.length > 0) {
@@ -2122,22 +2215,22 @@ function buildMetadata(raw) {
   let metadata = {};
   const http = buildHttpMetadataValue(raw);
   if (http !== null) {
-    metadata = (0, import_behavioral_ir4.withHttpMetadata)(metadata, http);
+    metadata = (0, import_behavioral_ir5.withHttpMetadata)(metadata, http);
   }
   const graphql = buildGraphqlMetadataValue(raw);
   if (graphql !== null) {
-    metadata = (0, import_behavioral_ir4.withGraphqlMetadata)(metadata, graphql);
+    metadata = (0, import_behavioral_ir5.withGraphqlMetadata)(metadata, graphql);
   }
   if (raw.sourceDocumentLabel !== void 0) {
-    metadata = (0, import_behavioral_ir4.withSourceDocumentMetadata)(metadata, {
+    metadata = (0, import_behavioral_ir5.withSourceDocumentMetadata)(metadata, {
       label: raw.sourceDocumentLabel
     });
   }
   if (raw.mount !== void 0) {
-    metadata = (0, import_behavioral_ir4.withMountMetadata)(metadata, raw.mount);
+    metadata = (0, import_behavioral_ir5.withMountMetadata)(metadata, raw.mount);
   }
   if (raw.wrappers !== void 0 && raw.wrappers.length > 0) {
-    metadata = (0, import_behavioral_ir4.withWrapperMetadata)(metadata, { applied: raw.wrappers });
+    metadata = (0, import_behavioral_ir5.withWrapperMetadata)(metadata, { applied: raw.wrappers });
   }
   return Object.keys(metadata).length > 0 ? metadata : null;
 }
@@ -2187,7 +2280,7 @@ function answersWithHttpResponses(raw) {
   if (raw.boundaryBinding === null || raw.boundaryBinding === void 0) {
     return true;
   }
-  return (0, import_behavioral_ir4.exchangesHttpResponses)(raw.boundaryBinding);
+  return (0, import_behavioral_ir5.exchangesHttpResponses)(raw.boundaryBinding);
 }
 function detectGaps(raw, transitions, options) {
   if (options.gapHandling === "silent") {
@@ -2221,41 +2314,7 @@ function detectGaps(raw, transitions, options) {
     });
   }
   if (raw.declaredContract && answersWithHttpResponses(raw)) {
-    const producedStatuses = new Set(
-      transitions.flatMap((t) => {
-        if (t.output.type !== "response") {
-          return [];
-        }
-        const sc = t.output.statusCode;
-        if (sc?.type === "literal") {
-          return [sc.value];
-        }
-        return [];
-      })
-    );
-    const declaredStatuses = new Set(
-      raw.declaredContract.responses.map((r) => r.statusCode)
-    );
-    for (const declared of declaredStatuses) {
-      if (!producedStatuses.has(declared)) {
-        gaps.push({
-          type: "unhandledCase",
-          conditions: [],
-          consequence: "frameworkDefault",
-          description: `Declared response ${declared} is never produced by the handler`
-        });
-      }
-    }
-    for (const produced of producedStatuses) {
-      if (!declaredStatuses.has(produced)) {
-        gaps.push({
-          type: "unhandledCase",
-          conditions: [],
-          consequence: "unknown",
-          description: `Handler produces status ${produced} which is not declared in the ${raw.declaredContract.framework} contract`
-        });
-      }
-    }
+    gaps.push(...contractStatusGaps(raw.declaredContract, transitions));
   }
   return gaps;
 }

package/dist/index.d.cts

@@ -721,6 +721,66 @@ type DeclaredBinding = {
     messageBus: MessageBusSemantics["messageBus"];
     channel: ChannelSource;
 };
+/**
+ * How a framework takes a function that runs around a handler rather
+ * than as one. Middleware and an error handler are registered through
+ * a method on the routable, `app.use(fn)` or `app.onError(fn)`. A
+ * validation hook is handed to the routable's constructor instead,
+ * `new OpenAPIHono({ defaultHook })`, and runs for every route on it.
+ */
+type WrapperRegistration = WrapperMethodRegistration | WrapperOptionRegistration;
+/** What every wrapper registration says about the function it registers. */
+interface WrapperFunctionShape {
+    /**
+     * Parameter position of the continuation inside the wrapper, the one
+     * it calls to hand control on. Absent when the wrapper never
+     * continues, which is how an error handler that always responds is
+     * written.
+     */
+    continuationParam?: number;
+    /**
+     * Parameter position that receives what the wrapped unit threw. A
+     * wrapper that declares one runs only when the wrapped unit's path
+     * ended by throwing, which is a fact about how the framework invokes
+     * it rather than anything its body says. Absent means the wrapper
+     * runs on the ordinary path.
+     */
+    throwParam?: number;
+    /**
+     * Parameter position that receives a value the framework worked out
+     * before calling the wrapper, the outcome of validating the request
+     * for a hook. The pack's terminals read one parameter further along
+     * from there, as they do past `throwParam`, and nothing else changes:
+     * the wrapper still runs on the ordinary path.
+     */
+    resultParam?: number;
+}
+/** A wrapper registered through a method on the routable. */
+interface WrapperMethodRegistration extends WrapperFunctionShape {
+    /** Method name that registers a wrapper, e.g. "use" or "onError". */
+    method: string;
+    /** Argument position of the wrapper function. */
+    targetPosition: number;
+    /**
+     * Argument position of a path pattern narrowing which routes the
+     * wrapper runs for, when the method takes one. Absent means the
+     * wrapper runs for every route on the subject.
+     */
+    scopePosition?: number;
+    /**
+     * Only match a registered function declared with exactly this many
+     * parameters. Express tells its error handlers apart from its
+     * middleware by arity alone, both being `app.use(fn)`.
+     */
+    arity?: number;
+}
+/** A wrapper handed to the routable's constructor as an option. */
+interface WrapperOptionRegistration extends WrapperFunctionShape {
+    /** The option the wrapper is under, e.g. "defaultHook". */
+    constructorOption: string;
+    /** Argument position of the options object in the constructor call. */
+    targetPosition: number;
+}
 interface DiscoveryPattern {
     /** The kind of code unit this discovers: "handler", "loader", "action", "component", etc. */
     kind: string;
@@ -767,39 +827,7 @@ interface DiscoveryPattern {
      * routable records a reference to it. A registration whose function
      * the resolution store cannot follow contributes nothing.
      */
-    wraps?: {
-        /** Method name that registers a wrapper, e.g. "use" or "onError". */
-        method: string;
-        /** Argument position of the wrapper function. */
-        targetPosition: number;
-        /**
-         * Argument position of a path pattern narrowing which routes the
-         * wrapper runs for, when the method takes one. Absent means the
-         * wrapper runs for every route on the subject.
-         */
-        scopePosition?: number;
-        /**
-         * Parameter position of the continuation inside the wrapper, the one
-         * it calls to hand control on. Absent when the wrapper never
-         * continues, which is how an error handler that always responds is
-         * written.
-         */
-        continuationParam?: number;
-        /**
-         * Parameter position that receives what the wrapped unit threw. A
-         * wrapper that declares one runs only when the wrapped unit's path
-         * ended by throwing, which is a fact about how the framework invokes
-         * it rather than anything its body says. Absent means the wrapper
-         * runs on the ordinary path.
-         */
-        throwParam?: number;
-        /**
-         * Only match a registered function declared with exactly this many
-         * parameters. Express tells its error handlers apart from its
-         * middleware by arity alone, both being `app.use(fn)`.
-         */
-        arity?: number;
-    };
+    wraps?: WrapperRegistration;
     /**
      * This pattern only runs against files that import one of these module
      * specifiers, or a sub-path of one. An empty array means no gate at all
@@ -1863,12 +1891,19 @@ declare function valueToReadFurtherFrom<T>(reading: Reading<T>): T | null;
  * what composition does not read.
  */
 
+/**
+ * Whether to keep gaps at all. A run that asked for none has none on
+ * the summaries coming in, and composition adds none either.
+ */
+interface ComposeOptions {
+    gapHandling?: "strict" | "permissive" | "silent";
+}
 /**
  * Every summary, with the ones that record wrappers replaced by their
  * composition. A summary with no wrappers, and one whose wrappers this
  * run has no summaries for, comes back untouched.
  */
-declare function composeWrappers(summaries: readonly BehavioralSummary[]): BehavioralSummary[];
+declare function composeWrappers(summaries: readonly BehavioralSummary[], options?: ComposeOptions): BehavioralSummary[];
 
 /**
  * Which branch an effect belongs to.
@@ -3407,4 +3442,4 @@ declare function rawConditionToPredicate(c: RawCondition): Predicate;
 declare function effectToIR(effect: RawEffect): Effect;
 declare function paramToInput(param: RawParameter): Input;
 
-export { type AccessRecognizer, type AdapterCodeStamp, type AdapterStamp, type AstCapableOps, type BindingExtraction, type BodyContent, type CacheAttribution, type CacheDiagnostic, type CacheInput, type CacheLayer, type CacheLookup, type CallOps, type CaseGroup, type ChannelSource, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ConstructedFrom, type ContractPattern, type DeclaredBinding, type DeclaredBy, type DeclaredMatch, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type EmptyStage, type ExitKind, type ExtractionReport, type ExtractorOptions, type FailureDelivery, type HealthCheck, type HealthViolation, type HelperDeclarations, type HelperSearch, type HelperSink, type HelperValue, IdMap, IdSet, type Identified, type InputMappingPattern, type InputRead, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, MAX_ENTRIES, MAX_PATHS, type ModuleInitOptions, type NodeVisitor, type OpsCarrier, type PackDeclarations, type PackFailure, type PackFunnel, type PackGradient, type PackTally, type PartialPlan, PathBudgetExceeded, type PatternPack, type ProjectHelper, type ProjectHelpers, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ReceiverOrigin, type RegistrationHelper, type ResponsePropertyMapping, type ResponsePropertyMeaning, type RootRecord, SKIP_CHILDREN, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type Timer, type TimingReport, type TransparentWrapper, UnmodeledFlow, type UnsettledName, type ValueEntry, type ValueOps, type WalkableNode, absentReading, ambiguousReading, 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, valueToReadFurtherFrom, walkDescendants, wrapperDiscovery, writtenReading };
+export { type AccessRecognizer, type AdapterCodeStamp, type AdapterStamp, type AstCapableOps, type BindingExtraction, type BodyContent, type CacheAttribution, type CacheDiagnostic, type CacheInput, type CacheLayer, type CacheLookup, type CallOps, type CaseGroup, type ChannelSource, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ConstructedFrom, type ContractPattern, type DeclaredBinding, type DeclaredBy, type DeclaredMatch, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type EmptyStage, type ExitKind, type ExtractionReport, type ExtractorOptions, type FailureDelivery, type HealthCheck, type HealthViolation, type HelperDeclarations, type HelperSearch, type HelperSink, type HelperValue, IdMap, IdSet, type Identified, type InputMappingPattern, type InputRead, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, MAX_ENTRIES, MAX_PATHS, type ModuleInitOptions, type NodeVisitor, type OpsCarrier, type PackDeclarations, type PackFailure, type PackFunnel, type PackGradient, type PackTally, type PartialPlan, PathBudgetExceeded, type PatternPack, type ProjectHelper, type ProjectHelpers, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ReceiverOrigin, type RegistrationHelper, type ResponsePropertyMapping, type ResponsePropertyMeaning, type RootRecord, SKIP_CHILDREN, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type Timer, type TimingReport, type TransparentWrapper, UnmodeledFlow, type UnsettledName, type ValueEntry, type ValueOps, type WalkableNode, type WrapperMethodRegistration, type WrapperOptionRegistration, type WrapperRegistration, absentReading, ambiguousReading, 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, valueToReadFurtherFrom, walkDescendants, wrapperDiscovery, writtenReading };

package/dist/index.d.ts

@@ -721,6 +721,66 @@ type DeclaredBinding = {
     messageBus: MessageBusSemantics["messageBus"];
     channel: ChannelSource;
 };
+/**
+ * How a framework takes a function that runs around a handler rather
+ * than as one. Middleware and an error handler are registered through
+ * a method on the routable, `app.use(fn)` or `app.onError(fn)`. A
+ * validation hook is handed to the routable's constructor instead,
+ * `new OpenAPIHono({ defaultHook })`, and runs for every route on it.
+ */
+type WrapperRegistration = WrapperMethodRegistration | WrapperOptionRegistration;
+/** What every wrapper registration says about the function it registers. */
+interface WrapperFunctionShape {
+    /**
+     * Parameter position of the continuation inside the wrapper, the one
+     * it calls to hand control on. Absent when the wrapper never
+     * continues, which is how an error handler that always responds is
+     * written.
+     */
+    continuationParam?: number;
+    /**
+     * Parameter position that receives what the wrapped unit threw. A
+     * wrapper that declares one runs only when the wrapped unit's path
+     * ended by throwing, which is a fact about how the framework invokes
+     * it rather than anything its body says. Absent means the wrapper
+     * runs on the ordinary path.
+     */
+    throwParam?: number;
+    /**
+     * Parameter position that receives a value the framework worked out
+     * before calling the wrapper, the outcome of validating the request
+     * for a hook. The pack's terminals read one parameter further along
+     * from there, as they do past `throwParam`, and nothing else changes:
+     * the wrapper still runs on the ordinary path.
+     */
+    resultParam?: number;
+}
+/** A wrapper registered through a method on the routable. */
+interface WrapperMethodRegistration extends WrapperFunctionShape {
+    /** Method name that registers a wrapper, e.g. "use" or "onError". */
+    method: string;
+    /** Argument position of the wrapper function. */
+    targetPosition: number;
+    /**
+     * Argument position of a path pattern narrowing which routes the
+     * wrapper runs for, when the method takes one. Absent means the
+     * wrapper runs for every route on the subject.
+     */
+    scopePosition?: number;
+    /**
+     * Only match a registered function declared with exactly this many
+     * parameters. Express tells its error handlers apart from its
+     * middleware by arity alone, both being `app.use(fn)`.
+     */
+    arity?: number;
+}
+/** A wrapper handed to the routable's constructor as an option. */
+interface WrapperOptionRegistration extends WrapperFunctionShape {
+    /** The option the wrapper is under, e.g. "defaultHook". */
+    constructorOption: string;
+    /** Argument position of the options object in the constructor call. */
+    targetPosition: number;
+}
 interface DiscoveryPattern {
     /** The kind of code unit this discovers: "handler", "loader", "action", "component", etc. */
     kind: string;
@@ -767,39 +827,7 @@ interface DiscoveryPattern {
      * routable records a reference to it. A registration whose function
      * the resolution store cannot follow contributes nothing.
      */
-    wraps?: {
-        /** Method name that registers a wrapper, e.g. "use" or "onError". */
-        method: string;
-        /** Argument position of the wrapper function. */
-        targetPosition: number;
-        /**
-         * Argument position of a path pattern narrowing which routes the
-         * wrapper runs for, when the method takes one. Absent means the
-         * wrapper runs for every route on the subject.
-         */
-        scopePosition?: number;
-        /**
-         * Parameter position of the continuation inside the wrapper, the one
-         * it calls to hand control on. Absent when the wrapper never
-         * continues, which is how an error handler that always responds is
-         * written.
-         */
-        continuationParam?: number;
-        /**
-         * Parameter position that receives what the wrapped unit threw. A
-         * wrapper that declares one runs only when the wrapped unit's path
-         * ended by throwing, which is a fact about how the framework invokes
-         * it rather than anything its body says. Absent means the wrapper
-         * runs on the ordinary path.
-         */
-        throwParam?: number;
-        /**
-         * Only match a registered function declared with exactly this many
-         * parameters. Express tells its error handlers apart from its
-         * middleware by arity alone, both being `app.use(fn)`.
-         */
-        arity?: number;
-    };
+    wraps?: WrapperRegistration;
     /**
      * This pattern only runs against files that import one of these module
      * specifiers, or a sub-path of one. An empty array means no gate at all
@@ -1863,12 +1891,19 @@ declare function valueToReadFurtherFrom<T>(reading: Reading<T>): T | null;
  * what composition does not read.
  */
 
+/**
+ * Whether to keep gaps at all. A run that asked for none has none on
+ * the summaries coming in, and composition adds none either.
+ */
+interface ComposeOptions {
+    gapHandling?: "strict" | "permissive" | "silent";
+}
 /**
  * Every summary, with the ones that record wrappers replaced by their
  * composition. A summary with no wrappers, and one whose wrappers this
  * run has no summaries for, comes back untouched.
  */
-declare function composeWrappers(summaries: readonly BehavioralSummary[]): BehavioralSummary[];
+declare function composeWrappers(summaries: readonly BehavioralSummary[], options?: ComposeOptions): BehavioralSummary[];
 
 /**
  * Which branch an effect belongs to.
@@ -3407,4 +3442,4 @@ declare function rawConditionToPredicate(c: RawCondition): Predicate;
 declare function effectToIR(effect: RawEffect): Effect;
 declare function paramToInput(param: RawParameter): Input;
 
-export { type AccessRecognizer, type AdapterCodeStamp, type AdapterStamp, type AstCapableOps, type BindingExtraction, type BodyContent, type CacheAttribution, type CacheDiagnostic, type CacheInput, type CacheLayer, type CacheLookup, type CallOps, type CaseGroup, type ChannelSource, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ConstructedFrom, type ContractPattern, type DeclaredBinding, type DeclaredBy, type DeclaredMatch, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type EmptyStage, type ExitKind, type ExtractionReport, type ExtractorOptions, type FailureDelivery, type HealthCheck, type HealthViolation, type HelperDeclarations, type HelperSearch, type HelperSink, type HelperValue, IdMap, IdSet, type Identified, type InputMappingPattern, type InputRead, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, MAX_ENTRIES, MAX_PATHS, type ModuleInitOptions, type NodeVisitor, type OpsCarrier, type PackDeclarations, type PackFailure, type PackFunnel, type PackGradient, type PackTally, type PartialPlan, PathBudgetExceeded, type PatternPack, type ProjectHelper, type ProjectHelpers, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ReceiverOrigin, type RegistrationHelper, type ResponsePropertyMapping, type ResponsePropertyMeaning, type RootRecord, SKIP_CHILDREN, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type Timer, type TimingReport, type TransparentWrapper, UnmodeledFlow, type UnsettledName, type ValueEntry, type ValueOps, type WalkableNode, absentReading, ambiguousReading, 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, valueToReadFurtherFrom, walkDescendants, wrapperDiscovery, writtenReading };
+export { type AccessRecognizer, type AdapterCodeStamp, type AdapterStamp, type AstCapableOps, type BindingExtraction, type BodyContent, type CacheAttribution, type CacheDiagnostic, type CacheInput, type CacheLayer, type CacheLookup, type CallOps, type CaseGroup, type ChannelSource, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ConstructedFrom, type ContractPattern, type DeclaredBinding, type DeclaredBy, type DeclaredMatch, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type EmptyStage, type ExitKind, type ExtractionReport, type ExtractorOptions, type FailureDelivery, type HealthCheck, type HealthViolation, type HelperDeclarations, type HelperSearch, type HelperSink, type HelperValue, IdMap, IdSet, type Identified, type InputMappingPattern, type InputRead, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, MAX_ENTRIES, MAX_PATHS, type ModuleInitOptions, type NodeVisitor, type OpsCarrier, type PackDeclarations, type PackFailure, type PackFunnel, type PackGradient, type PackTally, type PartialPlan, PathBudgetExceeded, type PatternPack, type ProjectHelper, type ProjectHelpers, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ReceiverOrigin, type RegistrationHelper, type ResponsePropertyMapping, type ResponsePropertyMeaning, type RootRecord, SKIP_CHILDREN, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type Timer, type TimingReport, type TransparentWrapper, UnmodeledFlow, type UnsettledName, type ValueEntry, type ValueOps, type WalkableNode, type WrapperMethodRegistration, type WrapperOptionRegistration, type WrapperRegistration, absentReading, ambiguousReading, 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, valueToReadFurtherFrom, walkDescendants, wrapperDiscovery, writtenReading };

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/index.ts
 import { createHash as createHash3 } from "crypto";
 import {
-  exchangesHttpResponses,
+  exchangesHttpResponses as exchangesHttpResponses2,
   withGraphqlMetadata,
   withHttpMetadata,
   withMountMetadata,
@@ -9,6 +9,67 @@ import {
   withWrapperMetadata as withWrapperMetadata2
 } from "@suss/behavioral-ir";
 
+// src/contractStatusGaps.ts
+import { readWrapperMetadata } from "@suss/behavioral-ir";
+function contractStatusGaps(contract, transitions) {
+  const producers = producersByStatus(transitions);
+  const declared = new Set(contract.responses.map((r) => r.statusCode));
+  const gaps = [];
+  for (const status of declared) {
+    if (!producers.has(status)) {
+      gaps.push({
+        type: "unhandledCase",
+        conditions: [],
+        consequence: "frameworkDefault",
+        description: `Declared response ${status} is never produced by the handler`
+      });
+    }
+  }
+  for (const [status, wrappers] of producers) {
+    if (declared.has(status)) {
+      continue;
+    }
+    gaps.push({
+      type: "unhandledCase",
+      conditions: [],
+      consequence: "unknown",
+      description: `${producerOf(wrappers)} produces status ${status} which is not declared in the ${contract.framework} contract`
+    });
+  }
+  return gaps;
+}
+function producersByStatus(transitions) {
+  const producers = /* @__PURE__ */ new Map();
+  for (const transition of transitions) {
+    if (transition.output.type !== "response") {
+      continue;
+    }
+    const status = transition.output.statusCode;
+    if (status?.type !== "literal" || typeof status.value !== "number") {
+      continue;
+    }
+    const from = readWrapperMetadata(transition)?.from;
+    const seen = producers.get(status.value);
+    if (seen === void 0) {
+      producers.set(
+        status.value,
+        new Set(from === void 0 ? [] : [from.name])
+      );
+    } else if (from === void 0) {
+      seen.clear();
+    } else if (seen.size > 0) {
+      seen.add(from.name);
+    }
+  }
+  return producers;
+}
+function producerOf(wrappers) {
+  if (wrappers.size === 0) {
+    return "Handler";
+  }
+  return `${[...wrappers].sort().join(" and ")}, registered around this handler,`;
+}
+
 // src/inputReads.ts
 function inputReadsOf(args) {
   const found = /* @__PURE__ */ new Map();
@@ -101,7 +162,9 @@ function mergeInputReads(derived, syntactic) {
 
 // src/composeWrappers.ts
 import {
-  readWrapperMetadata,
+  exchangesHttpResponses,
+  readHttpMetadata,
+  readWrapperMetadata as readWrapperMetadata2,
   withinScope,
   withWrapperMetadata
 } from "@suss/behavioral-ir";
@@ -528,7 +591,7 @@ var BUDGET_GAP = {
   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) {
+function composeWrappers(summaries, options = {}) {
   const byKey = /* @__PURE__ */ new Map();
   for (const summary of summaries) {
     const key = summaryKey(summary.location.file, summary.identity.name);
@@ -536,13 +599,14 @@ function composeWrappers(summaries) {
       byKey.set(key, summary);
     }
   }
-  return summaries.map((summary) => composeOne(summary, byKey));
+  const keepGaps = options.gapHandling !== "silent";
+  return summaries.map((summary) => composeOne(summary, byKey, keepGaps));
 }
 function summaryKey(file, name) {
   return `${file}::${name}`;
 }
-function composeOne(summary, byKey) {
-  const recorded = readWrapperMetadata(summary);
+function composeOne(summary, byKey, keepGaps) {
+  const recorded = readWrapperMetadata2(summary);
   const applied = recorded?.applied ?? [];
   const covering = applied.filter(
     (reference) => coversUnit(reference, summary)
@@ -576,14 +640,45 @@ function composeOne(summary, byKey) {
     }
     composition = merge(composition, applyThrowWrapper(wrapper, composition));
   }
-  if (composition.transitions === summary.transitions) {
+  const transitions = composition.transitions === summary.transitions ? summary.transitions : withDistinctIds(composition.transitions);
+  if (!keepGaps) {
+    return { ...narrowed, transitions };
+  }
+  const gaps = withContractStatusGaps(summary, transitions, wrappers);
+  if (transitions === summary.transitions && gaps === summary.gaps) {
     return narrowed;
   }
   return {
     ...narrowed,
-    transitions: withDistinctIds(composition.transitions),
-    gaps: composition.degraded ? [...summary.gaps, BUDGET_GAP] : summary.gaps
+    transitions,
+    gaps: composition.degraded ? [...gaps, BUDGET_GAP] : gaps
+  };
+}
+function withContractStatusGaps(summary, composed, wrappers) {
+  const contract = readHttpMetadata(summary)?.declaredContract;
+  const binding = summary.identity.boundaryBinding;
+  if (contract === void 0 || binding !== null && !exchangesHttpResponses(binding)) {
+    return summary.gaps;
+  }
+  const declared = {
+    framework: contract.framework ?? "declared",
+    responses: contract.responses
   };
+  const stale = new Set(
+    contractStatusGaps(declared, summary.transitions).map(gapKey)
+  );
+  const onThrow = wrappers.filter((wrapper) => wrapper.reference.onThrow === true).flatMap(
+    (wrapper) => attribute(wrapper.summary.transitions, wrapper.reference)
+  );
+  const gaps = [
+    ...summary.gaps.filter((gap) => !stale.has(gapKey(gap))),
+    ...contractStatusGaps(declared, [...composed, ...onThrow])
+  ];
+  const unchanged = gaps.length === summary.gaps.length && gaps.every((gap, i) => gapKey(gap) === gapKey(summary.gaps[i]));
+  return unchanged ? summary.gaps : gaps;
+}
+function gapKey(gap) {
+  return `${gap.type}|${gap.description}`;
 }
 function merge(before, step) {
   return {
@@ -2107,7 +2202,7 @@ function answersWithHttpResponses(raw) {
   if (raw.boundaryBinding === null || raw.boundaryBinding === void 0) {
     return true;
   }
-  return exchangesHttpResponses(raw.boundaryBinding);
+  return exchangesHttpResponses2(raw.boundaryBinding);
 }
 function detectGaps(raw, transitions, options) {
   if (options.gapHandling === "silent") {
@@ -2141,41 +2236,7 @@ function detectGaps(raw, transitions, options) {
     });
   }
   if (raw.declaredContract && answersWithHttpResponses(raw)) {
-    const producedStatuses = new Set(
-      transitions.flatMap((t) => {
-        if (t.output.type !== "response") {
-          return [];
-        }
-        const sc = t.output.statusCode;
-        if (sc?.type === "literal") {
-          return [sc.value];
-        }
-        return [];
-      })
-    );
-    const declaredStatuses = new Set(
-      raw.declaredContract.responses.map((r) => r.statusCode)
-    );
-    for (const declared of declaredStatuses) {
-      if (!producedStatuses.has(declared)) {
-        gaps.push({
-          type: "unhandledCase",
-          conditions: [],
-          consequence: "frameworkDefault",
-          description: `Declared response ${declared} is never produced by the handler`
-        });
-      }
-    }
-    for (const produced of producedStatuses) {
-      if (!declaredStatuses.has(produced)) {
-        gaps.push({
-          type: "unhandledCase",
-          conditions: [],
-          consequence: "unknown",
-          description: `Handler produces status ${produced} which is not declared in the ${raw.declaredContract.framework} contract`
-        });
-      }
-    }
+    gaps.push(...contractStatusGaps(raw.declaredContract, transitions));
   }
   return gaps;
 }

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@suss/extractor",
-  "version": "0.22.3",
+  "version": "0.23.0",
   "type": "module",
-  "description": "Framework-agnostic extraction pipeline that turns raw extractions into suss behavioral summaries.",
+  "description": "The suss extraction pipeline, which turns what a language adapter read into the summaries the checker pairs across a boundary.",
   "keywords": [
     "suss",
-    "behavioral-summary",
     "static-analysis",
+    "behavioral-summary",
     "extraction",
-    "typescript"
+    "typescript",
+    "api-contract"
   ],
   "license": "Apache-2.0",
   "author": "Nimbus Cloud AI LLC",
@@ -45,7 +46,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.22.3",
+    "@suss/behavioral-ir": "0.23.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {