@suss/adapter-typescript 0.19.0 → 0.21.0

package/dist/index.d.cts

@@ -1,6 +1,7 @@
-import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, Project, Symbol, Expression, NewExpression, TaggedTemplateExpression, PropertyAccessExpression } from 'ts-morph';
-import { PackDeclarations, TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, LanguageAdapter, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, EffectArg, RawDeclaredContract, ContractPattern, AstCapableOps, CallOps, ResponsePropertyMapping } from '@suss/extractor';
+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, 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
@@ -171,6 +180,13 @@ interface ExtractionReport {
      * nothing. Null when the run produced summaries.
      */
     emptyStage: EmptyStage | null;
+    /**
+     * Reassigned names the run stated nothing for, because control flow
+     * decides which write a reader sees. Each is a value resolution the
+     * facts decline; the count across a large corpus says whether scoped
+     * reaching definitions is worth writing.
+     */
+    reassignedNamesUnstated: number;
 }
 type EmptyStage = "tsconfig" | "gateResolution" | "candidateFiles" | "discovery" | "assembly";
 /**
@@ -238,6 +254,15 @@ declare class ResolutionStore {
     private readonly fullyExtracted;
     private readonly seededValues;
     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
+     * extraction elsewhere cannot change an entry.
+     */
+    private readonly exportTables;
     /** Files the most recent wave walk entered, for the memo to keep. */
     private lastQueryWalked;
     private readonly declarations;
@@ -273,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
@@ -280,6 +335,36 @@ declare class ResolutionStore {
      * decorators.
      */
     importedNamesOf(value: Node, modules: string[]): string[];
+    /**
+     * Which module export this value comes down to, with what made it
+     * included: a value written as `createClient()` is made from the
+     * module exporting `createClient`, and a member destructured off
+     * that result is one path segment further. The module half is the
+     * specifier as the source wrote it, so a subpath import keeps its
+     * subpath.
+     */
+    importOriginsOf(value: Node, modules: string[]): Array<{
+        module: string;
+        path: string[];
+    }>;
+    /**
+     * The batched form: one demand set, one derivation, one widening
+     * walk shared by every value. A discovery pass asks about every
+     * callee in a file, and per-value queries would re-pay demand
+     * clearing and re-derivation once per call site.
+     */
+    importOriginsOfMany(values: readonly Node[], modules: string[]): Map<Node, Array<{
+        module: string;
+        path: string[];
+    }>>;
+    /**
+     * The node a memo shares across references: a plain name's
+     * declaration, so a hundred call sites of one import pay one walk.
+     * Anything else keys as itself, since `a.foo` and `b.foo` share a
+     * declared `foo` without sharing a value.
+     */
+    private sharedDeclarationFor;
+    private lookupImportOrigins;
     /**
      * Null tells the walk to keep widening. A value that landed in a
      * package returns empty instead, because a library's own body is not
@@ -310,12 +395,39 @@ 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
      * SDK defeats a per-file import check and does not defeat this.
      */
     filesImportingTransitively(fileSets: ReadonlyArray<FileSetQuery>): ReadonlyArray<ReadonlySet<SourceFile>>;
+    /**
+     * The calls behind a receiver that `matches` accepts, walked out in
+     * waves the way every question is. The wave ends as soon as one file
+     * yields a match, and the caller applies the single-answer policy to
+     * the set; the resolution README's anchor section says why the rules
+     * cannot rank a nearer call above a farther one.
+     */
+    anchorCallsOf(value: Node, matches: (call: Node) => boolean): Node[];
+    /**
+     * Every name a module exports and the values behind each, with
+     * re-export chains flattened by the rules. The frontier follows
+     * re-export targets only, so a barrel of barrels extracts its own
+     * chain and nothing beside it, to any depth.
+     */
+    exportsOf(sourceFile: SourceFile): Map<string, Node[]>;
+    private collectExports;
+    /** Module keys this file re-exports from, read off its own facts. */
+    private reExportTargetsOf;
     /**
      * Null keeps the wave walk widening; any candidate at all ends it,
      * since more files can only add candidates, never take one away. The
@@ -342,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() */
@@ -464,6 +614,11 @@ interface DiscoveredUnit {
         packageName: string;
         exportPath: string[];
     };
+    /** A callable identity the pack stated: module and export name. */
+    functionCallInfo?: {
+        module: string;
+        exportName: string;
+    };
     /**
      * Populated by `decoratedRoute` discovery (NestJS-style REST
      * controllers). The adapter uses it to build a `rest` binding
@@ -488,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;
     /**
@@ -505,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;
 }
 
 /**
@@ -529,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;
@@ -560,6 +741,127 @@ interface Timer {
  */
 type DescentBarriers = ReadonlySet<Node>;
 
+/**
+ * Context handed to TypeScript-adapter access recognizers: sister
+ * to TsInvocationRecognizerContext but for property-access nodes.
+ * No `extractArgs` since property accesses don't take arguments.
+ */
+interface TsAccessRecognizerContext {
+    /** The property-access expression itself. */
+    access: Node;
+    /** Source file the access lives in. */
+    sourceFile: SourceFile;
+    /**
+     * One-hop lookup from a written name to the value it was bound to,
+     * from the run's facts (#300). Gives null when the run has no store,
+     * and the recognizer's own pattern match runs on the raw node.
+     */
+    resolveWrittenValue: (value: Node) => Node | null;
+    /**
+     * What a declared pack asks about this node, when the node is a call
+     * or a tagged template. This walk visits property accesses as well,
+     * and there is no call there to ask about, so a declared pack
+     * standing on one is handed nothing and matches nothing.
+     */
+    ops?: CallOps;
+}
+/**
+ * Context handed to TypeScript-adapter recognizers. Recognizers in
+ * `@suss/framework-prisma` (and other packs) receive this and use
+ * the type-checker / source-file primitives to decide whether the
+ * call site matches their semantics. `extractArgs` reuses the same
+ * `EffectArg` builder the adapter uses for `invocation` effects, so
+ * recognizers don't have to re-implement literal/object/identifier
+ * shape extraction.
+ */
+interface TsInvocationRecognizerContext {
+    /** The call expression itself (also passed as the first arg). */
+    call: CallExpression;
+    /** Source file the call lives in. Useful for import resolution. */
+    sourceFile: SourceFile;
+    /**
+     * Convert the call's arguments to `EffectArg[]` using the same
+     * literal / object / identifier extraction the adapter applies to
+     * `invocation` effects. Recognizers call this when they want
+     * field-level shape (e.g. Prisma's `select: { id: true }`).
+     */
+    extractArgs(): EffectArg[];
+    /**
+     * Whether `identifier` was introduced by an import of
+     * `expectedModule`. Recognizers use this to tell a library's export
+     * apart from a local class that happens to share its name.
+     *
+     * Named, default, and namespace imports all match. So does an import
+     * through a project-local barrel that re-exports the module: the
+     * aliased symbol is still in the package that declared it.
+     */
+    isImportedFrom(identifier: Node, expectedModule: string): boolean;
+    /**
+     * The expression `value` is written as, followed through const
+     * bindings, imports, and re-export barrels. A recognizer asks this
+     * before claiming the source does not name something:
+     *
+     *   const url = "https://sqs/.../orders";
+     *   client.send(new SendMessageCommand({ QueueUrl: url }));
+     *
+     * Resolving `url` gives back the string literal, and the recognizer's
+     * own pattern match runs on that. Null when the value has no written
+     * form (a parameter, a call result), which is exactly when null on the
+     * binding is correct.
+     */
+    resolveWrittenValue(value: Node): Node | null;
+    /**
+     * What a declared pack asks about this call, in the vocabulary
+     * `@suss/extractor` defines. A pack written as a chain of data links
+     * reads only this; the members above are what a pack written as code
+     * reaches for.
+     */
+    ops: CallOps;
+}
+/**
+ * Everything a recognizer may ask about one call site.
+ *
+ * A pack's tests build it here too, so a pack that passes them has run
+ * against the context extraction gives it.
+ */
+declare function invocationContextFor(call: CallExpression, resolveWrittenValue?: (value: Node) => Node | null, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf): TsInvocationRecognizerContext;
+/**
+ * Whether a value's chain reaches the module, asked of the store. The
+ * adapter binds it; a context built bare falls back to the checker's
+ * alias resolution.
+ */
+type OriginatesFrom = (value: Node, module: string) => boolean;
+/** The calls behind a value that a caller's own check accepts, from the store. */
+type AnchorCallsOf = (value: Node, matches: (call: Node) => boolean) => Node[];
+declare function isImportedFrom(identifier: Node, expectedModule: string, originatesFrom?: OriginatesFrom): boolean;
+/**
+ * Whether `expectedModule` declares the method a call goes to. A pack
+ * asks this when the receiver came from somewhere the source does not
+ * spell out: `const redis = await this.getClient()` says nothing about
+ * ioredis, and the type of `redis.get` says everything.
+ *
+ * A client cached on an untyped global, `global.x || new Redis()`,
+ * types as `any`, so the method has no symbol. With `resolve` supplied,
+ * what the receiver was written as still says which library: the value
+ * comes down to a construction or a factory call of something imported
+ * from it.
+ */
+declare function methodDeclaredIn(callee: Node, expectedModule: string, resolve?: (value: Node) => Node | null, originatesFrom?: OriginatesFrom): boolean;
+/** The nodes this walk stops at, which is every shape a pack can guard. */
+type Accessed = PropertyAccessExpression | CallExpression | TaggedTemplateExpression;
+/**
+ * What one node is handed. The ops are built on the first read rather
+ * than up front, the way the invocation walk builds them: most nodes
+ * reach no declared pack, and a pack written as code never asks.
+ *
+ * A pack's tests build it here too, so a pack that passes them has run
+ * against the context extraction gives it.
+ */
+declare function accessContextFor(node: Accessed, sourceFile: SourceFile, resolveWrittenValue?: (value: Node) => Node | null, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf): TsAccessRecognizerContext;
+
+/** Resolves a helper callee to its declaration; the adapter binds the store's ask. */
+type ResolveCallee = (callee: Node) => Node | null;
+
 /**
  * The whole extraction, from a tsconfig to a set of behavioral
  * summaries. `createTypeScriptAdapter` is what a caller uses;
@@ -575,7 +877,7 @@ type DescentBarriers = ReadonlySet<Node>;
  * framework or a runtime belongs to a pack.
  */
 
-declare function extractCodeStructure(unit: DiscoveredUnit, pack: PatternPack, invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers, resolveWrittenValue?: (value: Node) => Node | null): RawCodeStructure;
+declare function extractCodeStructure(unit: DiscoveredUnit, pack: PatternPack, invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers, resolveWrittenValue?: (value: Node) => Node | null, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf, resolveCallee?: ResolveCallee): RawCodeStructure;
 interface TypeScriptAdapterConfig {
     tsConfigFilePath?: string;
     /**
@@ -639,7 +941,7 @@ interface FoundTerminal {
  * discovered. Inside a nested function only escaping terminals are
  * matched: see `NESTED_ESCAPING_MATCH_TYPES`.
  */
-declare function findTerminals(func: FunctionRoot, patterns: TerminalPattern[], barriers?: DescentBarriers, resolveWrittenValue?: (value: Node) => Node | null): FoundTerminal[];
+declare function findTerminals(func: FunctionRoot, patterns: TerminalPattern[], barriers?: DescentBarriers, resolveWrittenValue?: (value: Node) => Node | null, originatesFrom?: OriginatesFrom, resolveCallee?: ResolveCallee): FoundTerminal[];
 
 /**
  * Turns one function into the list of branches a summary is built from.
@@ -668,7 +970,7 @@ interface RawBranchResult {
  * or when every condition on it came from an early return or throw,
  * since those are the paths that run when no guard fired.
  */
-declare function extractRawBranches(func: FunctionRoot, terminalPatterns: TerminalPattern[], invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers, resolveWrittenValue?: (value: Node) => Node | null): RawBranchResult;
+declare function extractRawBranches(func: FunctionRoot, terminalPatterns: TerminalPattern[], invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers, resolveWrittenValue?: (value: Node) => Node | null, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf, resolveCallee?: ResolveCallee): RawBranchResult;
 
 /**
  * A Project covering `rootDir`, for a codebase with no tsconfig to read.
@@ -698,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;
@@ -763,7 +1049,7 @@ interface ContractReadResult {
  * Returns null if the handler wasn't registered with a contract or the contract
  * can't be resolved.
  */
-declare function readContract(unit: DiscoveredUnit, pattern: ContractPattern, framework: string): ContractReadResult | null;
+declare function readContract(unit: DiscoveredUnit, pattern: ContractPattern, framework: string, resolution?: ResolutionStore): ContractReadResult | null;
 /**
  * Resolve the contract for a consumer call site.
  *
@@ -771,7 +1057,90 @@ declare function readContract(unit: DiscoveredUnit, pattern: ContractPattern, fr
  * call to find the contract, then extracts the endpoint definition for the
  * matched method name (e.g. "getUser").
  */
-declare function readContractForClientCall(callExpression: Node, methodName: string, pattern: ContractPattern, framework: string): ContractReadResult | null;
+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.
+ *
+ * Fifteen copies of "which names did this file import from module X"
+ * grew across discovery handlers and packs, and two of them disagreed
+ * about aliases (#674). Every question about a file's imports of a
+ * module is asked here: which declarations name it, what the named
+ * imports are called locally, and which local spellings the default
+ * and namespace imports go by. Matching semantics are explicit
+ * options, so a caller that accepts subpath specifiers or resolves
+ * path-shaped specifiers through the store says so, and one that
+ * matches the specifier verbatim stays verbatim.
+ */
+
+interface ImportScanOptions {
+    /**
+     * Accept `module/subpath` specifiers beside the exact module, the
+     * way `react-dom/client` is still react-dom's surface.
+     */
+    subpaths?: boolean;
+    /** Resolve path-shaped specifiers through the store's module graph. */
+    resolution?: ResolutionStore;
+}
+/** One named import: how the file spells it, and what it is. */
+interface NamedImport {
+    /** The spelling this file binds, the alias when there is one. */
+    local: string;
+    /** The name the module exports it as. */
+    canonical: string;
+    /** The specifier as written, for a caller that reads sub-paths. */
+    specifier: string;
+}
+/** Every named import of these modules, aliases resolved. */
+declare function namedImportsOf(sourceFile: SourceFile, modules: readonly string[], options?: ImportScanOptions): NamedImport[];
+/**
+ * Local spelling to canonical exported name, for every named import
+ * of these modules. `import { Get as HttpGet }` yields HttpGet -> Get.
+ */
+declare function importedNamesOf(sourceFile: SourceFile, modules: readonly string[], options?: ImportScanOptions): Map<string, string>;
+/** The local spellings of default and namespace imports of these modules. */
+declare function importedRootsOf(sourceFile: SourceFile, modules: readonly string[], options?: ImportScanOptions): Set<string>;
+/** Every import declaration in the file that names one of `modules`. */
+declare function importDeclarationsOf(sourceFile: SourceFile, modules: readonly string[], options?: ImportScanOptions): ImportDeclaration[];
 
 interface TsDiscoveryContext {
     /** Full filesystem path of the source file. Useful for excluding
@@ -794,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
@@ -899,14 +1242,11 @@ declare class WhySession {
     private displayPath;
 }
 
-type ExportedDeclarationMap = ReturnType<SourceFile["getExportedDeclarations"]>;
 /**
- * What a module exports, by exported name. Cached, because ts-morph
- * rebuilds the map from scratch on every `getExportedDeclarations` call
- * and callee resolution asks the same file the same thing once per
- * import site.
+ * What a module exports, by exported name. The store's rules flatten
+ * re-export chains of any length, and the store memoizes per file.
  */
-declare function exportedDeclarationsOf(sourceFile: SourceFile): ExportedDeclarationMap;
+declare function exportedDeclarationsOf(sourceFile: SourceFile, resolution: ResolutionStore): Map<string, Node[]>;
 /**
  * `Symbol.getAliasedSymbol`, with the re-export chains warmed first so
  * that an import sitting at the top of a deep chain still resolves
@@ -1031,117 +1371,31 @@ type Called = CallExpression | NewExpression | TaggedTemplateExpression;
 /** One-hop lookup from a written name to the value it was bound to. */
 type Resolve = (value: Node) => Node | null;
 /** What a declared pack can ask about one TypeScript call. */
-declare function callOpsFor(call: Called, resolveWrittenValue?: Resolve): AstCapableOps;
+declare function callOpsFor(call: Called, resolveWrittenValue?: Resolve, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf): AstCapableOps;
 
 /**
- * Context handed to TypeScript-adapter access recognizers: sister
- * to TsInvocationRecognizerContext but for property-access nodes.
- * No `extractArgs` since property accesses don't take arguments.
- */
-interface TsAccessRecognizerContext {
-    /** The property-access expression itself. */
-    access: Node;
-    /** Source file the access lives in. */
-    sourceFile: SourceFile;
-    /**
-     * One-hop lookup from a written name to the value it was bound to,
-     * from the run's facts (#300). Gives null when the run has no store,
-     * and the recognizer's own pattern match runs on the raw node.
-     */
-    resolveWrittenValue: (value: Node) => Node | null;
-    /**
-     * What a declared pack asks about this node, when the node is a call
-     * or a tagged template. This walk visits property accesses as well,
-     * and there is no call there to ask about, so a declared pack
-     * standing on one is handed nothing and matches nothing.
-     */
-    ops?: CallOps;
-}
-/**
- * Context handed to TypeScript-adapter recognizers. Recognizers in
- * `@suss/framework-prisma` (and other packs) receive this and use
- * the type-checker / source-file primitives to decide whether the
- * call site matches their semantics. `extractArgs` reuses the same
- * `EffectArg` builder the adapter uses for `invocation` effects, so
- * recognizers don't have to re-implement literal/object/identifier
- * shape extraction.
- */
-interface TsInvocationRecognizerContext {
-    /** The call expression itself (also passed as the first arg). */
-    call: CallExpression;
-    /** Source file the call lives in. Useful for import resolution. */
-    sourceFile: SourceFile;
-    /**
-     * Convert the call's arguments to `EffectArg[]` using the same
-     * literal / object / identifier extraction the adapter applies to
-     * `invocation` effects. Recognizers call this when they want
-     * field-level shape (e.g. Prisma's `select: { id: true }`).
-     */
-    extractArgs(): EffectArg[];
-    /**
-     * Whether `identifier` was introduced by an import of
-     * `expectedModule`. Recognizers use this to tell a library's export
-     * apart from a local class that happens to share its name.
-     *
-     * Named, default, and namespace imports all match. So does an import
-     * through a project-local barrel that re-exports the module: the
-     * aliased symbol is still in the package that declared it.
-     */
-    isImportedFrom(identifier: Node, expectedModule: string): boolean;
-    /**
-     * The expression `value` is written as, followed through const
-     * bindings, imports, and re-export barrels. A recognizer asks this
-     * before claiming the source does not name something:
-     *
-     *   const url = "https://sqs/.../orders";
-     *   client.send(new SendMessageCommand({ QueueUrl: url }));
-     *
-     * Resolving `url` gives back the string literal, and the recognizer's
-     * own pattern match runs on that. Null when the value has no written
-     * form (a parameter, a call result), which is exactly when null on the
-     * binding is correct.
-     */
-    resolveWrittenValue(value: Node): Node | null;
-    /**
-     * What a declared pack asks about this call, in the vocabulary
-     * `@suss/extractor` defines. A pack written as a chain of data links
-     * reads only this; the members above are what a pack written as code
-     * reaches for.
-     */
-    ops: CallOps;
-}
-/**
- * Everything a recognizer may ask about one call site.
+ * The one resolver from a reference to the function behind it.
  *
- * A pack's tests build it here too, so a pack that passes them has run
- * against the context extraction gives it.
+ * Four copies of "follow an identifier to its function declaration"
+ * grew across the closure, the render-tree builder, the react pack,
+ * and the parameter-read walk, three of them lossy (#674). The walk
+ * lives here: alias-following through imports, shorthand properties
+ * resolved to the binding they read, overload signatures routed to
+ * the declaration with the body, and external code refused. Callers
+ * that need only the file and name take `functionTargetOf`; the
+ * closure takes `resolveDecl` for the function root itself.
  */
-declare function invocationContextFor(call: CallExpression, resolveWrittenValue?: (value: Node) => Node | null): TsInvocationRecognizerContext;
-declare function isImportedFrom(identifier: Node, expectedModule: string): boolean;
-/**
- * Whether `expectedModule` declares the method a call goes to. A pack
- * asks this when the receiver came from somewhere the source does not
- * spell out: `const redis = await this.getClient()` says nothing about
- * ioredis, and the type of `redis.get` says everything.
- *
- * A client cached on an untyped global, `global.x || new Redis()`,
- * types as `any`, so the method has no symbol. With `resolve` supplied,
- * what the receiver was written as still says which library: the value
- * comes down to a construction or a factory call of something imported
- * from it.
- */
-declare function methodDeclaredIn(callee: Node, expectedModule: string, resolve?: (value: Node) => Node | null): boolean;
-/** The nodes this walk stops at, which is every shape a pack can guard. */
-type Accessed = PropertyAccessExpression | CallExpression | TaggedTemplateExpression;
+
 /**
- * What one node is handed. The ops are built on the first read rather
- * than up front, the way the invocation walk builds them: most nodes
- * reach no declared pack, and a pack written as code never asks.
- *
- * A pack's tests build it here too, so a pack that passes them has run
- * against the context extraction gives it.
+ * The function an identifier refers to, as its declaration's file and
+ * name, for joins that never walk the body. Null when the reference
+ * does not land on a project function.
  */
-declare function accessContextFor(node: Accessed, sourceFile: SourceFile, resolveWrittenValue?: (value: Node) => Node | null): TsAccessRecognizerContext;
+declare function functionTargetOf(node: Identifier): {
+    func: FunctionRoot;
+    file: string;
+    name: string;
+} | null;
 
 /**
  * What a name-valued expression says, as fixed text with a hole for
@@ -1192,6 +1446,33 @@ declare function collectClientFieldAccesses(callExpr: CallExpression, func: Node
     end: number;
 }>, responseSemantics?: ResponsePropertyMapping[]): BranchFieldAccesses[];
 
+/**
+ * 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 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.
+ */
+
+interface ObservedStubCall {
+    readonly file: string;
+    readonly line: number;
+    readonly args: EffectArg[];
+}
+interface StubCallEvidence {
+    readonly exportPath: string[];
+    readonly calls: ObservedStubCall[];
+}
+declare function stubEvidenceIn(project: Project, packageName: string, root: string): StubCallEvidence[];
+interface StubEvidenceOptions {
+    packageName: string;
+    tsConfigFilePath?: string;
+    /** Read when no tsconfig is given. */
+    directory?: string;
+}
+declare function stubEvidence(options: StubEvidenceOptions): StubCallEvidence[];
+
 /**
  * Resolve a ts-morph Expression node to a structured ValueRef.
  * Uses only expr.getSymbol()?.getDeclarations()[0] for symbol lookup ,
@@ -1330,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 PackFunnel, type PackGradient, type ReadNameOptions, ResolutionStore, 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, invocationContextFor, isImportedFrom, methodDeclaredIn, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, 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 };