@suss/extractor 0.20.0 → 0.21.1

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { Effect, MessageBusSemantics, DeployableUnit, Predicate, BehavioralSummary, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, GraphqlDeclaredContract, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
+import { Effect, MessageBusSemantics, DeployableUnit, BehavioralSummary, Predicate, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, WrapperReference, GraphqlDeclaredContract, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
+import { z } from 'zod';
 
 /**
  * What a unit reads out of what it was given.
@@ -21,6 +22,112 @@ interface InputRead {
     path: string[];
 }
 
+/**
+ * Reading a function the project wrote in front of a library, before
+ * anything is extracted.
+ *
+ * A service writes `registerCrud(app, "users", handlers)` and puts the
+ * library call one hop away, inside a helper of its own, where the path
+ * is a parameter. The call site has the literals and no library; the
+ * helper body has the library and no literals.
+ *
+ * A pack asks here for the helper to be read once, over the whole
+ * project, before any file is walked. What comes back says what the
+ * body does in terms of the helper's own parameters, and the pack turns
+ * that into the patterns and recognizers it used to take as config.
+ */
+
+/**
+ * One value inside a helper's body, said in the helper's own terms.
+ *
+ * Every variant is something a call site can fill in. Anything else is
+ * `unread`, which a pack drops rather than guesses at.
+ */
+type HelperValue = 
+/**
+ * A string, with `{N}` standing where parameter N was interpolated.
+ * A literal with no interpolation is the literal itself.
+ */
+{
+    as: "text";
+    text: string;
+}
+/** Parameter N, or one named property of it. */
+ | {
+    as: "parameter";
+    position: number;
+    property?: string;
+}
+/** An object literal, each property read the same way. */
+ | {
+    as: "object";
+    properties: Record<string, HelperValue>;
+}
+/** A call, so a pack can see through `JSON.stringify(request)`. */
+ | {
+    as: "call";
+    callee: string;
+    arguments: HelperValue[];
+}
+/** Something none of the above covers. */
+ | {
+    as: "unread";
+};
+/** One call a helper's body makes, read in the helper's own terms. */
+interface HelperSink {
+    /** The property the call was made through, or null for a bare call. */
+    method: string | null;
+    /** What the call was made on. */
+    receiver: HelperValue;
+    arguments: HelperValue[];
+}
+/** A function the project declares, as the index read it. */
+interface ProjectHelper {
+    /** What the declaration calls it, which is what a call site writes. */
+    name: string;
+    /** Absolute path of the file declaring it. */
+    file: string;
+    /** Its parameters, in order, by name. */
+    parameters: string[];
+    /**
+     * Parameters some caller handed this pack's own value to. Empty when
+     * the helper was found by its body rather than by a call site.
+     */
+    subjectParameters: number[];
+    /** Every call its body makes that the search asked about. */
+    sinks: HelperSink[];
+}
+/**
+ * How the index picks out which of the project's functions to read.
+ *
+ * `subject` starts at a call site: a function the project hands one of
+ * this pack's own values to is a helper of this pack's, whatever the
+ * helper's file imports. `text` starts at the body, for a pack whose
+ * library is reached over the wire and has no import to look for. Both
+ * come from the library itself, which is the bar `requiresImport` meets.
+ */
+type HelperSearch = {
+    by: "subject";
+} | {
+    by: "text";
+    contains: string[];
+};
+/** What a pack contributes to a run once its helpers have been read. */
+interface HelperDeclarations {
+    discovery?: DiscoveryPattern[];
+    invocationRecognizers?: InvocationRecognizer[];
+}
+/** A pack's standing request to have the project's helpers read. */
+interface ProjectHelpers {
+    find: HelperSearch;
+    /**
+     * Turned into patterns and recognizers before the first file is
+     * walked. It is handed data, never an AST, so a pack that declares
+     * one still runs on any adapter that implements the reading.
+     */
+    declare(helpers: readonly ProjectHelper[]): HelperDeclarations;
+}
+
 /**
  * The `PatternPack` interface, which is what a framework pack gives a language
  * adapter. The pack says WHAT to look for (which import, which call, which
@@ -384,6 +491,16 @@ type DiscoveryMatch = {
     type: "registrationTemplate";
     helperName: string;
     importModule?: string;
+    /**
+     * Which argument is the routable, so a route the helper writes
+     * keys on the same app as one written beside it and the
+     * middleware registered there covers it too.
+     */
+    subject?: {
+        argument: number;
+        importModule: string;
+        importNames: string[];
+    };
     registrations: Array<{
         method: string;
         pathTemplate: string;
@@ -637,6 +754,52 @@ interface DiscoveryPattern {
         /** Argument position of the mounted router/sub-app value. */
         targetPosition: number;
     };
+    /**
+     * How this framework registers a function that runs around a
+     * handler rather than as one: middleware, an error handler, a
+     * validation hook. Like `mount`, this only means anything when
+     * `match.type` is `"registrationCall"`, because wrapper discovery
+     * reuses that match's `importModule` and `importName` to work out
+     * which variables in a file are the routable being registered on.
+     *
+     * When set, the registered function becomes a unit of its own and is
+     * summarized like any other, and every unit registered on the same
+     * routable records a reference to it. A registration whose function
+     * the resolution store cannot follow contributes nothing.
+     */
+    wraps?: {
+        /** Method name that registers a wrapper, e.g. "use" or "onError". */
+        method: string;
+        /** Argument position of the wrapper function. */
+        targetPosition: number;
+        /**
+         * Argument position of a path pattern narrowing which routes the
+         * wrapper runs for, when the method takes one. Absent means the
+         * wrapper runs for every route on the subject.
+         */
+        scopePosition?: number;
+        /**
+         * Parameter position of the continuation inside the wrapper, the one
+         * it calls to hand control on. Absent when the wrapper never
+         * continues, which is how an error handler that always responds is
+         * written.
+         */
+        continuationParam?: number;
+        /**
+         * Parameter position that receives what the wrapped unit threw. A
+         * wrapper that declares one runs only when the wrapped unit's path
+         * ended by throwing, which is a fact about how the framework invokes
+         * it rather than anything its body says. Absent means the wrapper
+         * runs on the ordinary path.
+         */
+        throwParam?: number;
+        /**
+         * Only match a registered function declared with exactly this many
+         * parameters. Express tells its error handlers apart from its
+         * middleware by arity alone, both being `app.use(fn)`.
+         */
+        arity?: number;
+    };
     /**
      * This pattern only runs against files that import one of these module
      * specifiers, or a sub-path of one. An empty array means no gate at all
@@ -723,6 +886,17 @@ type TerminalMatch = {
      * `useEffect` bodies, Node `.on(...)` callbacks) should include it.
      */
     type: "functionFallthrough";
+} | {
+    /**
+     * A call to the parameter at this position, `next()` inside a
+     * middleware. Nothing declares this in a pack: the adapter builds
+     * it from `DiscoveryPattern.wraps.continuationParam`, so a
+     * wrapper's path that hands control on ends in a `delegate`
+     * output and a path that responds first does not. That is how
+     * composition tells the two apart.
+     */
+    type: "parameterCall";
+    parameterPosition: number;
 };
 interface TerminalExtraction {
     statusCode?: {
@@ -757,8 +931,8 @@ interface TerminalExtraction {
     defaultStatusCode?: number;
 }
 interface TerminalPattern {
-    /** What kind of output this terminal produces: "response", "throw", "return", "render" */
-    kind: "response" | "throw" | "return" | "render";
+    /** What kind of output this terminal produces: "response", "throw", "return", "render", "delegate" */
+    kind: "response" | "throw" | "return" | "render" | "delegate";
     match: TerminalMatch;
     extraction: TerminalExtraction;
     /**
@@ -941,6 +1115,19 @@ interface PatternPack {
      * will then serve results for code that has since changed.
      */
     version?: string;
+    /**
+     * Files under the project this pack reads that are not source files,
+     * given the files the run is about to walk. Their content feeds the
+     * same cache key the pack's own config does, so a run made after
+     * somebody edits one reads the project again instead of handing back
+     * the previous answer.
+     *
+     * The aws-lambda pack is the case this exists for: a SAM template
+     * decides which handlers there are and what invokes them, and no
+     * source file changes when that template does. A pack that reads only
+     * the code it is handed leaves this out.
+     */
+    discoveryInputs?: (files: readonly string[]) => string[];
     languages: string[];
     discovery: DiscoveryPattern[];
     terminals: TerminalPattern[];
@@ -1109,6 +1296,13 @@ interface PatternPack {
      * available without importing anything).
      */
     requiresImport?: string[];
+    /**
+     * Functions the project itself wrote in front of this library, read
+     * once across the whole project before any file is walked. What the
+     * pack makes of them joins its own patterns and recognizers for the
+     * rest of the run.
+     */
+    projectHelpers?: ProjectHelpers;
     /**
      * Environment variables the pack's library reads from inside
      * node_modules, where no walk ever looks. Declaring them keeps the
@@ -1355,6 +1549,14 @@ interface DiscoveredCustomUnit {
         /** Null when the pack knows the wire but not the channel on it. */
         channel: string | null;
     };
+    /**
+     * The deployed unit this one is, for a unit nothing else routes to.
+     * A Lambda with no event source in its template is reached by being
+     * invoked by name, so its own platform and name are the boundary, and
+     * the adapter builds a `unit-invocation` binding from them. Set it
+     * where a unit would otherwise fall back to a keyless function-call.
+     */
+    invocationInfo?: DeployableUnit;
     /** The thing that gets deployed and runs this unit, when known. */
     deployableUnit?: DeployableUnit;
     /**
@@ -1641,6 +1843,56 @@ declare function firstWrittenReading<T>(readings: readonly Reading<T>[]): Chosen
  */
 declare function valueToReadFurtherFrom<T>(reading: Reading<T>): T | null;
 
+/**
+ * composeWrappers.ts: what a unit does once the code registered around
+ * it is folded in.
+ *
+ * A wrapper is a meta-function: it takes a unit and returns a unit. Its
+ * summary already says what it does, because the call to its
+ * continuation comes through as a `delegate` transition, so one
+ * application is the wrapper's short circuits plus its pass-throughs
+ * times the wrapped unit's transitions, and a stack is repeated
+ * application. The package README works the example through and says
+ * what composition does not read.
+ */
+
+/**
+ * Every summary, with the ones that record wrappers replaced by their
+ * composition. A summary with no wrappers, and one whose wrappers this
+ * run has no summaries for, comes back untouched.
+ */
+declare function composeWrappers(summaries: readonly BehavioralSummary[]): BehavioralSummary[];
+
+/**
+ * Which branch an effect belongs to.
+ *
+ * An adapter finds the calls a body makes once, then has to say which
+ * of the branches it also found each call runs on. Two facts settle it,
+ * and both are already extracted: the guards the call is written under,
+ * and where the branch's terminal is in the file. Every adapter that
+ * attributes effects to branches reads from here, so they all decide
+ * it the same way.
+ *
+ * Neither test is enough alone, and the README beside this file says
+ * why with the two shapes that go wrong.
+ */
+
+/**
+ * Whether the branch leaves room for every guard on the effect. A guard
+ * the branch wrote down the other way around rules the effect out. A
+ * guard it says nothing about does not, because a branch out of a loop
+ * or a catch says nothing about what happened inside.
+ */
+declare function guardsHoldOn(preconditions: readonly RawCondition[] | undefined, conditions: readonly RawCondition[]): boolean;
+/**
+ * Whether a call on `effectLine` was written by the time the terminal
+ * ending on `terminalEndLine` is reached. The terminal's last line and
+ * not its first, because a call written inside the terminal's own
+ * expression, `return new Promise((resolve) => resolve(read()))`, runs
+ * as part of producing it.
+ */
+declare function runsBefore(effectLine: number, terminalEndLine: number): boolean;
+
 /**
  * Small helpers for pattern packs that are built the same way.
  *
@@ -1686,15 +1938,39 @@ declare function httpRouteDiscovery(opts: {
      */
     mount?: DiscoveryPattern["mount"];
 }): DiscoveryPattern[];
+/**
+ * Discovery entries for the functions a framework registers around its
+ * handlers: middleware, error handlers, validation hooks.
+ *
+ * A wrapper becomes a unit of its own, summarized like any other, so
+ * these entries carry no `bindingExtraction` and no registration chain.
+ * Their `match` is there for the import and the imported name, which is
+ * how wrapper discovery works out which variables in a file are the
+ * routable. One entry per (import name, wrapper shape) pair, since a
+ * framework can register more than one kind of wrapper on a routable.
+ */
+declare function wrapperDiscovery(opts: {
+    importModule: string;
+    importNames: readonly string[];
+    wraps: ReadonlyArray<NonNullable<DiscoveryPattern["wraps"]>>;
+    /** Defaults to "middleware". Override for packs that want another kind. */
+    kind?: string;
+}): 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. */
+    /** What the helper is called, as the project's code writes it. */
     helperName: string;
-    /** The module the helper is imported from, to tell two apart. */
+    /** The file declaring it, so a same-named function elsewhere is left alone. */
     importModule?: string;
+    /** Which argument is the app, so middleware on it covers these routes. */
+    subject?: {
+        argument: number;
+        importModule: string;
+        importNames: string[];
+    };
     registrations: Array<{
         method: string;
         pathTemplate: string;
@@ -1704,17 +1980,25 @@ interface RegistrationHelper {
 /**
  * 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.
+ * A helper like `registerCrud(app, "users", handlers)` registers routes
+ * the call site never spells out. What each one registers comes from
+ * the project helper index, which reads the helper's body before
+ * extraction, so a call site expands per call and a helper called twice
+ * gives two routes rather than none.
  */
 declare function registrationHelperDiscovery(helpers: readonly RegistrationHelper[], kind?: string): DiscoveryPattern[];
+/**
+ * The standing request an HTTP pack makes to have the project's own
+ * route helpers read, so what each one registers is a fact about the
+ * code rather than something the project restates in config.
+ */
+declare function routeHelperIndex(opts: {
+    importModule: string;
+    importNames: readonly string[];
+    methods: readonly string[];
+    /** Defaults to "handler", to match `httpRouteDiscovery`. */
+    kind?: string;
+}): ProjectHelpers;
 /**
  * The payload behind a `JSON.stringify(...)` call, or the argument
  * unchanged when it is anything else. A producer serializes its message
@@ -1723,6 +2007,52 @@ declare function registrationHelperDiscovery(helpers: readonly RegistrationHelpe
  */
 declare function unwrapJsonStringify(body: EffectArg | null): EffectArg | null;
 
+/**
+ * Option declarations more than one pack takes.
+ *
+ * A pack exports `optionsSchema` beside its factory, and the CLI parses
+ * a `-f pack=config.json` file against it before the factory runs, so a
+ * key nobody declared is refused by name instead of read as nothing.
+ *
+ * Four packs accept `storageSystem` and three accept `scope`. A copy
+ * per pack is how one of them ends up allowing a value the others
+ * reject, which is what happened when two doc comments named
+ * `"postgres"` and the union allowed only `"postgresql"`.
+ */
+
+/**
+ * Which database is behind the connection, spelled the way the
+ * provider summaries spell it. Both sides build a pairing key from
+ * this, so a value only one side would write stops the two pairing
+ * with nothing said about why.
+ */
+declare const storageSystemOption: z.ZodEnum<{
+    postgresql: "postgresql";
+    mysql: "mysql";
+    sqlite: "sqlite";
+}>;
+/**
+ * Which of a project's connections an access belongs to, matched
+ * against the scope the provider summaries carry. Packs default it to
+ * `"default"`, so a project with one connection never sets it.
+ */
+declare const scopeOption: z.ZodString;
+/**
+ * A call the project has declared to be its own dispatcher, which both
+ * message-bus packs take under `producers`.
+ *
+ * `receiver` is the type rather than the variable: a service keeps its
+ * dispatcher in a field, a closure or a constructor parameter, and the
+ * type is the only thing stable across all three.
+ */
+declare const configuredCallOption: z.ZodObject<{
+    module: z.ZodString;
+    receiver: z.ZodString;
+    method: z.ZodString;
+    subjectArg: z.ZodNumber;
+    bodyArg: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+
 /**
  * The path engine, written against `StructuredStatement` rather than any one
  * language. Every control-flow path from entry to a terminal contributes its
@@ -1738,6 +2068,8 @@ declare function unwrapJsonStringify(body: EffectArg | null): EffectArg | null;
  * enclosure conditions plus an opaque conjunct instead of guessing.
  */
 
+/** The cap on how many paths to enumerate. Past it the caller falls back to degraded conditions. */
+declare const MAX_PATHS = 256;
 /** A construct the lowering step will not model safely, such as switch and case rules the enumeration does not cover. Callers catch this and degrade. */
 declare class UnmodeledFlow extends Error {
 }
@@ -1820,6 +2152,40 @@ declare class IdMap<T extends Identified, V> implements Iterable<[T, V]> {
     [Symbol.iterator](): Iterator<[T, V]>;
 }
 
+/**
+ * nodeWalk.ts: the one recursion the adapters use to read a declaration
+ * wherever the language allows it to be written.
+ *
+ * A declaration goes where a statement goes, and every language has more
+ * places for a statement than a reader remembers to list. So an adapter
+ * does not list the containers it descends into. It walks every named
+ * child and says only which nodes keep their own body, because that set
+ * is short and a grammar's own vocabulary already names it.
+ */
+/** A parse tree, however a grammar spells one. */
+interface WalkableNode<T> {
+    readonly namedChildren: ReadonlyArray<T | null>;
+}
+/**
+ * Returned by `into` for a node whose children the walk should leave
+ * unread, such as one whose body belongs to what it declares. A symbol,
+ * so it cannot collide with whatever a caller carries.
+ */
+declare const SKIP_CHILDREN: unique symbol;
+/** What a walk does at each node it reaches. */
+interface NodeVisitor<T, C> {
+    /** Called once per node, in source order, before its own children. */
+    at(node: T, carried: C): void;
+    /** What to carry into this node's children, or `SKIP_CHILDREN` to leave them unread. */
+    into(node: T, carried: C): C | typeof SKIP_CHILDREN;
+}
+/**
+ * Every named node under `root`, depth first and in source order, with a
+ * value the visitor updates as the walk descends. `root` itself is not
+ * visited, because a caller starts from the body it is reading.
+ */
+declare function walkDescendants<T extends WalkableNode<T>, C>(root: T, carried: C, visitor: NodeVisitor<T, C>): void;
+
 /**
  * The small surface every language adapter implements, whatever that
  * language's own tooling looks like underneath.
@@ -2335,6 +2701,8 @@ interface RawCodeStructure {
         siblings: number;
         prefix: string;
     };
+    /** The wrappers registered around this unit: middleware, error handlers. */
+    wrappers?: WrapperReference[];
     /** The extractor cannot derive this. An adapter that has the SDL and knows
      * which field the resolver serves fills it in. */
     graphqlDeclaredContract?: GraphqlDeclaredContract;
@@ -2383,7 +2751,10 @@ declare function assembleSummary(raw: RawCodeStructure, options?: ExtractorOptio
 declare function detectGaps(raw: RawCodeStructure, transitions: Transition[], options: ExtractorOptions): Gap[];
 declare function assessConfidence(raw: RawCodeStructure): ConfidenceInfo;
 declare function terminalToOutput(terminal: RawTerminal): Output;
+/** A condition the adapter left unstructured becomes an opaque predicate
+ * rather than being dropped, so the branch keeps its guard. */
+declare function rawConditionToPredicate(c: RawCondition): Predicate;
 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 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 InputRead, 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 };
+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, type HelperDeclarations, type HelperSearch, type HelperSink, type HelperValue, IdMap, IdSet, type Identified, type InputMappingPattern, type InputRead, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, MAX_PATHS, type NodeVisitor, type OpsCarrier, type PackDeclarations, PathBudgetExceeded, type PatternPack, type ProjectHelper, type ProjectHelpers, 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, SKIP_CHILDREN, 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, type WalkableNode, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, composeWrappers, configuredCallOption, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, guardsHoldOn, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, rawConditionToPredicate, registrationHelperDiscovery, routeHelperIndex, runsBefore, scopeOption, sharedGatingConditions, storageSystemOption, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, walkDescendants, wrapperDiscovery, writtenReading };