@suss/extractor 0.14.1 → 0.16.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

@@ -187,8 +187,18 @@ type DiscoveryMatch = {
      * `development` conditions are not handled yet.
      */
     type: "packageExports";
-    /** Absolute path to the package's `package.json`. */
-    packageJsonPath: string;
+    /**
+     * Absolute path to the package's `package.json`. Left out when
+     * `workspaces` is set, since the workspace decides the list.
+     */
+    packageJsonPath?: string;
+    /**
+     * One pattern for every package the workspace declares. The pack
+     * cannot list the packages, because they belong to the project
+     * rather than to any library, so the adapter reads the workspace
+     * manifest and applies this pattern once per package it finds.
+     */
+    workspaces?: true;
     /**
      * Restrict to these `exports` keys (without the leading `./`). The
      * root export is keyed `"."`. Leave it unset for every sub-path that
@@ -316,6 +326,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
@@ -438,7 +460,14 @@ type DiscoveryMatch = {
      * than the original, because full symbol resolution is not built yet.
      */
     type: "packageImport";
-    packages: string[];
+    /** Left out when `workspaces` is set. */
+    packages?: string[];
+    /**
+     * Track imports of every package the workspace declares. A file
+     * inside one workspace package importing another is the consumer
+     * side of the package-export boundary, whichever two they are.
+     */
+    workspaces?: true;
 };
 type BindingExtraction = {
     method: {
@@ -519,11 +548,48 @@ type BindingExtraction = {
         type: "fromClientMethod";
     };
 };
+/**
+ * Where a declared channel's spelling comes from.
+ *
+ * `decoratorArgument` reads the argument off the same decorator the
+ * match selected the handler by, so `@EventPattern("order.placed")`
+ * gives "order.placed". `literal` is for a wire whose channel the
+ * library fixes. `unstated` says the wire is known and the channel is
+ * not, which pairs the way a null channel always has.
+ */
+type ChannelSource = {
+    from: "decoratorArgument";
+    position: number;
+} | {
+    from: "literal";
+    value: string;
+} | {
+    from: "unstated";
+};
+/**
+ * A binding the pattern states outright, for a boundary the match
+ * cannot read from the source.
+ *
+ * `bindingExtraction` speaks REST and nothing else, so a declarative
+ * pack whose boundary is a queue or a topic had nowhere to say so and
+ * was pushed into a callback, which pack health then reports as an
+ * ast-link. This is the same vocabulary `DiscoveredCustomUnit` already
+ * has, declared instead of returned. Message bus only for now; the
+ * design note in the proposals directory says what comes next and why
+ * the rest stays put.
+ */
+type DeclaredBinding = {
+    semantics: "message-bus";
+    messageBus: MessageBusSemantics["messageBus"];
+    channel: ChannelSource;
+};
 interface DiscoveryPattern {
     /** The kind of code unit this discovers: "handler", "loader", "action", "component", etc. */
     kind: string;
     match: DiscoveryMatch;
     bindingExtraction?: BindingExtraction;
+    /** A binding the pattern states outright. See `DeclaredBinding`. */
+    binding?: DeclaredBinding;
     /**
      * How the routable this pattern discovers (Express's `Router()`,
      * Hono's `new Hono()`, and similar) can itself be mounted onto
@@ -1589,6 +1655,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 +1870,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 +1907,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 +2316,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 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 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

@@ -187,8 +187,18 @@ type DiscoveryMatch = {
      * `development` conditions are not handled yet.
      */
     type: "packageExports";
-    /** Absolute path to the package's `package.json`. */
-    packageJsonPath: string;
+    /**
+     * Absolute path to the package's `package.json`. Left out when
+     * `workspaces` is set, since the workspace decides the list.
+     */
+    packageJsonPath?: string;
+    /**
+     * One pattern for every package the workspace declares. The pack
+     * cannot list the packages, because they belong to the project
+     * rather than to any library, so the adapter reads the workspace
+     * manifest and applies this pattern once per package it finds.
+     */
+    workspaces?: true;
     /**
      * Restrict to these `exports` keys (without the leading `./`). The
      * root export is keyed `"."`. Leave it unset for every sub-path that
@@ -316,6 +326,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
@@ -438,7 +460,14 @@ type DiscoveryMatch = {
      * than the original, because full symbol resolution is not built yet.
      */
     type: "packageImport";
-    packages: string[];
+    /** Left out when `workspaces` is set. */
+    packages?: string[];
+    /**
+     * Track imports of every package the workspace declares. A file
+     * inside one workspace package importing another is the consumer
+     * side of the package-export boundary, whichever two they are.
+     */
+    workspaces?: true;
 };
 type BindingExtraction = {
     method: {
@@ -519,11 +548,48 @@ type BindingExtraction = {
         type: "fromClientMethod";
     };
 };
+/**
+ * Where a declared channel's spelling comes from.
+ *
+ * `decoratorArgument` reads the argument off the same decorator the
+ * match selected the handler by, so `@EventPattern("order.placed")`
+ * gives "order.placed". `literal` is for a wire whose channel the
+ * library fixes. `unstated` says the wire is known and the channel is
+ * not, which pairs the way a null channel always has.
+ */
+type ChannelSource = {
+    from: "decoratorArgument";
+    position: number;
+} | {
+    from: "literal";
+    value: string;
+} | {
+    from: "unstated";
+};
+/**
+ * A binding the pattern states outright, for a boundary the match
+ * cannot read from the source.
+ *
+ * `bindingExtraction` speaks REST and nothing else, so a declarative
+ * pack whose boundary is a queue or a topic had nowhere to say so and
+ * was pushed into a callback, which pack health then reports as an
+ * ast-link. This is the same vocabulary `DiscoveredCustomUnit` already
+ * has, declared instead of returned. Message bus only for now; the
+ * design note in the proposals directory says what comes next and why
+ * the rest stays put.
+ */
+type DeclaredBinding = {
+    semantics: "message-bus";
+    messageBus: MessageBusSemantics["messageBus"];
+    channel: ChannelSource;
+};
 interface DiscoveryPattern {
     /** The kind of code unit this discovers: "handler", "loader", "action", "component", etc. */
     kind: string;
     match: DiscoveryMatch;
     bindingExtraction?: BindingExtraction;
+    /** A binding the pattern states outright. See `DeclaredBinding`. */
+    binding?: DeclaredBinding;
     /**
      * How the routable this pattern discovers (Express's `Router()`,
      * Hono's `new Hono()`, and similar) can itself be mounted onto
@@ -1589,6 +1655,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 +1870,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 +1907,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 +2316,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 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 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.1",
+  "version": "0.16.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.1"
+    "@suss/behavioral-ir": "0.16.0"
   },
   "devDependencies": {
     "tsup": "*",