@suss/adapter-typescript 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -1,18 +1,44 @@
 import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, Project, Symbol, Expression } from 'ts-morph';
 import { TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, LanguageAdapter, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, EffectArg, RawDeclaredContract, ContractPattern, 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';
+
+/**
+ * cache.ts: the on-disk extraction cache.
+ *
+ * A run reuses the previous one's summaries whole when nothing
+ * changed, and per file when some files did. The entry directory is
+ * named after everything that has to agree before any reuse is sound:
+ * schema version, adapter version and code hash, pack versions, the
+ * extraction config stamp and the tsconfig path. Inside it, the
+ * manifest records a stamp and content hash per file, each summary's
+ * owning files, and per owning file the other files its walk read, so
+ * a change to any of those re-extracts the owner instead of serving a
+ * stale answer. The full design, including what per-file reuse can
+ * and cannot promise, is in this package's README.
+ */
 
 /** Reported by `lookup`: what the cache decided, and why. */
 interface CacheDiagnostic {
-    kind: "hit" | "miss";
+    kind: "hit" | "miss" | "partial";
     /**
      * Reason the lookup missed (only set when kind === "miss").
-     * `key-changed` means the cache directory holds entries, but none
+     * `key-changed` means the cache directory contains entries, but none
      * under this run's schema, adapter, packs and tsconfig path.
      * `files-changed` means the include set is not the one the entry
      * was written from.
      */
     missReason?: "no-manifest" | "key-changed" | "tsconfig-changed" | "files-changed";
+    /** Set when kind === "partial". */
+    partial?: {
+        filesChanged: number;
+        filesRemoved: number;
+        rootsReused: number;
+        rootsReextracted: number;
+        rootsDeclined: number;
+        summariesReused: number;
+    };
 }
 /**
  * Result of a cache lookup. A hit gives back the whole summary set; a miss
@@ -174,12 +200,36 @@ interface FileSetQuery {
  * edges a query follows, so cost tracks how indirect the code is.
  */
 
+interface ExplainCallableOptions {
+    /** A second file to walk out from; see `resolveCallable`. */
+    alsoFrom?: SourceFile;
+    /** How many derived nodes deep the proof walk goes; see `proofOf`. */
+    maxDepth?: number;
+}
+/** What one witness re-evaluation cost, said rather than hidden. */
+interface ExplainStats {
+    /** Facts the demand walk had extracted, which the proof pass reran. */
+    baseFacts: number;
+    /** Facts the exhaustive pass derived on top of those. */
+    derivedFacts: number;
+    evaluateMs: number;
+}
+interface ExplainedResolution {
+    /** The node the value comes down to. */
+    target: Node;
+    proof: Proof;
+    /** The source node behind a proof atom, when the atom is a node id. */
+    nodeFor: (atom: Atom) => Node | undefined;
+    stats: ExplainStats;
+}
 declare class ResolutionStore {
     private readonly db;
     private readonly table;
     private readonly fullyExtracted;
     private readonly seededValues;
     private readonly importedNames;
+    /** Files the most recent wave walk entered, for the memo to keep. */
+    private lastQueryWalked;
     private readonly declarations;
     private readonly graph;
     private stale;
@@ -192,6 +242,21 @@ declare class ResolutionStore {
      * the walk never reaches on its own.
      */
     resolveCallable(value: Node, alsoFrom?: SourceFile): Node | null;
+    /**
+     * Every function the value comes down to. One is the answer
+     * `resolveCallable` gives; several is a value with more than one
+     * possible source, which a caller says at the site rather than
+     * folding into the same nothing as a chain that went nowhere.
+     */
+    resolveCallableSources(value: Node, alsoFrom?: SourceFile): Node[];
+    /**
+     * The witness proof behind `resolveCallable`'s answer. Resolves the
+     * value first, which walks files and extracts facts in the usual
+     * waves, then re-evaluates the rules over those base facts under the
+     * witness algebra and rebuilds the proof of the answer. Null when
+     * the value does not resolve at all.
+     */
+    explainCallable(value: Node, options?: ExplainCallableOptions): ExplainedResolution | null;
     resolveObject(value: Node): Node | null;
     /**
      * For a value that is neither a function nor an object, such as a
@@ -239,10 +304,12 @@ declare class ResolutionStore {
      */
     filesImportingTransitively(fileSets: ReadonlyArray<FileSetQuery>): ReadonlyArray<ReadonlySet<SourceFile>>;
     /**
-     * Two candidates give null. Picking whichever arrived first would make
-     * the result depend on the order the facts came in.
+     * Null keeps the wave walk widening; any candidate at all ends it,
+     * since more files can only add candidates, never take one away. The
+     * single-answer policy stays with the callers: picking one of two
+     * would make the result depend on the order the facts came in.
      */
-    private lookup;
+    private lookupSources;
     private derive;
     private answersFor;
     /**
@@ -313,17 +380,19 @@ interface DiscoveredUnit {
      * path.
      *
      * `schemaSdl` is the typeDefs string captured from the same
-     * ApolloServer config object the resolver map came from, when
-     * we can statically resolve it (string literal or gql-tagged
-     * template, inline or const-bound). Surfaced on the summary so
-     * the checker's nested-selection pairing can look up return-type
-     * fields without needing a separate schema provenance.
+     * ApolloServer config object the resolver map came from, when we can
+     * statically resolve it (string literal or gql-tagged template,
+     * inline or const-bound). The adapter puts it on one summary
+     * standing for that schema, and `schemaDocument` is the label
+     * pointing every resolver at it.
      */
     resolverInfo?: {
         /** Null when the source never says which type the resolver attaches to. */
         typeName: string | null;
         fieldName: string;
         schemaSdl?: string;
+        /** The file whose server config declares the schema. */
+        schemaDocument?: string;
     };
     /**
      * Populated by `graphqlHookCall` discovery (GraphQL consumer side).
@@ -365,6 +434,8 @@ interface DiscoveredUnit {
             required: boolean;
         }>;
         rootFields: string[];
+        /** Spreads in `document` with no definition in it: read partially. */
+        unresolvedFragments?: string[];
         unresolved?: {
             reference: string;
             reason: string;
@@ -438,6 +509,12 @@ interface MountPrefixIndex {
      * couldn't be resolved to a literal prefix and a concrete router.
      */
     effectivePrefixFor(routerNode: Node): string;
+    /**
+     * The same resolution by a router's node id, for callers replaying a
+     * recorded consumption without the node in hand (the per-file cache
+     * re-checks a stored prefix against a rebuilt index this way).
+     */
+    prefixForId?(childId: string): string;
 }
 
 /**
@@ -488,6 +565,11 @@ type DescentBarriers = ReadonlySet<Node>;
 declare function extractCodeStructure(unit: DiscoveredUnit, pack: PatternPack, invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers, resolveWrittenValue?: (value: Node) => Node | null): RawCodeStructure;
 interface TypeScriptAdapterConfig {
     tsConfigFilePath?: string;
+    /**
+     * Absolute. Every id's file path is relative to this directory. When
+     * absent, settled by workspaceRootFor from the tsconfig's directory.
+     */
+    projectRoot?: string;
     /** Separates two services in one repository whose file names match. */
     workspace?: string;
     project?: Project;
@@ -739,6 +821,71 @@ interface TsDiscoveryContext {
 }
 declare function createTsDiscoveryContext(resolution?: ResolutionStore): TsDiscoveryContext;
 
+/**
+ * The session behind `suss ask why`: a ts-morph project over the
+ * asked-about source, a way to point at the expression somebody
+ * spelled, and the witness proof of what it resolved to, rendered
+ * through `@suss/resolution`'s phrases.
+ *
+ * The CLI points at values with a file, a line, and the text as
+ * written, because that is what a person has in hand. Everything
+ * ts-morph stays behind this class; callers treat the found nodes as
+ * opaque handles to pass back in.
+ */
+
+interface WhySessionOptions {
+    /** The project root, which paths in every answer come out relative to. */
+    dir: string;
+}
+/** A value or function said the way an answer prints it. */
+interface ValueLocation {
+    name: string;
+    /** Relative to the session root when under it, absolute otherwise. */
+    file: string;
+    line: number;
+}
+interface WhyExplained {
+    explanation: ResolutionExplanation;
+    /** The chain's atoms, each said in source terms. */
+    chain: string[];
+    /** The chain and its reasons as printable lines. */
+    lines: string[];
+    target: ValueLocation;
+    stats: ExplainStats;
+}
+declare class WhySession {
+    private readonly project;
+    private readonly store;
+    private readonly root;
+    constructor(options: WhySessionOptions);
+    /**
+     * The smallest expression on `line` of `file` whose text is exactly
+     * `text`, or null. Spelled from the person's side: the name as
+     * written, not a node id.
+     */
+    findExpression(file: string, line: number, text: string): Node | null;
+    /**
+     * The callee of the call written as `calleeText` between `startLine`
+     * and `endLine` of `file`, or null. This is how a summary's recorded
+     * callee gets back to its node: the summary keeps source text and a
+     * range, not ids.
+     */
+    findCallee(file: string, startLine: number, endLine: number, calleeText: string): Node | null;
+    /**
+     * Why `value` resolves to what it does: the witness proof, flattened
+     * to the chain and rendered. Null when the value does not resolve,
+     * which the caller says in its own words.
+     */
+    explain(value: Node, options?: {
+        maxDepth?: number;
+    }): WhyExplained | null;
+    /** Where a found node is, in the terms an answer prints. */
+    locate(node: Node): ValueLocation;
+    private sourceFileAt;
+    /** A module key: a file path said relative to the root, or a package name. */
+    private displayPath;
+}
+
 type ExportedDeclarationMap = ReturnType<SourceFile["getExportedDeclarations"]>;
 /**
  * What a module exports, by exported name. Cached, because ts-morph
@@ -832,8 +979,14 @@ declare function isImportedFrom(identifier: Node, expectedModule: string): boole
  * 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): boolean;
+declare function methodDeclaredIn(callee: Node, expectedModule: string, resolve?: (value: Node) => Node | null): boolean;
 
 /**
  * What a name-valued expression says, as fixed text with a hole for
@@ -846,9 +999,8 @@ declare function methodDeclaredIn(callee: Node, expectedModule: string): boolean
 interface ReadNameOptions {
     /**
      * What to say about a name nothing here settles. `"nothing"` gives
-     * null. `"reference"` gives a hole named after what the source asked
-     * for, `{location.bucket}`, which says which value to go and ask
-     * about rather than which bucket this is.
+     * null. `"reference"` gives `{location.bucket}`, which says which
+     * value to go and ask about rather than which bucket this is.
      */
     unsettled?: "nothing" | "reference";
     /**
@@ -961,6 +1113,37 @@ interface TsJsxAttributeLocation {
 }
 declare function createTsSubUnitContext(): TsSubUnitContext;
 
+/**
+ * Naming a summary, so that something else can point at it.
+ *
+ * A bare function name is not enough. Reading suss's own source turns up
+ * 404 summaries that share a name with another one, and a large
+ * repository is worse: two services with the same `src/handlers.ts` give
+ * every summary in one an exact twin in the other. Following a call by
+ * matching names was always a guess about which one was meant.
+ *
+ * So the name includes the project the summary came from, the file it is
+ * in, and the path its export is reached by. That is unique across
+ * everything one run can see, and it still looks like something a person
+ * would have written down.
+ */
+
+/**
+ * The one root a run measures its file paths from: the nearest
+ * directory at or above the run's anchor whose package.json has a
+ * name. The anchor is the tsconfig's directory, or the directory a
+ * run without one was pointed at. When no package.json declares a
+ * name above the anchor, the anchor itself is the root.
+ *
+ * The same directory supplies the workspace segment of an id, so both
+ * parts of an id are measured from one place. The walk starts from the
+ * run's configuration, not from whichever files the run loaded, so a
+ * run over one nested tsconfig spells a file the same way a run over
+ * the whole workspace does, and the same command spells it the same
+ * way twice.
+ */
+declare function workspaceRootFor(anchor: string): string;
+
 declare const ADAPTER_VERSION = "0.2.1";
 /**
  * Content hash of the given files, in the order they arrive. Empty when
@@ -992,4 +1175,4 @@ declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     version?: string;
 }>): string;
 
-export { ADAPTER_VERSION, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExtractionReport, type FoundTerminal, type FunctionRoot, type HealthCheck, type HealthViolation, type PackFunnel, type ReadNameOptions, ResolutionStore, type Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, isImportedFrom, methodDeclaredIn, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier };
+export { ADAPTER_VERSION, 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 ReadNameOptions, ResolutionStore, type Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, type ValueLocation, type WhyExplained, WhySession, type WhySessionOptions, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, isImportedFrom, methodDeclaredIn, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, workspaceRootFor };

package/dist/index.d.ts

@@ -1,18 +1,44 @@
 import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, Project, Symbol, Expression } from 'ts-morph';
 import { TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, LanguageAdapter, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, EffectArg, RawDeclaredContract, ContractPattern, 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';
+
+/**
+ * cache.ts: the on-disk extraction cache.
+ *
+ * A run reuses the previous one's summaries whole when nothing
+ * changed, and per file when some files did. The entry directory is
+ * named after everything that has to agree before any reuse is sound:
+ * schema version, adapter version and code hash, pack versions, the
+ * extraction config stamp and the tsconfig path. Inside it, the
+ * manifest records a stamp and content hash per file, each summary's
+ * owning files, and per owning file the other files its walk read, so
+ * a change to any of those re-extracts the owner instead of serving a
+ * stale answer. The full design, including what per-file reuse can
+ * and cannot promise, is in this package's README.
+ */
 
 /** Reported by `lookup`: what the cache decided, and why. */
 interface CacheDiagnostic {
-    kind: "hit" | "miss";
+    kind: "hit" | "miss" | "partial";
     /**
      * Reason the lookup missed (only set when kind === "miss").
-     * `key-changed` means the cache directory holds entries, but none
+     * `key-changed` means the cache directory contains entries, but none
      * under this run's schema, adapter, packs and tsconfig path.
      * `files-changed` means the include set is not the one the entry
      * was written from.
      */
     missReason?: "no-manifest" | "key-changed" | "tsconfig-changed" | "files-changed";
+    /** Set when kind === "partial". */
+    partial?: {
+        filesChanged: number;
+        filesRemoved: number;
+        rootsReused: number;
+        rootsReextracted: number;
+        rootsDeclined: number;
+        summariesReused: number;
+    };
 }
 /**
  * Result of a cache lookup. A hit gives back the whole summary set; a miss
@@ -174,12 +200,36 @@ interface FileSetQuery {
  * edges a query follows, so cost tracks how indirect the code is.
  */
 
+interface ExplainCallableOptions {
+    /** A second file to walk out from; see `resolveCallable`. */
+    alsoFrom?: SourceFile;
+    /** How many derived nodes deep the proof walk goes; see `proofOf`. */
+    maxDepth?: number;
+}
+/** What one witness re-evaluation cost, said rather than hidden. */
+interface ExplainStats {
+    /** Facts the demand walk had extracted, which the proof pass reran. */
+    baseFacts: number;
+    /** Facts the exhaustive pass derived on top of those. */
+    derivedFacts: number;
+    evaluateMs: number;
+}
+interface ExplainedResolution {
+    /** The node the value comes down to. */
+    target: Node;
+    proof: Proof;
+    /** The source node behind a proof atom, when the atom is a node id. */
+    nodeFor: (atom: Atom) => Node | undefined;
+    stats: ExplainStats;
+}
 declare class ResolutionStore {
     private readonly db;
     private readonly table;
     private readonly fullyExtracted;
     private readonly seededValues;
     private readonly importedNames;
+    /** Files the most recent wave walk entered, for the memo to keep. */
+    private lastQueryWalked;
     private readonly declarations;
     private readonly graph;
     private stale;
@@ -192,6 +242,21 @@ declare class ResolutionStore {
      * the walk never reaches on its own.
      */
     resolveCallable(value: Node, alsoFrom?: SourceFile): Node | null;
+    /**
+     * Every function the value comes down to. One is the answer
+     * `resolveCallable` gives; several is a value with more than one
+     * possible source, which a caller says at the site rather than
+     * folding into the same nothing as a chain that went nowhere.
+     */
+    resolveCallableSources(value: Node, alsoFrom?: SourceFile): Node[];
+    /**
+     * The witness proof behind `resolveCallable`'s answer. Resolves the
+     * value first, which walks files and extracts facts in the usual
+     * waves, then re-evaluates the rules over those base facts under the
+     * witness algebra and rebuilds the proof of the answer. Null when
+     * the value does not resolve at all.
+     */
+    explainCallable(value: Node, options?: ExplainCallableOptions): ExplainedResolution | null;
     resolveObject(value: Node): Node | null;
     /**
      * For a value that is neither a function nor an object, such as a
@@ -239,10 +304,12 @@ declare class ResolutionStore {
      */
     filesImportingTransitively(fileSets: ReadonlyArray<FileSetQuery>): ReadonlyArray<ReadonlySet<SourceFile>>;
     /**
-     * Two candidates give null. Picking whichever arrived first would make
-     * the result depend on the order the facts came in.
+     * Null keeps the wave walk widening; any candidate at all ends it,
+     * since more files can only add candidates, never take one away. The
+     * single-answer policy stays with the callers: picking one of two
+     * would make the result depend on the order the facts came in.
      */
-    private lookup;
+    private lookupSources;
     private derive;
     private answersFor;
     /**
@@ -313,17 +380,19 @@ interface DiscoveredUnit {
      * path.
      *
      * `schemaSdl` is the typeDefs string captured from the same
-     * ApolloServer config object the resolver map came from, when
-     * we can statically resolve it (string literal or gql-tagged
-     * template, inline or const-bound). Surfaced on the summary so
-     * the checker's nested-selection pairing can look up return-type
-     * fields without needing a separate schema provenance.
+     * ApolloServer config object the resolver map came from, when we can
+     * statically resolve it (string literal or gql-tagged template,
+     * inline or const-bound). The adapter puts it on one summary
+     * standing for that schema, and `schemaDocument` is the label
+     * pointing every resolver at it.
      */
     resolverInfo?: {
         /** Null when the source never says which type the resolver attaches to. */
         typeName: string | null;
         fieldName: string;
         schemaSdl?: string;
+        /** The file whose server config declares the schema. */
+        schemaDocument?: string;
     };
     /**
      * Populated by `graphqlHookCall` discovery (GraphQL consumer side).
@@ -365,6 +434,8 @@ interface DiscoveredUnit {
             required: boolean;
         }>;
         rootFields: string[];
+        /** Spreads in `document` with no definition in it: read partially. */
+        unresolvedFragments?: string[];
         unresolved?: {
             reference: string;
             reason: string;
@@ -438,6 +509,12 @@ interface MountPrefixIndex {
      * couldn't be resolved to a literal prefix and a concrete router.
      */
     effectivePrefixFor(routerNode: Node): string;
+    /**
+     * The same resolution by a router's node id, for callers replaying a
+     * recorded consumption without the node in hand (the per-file cache
+     * re-checks a stored prefix against a rebuilt index this way).
+     */
+    prefixForId?(childId: string): string;
 }
 
 /**
@@ -488,6 +565,11 @@ type DescentBarriers = ReadonlySet<Node>;
 declare function extractCodeStructure(unit: DiscoveredUnit, pack: PatternPack, invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers, resolveWrittenValue?: (value: Node) => Node | null): RawCodeStructure;
 interface TypeScriptAdapterConfig {
     tsConfigFilePath?: string;
+    /**
+     * Absolute. Every id's file path is relative to this directory. When
+     * absent, settled by workspaceRootFor from the tsconfig's directory.
+     */
+    projectRoot?: string;
     /** Separates two services in one repository whose file names match. */
     workspace?: string;
     project?: Project;
@@ -739,6 +821,71 @@ interface TsDiscoveryContext {
 }
 declare function createTsDiscoveryContext(resolution?: ResolutionStore): TsDiscoveryContext;
 
+/**
+ * The session behind `suss ask why`: a ts-morph project over the
+ * asked-about source, a way to point at the expression somebody
+ * spelled, and the witness proof of what it resolved to, rendered
+ * through `@suss/resolution`'s phrases.
+ *
+ * The CLI points at values with a file, a line, and the text as
+ * written, because that is what a person has in hand. Everything
+ * ts-morph stays behind this class; callers treat the found nodes as
+ * opaque handles to pass back in.
+ */
+
+interface WhySessionOptions {
+    /** The project root, which paths in every answer come out relative to. */
+    dir: string;
+}
+/** A value or function said the way an answer prints it. */
+interface ValueLocation {
+    name: string;
+    /** Relative to the session root when under it, absolute otherwise. */
+    file: string;
+    line: number;
+}
+interface WhyExplained {
+    explanation: ResolutionExplanation;
+    /** The chain's atoms, each said in source terms. */
+    chain: string[];
+    /** The chain and its reasons as printable lines. */
+    lines: string[];
+    target: ValueLocation;
+    stats: ExplainStats;
+}
+declare class WhySession {
+    private readonly project;
+    private readonly store;
+    private readonly root;
+    constructor(options: WhySessionOptions);
+    /**
+     * The smallest expression on `line` of `file` whose text is exactly
+     * `text`, or null. Spelled from the person's side: the name as
+     * written, not a node id.
+     */
+    findExpression(file: string, line: number, text: string): Node | null;
+    /**
+     * The callee of the call written as `calleeText` between `startLine`
+     * and `endLine` of `file`, or null. This is how a summary's recorded
+     * callee gets back to its node: the summary keeps source text and a
+     * range, not ids.
+     */
+    findCallee(file: string, startLine: number, endLine: number, calleeText: string): Node | null;
+    /**
+     * Why `value` resolves to what it does: the witness proof, flattened
+     * to the chain and rendered. Null when the value does not resolve,
+     * which the caller says in its own words.
+     */
+    explain(value: Node, options?: {
+        maxDepth?: number;
+    }): WhyExplained | null;
+    /** Where a found node is, in the terms an answer prints. */
+    locate(node: Node): ValueLocation;
+    private sourceFileAt;
+    /** A module key: a file path said relative to the root, or a package name. */
+    private displayPath;
+}
+
 type ExportedDeclarationMap = ReturnType<SourceFile["getExportedDeclarations"]>;
 /**
  * What a module exports, by exported name. Cached, because ts-morph
@@ -832,8 +979,14 @@ declare function isImportedFrom(identifier: Node, expectedModule: string): boole
  * 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): boolean;
+declare function methodDeclaredIn(callee: Node, expectedModule: string, resolve?: (value: Node) => Node | null): boolean;
 
 /**
  * What a name-valued expression says, as fixed text with a hole for
@@ -846,9 +999,8 @@ declare function methodDeclaredIn(callee: Node, expectedModule: string): boolean
 interface ReadNameOptions {
     /**
      * What to say about a name nothing here settles. `"nothing"` gives
-     * null. `"reference"` gives a hole named after what the source asked
-     * for, `{location.bucket}`, which says which value to go and ask
-     * about rather than which bucket this is.
+     * null. `"reference"` gives `{location.bucket}`, which says which
+     * value to go and ask about rather than which bucket this is.
      */
     unsettled?: "nothing" | "reference";
     /**
@@ -961,6 +1113,37 @@ interface TsJsxAttributeLocation {
 }
 declare function createTsSubUnitContext(): TsSubUnitContext;
 
+/**
+ * Naming a summary, so that something else can point at it.
+ *
+ * A bare function name is not enough. Reading suss's own source turns up
+ * 404 summaries that share a name with another one, and a large
+ * repository is worse: two services with the same `src/handlers.ts` give
+ * every summary in one an exact twin in the other. Following a call by
+ * matching names was always a guess about which one was meant.
+ *
+ * So the name includes the project the summary came from, the file it is
+ * in, and the path its export is reached by. That is unique across
+ * everything one run can see, and it still looks like something a person
+ * would have written down.
+ */
+
+/**
+ * The one root a run measures its file paths from: the nearest
+ * directory at or above the run's anchor whose package.json has a
+ * name. The anchor is the tsconfig's directory, or the directory a
+ * run without one was pointed at. When no package.json declares a
+ * name above the anchor, the anchor itself is the root.
+ *
+ * The same directory supplies the workspace segment of an id, so both
+ * parts of an id are measured from one place. The walk starts from the
+ * run's configuration, not from whichever files the run loaded, so a
+ * run over one nested tsconfig spells a file the same way a run over
+ * the whole workspace does, and the same command spells it the same
+ * way twice.
+ */
+declare function workspaceRootFor(anchor: string): string;
+
 declare const ADAPTER_VERSION = "0.2.1";
 /**
  * Content hash of the given files, in the order they arrive. Empty when
@@ -992,4 +1175,4 @@ declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     version?: string;
 }>): string;
 
-export { ADAPTER_VERSION, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExtractionReport, type FoundTerminal, type FunctionRoot, type HealthCheck, type HealthViolation, type PackFunnel, type ReadNameOptions, ResolutionStore, type Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, isImportedFrom, methodDeclaredIn, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier };
+export { ADAPTER_VERSION, 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 ReadNameOptions, ResolutionStore, type Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, type ValueLocation, type WhyExplained, WhySession, type WhySessionOptions, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, isImportedFrom, methodDeclaredIn, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, workspaceRootFor };