@suss/extractor 0.14.0 → 0.15.0

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   makeTransitionId: () => makeTransitionId,
   mapReading: () => mapReading,
   paramToInput: () => paramToInput,
+  registrationHelperDiscovery: () => registrationHelperDiscovery,
   sharedGatingConditions: () => sharedGatingConditions,
   terminalToOutput: () => terminalToOutput,
   unreadableReading: () => unreadableReading,
@@ -132,7 +133,7 @@ function nested(value, depth) {
 // src/packHelpers.ts
 function httpRouteDiscovery(opts) {
   const kind = opts.kind ?? "handler";
-  return opts.importNames.map((importName) => ({
+  const calls = opts.importNames.map((importName) => ({
     kind,
     match: {
       type: "registrationCall",
@@ -153,6 +154,44 @@ function httpRouteDiscovery(opts) {
     ...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") {
@@ -1126,6 +1165,7 @@ function paramToInput(param) {
   makeTransitionId,
   mapReading,
   paramToInput,
+  registrationHelperDiscovery,
   sharedGatingConditions,
   terminalToOutput,
   unreadableReading,

package/dist/index.d.cts

@@ -316,6 +316,18 @@ type DiscoveryMatch = {
         pathKey: string;
         handlerKey: string;
     };
+    /**
+     * The routable the loop registers on. When set, the loop's body
+     * must call a method on a variable constructed from one of these
+     * imports, the same resolution a registration call's subject
+     * gets. Without it, any loop over objects with the three keys
+     * above matches, and a file that imports the library can contain
+     * an unrelated one.
+     */
+    receiver?: {
+        importModule: string;
+        importNames: string[];
+    };
 } | {
     /**
      * Helper-call expansion: one function call at the user's site is
@@ -1589,6 +1601,35 @@ declare function httpRouteDiscovery(opts: {
      */
     mount?: DiscoveryPattern["mount"];
 }): DiscoveryPattern[];
+/**
+ * One route a project helper registers when called, spelled with `{N}`
+ * placeholders for the call's positional arguments.
+ */
+interface RegistrationHelper {
+    /** The helper's exported name, as the project's code imports it. */
+    helperName: string;
+    /** The module the helper is imported from, to tell two apart. */
+    importModule?: string;
+    registrations: Array<{
+        method: string;
+        pathTemplate: string;
+        handlerArg: string;
+    }>;
+}
+/**
+ * Discovery patterns for a project's own registration helpers.
+ *
+ * A helper like `registerCrud(app, "users", handlers)` registers
+ * routes the call-site never spells out, so registration-call
+ * discovery cannot see them. The helper's name belongs to one project,
+ * which is why this arrives through per-project pack config rather
+ * than shipping inside any framework pack:
+ *
+ *   suss extract -f express=config.json
+ *
+ * with `{ "registrationHelpers": [...] }` in the file.
+ */
+declare function registrationHelperDiscovery(helpers: readonly RegistrationHelper[], kind?: string): DiscoveryPattern[];
 /**
  * The payload behind a `JSON.stringify(...)` call, or the argument
  * unchanged when it is anything else. A producer serializes its message
@@ -1775,11 +1816,7 @@ interface ConstructedFrom {
      */
     readonly named?: readonly string[];
 }
-/**
- * What a reader gives back for a name nothing in the source settles.
- * `"nothing"` gives null, `"reference"` gives the value to go and ask
- * about instead.
- */
+
 type UnsettledName = "nothing" | "reference";
 /**
  * One value a call states, as the questions a pack can ask about it.
@@ -1816,6 +1853,13 @@ interface ValueOps {
     items(): readonly ValueOps[];
     /** What one named property of this object states, or null for none. */
     property(name: string): ValueOps | null;
+    /**
+     * This value in the form an effect records an argument, or null when
+     * the adapter cannot write one. A pack that wants a payload compared
+     * across a boundary asks for this, since a body reduced to text
+     * cannot be paired field by field.
+     */
+    asArg(): EffectArg | null;
     /**
      * The pieces of text the source wrote here, in order, with whatever
      * it interpolated between them left out. A string is one piece and a
@@ -2218,4 +2262,4 @@ declare function terminalToOutput(terminal: RawTerminal): Output;
 declare function effectToIR(effect: RawEffect): Effect;
 declare function paramToInput(param: RawParameter): Input;
 
-export { type AccessRecognizer, type AstCapableOps, type BindingExtraction, type BodyContent, type CallOps, type CaseGroup, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ConstructedFrom, type ContractPattern, type DeclaredBy, 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 OpsCarrier, type PackDeclarations, PathBudgetExceeded, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ReceiverOrigin, type ResponsePropertyMapping, type ResponsePropertyMeaning, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, UnmodeledFlow, type UnsettledName, type ValueEntry, type ValueOps, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, sharedGatingConditions, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, writtenReading };
+export { type AccessRecognizer, type AstCapableOps, type BindingExtraction, type BodyContent, type CallOps, type CaseGroup, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ConstructedFrom, type ContractPattern, type DeclaredBy, 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 OpsCarrier, type PackDeclarations, PathBudgetExceeded, type PatternPack, 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 SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, UnmodeledFlow, type UnsettledName, type ValueEntry, type ValueOps, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, registrationHelperDiscovery, sharedGatingConditions, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, writtenReading };

package/dist/index.d.ts

@@ -316,6 +316,18 @@ type DiscoveryMatch = {
         pathKey: string;
         handlerKey: string;
     };
+    /**
+     * The routable the loop registers on. When set, the loop's body
+     * must call a method on a variable constructed from one of these
+     * imports, the same resolution a registration call's subject
+     * gets. Without it, any loop over objects with the three keys
+     * above matches, and a file that imports the library can contain
+     * an unrelated one.
+     */
+    receiver?: {
+        importModule: string;
+        importNames: string[];
+    };
 } | {
     /**
      * Helper-call expansion: one function call at the user's site is
@@ -1589,6 +1601,35 @@ declare function httpRouteDiscovery(opts: {
      */
     mount?: DiscoveryPattern["mount"];
 }): DiscoveryPattern[];
+/**
+ * One route a project helper registers when called, spelled with `{N}`
+ * placeholders for the call's positional arguments.
+ */
+interface RegistrationHelper {
+    /** The helper's exported name, as the project's code imports it. */
+    helperName: string;
+    /** The module the helper is imported from, to tell two apart. */
+    importModule?: string;
+    registrations: Array<{
+        method: string;
+        pathTemplate: string;
+        handlerArg: string;
+    }>;
+}
+/**
+ * Discovery patterns for a project's own registration helpers.
+ *
+ * A helper like `registerCrud(app, "users", handlers)` registers
+ * routes the call-site never spells out, so registration-call
+ * discovery cannot see them. The helper's name belongs to one project,
+ * which is why this arrives through per-project pack config rather
+ * than shipping inside any framework pack:
+ *
+ *   suss extract -f express=config.json
+ *
+ * with `{ "registrationHelpers": [...] }` in the file.
+ */
+declare function registrationHelperDiscovery(helpers: readonly RegistrationHelper[], kind?: string): DiscoveryPattern[];
 /**
  * The payload behind a `JSON.stringify(...)` call, or the argument
  * unchanged when it is anything else. A producer serializes its message
@@ -1775,11 +1816,7 @@ interface ConstructedFrom {
      */
     readonly named?: readonly string[];
 }
-/**
- * What a reader gives back for a name nothing in the source settles.
- * `"nothing"` gives null, `"reference"` gives the value to go and ask
- * about instead.
- */
+
 type UnsettledName = "nothing" | "reference";
 /**
  * One value a call states, as the questions a pack can ask about it.
@@ -1816,6 +1853,13 @@ interface ValueOps {
     items(): readonly ValueOps[];
     /** What one named property of this object states, or null for none. */
     property(name: string): ValueOps | null;
+    /**
+     * This value in the form an effect records an argument, or null when
+     * the adapter cannot write one. A pack that wants a payload compared
+     * across a boundary asks for this, since a body reduced to text
+     * cannot be paired field by field.
+     */
+    asArg(): EffectArg | null;
     /**
      * The pieces of text the source wrote here, in order, with whatever
      * it interpolated between them left out. A string is one piece and a
@@ -2218,4 +2262,4 @@ declare function terminalToOutput(terminal: RawTerminal): Output;
 declare function effectToIR(effect: RawEffect): Effect;
 declare function paramToInput(param: RawParameter): Input;
 
-export { type AccessRecognizer, type AstCapableOps, type BindingExtraction, type BodyContent, type CallOps, type CaseGroup, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ConstructedFrom, type ContractPattern, type DeclaredBy, 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 OpsCarrier, type PackDeclarations, PathBudgetExceeded, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ReceiverOrigin, type ResponsePropertyMapping, type ResponsePropertyMeaning, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, UnmodeledFlow, type UnsettledName, type ValueEntry, type ValueOps, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, sharedGatingConditions, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, writtenReading };
+export { type AccessRecognizer, type AstCapableOps, type BindingExtraction, type BodyContent, type CallOps, type CaseGroup, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ConstructedFrom, type ContractPattern, type DeclaredBy, 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 OpsCarrier, type PackDeclarations, PathBudgetExceeded, type PatternPack, 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 SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, UnmodeledFlow, type UnsettledName, type ValueEntry, type ValueOps, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, registrationHelperDiscovery, sharedGatingConditions, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, writtenReading };

package/dist/index.js

@@ -90,7 +90,7 @@ function nested(value, depth) {
 // src/packHelpers.ts
 function httpRouteDiscovery(opts) {
   const kind = opts.kind ?? "handler";
-  return opts.importNames.map((importName) => ({
+  const calls = opts.importNames.map((importName) => ({
     kind,
     match: {
       type: "registrationCall",
@@ -111,6 +111,44 @@ function httpRouteDiscovery(opts) {
     ...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") {
@@ -1083,6 +1121,7 @@ export {
   makeTransitionId,
   mapReading,
   paramToInput,
+  registrationHelperDiscovery,
   sharedGatingConditions,
   terminalToOutput,
   unreadableReading,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/extractor",
-  "version": "0.14.0",
+  "version": "0.15.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.14.0"
+    "@suss/behavioral-ir": "0.15.0"
   },
   "devDependencies": {
     "tsup": "*",