@suss/adapter-typescript 0.20.0 → 0.21.1

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, PropertyAccessExpression, TaggedTemplateExpression, Project, ImportDeclaration, Symbol, Expression, NewExpression, Identifier } from 'ts-morph';
-import { PackDeclarations, TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, EffectArg, CallOps, LanguageAdapter, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, RawDeclaredContract, ContractPattern, AstCapableOps, ResponsePropertyMapping } from '@suss/extractor';
+import { PackDeclarations, TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, EffectArg, CallOps, LanguageAdapter, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, configuredCallOption, RawDeclaredContract, ContractPattern, AstCapableOps, ResponsePropertyMapping } from '@suss/extractor';
 import { BehavioralSummary, MessageBusSemantics, DeployableUnit, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
+import { z } from 'zod';
 import { Proof, Atom } from '@suss/datalog';
 import { ResolutionExplanation } from '@suss/resolution';
 
@@ -140,6 +141,14 @@ interface PackFunnel {
      * while this is non-empty.
      */
     failures: PackFailure[];
+    /**
+     * Registration helpers this pack's config asked for that no call in
+     * the run matched. The helper belongs to the project, so a spelling
+     * that matches nothing is a config mistake with no other symptom: the
+     * routes go missing and every count reads the same as a project
+     * without them.
+     */
+    helpersUnmatched: string[];
     /**
      * What the pack wrote as data rather than as code, or null for a pack
      * written as a hand-rolled walk. This is the one thing in the funnel
@@ -247,6 +256,7 @@ declare class ResolutionStore {
     private readonly importedNames;
     private readonly writtenValues;
     private readonly importOrigins;
+    private readonly subjectConstructions;
     /**
      * A file's table depends only on its re-export closure, which
      * `collectExports` extracts whole before answering, so later
@@ -288,6 +298,36 @@ declare class ResolutionStore {
      * GraphQL document kept in a constant in another file.
      */
     resolveWrittenValue(value: Node): Node | null;
+    /**
+     * The construction behind a registration subject: the call or `new`
+     * this value is written as, kept only when its callee comes from
+     * `importModule` under `importName`. A value written as two
+     * different things comes back null, since keying a route on the
+     * wrong app is worse than not keying it.
+     */
+    subjectConstructionOf(value: Node, importModule: string, importName: string): Node | null;
+    /**
+     * How many constructions this value was written as, which is what
+     * `subjectConstructionOf` weighed before it declined. Ask it after
+     * that call, so the walk it needs has already been paid for.
+     */
+    subjectCandidateCountOf(value: Node, importModule: string, importName: string): number;
+    /**
+     * The single-answer policy over the written-value walk, then the
+     * origin check on the one candidate. A candidate failing the check
+     * is settled refusal rather than a reason to widen: its own file's
+     * import facts are already in, and more files only add candidates.
+     */
+    private lookupSubjectConstruction;
+    /**
+     * Whether the construction's callee was imported from this module
+     * under this name. A default import records its name as "default",
+     * and a pack declares a default export by the local name people
+     * give it, so "default" counts when the callee is spelled with the
+     * declared name.
+     */
+    private constructionComesFrom;
+    private calleeNameOf;
     /**
      * Which names from `modules` this value comes down to, either by being
      * one of them under a local name or by calling into one. Getting
@@ -355,6 +395,15 @@ declare class ResolutionStore {
      * construction makes an instance of. The README says why.
      */
     private lookupWritten;
+    /**
+     * Read these files' facts now, before anything asks a question.
+     *
+     * A query widens along the imports of the file it starts in, which
+     * is where a value's definition is. What a caller passed is the other
+     * direction, so a question about a parameter is answered only by
+     * files the walk never reaches on its own.
+     */
+    extractFiles(sourceFiles: Iterable<SourceFile>): void;
     /**
      * Which of these files reach any of these packages, following
      * project-local re-export chains. A barrel package that re-exports an
@@ -405,6 +454,44 @@ type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | M
  */
 declare function collectAncestorBranches(terminalNode: Node, functionRoot: FunctionRoot): RawCondition[];
 
+/**
+ * unfollowedCall.ts: naming the calls the reachable closure stops at.
+ *
+ * The closure follows a call by resolving its callee to a function with a
+ * body. When that fails the edge is dropped, and a unit whose body is full
+ * of dropped edges produces the same empty summary as a unit that does
+ * nothing. This module says which kind of stop a call site is, and which
+ * kinds are worth leaving a gap for.
+ *
+ * The README beside this file explains where that line is drawn, and why
+ * a call into a dependency stays on the other side of it.
+ */
+
+/**
+ * Why the walk stopped.
+ *
+ * `noBody` states a shape and nothing else: a method on an interface, an
+ * abstract method, an ambient declaration. `unsettledValue` is declared
+ * as something other than a function, with something in it that could
+ * not be read. `multipleSources` reaches two different functions, so no
+ * single body can be followed. `outsideRun` is a declaration in a
+ * dependency, whose source this run never read. `noDeclaration` is a
+ * callee nothing declares, which is what a call on an untyped value
+ * comes to. `callerSupplied` is a parameter of the function being
+ * scanned, so the call runs whatever its caller handed in.
+ * `multipleReceivers` is a registration whose receiver comes down to
+ * more than one thing, so nothing says which one it registers on.
+ */
+type UnfollowedReason = "noBody" | "unsettledValue" | "multipleSources" | "outsideRun" | "noDeclaration" | "callerSupplied" | "multipleReceivers";
+/** One call the walk met and could not follow. */
+interface UnfollowedCall {
+    /** The callee as the source writes it, `this.dao.getEditions` say. */
+    readonly callee: string;
+    readonly reason: UnfollowedReason;
+    /** How many things the walk reached where it needed one. */
+    readonly candidates?: number;
+}
+
 interface ClientCallSite {
     callExpression: CallExpression;
     /** Method name on the client object (e.g. "getUser"), null for bare calls like fetch() */
@@ -556,6 +643,19 @@ interface DiscoveredUnit {
         /** Null when the pack knows the wire but not the channel on it. */
         channel: string | null;
     };
+    /**
+     * Populated by a pack's `discoverUnits` callback for a deployed unit
+     * nothing else routes to, which is reached by being invoked by name.
+     * The adapter builds a `unit-invocation` binding from it, which pairs
+     * with the calls that name the same unit.
+     */
+    invocationInfo?: DeployableUnit;
+    /**
+     * Identity of the routable this unit was registered on, when a
+     * registration call put it there. What the wrapper index is keyed on,
+     * since a wrapper is registered on the routable and not on the unit.
+     */
+    registrationSubjectId?: string;
     /** The thing that gets deployed and runs this unit, when known. */
     deployableUnit?: DeployableUnit;
     /**
@@ -573,6 +673,12 @@ interface DiscoveredUnit {
      * summary as an `unreadOutcome` gap.
      */
     unreadBinding?: string;
+    /**
+     * A call the handler met and could not follow, which reaches the
+     * summary as an `unfollowedCall` gap beside the ones the closure
+     * walk records.
+     */
+    unfollowed?: UnfollowedCall;
 }
 
 /**
@@ -597,12 +703,19 @@ interface MountPrefixIndex {
      */
     prefixForId?(childId: string): string;
 }
+/**
+ * What the project helper index says it has already expanded, which the
+ * walk consults so one registration does not become two summaries.
+ */
+interface ExpandedRegistrations {
+    expandedAtCallSites(helper: Node, method: string): boolean;
+}
 
 /**
  * Discover code units in `sourceFile` by running all patterns.
  * Deduplicates entries with the same function node and kind.
  */
-declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPattern[], resolution?: ResolutionStore, mountPrefixes?: MountPrefixIndex): DiscoveredUnit[];
+declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPattern[], resolution?: ResolutionStore, mountPrefixes?: MountPrefixIndex, expandedElsewhere?: ExpandedRegistrations): DiscoveredUnit[];
 
 interface TimingReport {
     totalMs: number;
@@ -887,28 +1000,12 @@ declare function findNearestTsconfig(startDir: string): string | null;
  */
 
 /**
- * A call the project has declared to be its own dispatcher.
- *
- * `receiver` is the type name 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.
+ * A call the project has declared to be its own dispatcher. The
+ * declaration a project config is parsed against lives with the other
+ * shared pack options, so this reader and the packs that take it under
+ * `producers` describe one shape.
  */
-interface ConfiguredCallSpec {
-    /** Module that declares the receiver's type. */
-    module: string;
-    /** Type name of the receiver, as exported from that module. */
-    receiver: string;
-    /** Method that performs the send. */
-    method: string;
-    /** Argument index carrying the subject. */
-    subjectArg: number;
-    /**
-     * Which argument the message body is. Left out when the method has no
-     * single body argument, as a batch method taking a list of entries
-     * does, and then no body is reported.
-     */
-    bodyArg?: number;
-}
+type ConfiguredCallSpec = z.infer<typeof configuredCallOption>;
 interface ConfiguredCallRead {
     /** The subject the call sends to, always a literal string. */
     subject: string;
@@ -962,6 +1059,45 @@ declare function readContract(unit: DiscoveredUnit, pattern: ContractPattern, fr
  */
 declare function readContractForClientCall(callExpression: Node, methodName: string, pattern: ContractPattern, framework: string, resolution?: ResolutionStore): ContractReadResult | null;
 
+/**
+ * helperIndex.ts: reading the project's own helpers once, before any
+ * file is walked.
+ *
+ * A pack that declares `projectHelpers` gets every helper the project
+ * wrote in front of its library, each read in terms of its own
+ * parameters, and gives back the patterns and recognizers it would
+ * otherwise have taken as config. Those join the pack for the rest of
+ * the run, so the match happens at the call site, where the arguments
+ * are literal.
+ *
+ * Built alongside the mount and wrapper indexes, over the same files.
+ * The discovery README has the ordering and the cost.
+ */
+
+interface ProjectHelperIndex {
+    /** Discovery patterns `packName` contributed after reading the project. */
+    patternsFor(packName: string): readonly DiscoveryPattern[];
+    /**
+     * Recognizers the packs contributed. They match calls to functions
+     * this project declares, so they run wherever a call can appear
+     * rather than only where the pack's own import gate reaches.
+     */
+    contributedRecognizers(): readonly InvocationRecognizer[];
+    /**
+     * The helper files that shaped what `file` extracts to, so the
+     * per-file cache invalidates `file` when one of them is edited.
+     */
+    helperFilesFor(file: SourceFile): readonly string[];
+    /**
+     * Whether a registration written inside `helper` with `method` is one
+     * the call sites already expand. Reading it here as well would give
+     * one registration two summaries, and which of the two a run kept
+     * would come down to the order the files were walked in.
+     */
+    expandedAtCallSites(helper: Node, method: string): boolean;
+}
+declare function buildProjectHelperIndex(sourceFiles: ReadonlyArray<SourceFile>, packs: ReadonlyArray<PatternPack>, packsByFile: ReadonlyMap<SourceFile, readonly PatternPack[]>, resolution: ResolutionStore): ProjectHelperIndex;
+
 /**
  * The one import scan.
  *
@@ -1027,32 +1163,6 @@ interface TsDiscoveryContext {
         func: FunctionRoot;
         isDefault: boolean;
     }>;
-    /**
-     * For an export the project builds by calling a factory, the string
-     * under a property of that call's config object:
-     * `export const handler = makeWidgetHandler({ subject: "a.b" }, ...)`
-     * with `{ property: "subject" }` gives back `"a.b"`.
-     *
-     * The caller does not have to say which function was called or which
-     * argument the config was in. Every object argument is read. Giving the
-     * callee or fixing the argument position narrows that down, for a
-     * project whose factories would otherwise collide.
-     *
-     * Two arguments with the property set to different values give back
-     * null, since nothing says which one was meant.
-     *
-     * The config argument is usually an object literal at the call site;
-     * a variable or import is followed to the literal it resolves to.
-     * `as const` and parentheses around the property value are peeled.
-     * Anything but a string literal underneath (a computed subject, a
-     * template, a call) gives back null, and the caller attaches nothing
-     * rather than guessing.
-     */
-    exportedCallConfigString(sourceFile: SourceFile, exportName: string, spec: {
-        callees?: string[];
-        argIndex?: number;
-        property: string;
-    }): string | null;
     /**
      * Walk a function's body for return statements whose value is a
      * JSX element / fragment / self-closing tag. Returns true on the
@@ -1339,7 +1449,7 @@ declare function collectClientFieldAccesses(callExpr: CallExpression, func: Node
 /**
  * Evidence for drafting a dependency stub: every call the project
  * makes into a named package, grouped by the export it reaches, with
- * the argument shapes observed at each call site. `suss stub draft`
+ * the argument shapes observed at each call site. `suss infer stub`
  * turns this into a stub skeleton for an author to fill in. The
  * package's own code is never read, only the project's calls into it,
  * so this works for packages whose source no adapter can parse.
@@ -1501,4 +1611,4 @@ declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     version?: string;
 }>): string;
 
-export { ADAPTER_VERSION, type Accessed, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExplainCallableOptions, type ExplainStats, type ExplainedResolution, type ExtractionReport, type FoundTerminal, type FunctionRoot, type HealthCheck, type HealthViolation, type ImportScanOptions, type ObservedStubCall, type PackFunnel, type PackGradient, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, type Timer, type TimingReport, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, type ValueLocation, type WhyExplained, WhySession, type WhySessionOptions, accessContextFor, callOpsFor, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, functionTargetOf, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isImportedFrom, methodDeclaredIn, namedImportsOf, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, stubEvidence, stubEvidenceIn, workspaceRootFor };
+export { ADAPTER_VERSION, type Accessed, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExplainCallableOptions, type ExplainStats, type ExplainedResolution, type ExtractionReport, type FoundTerminal, type FunctionRoot, type HealthCheck, type HealthViolation, type ImportScanOptions, type ObservedStubCall, type PackFunnel, type PackGradient, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, type Timer, type TimingReport, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, type ValueLocation, type WhyExplained, WhySession, type WhySessionOptions, accessContextFor, buildProjectHelperIndex, callOpsFor, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, functionTargetOf, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isImportedFrom, methodDeclaredIn, namedImportsOf, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, stubEvidence, stubEvidenceIn, workspaceRootFor };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, PropertyAccessExpression, TaggedTemplateExpression, Project, ImportDeclaration, Symbol, Expression, NewExpression, Identifier } from 'ts-morph';
-import { PackDeclarations, TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, EffectArg, CallOps, LanguageAdapter, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, RawDeclaredContract, ContractPattern, AstCapableOps, ResponsePropertyMapping } from '@suss/extractor';
+import { PackDeclarations, TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, EffectArg, CallOps, LanguageAdapter, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, configuredCallOption, RawDeclaredContract, ContractPattern, AstCapableOps, ResponsePropertyMapping } from '@suss/extractor';
 import { BehavioralSummary, MessageBusSemantics, DeployableUnit, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
+import { z } from 'zod';
 import { Proof, Atom } from '@suss/datalog';
 import { ResolutionExplanation } from '@suss/resolution';
 
@@ -140,6 +141,14 @@ interface PackFunnel {
      * while this is non-empty.
      */
     failures: PackFailure[];
+    /**
+     * Registration helpers this pack's config asked for that no call in
+     * the run matched. The helper belongs to the project, so a spelling
+     * that matches nothing is a config mistake with no other symptom: the
+     * routes go missing and every count reads the same as a project
+     * without them.
+     */
+    helpersUnmatched: string[];
     /**
      * What the pack wrote as data rather than as code, or null for a pack
      * written as a hand-rolled walk. This is the one thing in the funnel
@@ -247,6 +256,7 @@ declare class ResolutionStore {
     private readonly importedNames;
     private readonly writtenValues;
     private readonly importOrigins;
+    private readonly subjectConstructions;
     /**
      * A file's table depends only on its re-export closure, which
      * `collectExports` extracts whole before answering, so later
@@ -288,6 +298,36 @@ declare class ResolutionStore {
      * GraphQL document kept in a constant in another file.
      */
     resolveWrittenValue(value: Node): Node | null;
+    /**
+     * The construction behind a registration subject: the call or `new`
+     * this value is written as, kept only when its callee comes from
+     * `importModule` under `importName`. A value written as two
+     * different things comes back null, since keying a route on the
+     * wrong app is worse than not keying it.
+     */
+    subjectConstructionOf(value: Node, importModule: string, importName: string): Node | null;
+    /**
+     * How many constructions this value was written as, which is what
+     * `subjectConstructionOf` weighed before it declined. Ask it after
+     * that call, so the walk it needs has already been paid for.
+     */
+    subjectCandidateCountOf(value: Node, importModule: string, importName: string): number;
+    /**
+     * The single-answer policy over the written-value walk, then the
+     * origin check on the one candidate. A candidate failing the check
+     * is settled refusal rather than a reason to widen: its own file's
+     * import facts are already in, and more files only add candidates.
+     */
+    private lookupSubjectConstruction;
+    /**
+     * Whether the construction's callee was imported from this module
+     * under this name. A default import records its name as "default",
+     * and a pack declares a default export by the local name people
+     * give it, so "default" counts when the callee is spelled with the
+     * declared name.
+     */
+    private constructionComesFrom;
+    private calleeNameOf;
     /**
      * Which names from `modules` this value comes down to, either by being
      * one of them under a local name or by calling into one. Getting
@@ -355,6 +395,15 @@ declare class ResolutionStore {
      * construction makes an instance of. The README says why.
      */
     private lookupWritten;
+    /**
+     * Read these files' facts now, before anything asks a question.
+     *
+     * A query widens along the imports of the file it starts in, which
+     * is where a value's definition is. What a caller passed is the other
+     * direction, so a question about a parameter is answered only by
+     * files the walk never reaches on its own.
+     */
+    extractFiles(sourceFiles: Iterable<SourceFile>): void;
     /**
      * Which of these files reach any of these packages, following
      * project-local re-export chains. A barrel package that re-exports an
@@ -405,6 +454,44 @@ type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | M
  */
 declare function collectAncestorBranches(terminalNode: Node, functionRoot: FunctionRoot): RawCondition[];
 
+/**
+ * unfollowedCall.ts: naming the calls the reachable closure stops at.
+ *
+ * The closure follows a call by resolving its callee to a function with a
+ * body. When that fails the edge is dropped, and a unit whose body is full
+ * of dropped edges produces the same empty summary as a unit that does
+ * nothing. This module says which kind of stop a call site is, and which
+ * kinds are worth leaving a gap for.
+ *
+ * The README beside this file explains where that line is drawn, and why
+ * a call into a dependency stays on the other side of it.
+ */
+
+/**
+ * Why the walk stopped.
+ *
+ * `noBody` states a shape and nothing else: a method on an interface, an
+ * abstract method, an ambient declaration. `unsettledValue` is declared
+ * as something other than a function, with something in it that could
+ * not be read. `multipleSources` reaches two different functions, so no
+ * single body can be followed. `outsideRun` is a declaration in a
+ * dependency, whose source this run never read. `noDeclaration` is a
+ * callee nothing declares, which is what a call on an untyped value
+ * comes to. `callerSupplied` is a parameter of the function being
+ * scanned, so the call runs whatever its caller handed in.
+ * `multipleReceivers` is a registration whose receiver comes down to
+ * more than one thing, so nothing says which one it registers on.
+ */
+type UnfollowedReason = "noBody" | "unsettledValue" | "multipleSources" | "outsideRun" | "noDeclaration" | "callerSupplied" | "multipleReceivers";
+/** One call the walk met and could not follow. */
+interface UnfollowedCall {
+    /** The callee as the source writes it, `this.dao.getEditions` say. */
+    readonly callee: string;
+    readonly reason: UnfollowedReason;
+    /** How many things the walk reached where it needed one. */
+    readonly candidates?: number;
+}
+
 interface ClientCallSite {
     callExpression: CallExpression;
     /** Method name on the client object (e.g. "getUser"), null for bare calls like fetch() */
@@ -556,6 +643,19 @@ interface DiscoveredUnit {
         /** Null when the pack knows the wire but not the channel on it. */
         channel: string | null;
     };
+    /**
+     * Populated by a pack's `discoverUnits` callback for a deployed unit
+     * nothing else routes to, which is reached by being invoked by name.
+     * The adapter builds a `unit-invocation` binding from it, which pairs
+     * with the calls that name the same unit.
+     */
+    invocationInfo?: DeployableUnit;
+    /**
+     * Identity of the routable this unit was registered on, when a
+     * registration call put it there. What the wrapper index is keyed on,
+     * since a wrapper is registered on the routable and not on the unit.
+     */
+    registrationSubjectId?: string;
     /** The thing that gets deployed and runs this unit, when known. */
     deployableUnit?: DeployableUnit;
     /**
@@ -573,6 +673,12 @@ interface DiscoveredUnit {
      * summary as an `unreadOutcome` gap.
      */
     unreadBinding?: string;
+    /**
+     * A call the handler met and could not follow, which reaches the
+     * summary as an `unfollowedCall` gap beside the ones the closure
+     * walk records.
+     */
+    unfollowed?: UnfollowedCall;
 }
 
 /**
@@ -597,12 +703,19 @@ interface MountPrefixIndex {
      */
     prefixForId?(childId: string): string;
 }
+/**
+ * What the project helper index says it has already expanded, which the
+ * walk consults so one registration does not become two summaries.
+ */
+interface ExpandedRegistrations {
+    expandedAtCallSites(helper: Node, method: string): boolean;
+}
 
 /**
  * Discover code units in `sourceFile` by running all patterns.
  * Deduplicates entries with the same function node and kind.
  */
-declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPattern[], resolution?: ResolutionStore, mountPrefixes?: MountPrefixIndex): DiscoveredUnit[];
+declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPattern[], resolution?: ResolutionStore, mountPrefixes?: MountPrefixIndex, expandedElsewhere?: ExpandedRegistrations): DiscoveredUnit[];
 
 interface TimingReport {
     totalMs: number;
@@ -887,28 +1000,12 @@ declare function findNearestTsconfig(startDir: string): string | null;
  */
 
 /**
- * A call the project has declared to be its own dispatcher.
- *
- * `receiver` is the type name 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.
+ * A call the project has declared to be its own dispatcher. The
+ * declaration a project config is parsed against lives with the other
+ * shared pack options, so this reader and the packs that take it under
+ * `producers` describe one shape.
  */
-interface ConfiguredCallSpec {
-    /** Module that declares the receiver's type. */
-    module: string;
-    /** Type name of the receiver, as exported from that module. */
-    receiver: string;
-    /** Method that performs the send. */
-    method: string;
-    /** Argument index carrying the subject. */
-    subjectArg: number;
-    /**
-     * Which argument the message body is. Left out when the method has no
-     * single body argument, as a batch method taking a list of entries
-     * does, and then no body is reported.
-     */
-    bodyArg?: number;
-}
+type ConfiguredCallSpec = z.infer<typeof configuredCallOption>;
 interface ConfiguredCallRead {
     /** The subject the call sends to, always a literal string. */
     subject: string;
@@ -962,6 +1059,45 @@ declare function readContract(unit: DiscoveredUnit, pattern: ContractPattern, fr
  */
 declare function readContractForClientCall(callExpression: Node, methodName: string, pattern: ContractPattern, framework: string, resolution?: ResolutionStore): ContractReadResult | null;
 
+/**
+ * helperIndex.ts: reading the project's own helpers once, before any
+ * file is walked.
+ *
+ * A pack that declares `projectHelpers` gets every helper the project
+ * wrote in front of its library, each read in terms of its own
+ * parameters, and gives back the patterns and recognizers it would
+ * otherwise have taken as config. Those join the pack for the rest of
+ * the run, so the match happens at the call site, where the arguments
+ * are literal.
+ *
+ * Built alongside the mount and wrapper indexes, over the same files.
+ * The discovery README has the ordering and the cost.
+ */
+
+interface ProjectHelperIndex {
+    /** Discovery patterns `packName` contributed after reading the project. */
+    patternsFor(packName: string): readonly DiscoveryPattern[];
+    /**
+     * Recognizers the packs contributed. They match calls to functions
+     * this project declares, so they run wherever a call can appear
+     * rather than only where the pack's own import gate reaches.
+     */
+    contributedRecognizers(): readonly InvocationRecognizer[];
+    /**
+     * The helper files that shaped what `file` extracts to, so the
+     * per-file cache invalidates `file` when one of them is edited.
+     */
+    helperFilesFor(file: SourceFile): readonly string[];
+    /**
+     * Whether a registration written inside `helper` with `method` is one
+     * the call sites already expand. Reading it here as well would give
+     * one registration two summaries, and which of the two a run kept
+     * would come down to the order the files were walked in.
+     */
+    expandedAtCallSites(helper: Node, method: string): boolean;
+}
+declare function buildProjectHelperIndex(sourceFiles: ReadonlyArray<SourceFile>, packs: ReadonlyArray<PatternPack>, packsByFile: ReadonlyMap<SourceFile, readonly PatternPack[]>, resolution: ResolutionStore): ProjectHelperIndex;
+
 /**
  * The one import scan.
  *
@@ -1027,32 +1163,6 @@ interface TsDiscoveryContext {
         func: FunctionRoot;
         isDefault: boolean;
     }>;
-    /**
-     * For an export the project builds by calling a factory, the string
-     * under a property of that call's config object:
-     * `export const handler = makeWidgetHandler({ subject: "a.b" }, ...)`
-     * with `{ property: "subject" }` gives back `"a.b"`.
-     *
-     * The caller does not have to say which function was called or which
-     * argument the config was in. Every object argument is read. Giving the
-     * callee or fixing the argument position narrows that down, for a
-     * project whose factories would otherwise collide.
-     *
-     * Two arguments with the property set to different values give back
-     * null, since nothing says which one was meant.
-     *
-     * The config argument is usually an object literal at the call site;
-     * a variable or import is followed to the literal it resolves to.
-     * `as const` and parentheses around the property value are peeled.
-     * Anything but a string literal underneath (a computed subject, a
-     * template, a call) gives back null, and the caller attaches nothing
-     * rather than guessing.
-     */
-    exportedCallConfigString(sourceFile: SourceFile, exportName: string, spec: {
-        callees?: string[];
-        argIndex?: number;
-        property: string;
-    }): string | null;
     /**
      * Walk a function's body for return statements whose value is a
      * JSX element / fragment / self-closing tag. Returns true on the
@@ -1339,7 +1449,7 @@ declare function collectClientFieldAccesses(callExpr: CallExpression, func: Node
 /**
  * Evidence for drafting a dependency stub: every call the project
  * makes into a named package, grouped by the export it reaches, with
- * the argument shapes observed at each call site. `suss stub draft`
+ * the argument shapes observed at each call site. `suss infer stub`
  * turns this into a stub skeleton for an author to fill in. The
  * package's own code is never read, only the project's calls into it,
  * so this works for packages whose source no adapter can parse.
@@ -1501,4 +1611,4 @@ declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     version?: string;
 }>): string;
 
-export { ADAPTER_VERSION, type Accessed, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExplainCallableOptions, type ExplainStats, type ExplainedResolution, type ExtractionReport, type FoundTerminal, type FunctionRoot, type HealthCheck, type HealthViolation, type ImportScanOptions, type ObservedStubCall, type PackFunnel, type PackGradient, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, type Timer, type TimingReport, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, type ValueLocation, type WhyExplained, WhySession, type WhySessionOptions, accessContextFor, callOpsFor, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, functionTargetOf, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isImportedFrom, methodDeclaredIn, namedImportsOf, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, stubEvidence, stubEvidenceIn, workspaceRootFor };
+export { ADAPTER_VERSION, type Accessed, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExplainCallableOptions, type ExplainStats, type ExplainedResolution, type ExtractionReport, type FoundTerminal, type FunctionRoot, type HealthCheck, type HealthViolation, type ImportScanOptions, type ObservedStubCall, type PackFunnel, type PackGradient, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, type Timer, type TimingReport, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, type ValueLocation, type WhyExplained, WhySession, type WhySessionOptions, accessContextFor, buildProjectHelperIndex, callOpsFor, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, functionTargetOf, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isImportedFrom, methodDeclaredIn, namedImportsOf, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, stubEvidence, stubEvidenceIn, workspaceRootFor };