@suss/extractor 0.0.1 → 0.1.0

package/README.md

@@ -4,7 +4,7 @@ Assembly engine that turns raw language-adapter output into a `BehavioralSummary
 
 ## What this package is
 
-`@suss/extractor` is the core assembly layer of the suss pipeline. Language adapters (such as `@suss/adapter-typescript`) parse source code and produce a `RawCodeStructure` — a normalized, adapter-specific intermediate form. The extractor's `assembleSummary` function converts that structure into the final `BehavioralSummary` IR, handling condition polarity, terminal mapping, gap detection, confidence assessment, and `expectedInput` pass-through for client field tracking. It also exports the `RawCodeStructure` type, the `PatternPack` interface, and all related raw types so adapters can share a common contract.
+`@suss/extractor` is the core assembly layer of the suss pipeline. Language adapters (such as `@suss/adapter-typescript`) parse source code and produce a `RawCodeStructure`, a normalized, adapter-specific intermediate form. The extractor's `assembleSummary` function converts that structure into the final `BehavioralSummary` IR, handling condition polarity, terminal mapping, gap detection, confidence assessment, and `expectedInput` pass-through for client field tracking. It also exports the `RawCodeStructure` type, the `PatternPack` interface, and all related raw types so adapters can share a common contract.
 
 ## Where it sits in suss
 

package/dist/index.cjs

@@ -150,6 +150,17 @@ function detectGaps(raw, transitions, options) {
     return [];
   }
   const gaps = [];
+  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.declaredContract) {
     const producedStatuses = new Set(
       transitions.flatMap((t) => {
@@ -190,6 +201,9 @@ function detectGaps(raw, transitions, options) {
   return gaps;
 }
 function assessConfidence(raw) {
+  if ((raw.unmatchedReturns ?? 0) > 0) {
+    return { source: "inferred_static", level: "low" };
+  }
   let total = 0;
   let opaque = 0;
   for (const branch of raw.branches) {

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Effect, Predicate, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, BehavioralSummary, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
+import { Effect, MessageBusSemantics, Predicate, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, BehavioralSummary, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
 
 type DiscoveryMatch = {
     type: "namedExport";
@@ -374,7 +374,49 @@ type BindingExtraction = {
         type: "fromRegistration";
         position: number;
     } | {
+        type: "fromArgumentProperty";
+        position: number;
+        property: string;
+    } | {
+        /**
+         * The route path comes from where the file sits, which is how
+         * Next.js and React Router describe their routes. The pack
+         * spells out its own convention here, since the adapter knows
+         * about files and the pack knows what the framework does with
+         * their names.
+         *
+         * `app/api/orders/[id]/route.ts` under `{ root: "app",
+         * dropBasenames: ["route"], dynamic: "brackets" }` comes out as
+         * `/api/orders/{id}`, which pairs with an Express provider
+         * writing `/api/orders/:id`.
+         */
         type: "fromFilename";
+        /**
+         * Where a route path starts. The directories below it become
+         * the path; everything above it belongs to the project layout
+         * and is dropped.
+         */
+        root: string;
+        /**
+         * Filenames that say what a file is rather than adding a
+         * segment: `route`, `page`, `index`, `_index`.
+         */
+        dropBasenames?: string[];
+        /**
+         * How the framework writes a parameter in a filename. Next.js
+         * uses `[id]`, React Router uses `$id`.
+         */
+        dynamic?: "brackets" | "dollarPrefix";
+        /**
+         * Whether a directory in parentheses organises files without
+         * appearing in the URL, as `app/(marketing)/about` does.
+         */
+        dropParenthesized?: boolean;
+        /**
+         * Whether one filename holds the whole path with dots between
+         * the segments, as `routes/orders.$id.tsx` does.
+         */
+        flat?: boolean;
     } | {
         type: "fromContract";
     } | {
@@ -487,6 +529,10 @@ interface TerminalExtraction {
     } | {
         from: "constructor";
         codes: Record<string, number>;
+    } | {
+        from: "argumentProperty";
+        position: number;
+        name: string;
     } | {
         from: "argumentConstructor";
         position: number;
@@ -619,6 +665,23 @@ interface ResponsePropertyMapping {
     /** What the value semantically represents */
     semantics: ResponsePropertyMeaning;
 }
+/**
+ * A library wrapper whose result is the function it was handed. The
+ * adapter works this out on its own for factories declared in the
+ * project by reading their bodies. A library's body is not readable,
+ * so the pack states it.
+ */
+interface TransparentWrapper {
+    /** Callee text as written, e.g. "Sentry.wrapHandler". */
+    callee: string;
+    /** Which argument holds the wrapped function. */
+    argument: number;
+    /**
+     * The module the callee has to have been imported from. Without it a
+     * local object spelled the same way would be taken for the library.
+     */
+    module: string;
+}
 interface PatternPack {
     name: string;
     /**
@@ -792,6 +855,17 @@ interface PatternPack {
      * available without an import).
      */
     requiresImport?: string[];
+    /**
+     * Library wrappers whose result is the wrapped function. The adapter
+     * derives this automatically for project-local factories by reading
+     * their bodies; a library wrapper's body is not readable, so the
+     * pack states the judgment: a call to `callee` resolves to its
+     * `argument`-th argument.
+     *
+     * `callee` matches the call expression text as written, e.g.
+     * `"Sentry.wrapHandler"`.
+     */
+    transparentWrappers?: TransparentWrapper[];
     /**
      * Per-property-access recognizers — sister to
      * `invocationRecognizers` but firing on `PropertyAccessExpression`
@@ -884,6 +958,29 @@ interface DiscoveredCustomUnit {
         method: string;
         path: string;
     };
+    /**
+     * GraphQL field identity for units a callback discovers against an
+     * external manifest rather than an in-code resolver map. AppSync
+     * routes a field to a Lambda in the deploy template, so the field is
+     * the boundary that code serves. When set, the adapter builds a
+     * `graphql-resolver` binding from `(typeName, fieldName)`, which
+     * pairs with the operations a client sends.
+     */
+    resolverInfo?: {
+        typeName: string;
+        fieldName: string;
+    };
+    /**
+     * Message-bus channel identity for consumer units a callback
+     * discovers against a subject the code itself names (a handler
+     * factory whose config carries the expected subject). When set, the
+     * adapter builds a `message-bus` binding from `(messageBus, channel)`,
+     * which pairs with producers sending on the same channel.
+     */
+    channelInfo?: {
+        messageBus: MessageBusSemantics["messageBus"];
+        channel: string;
+    };
     /**
      * Metadata merged onto the resulting summary's `metadata` field.
      */
@@ -1188,6 +1285,13 @@ interface RawCodeStructure {
     boundaryBinding: BoundaryBinding | null;
     parameters: RawParameter[];
     branches: RawBranch[];
+    /**
+     * Return statements in the body that none of the pack's terminals
+     * matched. A handler shaped in a way the pack does not describe still
+     * returns something, and saying nothing about it reads the same as
+     * saying it does nothing.
+     */
+    unmatchedReturns?: number;
     dependencyCalls: RawDependencyCall[];
     declaredContract: RawDeclaredContract | null;
     /**
@@ -1266,4 +1370,4 @@ declare function terminalToOutput(terminal: RawTerminal): Output;
 declare function effectToIR(effect: RawEffect): Effect;
 declare function paramToInput(param: RawParameter): Input;
 
-export { type AccessRecognizer, type BindingExtraction, type ContractPattern, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExtractorOptions, type InputMappingPattern, type InvocationRecognizer, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type ResponsePropertyMapping, type ResponsePropertyMeaning, type TerminalExtraction, type TerminalMatch, type TerminalPattern, assembleSummary, assessConfidence, detectGaps, effectToIR, httpRouteDiscovery, makeTransitionId, paramToInput, terminalToOutput };
+export { type AccessRecognizer, type BindingExtraction, type ContractPattern, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExtractorOptions, type InputMappingPattern, type InvocationRecognizer, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type ResponsePropertyMapping, type ResponsePropertyMeaning, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, assembleSummary, assessConfidence, detectGaps, effectToIR, httpRouteDiscovery, makeTransitionId, paramToInput, terminalToOutput };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Effect, Predicate, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, BehavioralSummary, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
+import { Effect, MessageBusSemantics, Predicate, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, BehavioralSummary, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
 
 type DiscoveryMatch = {
     type: "namedExport";
@@ -374,7 +374,49 @@ type BindingExtraction = {
         type: "fromRegistration";
         position: number;
     } | {
+        type: "fromArgumentProperty";
+        position: number;
+        property: string;
+    } | {
+        /**
+         * The route path comes from where the file sits, which is how
+         * Next.js and React Router describe their routes. The pack
+         * spells out its own convention here, since the adapter knows
+         * about files and the pack knows what the framework does with
+         * their names.
+         *
+         * `app/api/orders/[id]/route.ts` under `{ root: "app",
+         * dropBasenames: ["route"], dynamic: "brackets" }` comes out as
+         * `/api/orders/{id}`, which pairs with an Express provider
+         * writing `/api/orders/:id`.
+         */
         type: "fromFilename";
+        /**
+         * Where a route path starts. The directories below it become
+         * the path; everything above it belongs to the project layout
+         * and is dropped.
+         */
+        root: string;
+        /**
+         * Filenames that say what a file is rather than adding a
+         * segment: `route`, `page`, `index`, `_index`.
+         */
+        dropBasenames?: string[];
+        /**
+         * How the framework writes a parameter in a filename. Next.js
+         * uses `[id]`, React Router uses `$id`.
+         */
+        dynamic?: "brackets" | "dollarPrefix";
+        /**
+         * Whether a directory in parentheses organises files without
+         * appearing in the URL, as `app/(marketing)/about` does.
+         */
+        dropParenthesized?: boolean;
+        /**
+         * Whether one filename holds the whole path with dots between
+         * the segments, as `routes/orders.$id.tsx` does.
+         */
+        flat?: boolean;
     } | {
         type: "fromContract";
     } | {
@@ -487,6 +529,10 @@ interface TerminalExtraction {
     } | {
         from: "constructor";
         codes: Record<string, number>;
+    } | {
+        from: "argumentProperty";
+        position: number;
+        name: string;
     } | {
         from: "argumentConstructor";
         position: number;
@@ -619,6 +665,23 @@ interface ResponsePropertyMapping {
     /** What the value semantically represents */
     semantics: ResponsePropertyMeaning;
 }
+/**
+ * A library wrapper whose result is the function it was handed. The
+ * adapter works this out on its own for factories declared in the
+ * project by reading their bodies. A library's body is not readable,
+ * so the pack states it.
+ */
+interface TransparentWrapper {
+    /** Callee text as written, e.g. "Sentry.wrapHandler". */
+    callee: string;
+    /** Which argument holds the wrapped function. */
+    argument: number;
+    /**
+     * The module the callee has to have been imported from. Without it a
+     * local object spelled the same way would be taken for the library.
+     */
+    module: string;
+}
 interface PatternPack {
     name: string;
     /**
@@ -792,6 +855,17 @@ interface PatternPack {
      * available without an import).
      */
     requiresImport?: string[];
+    /**
+     * Library wrappers whose result is the wrapped function. The adapter
+     * derives this automatically for project-local factories by reading
+     * their bodies; a library wrapper's body is not readable, so the
+     * pack states the judgment: a call to `callee` resolves to its
+     * `argument`-th argument.
+     *
+     * `callee` matches the call expression text as written, e.g.
+     * `"Sentry.wrapHandler"`.
+     */
+    transparentWrappers?: TransparentWrapper[];
     /**
      * Per-property-access recognizers — sister to
      * `invocationRecognizers` but firing on `PropertyAccessExpression`
@@ -884,6 +958,29 @@ interface DiscoveredCustomUnit {
         method: string;
         path: string;
     };
+    /**
+     * GraphQL field identity for units a callback discovers against an
+     * external manifest rather than an in-code resolver map. AppSync
+     * routes a field to a Lambda in the deploy template, so the field is
+     * the boundary that code serves. When set, the adapter builds a
+     * `graphql-resolver` binding from `(typeName, fieldName)`, which
+     * pairs with the operations a client sends.
+     */
+    resolverInfo?: {
+        typeName: string;
+        fieldName: string;
+    };
+    /**
+     * Message-bus channel identity for consumer units a callback
+     * discovers against a subject the code itself names (a handler
+     * factory whose config carries the expected subject). When set, the
+     * adapter builds a `message-bus` binding from `(messageBus, channel)`,
+     * which pairs with producers sending on the same channel.
+     */
+    channelInfo?: {
+        messageBus: MessageBusSemantics["messageBus"];
+        channel: string;
+    };
     /**
      * Metadata merged onto the resulting summary's `metadata` field.
      */
@@ -1188,6 +1285,13 @@ interface RawCodeStructure {
     boundaryBinding: BoundaryBinding | null;
     parameters: RawParameter[];
     branches: RawBranch[];
+    /**
+     * Return statements in the body that none of the pack's terminals
+     * matched. A handler shaped in a way the pack does not describe still
+     * returns something, and saying nothing about it reads the same as
+     * saying it does nothing.
+     */
+    unmatchedReturns?: number;
     dependencyCalls: RawDependencyCall[];
     declaredContract: RawDeclaredContract | null;
     /**
@@ -1266,4 +1370,4 @@ declare function terminalToOutput(terminal: RawTerminal): Output;
 declare function effectToIR(effect: RawEffect): Effect;
 declare function paramToInput(param: RawParameter): Input;
 
-export { type AccessRecognizer, type BindingExtraction, type ContractPattern, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExtractorOptions, type InputMappingPattern, type InvocationRecognizer, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type ResponsePropertyMapping, type ResponsePropertyMeaning, type TerminalExtraction, type TerminalMatch, type TerminalPattern, assembleSummary, assessConfidence, detectGaps, effectToIR, httpRouteDiscovery, makeTransitionId, paramToInput, terminalToOutput };
+export { type AccessRecognizer, type BindingExtraction, type ContractPattern, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExtractorOptions, type InputMappingPattern, type InvocationRecognizer, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type ResponsePropertyMapping, type ResponsePropertyMeaning, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, assembleSummary, assessConfidence, detectGaps, effectToIR, httpRouteDiscovery, makeTransitionId, paramToInput, terminalToOutput };

package/dist/index.js

@@ -119,6 +119,17 @@ function detectGaps(raw, transitions, options) {
     return [];
   }
   const gaps = [];
+  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.declaredContract) {
     const producedStatuses = new Set(
       transitions.flatMap((t) => {
@@ -159,6 +170,9 @@ function detectGaps(raw, transitions, options) {
   return gaps;
 }
 function assessConfidence(raw) {
+  if ((raw.unmatchedReturns ?? 0) > 0) {
+    return { source: "inferred_static", level: "low" };
+  }
   let total = 0;
   let opaque = 0;
   for (const branch of raw.branches) {

package/package.json

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