@suss/extractor 0.1.0 → 0.1.1

package/dist/index.cjs

@@ -95,7 +95,8 @@ function assembleSummary(raw, options = DEFAULT_OPTIONS) {
     identity: {
       name: raw.identity.name,
       exportPath: raw.identity.exportPath,
-      boundaryBinding: raw.boundaryBinding ?? null
+      boundaryBinding: raw.boundaryBinding ?? null,
+      ...raw.deployableUnit !== void 0 ? { deployableUnit: raw.deployableUnit } : {}
     },
     inputs,
     transitions,
@@ -161,6 +162,23 @@ function detectGaps(raw, transitions, options) {
       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.unreadBinding !== void 0) {
+    gaps.push({
+      type: "unreadOutcome",
+      conditions: [],
+      consequence: "unknown",
+      description: raw.unreadBinding
+    });
+  }
+  const unreadBody = describeUnreadBody(raw);
+  if (unreadBody !== null) {
+    gaps.push({
+      type: "unreadOutcome",
+      conditions: [],
+      consequence: "unknown",
+      description: unreadBody
+    });
+  }
   if (raw.declaredContract) {
     const producedStatuses = new Set(
       transitions.flatMap((t) => {
@@ -200,10 +218,34 @@ function detectGaps(raw, transitions, options) {
   }
   return gaps;
 }
+function bodyWentUnread(raw) {
+  if (raw.bodyContent === "absent" || raw.bodyContent === "elsewhere") {
+    return true;
+  }
+  return raw.bodyContent === "statements" && raw.branches.length === 0;
+}
+function describeUnreadBody(raw) {
+  if (!bodyWentUnread(raw)) {
+    return null;
+  }
+  if (raw.bodyContent === "absent") {
+    return "This unit is a declaration with no body behind it, so nothing about what it does was read here";
+  }
+  if (raw.bodyContent === "elsewhere") {
+    return "The handler on this boundary comes from outside the code that registers it, so nothing about what it does was read here";
+  }
+  if ((raw.unmatchedReturns ?? 0) > 0) {
+    return null;
+  }
+  return "Nothing this unit's body does matches a shape this pack looks for, so what it does is not described here";
+}
 function assessConfidence(raw) {
   if ((raw.unmatchedReturns ?? 0) > 0) {
     return { source: "inferred_static", level: "low" };
   }
+  if (bodyWentUnread(raw)) {
+    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, MessageBusSemantics, Predicate, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, BehavioralSummary, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
+import { Effect, MessageBusSemantics, DeployableUnit, Predicate, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, BehavioralSummary, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
 
 type DiscoveryMatch = {
     type: "namedExport";
@@ -211,30 +211,42 @@ type DiscoveryMatch = {
      * The adapter populates `DiscoveredUnit.resolverInfo` so the
      * produced binding carries `graphql-resolver(typeName, fieldName)`.
      * `typeName` resolves from the class decorator's first argument
-     * (`@Resolver(() => User)` → `"User"`); when the class decorator
-     * has no argument it defaults to the operation kind (`"Query"`,
-     * `"Mutation"`, `"Subscription"`). `fieldName` reads the method
-     * decorator's `{ name }` option override when present, otherwise
-     * the method name.
+     * (`@Resolver(() => User)` → `"User"`), and from
+     * `methodDecoratorTypeMap` when the class decorator has no
+     * argument. `fieldName` reads the method decorator's `{ name }`
+     * option override when present, otherwise the method name.
      */
     type: "decoratedMethod";
     /**
      * The module a pack-recognised decorator must be imported from
      * for discovery to fire. Codebases sometimes wrap framework
-     * decorators in their own re-exports (NestJS apps frequently
-     * declare `MetadataResolver` / `CoreResolver` factories that
-     * compose `@Resolver()` with extra metadata). When that happens,
-     * the import-module gate would miss them; pass an array of
-     * accepted modules and any one match suffices.
+     * decorators in their own re-exports, composing the framework's
+     * decorator with extra metadata. When that happens, the
+     * import-module gate would miss them; pass an array of accepted
+     * modules and any one match suffices.
      */
     importModule: string | string[];
     /**
      * Class decorator names to recognise. The first entry that
      * appears on a class wins for typeName extraction (the rest are
-     * fallbacks for codebases with multiple wrapper styles).
+     * fallbacks for codebases with multiple wrapper styles). A pack
+     * ships only what its own framework declares here and takes a
+     * project's wrappers through its options.
      */
     classDecorators: string[];
     methodDecorators: string[];
+    /**
+     * Method decorator name → the type its field hangs off when the
+     * class decorator names none. NestJS puts `@Query` on the root
+     * `Query` type and `@Mutation` on `Mutation` whatever the class
+     * says, so those two answer for themselves.
+     *
+     * A decorator the map leaves out has no answer of its own, and a
+     * class that names no type leaves the field's owner unread. The
+     * binding then names no type and pairs with nothing, rather than
+     * claiming a field the schema does not have.
+     */
+    methodDecoratorTypeMap: Record<string, string>;
 } | {
     /**
      * NestJS-style REST controller discovery. Class decorated with
@@ -248,10 +260,9 @@ type DiscoveryMatch = {
      * Same wrapper-decorator tolerance as `decoratedMethod`: the
      * import-module gate fires on at least one method-route
      * decorator from the framework module, but class decorators
-     * match by name only so project-internal wrappers
-     * (`@PublicController` / `@AuthedController` factories
-     * composing `@Controller()`) work without per-project pack
-     * config.
+     * match by name only, so a project-internal wrapper composing
+     * the framework's decorator matches once the project names it
+     * in the pack's options.
      *
      * The adapter populates `DiscoveredUnit.routeInfo` so the
      * produced binding carries `rest(method, path)`.
@@ -685,14 +696,18 @@ interface TransparentWrapper {
 interface PatternPack {
     name: string;
     /**
-     * Pack version stamp — feeds the cache invalidation key. Bump on
+     * Pack version stamp, which feeds the cache invalidation key. Bump on
      * any change that affects discovered units / extracted summaries.
-     * Format is opaque to the adapter; semver is the obvious choice
-     * but a content hash, build SHA, or monotonic integer works too.
-     * Optional — packs that omit it use the literal string `"unset"`,
-     * which means cache entries from one process to the next aren't
-     * meaningfully versioned (suitable for development; production
-     * packs should declare a version).
+     * Format is opaque to the adapter, so semver or a content hash both
+     * work.
+     *
+     * Optional, because whoever loads the pack knows more about it than
+     * the pack does. The CLI folds a hash of the file it loaded and of
+     * the config it passed into this stamp, so a pack run through the CLI
+     * invalidates on an edit whether or not it declares a version. A host
+     * that builds packs some other way carries that responsibility
+     * itself. A pack with nothing to stamp reads as `"unset"`, and warm
+     * caches will answer for code that has since changed.
      */
     version?: string;
     languages: string[];
@@ -981,6 +996,8 @@ interface DiscoveredCustomUnit {
         messageBus: MessageBusSemantics["messageBus"];
         channel: string;
     };
+    /** The thing that gets deployed and runs this unit, when known. */
+    deployableUnit?: DeployableUnit;
     /**
      * Metadata merged onto the resulting summary's `metadata` field.
      */
@@ -1264,6 +1281,23 @@ interface RawDeclaredContract {
      */
     provenance?: "derived" | "independent";
 }
+/**
+ * What sits where a unit's body should be.
+ *
+ *   - "absent": there is no body behind this declaration (an overload
+ *     signature, an ambient declaration, an abstract method), so the
+ *     pack read nothing about what the unit does.
+ *   - "empty": a body with nothing in it. A summary that says nothing
+ *     about it has described it completely.
+ *   - "statements": a body with work in it, including a concise
+ *     arrow's expression. A summary that says nothing about it has
+ *     described none of it.
+ *   - "elsewhere": the unit's body is not in what this run read. A
+ *     route registered with a handler the caller supplies announces a
+ *     boundary and names no function to look in, and the boundary is
+ *     worth reporting with nothing behind it.
+ */
+type BodyContent = "absent" | "empty" | "statements" | "elsewhere";
 interface RawCodeStructure {
     identity: {
         name: string;
@@ -1283,6 +1317,8 @@ interface RawCodeStructure {
      * helpers, pure utilities, and anything the adapter can't place.
      */
     boundaryBinding: BoundaryBinding | null;
+    /** The thing that gets deployed and runs this code, when known. */
+    deployableUnit?: DeployableUnit;
     parameters: RawParameter[];
     branches: RawBranch[];
     /**
@@ -1292,6 +1328,14 @@ interface RawCodeStructure {
      * saying it does nothing.
      */
     unmatchedReturns?: number;
+    /**
+     * What the adapter found where the unit's body should be. A summary
+     * with nothing in it means one of two different things, and only the
+     * adapter can say which: a body nobody could read, or a body with
+     * nothing in it to read. Adapters that do not say leave this unset,
+     * and everything downstream treats the summary as it did before.
+     */
+    bodyContent?: BodyContent;
     dependencyCalls: RawDependencyCall[];
     declaredContract: RawDeclaredContract | null;
     /**
@@ -1358,6 +1402,17 @@ interface RawCodeStructure {
         reference: string;
         reason: string;
     };
+    /**
+     * Set when the source does not state part of the boundary this unit
+     * sits on. The binding still goes out with that part left empty, so
+     * the unit pairs with nothing rather than with whatever a guess named,
+     * and this sentence tells a reader which part is missing and why.
+     *
+     * A statement about the reading rather than about the code, so it
+     * lands as an `unreadOutcome` gap and no checker holds it against the
+     * unit.
+     */
+    unreadBinding?: string;
 }
 interface ExtractorOptions {
     gapHandling: "strict" | "permissive" | "silent";
@@ -1370,4 +1425,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, type TransparentWrapper, assembleSummary, assessConfidence, detectGaps, effectToIR, httpRouteDiscovery, makeTransitionId, paramToInput, terminalToOutput };
+export { type AccessRecognizer, type BindingExtraction, type BodyContent, 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, MessageBusSemantics, Predicate, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, BehavioralSummary, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
+import { Effect, MessageBusSemantics, DeployableUnit, Predicate, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, BehavioralSummary, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
 
 type DiscoveryMatch = {
     type: "namedExport";
@@ -211,30 +211,42 @@ type DiscoveryMatch = {
      * The adapter populates `DiscoveredUnit.resolverInfo` so the
      * produced binding carries `graphql-resolver(typeName, fieldName)`.
      * `typeName` resolves from the class decorator's first argument
-     * (`@Resolver(() => User)` → `"User"`); when the class decorator
-     * has no argument it defaults to the operation kind (`"Query"`,
-     * `"Mutation"`, `"Subscription"`). `fieldName` reads the method
-     * decorator's `{ name }` option override when present, otherwise
-     * the method name.
+     * (`@Resolver(() => User)` → `"User"`), and from
+     * `methodDecoratorTypeMap` when the class decorator has no
+     * argument. `fieldName` reads the method decorator's `{ name }`
+     * option override when present, otherwise the method name.
      */
     type: "decoratedMethod";
     /**
      * The module a pack-recognised decorator must be imported from
      * for discovery to fire. Codebases sometimes wrap framework
-     * decorators in their own re-exports (NestJS apps frequently
-     * declare `MetadataResolver` / `CoreResolver` factories that
-     * compose `@Resolver()` with extra metadata). When that happens,
-     * the import-module gate would miss them; pass an array of
-     * accepted modules and any one match suffices.
+     * decorators in their own re-exports, composing the framework's
+     * decorator with extra metadata. When that happens, the
+     * import-module gate would miss them; pass an array of accepted
+     * modules and any one match suffices.
      */
     importModule: string | string[];
     /**
      * Class decorator names to recognise. The first entry that
      * appears on a class wins for typeName extraction (the rest are
-     * fallbacks for codebases with multiple wrapper styles).
+     * fallbacks for codebases with multiple wrapper styles). A pack
+     * ships only what its own framework declares here and takes a
+     * project's wrappers through its options.
      */
     classDecorators: string[];
     methodDecorators: string[];
+    /**
+     * Method decorator name → the type its field hangs off when the
+     * class decorator names none. NestJS puts `@Query` on the root
+     * `Query` type and `@Mutation` on `Mutation` whatever the class
+     * says, so those two answer for themselves.
+     *
+     * A decorator the map leaves out has no answer of its own, and a
+     * class that names no type leaves the field's owner unread. The
+     * binding then names no type and pairs with nothing, rather than
+     * claiming a field the schema does not have.
+     */
+    methodDecoratorTypeMap: Record<string, string>;
 } | {
     /**
      * NestJS-style REST controller discovery. Class decorated with
@@ -248,10 +260,9 @@ type DiscoveryMatch = {
      * Same wrapper-decorator tolerance as `decoratedMethod`: the
      * import-module gate fires on at least one method-route
      * decorator from the framework module, but class decorators
-     * match by name only so project-internal wrappers
-     * (`@PublicController` / `@AuthedController` factories
-     * composing `@Controller()`) work without per-project pack
-     * config.
+     * match by name only, so a project-internal wrapper composing
+     * the framework's decorator matches once the project names it
+     * in the pack's options.
      *
      * The adapter populates `DiscoveredUnit.routeInfo` so the
      * produced binding carries `rest(method, path)`.
@@ -685,14 +696,18 @@ interface TransparentWrapper {
 interface PatternPack {
     name: string;
     /**
-     * Pack version stamp — feeds the cache invalidation key. Bump on
+     * Pack version stamp, which feeds the cache invalidation key. Bump on
      * any change that affects discovered units / extracted summaries.
-     * Format is opaque to the adapter; semver is the obvious choice
-     * but a content hash, build SHA, or monotonic integer works too.
-     * Optional — packs that omit it use the literal string `"unset"`,
-     * which means cache entries from one process to the next aren't
-     * meaningfully versioned (suitable for development; production
-     * packs should declare a version).
+     * Format is opaque to the adapter, so semver or a content hash both
+     * work.
+     *
+     * Optional, because whoever loads the pack knows more about it than
+     * the pack does. The CLI folds a hash of the file it loaded and of
+     * the config it passed into this stamp, so a pack run through the CLI
+     * invalidates on an edit whether or not it declares a version. A host
+     * that builds packs some other way carries that responsibility
+     * itself. A pack with nothing to stamp reads as `"unset"`, and warm
+     * caches will answer for code that has since changed.
      */
     version?: string;
     languages: string[];
@@ -981,6 +996,8 @@ interface DiscoveredCustomUnit {
         messageBus: MessageBusSemantics["messageBus"];
         channel: string;
     };
+    /** The thing that gets deployed and runs this unit, when known. */
+    deployableUnit?: DeployableUnit;
     /**
      * Metadata merged onto the resulting summary's `metadata` field.
      */
@@ -1264,6 +1281,23 @@ interface RawDeclaredContract {
      */
     provenance?: "derived" | "independent";
 }
+/**
+ * What sits where a unit's body should be.
+ *
+ *   - "absent": there is no body behind this declaration (an overload
+ *     signature, an ambient declaration, an abstract method), so the
+ *     pack read nothing about what the unit does.
+ *   - "empty": a body with nothing in it. A summary that says nothing
+ *     about it has described it completely.
+ *   - "statements": a body with work in it, including a concise
+ *     arrow's expression. A summary that says nothing about it has
+ *     described none of it.
+ *   - "elsewhere": the unit's body is not in what this run read. A
+ *     route registered with a handler the caller supplies announces a
+ *     boundary and names no function to look in, and the boundary is
+ *     worth reporting with nothing behind it.
+ */
+type BodyContent = "absent" | "empty" | "statements" | "elsewhere";
 interface RawCodeStructure {
     identity: {
         name: string;
@@ -1283,6 +1317,8 @@ interface RawCodeStructure {
      * helpers, pure utilities, and anything the adapter can't place.
      */
     boundaryBinding: BoundaryBinding | null;
+    /** The thing that gets deployed and runs this code, when known. */
+    deployableUnit?: DeployableUnit;
     parameters: RawParameter[];
     branches: RawBranch[];
     /**
@@ -1292,6 +1328,14 @@ interface RawCodeStructure {
      * saying it does nothing.
      */
     unmatchedReturns?: number;
+    /**
+     * What the adapter found where the unit's body should be. A summary
+     * with nothing in it means one of two different things, and only the
+     * adapter can say which: a body nobody could read, or a body with
+     * nothing in it to read. Adapters that do not say leave this unset,
+     * and everything downstream treats the summary as it did before.
+     */
+    bodyContent?: BodyContent;
     dependencyCalls: RawDependencyCall[];
     declaredContract: RawDeclaredContract | null;
     /**
@@ -1358,6 +1402,17 @@ interface RawCodeStructure {
         reference: string;
         reason: string;
     };
+    /**
+     * Set when the source does not state part of the boundary this unit
+     * sits on. The binding still goes out with that part left empty, so
+     * the unit pairs with nothing rather than with whatever a guess named,
+     * and this sentence tells a reader which part is missing and why.
+     *
+     * A statement about the reading rather than about the code, so it
+     * lands as an `unreadOutcome` gap and no checker holds it against the
+     * unit.
+     */
+    unreadBinding?: string;
 }
 interface ExtractorOptions {
     gapHandling: "strict" | "permissive" | "silent";
@@ -1370,4 +1425,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, type TransparentWrapper, assembleSummary, assessConfidence, detectGaps, effectToIR, httpRouteDiscovery, makeTransitionId, paramToInput, terminalToOutput };
+export { type AccessRecognizer, type BindingExtraction, type BodyContent, 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

@@ -64,7 +64,8 @@ function assembleSummary(raw, options = DEFAULT_OPTIONS) {
     identity: {
       name: raw.identity.name,
       exportPath: raw.identity.exportPath,
-      boundaryBinding: raw.boundaryBinding ?? null
+      boundaryBinding: raw.boundaryBinding ?? null,
+      ...raw.deployableUnit !== void 0 ? { deployableUnit: raw.deployableUnit } : {}
     },
     inputs,
     transitions,
@@ -130,6 +131,23 @@ function detectGaps(raw, transitions, options) {
       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.unreadBinding !== void 0) {
+    gaps.push({
+      type: "unreadOutcome",
+      conditions: [],
+      consequence: "unknown",
+      description: raw.unreadBinding
+    });
+  }
+  const unreadBody = describeUnreadBody(raw);
+  if (unreadBody !== null) {
+    gaps.push({
+      type: "unreadOutcome",
+      conditions: [],
+      consequence: "unknown",
+      description: unreadBody
+    });
+  }
   if (raw.declaredContract) {
     const producedStatuses = new Set(
       transitions.flatMap((t) => {
@@ -169,10 +187,34 @@ function detectGaps(raw, transitions, options) {
   }
   return gaps;
 }
+function bodyWentUnread(raw) {
+  if (raw.bodyContent === "absent" || raw.bodyContent === "elsewhere") {
+    return true;
+  }
+  return raw.bodyContent === "statements" && raw.branches.length === 0;
+}
+function describeUnreadBody(raw) {
+  if (!bodyWentUnread(raw)) {
+    return null;
+  }
+  if (raw.bodyContent === "absent") {
+    return "This unit is a declaration with no body behind it, so nothing about what it does was read here";
+  }
+  if (raw.bodyContent === "elsewhere") {
+    return "The handler on this boundary comes from outside the code that registers it, so nothing about what it does was read here";
+  }
+  if ((raw.unmatchedReturns ?? 0) > 0) {
+    return null;
+  }
+  return "Nothing this unit's body does matches a shape this pack looks for, so what it does is not described here";
+}
 function assessConfidence(raw) {
   if ((raw.unmatchedReturns ?? 0) > 0) {
     return { source: "inferred_static", level: "low" };
   }
+  if (bodyWentUnread(raw)) {
+    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.1.0",
+  "version": "0.1.1",
   "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.1.0"
+    "@suss/behavioral-ir": "0.1.1"
   },
   "devDependencies": {
     "tsup": "*",