@suss/adapter-typescript 0.18.0 → 0.20.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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, RawDeclaredContract, ContractPattern, AstCapableOps, ResponsePropertyMapping } from '@suss/extractor';
 import { BehavioralSummary, MessageBusSemantics, DeployableUnit, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
 import { Proof, Atom } from '@suss/datalog';
 import { ResolutionExplanation } from '@suss/resolution';
@@ -171,6 +171,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 +245,14 @@ declare class ResolutionStore {
     private readonly fullyExtracted;
     private readonly seededValues;
     private readonly importedNames;
+    private readonly writtenValues;
+    private readonly importOrigins;
+    /**
+     * 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;
@@ -280,6 +295,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
@@ -316,6 +361,24 @@ declare class ResolutionStore {
      * 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
@@ -464,6 +527,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
@@ -560,6 +628,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 +764,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 +828,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 +857,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.
@@ -763,7 +952,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 +960,51 @@ 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;
+
+/**
+ * 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
@@ -899,14 +1132,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 +1261,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 +1336,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 stub draft`
+ * 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 +1501,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, 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 };