@suss/extractor 0.32.0 → 0.33.0

package/README.md

@@ -63,8 +63,8 @@ const summary = assembleSummary(raw);
 ## More
 
 - [How the extractor assembles a summary](./DESIGN.md)
-- [Documentation](https://nimbuscloud-ai.github.io/suss/)
-- [Every package and pack suss ships](https://nimbuscloud-ai.github.io/suss/reference/packages)
+- [Documentation](https://suss.sh/)
+- [Every package and pack suss ships](https://suss.sh/packs/catalog)
 - [Source and issues](https://github.com/nimbuscloud-ai/suss)
 
 ## Coverage
@@ -77,4 +77,4 @@ Licensed under Apache 2.0. See [LICENSE](../../LICENSE).
 
 ---
 
-For the canonical design, see [docs/architecture.md](../../docs/architecture.md).
+For the canonical design, see [docs/theory/architecture.md](../../docs/theory/architecture.md).

package/dist/index.cjs

@@ -395,7 +395,7 @@ function stampModuleImports(summaries, importsOf) {
 
 // src/moduleInit.ts
 function moduleInitStructure(options) {
-  const { name, file, range, effects } = options;
+  const { name, file, range, effects, calls } = options;
   return {
     identity: {
       name,
@@ -422,7 +422,7 @@ function moduleInitStructure(options) {
           emitEvent: null,
           location: range
         },
-        effects: [],
+        effects: calls ?? [],
         extraEffects: effects,
         location: range,
         isDefault: true
@@ -1809,6 +1809,14 @@ function recognizersWithNoUnits(packs) {
     detail: `${funnel.candidateFiles} gated files, and no pack in this run discovered a unit in them. ${funnel.pack} reads calls inside units another pack finds, so add the pack that finds this project's handlers (-f express, -f fastify, ...), or run suss init to work out which.`
   }));
 }
+function gatedPacksWithNoFiles(packs) {
+  return packs.filter(
+    (funnel) => funnel.gates.length > 0 && funnel.unresolvedGates.length === 0 && funnel.candidateFiles === 0
+  ).map((funnel) => ({
+    label: funnel.pack,
+    detail: `${funnel.gates.join(", ")} is installed and no file in this run imports it, directly or through a module of the project's own. Either this code does not use the library, or it reaches it some way the import gate does not follow.`
+  }));
+}
 function helpersThatMatchedNothing(packs) {
   return packs.flatMap(
     (funnel) => funnel.helpersUnmatched.map((helper) => ({
@@ -1899,6 +1907,12 @@ function evaluatePackHealth(report) {
       audience: "run",
       violations: funnelDrops(report.packs)
     },
+    {
+      name: "every pack whose library is installed had files to read",
+      code: "no-files",
+      audience: "run",
+      violations: gatedPacksWithNoFiles(report.packs)
+    },
     {
       name: "every recognizer had units to look inside",
       code: "no-units",
@@ -2093,6 +2107,22 @@ function unreadSentences(raw) {
     ...handedOver.map(unreadReasonOf).filter((reason) => reason !== null)
   ];
 }
+function effectsOfBranch(branch) {
+  const effects = [
+    ...branch.effects.map(effectToIR),
+    ...branch.extraEffects ?? []
+  ];
+  return (0, import_behavioral_ir5.foldRepeatedEffects)(effects.map(withNormalizedCallee));
+}
+function withNormalizedCallee(effect) {
+  if (effect.type !== "invocation" && effect.type !== "interaction") {
+    return effect;
+  }
+  if (effect.callee === void 0) {
+    return effect;
+  }
+  return { ...effect, callee: (0, import_behavioral_ir5.normalizeCalleeText)(effect.callee) };
+}
 function assembleSummary(raw, options = DEFAULT_OPTIONS) {
   const transitions = raw.branches.map((rawBranch) => {
     const branch = branchWithCollapsedReadings(rawBranch);
@@ -2103,10 +2133,7 @@ function assembleSummary(raw, options = DEFAULT_OPTIONS) {
       id: makeTransitionId(raw.identity.name, branch),
       conditions,
       output: terminalToOutput(branch.terminal),
-      effects: [
-        ...branch.effects.map(effectToIR),
-        ...branch.extraEffects ?? []
-      ],
+      effects: effectsOfBranch(branch),
       location: branch.location,
       isDefault: branch.isDefault
     };
@@ -2171,6 +2198,9 @@ function buildMetadata(raw) {
   if (raw.wrappers !== void 0 && raw.wrappers.length > 0) {
     metadata = (0, import_behavioral_ir5.withWrapperMetadata)(metadata, { applied: raw.wrappers });
   }
+  if (raw.requestSpelling !== void 0) {
+    metadata = (0, import_behavioral_ir5.withRequestSpellingMetadata)(metadata, raw.requestSpelling);
+  }
   return Object.keys(metadata).length > 0 ? metadata : null;
 }
 function buildHttpMetadataValue(raw) {

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Effect, MessageBusSemantics, DeployableUnit, CodeUnitKind, BehavioralSummary, Predicate, TypeShape, RenderNode, BoundaryBinding, WrapperReference, GraphqlDeclaredContract, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
+import { Effect, MessageBusSemantics, DeployableUnit, CodeUnitKind, RequestSpellingMetadata, BehavioralSummary, Predicate, TypeShape, RenderNode, BoundaryBinding, WrapperReference, GraphqlDeclaredContract, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
 import { z } from 'zod';
 
 /**
@@ -173,6 +173,15 @@ type DiscoveryMatch = {
      * `axios.get(...)`.
      */
     factoryMethods?: string[];
+    /**
+     * The property of the factory call's config object that every
+     * request through the instance is sent under, `baseURL` for axios.
+     * Both sides of a boundary have to read one route the same way,
+     * and a spec's `servers[0].url` already goes in front of the
+     * provider's paths, so a base written here goes in front of the
+     * consumer's.
+     */
+    basePathOption?: string;
     /**
      * The import and every instance built from it can be called as a
      * function, so `axios(config)` and `api(config)` are requests the
@@ -1174,6 +1183,18 @@ interface PatternPack {
     terminals: TerminalPattern[];
     contractReading?: ContractPattern;
     inputMapping: InputMappingPattern;
+    /**
+     * For a REST pack, where in the handler each part of the request is
+     * read, in the same words `inputMapping` gives the parameters: an
+     * Express handler reads a header at `request.headers`, a Lambda
+     * handler at `event.headers`. The adapter stamps this on every route
+     * the pack recognizes, and the intent pass rewrites the route's reads
+     * from it into the sections an author writes under `receives`.
+     *
+     * Leave it out on a pack whose handlers do not take a request, and
+     * leave a section out when the framework has no path for it.
+     */
+    requestSpelling?: RequestSpellingMetadata;
     /**
      * Transport (wire protocol) used in the `BoundaryBinding.transport`
      * of discovered units. Every pack has to say what its transport is
@@ -1337,6 +1358,16 @@ interface PatternPack {
      * available without importing anything).
      */
     requiresImport?: string[];
+    /**
+     * Files this library's code generator writes beside the module it
+     * generates, e.g. `["schema.prisma"]`. A project can point the
+     * generator at a directory of its own, and then every consumer
+     * imports the module by relative path and `requiresImport` matches
+     * nothing. A directory containing one of these files counts as the
+     * gated package, so those consumers reach the pack the way an
+     * ordinary import would.
+     */
+    generatedModuleMarkers?: string[];
     /**
      * Functions the project itself wrote in front of this library, read
      * once across the whole project before any file is walked. What the
@@ -1974,12 +2005,12 @@ declare function stampModuleImports(summaries: BehavioralSummary[], importsOf: (
  * and a service that reads its configuration there reads it there for
  * good. Walking unit bodies alone never sees that read, so the read gets
  * a unit of its own, one per file, named after the file, with no
- * boundary. Attributing it to each handler in the file would report one
- * read as several, and a file with no handler would still report nothing.
+ * boundary. Attributing it to each handler would report one read as
+ * several. The calls those statements make go on the same unit, so the
+ * closure can reach the functions behind them.
  *
- * The structure is one default branch whose terminal is `void`, because
- * module initialization returns to nobody. Every adapter builds it the
- * same way, so it lives here.
+ * The one default branch has a `void` terminal, because module
+ * initialization returns to nobody. Every adapter builds it the same way.
  */
 
 interface ModuleInitOptions {
@@ -1991,6 +2022,8 @@ interface ModuleInitOptions {
         end: number;
     };
     effects: Effect[];
+    /** The calls the top-level statements make while the module loads. */
+    calls?: RawEffect[];
 }
 declare function moduleInitStructure(options: ModuleInitOptions): RawCodeStructure;
 
@@ -3032,6 +3065,17 @@ interface ValueOps {
      * there, so a query that hands over a table object can still be read.
      */
     holes(): readonly (CallOps | null)[];
+    /**
+     * The same holes as values, in the same order, for a reader that
+     * wants what the source settled a hole to rather than what call was
+     * written there. A table kept in a module constant is the case: the
+     * hole is a name, not a call, so `holes` gives null for it and this
+     * gives the constant.
+     *
+     * An adapter that has not implemented this leaves it out, and a
+     * reader then has only the calls.
+     */
+    interpolated?(): readonly ValueOps[];
 }
 /** One entry of an object a call states. */
 interface ValueEntry {
@@ -3405,6 +3449,8 @@ interface RawCodeStructure {
     };
     /** The wrappers registered around this unit: middleware, error handlers. */
     wrappers?: WrapperReference[];
+    /** Where a REST pack's handlers read each part of the request, from the pack. */
+    requestSpelling?: RequestSpellingMetadata;
     /** The extractor cannot derive this. An adapter that has the SDL and knows
      * which field the resolver serves fills it in. */
     graphqlDeclaredContract?: GraphqlDeclaredContract;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Effect, MessageBusSemantics, DeployableUnit, CodeUnitKind, BehavioralSummary, Predicate, TypeShape, RenderNode, BoundaryBinding, WrapperReference, GraphqlDeclaredContract, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
+import { Effect, MessageBusSemantics, DeployableUnit, CodeUnitKind, RequestSpellingMetadata, BehavioralSummary, Predicate, TypeShape, RenderNode, BoundaryBinding, WrapperReference, GraphqlDeclaredContract, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
 import { z } from 'zod';
 
 /**
@@ -173,6 +173,15 @@ type DiscoveryMatch = {
      * `axios.get(...)`.
      */
     factoryMethods?: string[];
+    /**
+     * The property of the factory call's config object that every
+     * request through the instance is sent under, `baseURL` for axios.
+     * Both sides of a boundary have to read one route the same way,
+     * and a spec's `servers[0].url` already goes in front of the
+     * provider's paths, so a base written here goes in front of the
+     * consumer's.
+     */
+    basePathOption?: string;
     /**
      * The import and every instance built from it can be called as a
      * function, so `axios(config)` and `api(config)` are requests the
@@ -1174,6 +1183,18 @@ interface PatternPack {
     terminals: TerminalPattern[];
     contractReading?: ContractPattern;
     inputMapping: InputMappingPattern;
+    /**
+     * For a REST pack, where in the handler each part of the request is
+     * read, in the same words `inputMapping` gives the parameters: an
+     * Express handler reads a header at `request.headers`, a Lambda
+     * handler at `event.headers`. The adapter stamps this on every route
+     * the pack recognizes, and the intent pass rewrites the route's reads
+     * from it into the sections an author writes under `receives`.
+     *
+     * Leave it out on a pack whose handlers do not take a request, and
+     * leave a section out when the framework has no path for it.
+     */
+    requestSpelling?: RequestSpellingMetadata;
     /**
      * Transport (wire protocol) used in the `BoundaryBinding.transport`
      * of discovered units. Every pack has to say what its transport is
@@ -1337,6 +1358,16 @@ interface PatternPack {
      * available without importing anything).
      */
     requiresImport?: string[];
+    /**
+     * Files this library's code generator writes beside the module it
+     * generates, e.g. `["schema.prisma"]`. A project can point the
+     * generator at a directory of its own, and then every consumer
+     * imports the module by relative path and `requiresImport` matches
+     * nothing. A directory containing one of these files counts as the
+     * gated package, so those consumers reach the pack the way an
+     * ordinary import would.
+     */
+    generatedModuleMarkers?: string[];
     /**
      * Functions the project itself wrote in front of this library, read
      * once across the whole project before any file is walked. What the
@@ -1974,12 +2005,12 @@ declare function stampModuleImports(summaries: BehavioralSummary[], importsOf: (
  * and a service that reads its configuration there reads it there for
  * good. Walking unit bodies alone never sees that read, so the read gets
  * a unit of its own, one per file, named after the file, with no
- * boundary. Attributing it to each handler in the file would report one
- * read as several, and a file with no handler would still report nothing.
+ * boundary. Attributing it to each handler would report one read as
+ * several. The calls those statements make go on the same unit, so the
+ * closure can reach the functions behind them.
  *
- * The structure is one default branch whose terminal is `void`, because
- * module initialization returns to nobody. Every adapter builds it the
- * same way, so it lives here.
+ * The one default branch has a `void` terminal, because module
+ * initialization returns to nobody. Every adapter builds it the same way.
  */
 
 interface ModuleInitOptions {
@@ -1991,6 +2022,8 @@ interface ModuleInitOptions {
         end: number;
     };
     effects: Effect[];
+    /** The calls the top-level statements make while the module loads. */
+    calls?: RawEffect[];
 }
 declare function moduleInitStructure(options: ModuleInitOptions): RawCodeStructure;
 
@@ -3032,6 +3065,17 @@ interface ValueOps {
      * there, so a query that hands over a table object can still be read.
      */
     holes(): readonly (CallOps | null)[];
+    /**
+     * The same holes as values, in the same order, for a reader that
+     * wants what the source settled a hole to rather than what call was
+     * written there. A table kept in a module constant is the case: the
+     * hole is a name, not a call, so `holes` gives null for it and this
+     * gives the constant.
+     *
+     * An adapter that has not implemented this leaves it out, and a
+     * reader then has only the calls.
+     */
+    interpolated?(): readonly ValueOps[];
 }
 /** One entry of an object a call states. */
 interface ValueEntry {
@@ -3405,6 +3449,8 @@ interface RawCodeStructure {
     };
     /** The wrappers registered around this unit: middleware, error handlers. */
     wrappers?: WrapperReference[];
+    /** Where a REST pack's handlers read each part of the request, from the pack. */
+    requestSpelling?: RequestSpellingMetadata;
     /** The extractor cannot derive this. An adapter that has the SDL and knows
      * which field the resolver serves fills it in. */
     graphqlDeclaredContract?: GraphqlDeclaredContract;

package/dist/index.js

@@ -2,9 +2,12 @@
 import { createHash as createHash3 } from "crypto";
 import {
   exchangesHttpResponses as exchangesHttpResponses2,
+  foldRepeatedEffects,
+  normalizeCalleeText,
   withGraphqlMetadata,
   withHttpMetadata,
   withMountMetadata,
+  withRequestSpellingMetadata,
   withSourceDocumentMetadata,
   withWrapperMetadata as withWrapperMetadata2
 } from "@suss/behavioral-ir";
@@ -319,7 +322,7 @@ function stampModuleImports(summaries, importsOf) {
 
 // src/moduleInit.ts
 function moduleInitStructure(options) {
-  const { name, file, range, effects } = options;
+  const { name, file, range, effects, calls } = options;
   return {
     identity: {
       name,
@@ -346,7 +349,7 @@ function moduleInitStructure(options) {
           emitEvent: null,
           location: range
         },
-        effects: [],
+        effects: calls ?? [],
         extraEffects: effects,
         location: range,
         isDefault: true
@@ -1732,6 +1735,14 @@ function recognizersWithNoUnits(packs) {
     detail: `${funnel.candidateFiles} gated files, and no pack in this run discovered a unit in them. ${funnel.pack} reads calls inside units another pack finds, so add the pack that finds this project's handlers (-f express, -f fastify, ...), or run suss init to work out which.`
   }));
 }
+function gatedPacksWithNoFiles(packs) {
+  return packs.filter(
+    (funnel) => funnel.gates.length > 0 && funnel.unresolvedGates.length === 0 && funnel.candidateFiles === 0
+  ).map((funnel) => ({
+    label: funnel.pack,
+    detail: `${funnel.gates.join(", ")} is installed and no file in this run imports it, directly or through a module of the project's own. Either this code does not use the library, or it reaches it some way the import gate does not follow.`
+  }));
+}
 function helpersThatMatchedNothing(packs) {
   return packs.flatMap(
     (funnel) => funnel.helpersUnmatched.map((helper) => ({
@@ -1822,6 +1833,12 @@ function evaluatePackHealth(report) {
       audience: "run",
       violations: funnelDrops(report.packs)
     },
+    {
+      name: "every pack whose library is installed had files to read",
+      code: "no-files",
+      audience: "run",
+      violations: gatedPacksWithNoFiles(report.packs)
+    },
     {
       name: "every recognizer had units to look inside",
       code: "no-units",
@@ -2016,6 +2033,22 @@ function unreadSentences(raw) {
     ...handedOver.map(unreadReasonOf).filter((reason) => reason !== null)
   ];
 }
+function effectsOfBranch(branch) {
+  const effects = [
+    ...branch.effects.map(effectToIR),
+    ...branch.extraEffects ?? []
+  ];
+  return foldRepeatedEffects(effects.map(withNormalizedCallee));
+}
+function withNormalizedCallee(effect) {
+  if (effect.type !== "invocation" && effect.type !== "interaction") {
+    return effect;
+  }
+  if (effect.callee === void 0) {
+    return effect;
+  }
+  return { ...effect, callee: normalizeCalleeText(effect.callee) };
+}
 function assembleSummary(raw, options = DEFAULT_OPTIONS) {
   const transitions = raw.branches.map((rawBranch) => {
     const branch = branchWithCollapsedReadings(rawBranch);
@@ -2026,10 +2059,7 @@ function assembleSummary(raw, options = DEFAULT_OPTIONS) {
       id: makeTransitionId(raw.identity.name, branch),
       conditions,
       output: terminalToOutput(branch.terminal),
-      effects: [
-        ...branch.effects.map(effectToIR),
-        ...branch.extraEffects ?? []
-      ],
+      effects: effectsOfBranch(branch),
       location: branch.location,
       isDefault: branch.isDefault
     };
@@ -2094,6 +2124,9 @@ function buildMetadata(raw) {
   if (raw.wrappers !== void 0 && raw.wrappers.length > 0) {
     metadata = withWrapperMetadata2(metadata, { applied: raw.wrappers });
   }
+  if (raw.requestSpelling !== void 0) {
+    metadata = withRequestSpellingMetadata(metadata, raw.requestSpelling);
+  }
   return Object.keys(metadata).length > 0 ? metadata : null;
 }
 function buildHttpMetadataValue(raw) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/extractor",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "type": "module",
   "description": "The suss extraction pipeline, which turns what a language adapter read into the summaries the checker pairs across a boundary.",
   "keywords": [
@@ -46,7 +46,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.32.0",
+    "@suss/behavioral-ir": "0.33.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {