@suss/extractor 0.11.0 → 0.13.0

package/dist/index.cjs

@@ -148,7 +148,7 @@ function httpRouteDiscovery(opts) {
         position: "methodName",
         nameMap: { all: "*" }
       },
-      path: { type: "fromRegistration", position: 0 }
+      path: { type: "fromArgument", position: 0 }
     },
     ...opts.mount !== void 0 ? { mount: opts.mount } : {},
     requiresImport: [opts.importModule]

package/dist/index.d.cts

@@ -23,10 +23,6 @@ type DiscoveryMatch = {
     importModule: string;
     importName: string;
     registrationChain: string[];
-} | {
-    type: "decorator";
-    decoratorModule: string;
-    decoratorName: string;
 } | {
     type: "fileConvention";
     filePattern: string;
@@ -312,7 +308,7 @@ type DiscoveryMatch = {
      * bound to a `const` one hop away, gets expanded. Cross-file and
      * computed iterables are outside v0.
      *
-     * Pack-author docs: `docs/internal/proposals/dynamic-registration.md`.
+     * Pack-author docs: `design/proposals/dynamic-registration.md`.
      */
     type: "registrationLoop";
     elementShape: {
@@ -340,7 +336,7 @@ type DiscoveryMatch = {
      * one specific module, which helps when two packages happen to export
      * a function with the same name.
      *
-     * Pack-author docs: `docs/internal/proposals/dynamic-registration.md`.
+     * Pack-author docs: `design/proposals/dynamic-registration.md`.
      */
     type: "registrationTemplate";
     helperName: string;
@@ -471,7 +467,7 @@ type BindingExtraction = {
         value: string;
     };
     path: {
-        type: "fromRegistration";
+        type: "fromArgument";
         position: number;
     } | {
         type: "fromArgumentProperty";
@@ -521,9 +517,6 @@ type BindingExtraction = {
         type: "fromContract";
     } | {
         type: "fromClientMethod";
-    } | {
-        type: "fromArgumentLiteral";
-        position: number;
     };
 };
 interface DiscoveryPattern {
@@ -727,12 +720,6 @@ interface ContractPattern {
     };
 }
 type InputMappingPattern = {
-    /** Single object parameter, e.g. React Router LoaderFunctionArgs */
-    type: "singleObjectParam";
-    paramPosition: number;
-    /** Property name → role, e.g. { params: "pathParams", request: "request" } */
-    knownProperties: Record<string, string>;
-} | {
     /** Positional parameters, e.g. Express (req, res, next) */
     type: "positionalParams";
     params: Array<{
@@ -740,10 +727,21 @@ type InputMappingPattern = {
         role: string;
     }>;
 } | {
-    /** Destructured from framework call, e.g. ts-rest { params, body, query } */
-    type: "destructuredObject";
-    /** Property name → role, e.g. { params: "pathParams", body: "requestBody" } */
+    /**
+     * One object parameter whose properties are the inputs, the way
+     * ts-rest passes `{ params, body, query }` and React Router passes
+     * `{ params, request }`. A handler that destructures it gets one
+     * input per name it binds; a handler that takes it whole gets a
+     * single input, since the source does not say which properties it
+     * reads.
+     */
+    type: "objectParam";
+    /** Defaults to the first parameter. */
+    paramPosition?: number;
+    /** Property name mapped to the role it takes, e.g. `{ params: "pathParams" }`. A name not here keeps the name it was bound under. */
     knownProperties: Record<string, string>;
+    /** The role for a parameter taken whole. Defaults to "request". */
+    wholeParamRole?: string;
 } | {
     /**
      * Component props, React / Vue / Svelte-style: one parameter that
@@ -753,10 +751,10 @@ type InputMappingPattern = {
      * not destructured (`function X(props) {...}`), a single Input comes
      * out with `wholeParamRole`, which defaults to `"props"`.
      *
-     * This differs from `destructuredObject` because the pack does not
-     * declare the prop names up front; they are whatever the component
-     * author wrote. It differs from `singleObjectParam` because the
-     * destructuring pattern is respected when there is one.
+     * This differs from `objectParam` in two ways. The pack declares no
+     * prop names up front, since they are whatever the component author
+     * wrote, and each input records the type text of the prop, which a
+     * component's shape comparison reads.
      */
     type: "componentProps";
     paramPosition: number;
@@ -769,7 +767,7 @@ type InputMappingPattern = {
      * reachable-closure pass for internal library functions, where no
      * framework declares a set of roles, so the name a caller sees IS
      * the role. Destructured parameters are captured the
-     * same way `destructuredObject` captures them, so `(ctx, { userId })`
+     * same way `objectParam` captures them, so `(ctx, { userId })`
      * gives two inputs, `ctx` and `userId`.
      */
     type: "allPositional";
@@ -1127,6 +1125,41 @@ interface PatternPack {
      * same reason as in invocationRecognizers.
      */
     accessRecognizers?: AccessRecognizer[];
+    /**
+     * What the pack wrote as data rather than as code, for the health
+     * report. Absent for a pack written as a hand-rolled walk, which is
+     * itself the thing the report says.
+     */
+    declarations?: PackDeclarations;
+}
+/**
+ * The price a pack paid for what it matches, so the migration onto the
+ * declared surface can be measured rather than asserted.
+ *
+ * Expressiveness is bought link by link: a link answered with data is
+ * inspectable, serializable and runs on any adapter, while a link
+ * answered with a function is code that only its own language runs.
+ * Both are allowed, and the report says which is which.
+ */
+interface PackDeclarations {
+    declarations: DeclaredMatch[];
+}
+/** One thing a pack declared it matches. */
+interface DeclaredMatch {
+    /** What it matches, in the pack's own words. */
+    name: string;
+    /** Links whose answer is data. */
+    dataLinks: number;
+    /** Links answered with a function, by the question each one asks. */
+    functionLinks: string[];
+    /**
+     * Links whose function reaches the adapter's own syntax tree, by the
+     * question each one asks. Reaching the tree needs a separate import,
+     * so a pack cannot arrive here without saying so.
+     */
+    astLinks: string[];
+    /** A line of code the pack says this matches, or null when it says none. */
+    example: string | null;
 }
 /**
  * Per-call-site recognizer hook. See `PatternPack.invocationRecognizers`
@@ -1755,7 +1788,14 @@ type EffectArg = {
 } | {
     kind: "object";
     fields: Record<string, EffectArg>;
-} | {
+}
+/**
+ * The element shapes the adapter could read, which is not always one
+ * per runtime element. An array a callback builds,
+ * `tags.map((tag) => ({ name: tag }))`, arrives with a single item,
+ * because every element it produces has that one shape.
+ */
+ | {
     kind: "array";
     items: EffectArg[];
 } | {
@@ -1964,4 +2004,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 BodyContent, type CaseGroup, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ContractPattern, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExitKind, type ExtractorOptions, type FailureDelivery, IdMap, IdSet, type Identified, type InputMappingPattern, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, PathBudgetExceeded, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ResponsePropertyMapping, type ResponsePropertyMeaning, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, UnmodeledFlow, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, sharedGatingConditions, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, writtenReading };
+export { type AccessRecognizer, type BindingExtraction, type BodyContent, type CaseGroup, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ContractPattern, type DeclaredMatch, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExitKind, type ExtractorOptions, type FailureDelivery, IdMap, IdSet, type Identified, type InputMappingPattern, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, type PackDeclarations, PathBudgetExceeded, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ResponsePropertyMapping, type ResponsePropertyMeaning, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, UnmodeledFlow, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, sharedGatingConditions, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, writtenReading };

package/dist/index.d.ts

@@ -23,10 +23,6 @@ type DiscoveryMatch = {
     importModule: string;
     importName: string;
     registrationChain: string[];
-} | {
-    type: "decorator";
-    decoratorModule: string;
-    decoratorName: string;
 } | {
     type: "fileConvention";
     filePattern: string;
@@ -312,7 +308,7 @@ type DiscoveryMatch = {
      * bound to a `const` one hop away, gets expanded. Cross-file and
      * computed iterables are outside v0.
      *
-     * Pack-author docs: `docs/internal/proposals/dynamic-registration.md`.
+     * Pack-author docs: `design/proposals/dynamic-registration.md`.
      */
     type: "registrationLoop";
     elementShape: {
@@ -340,7 +336,7 @@ type DiscoveryMatch = {
      * one specific module, which helps when two packages happen to export
      * a function with the same name.
      *
-     * Pack-author docs: `docs/internal/proposals/dynamic-registration.md`.
+     * Pack-author docs: `design/proposals/dynamic-registration.md`.
      */
     type: "registrationTemplate";
     helperName: string;
@@ -471,7 +467,7 @@ type BindingExtraction = {
         value: string;
     };
     path: {
-        type: "fromRegistration";
+        type: "fromArgument";
         position: number;
     } | {
         type: "fromArgumentProperty";
@@ -521,9 +517,6 @@ type BindingExtraction = {
         type: "fromContract";
     } | {
         type: "fromClientMethod";
-    } | {
-        type: "fromArgumentLiteral";
-        position: number;
     };
 };
 interface DiscoveryPattern {
@@ -727,12 +720,6 @@ interface ContractPattern {
     };
 }
 type InputMappingPattern = {
-    /** Single object parameter, e.g. React Router LoaderFunctionArgs */
-    type: "singleObjectParam";
-    paramPosition: number;
-    /** Property name → role, e.g. { params: "pathParams", request: "request" } */
-    knownProperties: Record<string, string>;
-} | {
     /** Positional parameters, e.g. Express (req, res, next) */
     type: "positionalParams";
     params: Array<{
@@ -740,10 +727,21 @@ type InputMappingPattern = {
         role: string;
     }>;
 } | {
-    /** Destructured from framework call, e.g. ts-rest { params, body, query } */
-    type: "destructuredObject";
-    /** Property name → role, e.g. { params: "pathParams", body: "requestBody" } */
+    /**
+     * One object parameter whose properties are the inputs, the way
+     * ts-rest passes `{ params, body, query }` and React Router passes
+     * `{ params, request }`. A handler that destructures it gets one
+     * input per name it binds; a handler that takes it whole gets a
+     * single input, since the source does not say which properties it
+     * reads.
+     */
+    type: "objectParam";
+    /** Defaults to the first parameter. */
+    paramPosition?: number;
+    /** Property name mapped to the role it takes, e.g. `{ params: "pathParams" }`. A name not here keeps the name it was bound under. */
     knownProperties: Record<string, string>;
+    /** The role for a parameter taken whole. Defaults to "request". */
+    wholeParamRole?: string;
 } | {
     /**
      * Component props, React / Vue / Svelte-style: one parameter that
@@ -753,10 +751,10 @@ type InputMappingPattern = {
      * not destructured (`function X(props) {...}`), a single Input comes
      * out with `wholeParamRole`, which defaults to `"props"`.
      *
-     * This differs from `destructuredObject` because the pack does not
-     * declare the prop names up front; they are whatever the component
-     * author wrote. It differs from `singleObjectParam` because the
-     * destructuring pattern is respected when there is one.
+     * This differs from `objectParam` in two ways. The pack declares no
+     * prop names up front, since they are whatever the component author
+     * wrote, and each input records the type text of the prop, which a
+     * component's shape comparison reads.
      */
     type: "componentProps";
     paramPosition: number;
@@ -769,7 +767,7 @@ type InputMappingPattern = {
      * reachable-closure pass for internal library functions, where no
      * framework declares a set of roles, so the name a caller sees IS
      * the role. Destructured parameters are captured the
-     * same way `destructuredObject` captures them, so `(ctx, { userId })`
+     * same way `objectParam` captures them, so `(ctx, { userId })`
      * gives two inputs, `ctx` and `userId`.
      */
     type: "allPositional";
@@ -1127,6 +1125,41 @@ interface PatternPack {
      * same reason as in invocationRecognizers.
      */
     accessRecognizers?: AccessRecognizer[];
+    /**
+     * What the pack wrote as data rather than as code, for the health
+     * report. Absent for a pack written as a hand-rolled walk, which is
+     * itself the thing the report says.
+     */
+    declarations?: PackDeclarations;
+}
+/**
+ * The price a pack paid for what it matches, so the migration onto the
+ * declared surface can be measured rather than asserted.
+ *
+ * Expressiveness is bought link by link: a link answered with data is
+ * inspectable, serializable and runs on any adapter, while a link
+ * answered with a function is code that only its own language runs.
+ * Both are allowed, and the report says which is which.
+ */
+interface PackDeclarations {
+    declarations: DeclaredMatch[];
+}
+/** One thing a pack declared it matches. */
+interface DeclaredMatch {
+    /** What it matches, in the pack's own words. */
+    name: string;
+    /** Links whose answer is data. */
+    dataLinks: number;
+    /** Links answered with a function, by the question each one asks. */
+    functionLinks: string[];
+    /**
+     * Links whose function reaches the adapter's own syntax tree, by the
+     * question each one asks. Reaching the tree needs a separate import,
+     * so a pack cannot arrive here without saying so.
+     */
+    astLinks: string[];
+    /** A line of code the pack says this matches, or null when it says none. */
+    example: string | null;
 }
 /**
  * Per-call-site recognizer hook. See `PatternPack.invocationRecognizers`
@@ -1755,7 +1788,14 @@ type EffectArg = {
 } | {
     kind: "object";
     fields: Record<string, EffectArg>;
-} | {
+}
+/**
+ * The element shapes the adapter could read, which is not always one
+ * per runtime element. An array a callback builds,
+ * `tags.map((tag) => ({ name: tag }))`, arrives with a single item,
+ * because every element it produces has that one shape.
+ */
+ | {
     kind: "array";
     items: EffectArg[];
 } | {
@@ -1964,4 +2004,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 BodyContent, type CaseGroup, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ContractPattern, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExitKind, type ExtractorOptions, type FailureDelivery, IdMap, IdSet, type Identified, type InputMappingPattern, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, PathBudgetExceeded, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ResponsePropertyMapping, type ResponsePropertyMeaning, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, UnmodeledFlow, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, sharedGatingConditions, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, writtenReading };
+export { type AccessRecognizer, type BindingExtraction, type BodyContent, type CaseGroup, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ContractPattern, type DeclaredMatch, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExitKind, type ExtractorOptions, type FailureDelivery, IdMap, IdSet, type Identified, type InputMappingPattern, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, type PackDeclarations, PathBudgetExceeded, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ResponsePropertyMapping, type ResponsePropertyMeaning, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, UnmodeledFlow, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, sharedGatingConditions, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, writtenReading };

package/dist/index.js

@@ -106,7 +106,7 @@ function httpRouteDiscovery(opts) {
         position: "methodName",
         nameMap: { all: "*" }
       },
-      path: { type: "fromRegistration", position: 0 }
+      path: { type: "fromArgument", position: 0 }
     },
     ...opts.mount !== void 0 ? { mount: opts.mount } : {},
     requiresImport: [opts.importModule]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/extractor",
-  "version": "0.11.0",
+  "version": "0.13.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.11.0"
+    "@suss/behavioral-ir": "0.13.0"
   },
   "devDependencies": {
     "tsup": "*",