@suss/adapter-typescript 0.33.1 → 0.34.1

package/dist/index.d.ts

@@ -1,22 +1,64 @@
-import { SourceFile, Node, Project, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, Symbol, CallExpression, PropertyAccessExpression, TaggedTemplateExpression, ImportDeclaration, ArrayLiteralExpression, ObjectLiteralExpression, ObjectLiteralElementLike, Expression, NewExpression, Identifier } from 'ts-morph';
-import { TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, EffectArg, CallOps, LanguageAdapter, PatternPack, ExtractorOptions, TimingReport, CacheDiagnostic, ExtractionReport, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, configuredCallOption, RawDeclaredContract, ContractPattern, AstCapableOps, ResponsePropertyMapping } from '@suss/extractor';
+import { SourceFile, Node, Project, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, Symbol, CallExpression, NewExpression, TaggedTemplateExpression, PropertyAccessExpression, Expression, ImportDeclaration, ArrayLiteralExpression, ObjectLiteralExpression, ObjectLiteralElementLike, Identifier } from 'ts-morph';
+import { PatternPack, TransparentWrapper, ParameterSupplier, VersionPlacement, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, ArgumentParser, StatedSlot, AstCapableOps, CallOps, EffectArg, LanguageAdapter, ExtractorOptions, TimingReport, CacheDiagnostic, ExtractionReport, DeclaredModule, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, ResponsePropertyMapping, RawBranch, KeepsArms, configuredCallOption, RawDeclaredContract, ContractPattern } from '@suss/extractor';
 export { EmptyStage, ExtractionReport, PackFunnel, Timer, TimingReport, computeContentHash } from '@suss/extractor';
-import { MessageBusSemantics, DeployableUnit, UnfollowedCall, WrapperReference, BehavioralSummary, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
-import { ExplainStats, WhyExplained, ValueLocation } from '@suss/resolution';
+import { MessageBusSemantics, DeployableUnit, UnfollowedCall, WrapperReference, Effect, BehavioralSummary, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
+import { ExplainStats, SourceLeaf, ValueUses, WhyExplained, ValueLocation } from '@suss/resolution';
 export { ExplainStats, ValueLocation, WhyExplained } from '@suss/resolution';
 import { Proof, Atom } from '@suss/datalog';
 import { z } from 'zod';
 
+/** How the packs in a run spell the parts of the process nothing declares. */
+interface RuntimeSpellings {
+    streamObjects: readonly string[];
+    exitCalls: readonly string[];
+    exitCodeWrites: readonly string[];
+}
+
+/**
+ * A library's own module, written into the project by that library's
+ * code generator.
+ *
+ * A pack says which file its generator leaves beside the module it
+ * wrote, and a directory containing that file counts as the package. A
+ * pack whose generator leaves no such file says instead where the
+ * project's configuration tells the generator to write. The README says
+ * why the import gate needs this.
+ */
+
+type DirFinder = NonNullable<PatternPack["generatedModuleDirs"]>;
+declare class GeneratedModules {
+    private readonly markers;
+    private readonly finders;
+    private readonly generatedDirs;
+    private readonly declaredDirs;
+    constructor(markers: ReadonlyArray<string>, finders?: ReadonlyArray<{
+        pack: string;
+        find: DirFinder;
+    }>);
+    /** Whether any pack asked for a generated module to be looked for. */
+    get declared(): boolean;
+    /** Distinguishes two asks about one package that declare different markers. */
+    get key(): string;
+    /**
+     * Whether any of this file's specifiers points into a directory the
+     * generator wrote. A specifier can name the directory itself or a
+     * file in it, so both are checked.
+     */
+    reachedFrom(fromFile: string, specifiers: ReadonlyArray<string>): boolean;
+    private isGenerated;
+    private isDeclaredOutput;
+}
+
 /** One question: do these files reach any of these packages. */
 interface FileSetQuery {
     sourceFiles: ReadonlyArray<SourceFile>;
     packages: ReadonlyArray<string>;
     /**
-     * Files the asking pack's code generator leaves beside a module it
-     * wrote into the project. A relative import into such a directory
-     * counts as an import of the package.
+     * Where the asking pack's code generator writes a module into the
+     * project. A relative import into such a directory counts as an
+     * import of the package.
      */
-    generatedMarkers?: ReadonlyArray<string>;
+    generated?: GeneratedModules;
 }
 
 /**
@@ -33,6 +75,16 @@ interface FileSetQuery {
  * local barrel re-exports the SDK.
  */
 
+/** One place a value's walk ended, with the nodes the store keyed it by. */
+interface SourceFound {
+    leaf: SourceLeaf;
+    /** The node the walk ended at, or null when the store keyed none. */
+    node: Node | null;
+    /** The read at a computed key on the way, when there was one. */
+    computedAt: Node | null;
+    /** The function a parameter the walk ended at belongs to. */
+    parameterOf: Node | null;
+}
 interface ExplainCallableOptions {
     /** A second file to walk out from; see `resolveCallable`. */
     alsoFrom?: SourceFile;
@@ -82,19 +134,25 @@ declare class ResolutionStore {
     /** Keyed by value and site both, since one value differs per site. */
     private readonly writtenUnderSite;
     private readonly constructionSites;
+    /** What each local's reads do with it, by its declaration. A local's function is walked whole, so an answer stays true. */
+    private readonly localUses;
     /** Files the most recent query read, for the memo to keep. */
     private lastQueryWalked;
     /** See `environmentSiteFiles`; null until the first env question. */
     private envSiteFiles;
     /** See `environmentAnswers`; null until the first env question. */
     private envAnswers;
+    /** See `streamAnswers`: the declared streams each expression reaches. */
+    private streamsReached;
     private readonly declarations;
     private readonly graph;
     /** See `notePossibleCallers`. */
     private readonly possibleCallers;
     private readonly callerFilesRead;
     private stale;
-    constructor(wrappers?: TransparentWrapper[], environmentObjects?: readonly string[]);
+    constructor(wrappers?: TransparentWrapper[], environmentObjects?: readonly string[], runtime?: RuntimeSpellings, parameterSuppliers?: readonly ParameterSupplier[]);
+    /** A store with the wrappers and runtime objects these packs declare, as an extraction over them starts from. */
+    static forPacks(packs: readonly PatternPack[]): ResolutionStore;
     /**
      * `alsoFrom` is a second file to walk out from, for a caller that
      * knows where the value it is asking about was set up. The walk
@@ -110,6 +168,12 @@ declare class ResolutionStore {
      * folding into the same nothing as a chain that went nowhere.
      */
     resolveCallableSources(value: Node, alsoFrom?: SourceFile): Node[];
+    /**
+     * `resolveCallable` for several values, asked as one question. A file
+     * with a receiver at every call would otherwise derive and clear the
+     * rules once per receiver.
+     */
+    resolveCallables(values: readonly Node[]): Map<Node, Node | null>;
     /**
      * The witness proof behind `resolveCallable`'s answer. Resolves the
      * value first, which extracts the files the question demands, then
@@ -128,11 +192,43 @@ declare class ResolutionStore {
      * single-answer question here.
      */
     resolveReturnedCallable(call: Node): Node | null;
+    /**
+     * The function a call through this value runs: the one it comes down
+     * to, and failing that the one it gives back, so a name written as
+     * `useNavigator()` runs what that factory returned. Both answers come
+     * from the same derivation, so asking them together costs one query.
+     */
+    resolveCalledFunction(value: Node): Node | null;
+    /**
+     * The batched form, for a caller with a body's worth of callees: one
+     * demand set and one derivation shared by all of them, where asking
+     * each alone re-derives once per value.
+     */
+    resolveCalledFunctions(values: readonly Node[]): Map<Node, Node | null>;
+    private calledFunctionOf;
     /**
      * For a value that is neither a function nor an object, such as a
      * GraphQL document kept in a constant in another file.
      */
     resolveWrittenValue(value: Node): Node | null;
+    /**
+     * Where each value came from, asked as one question: every place the
+     * walk from it ended, with the node there and, for a parameter, the
+     * function it belongs to.
+     */
+    sourcesOf(values: readonly Node[]): Map<Node, SourceFound[]>;
+    /**
+     * `resolveWrittenValue` for several values, asked as one question.
+     * Values that share a declaration share one answer, as they do when
+     * asked one at a time.
+     */
+    resolveWrittenValues(values: readonly Node[]): Map<Node, Node | null>;
+    /**
+     * The class a name refers to, asked the same narrow way. A class is
+     * not an expression, so `resolveWrittenValue` never gives one back.
+     */
+    resolveWrittenClass(value: Node): Node | null;
+    private writtenAnswers;
     /**
      * The same question under one construction site: what the value is
      * when the receiver behind it is the instance that site made. A field
@@ -213,6 +309,36 @@ declare class ResolutionStore {
      * project's own sources and it happens once.
      */
     private environmentSiteFiles;
+    /**
+     * Which output stream a receiver is, for a writer standing at
+     * `out.write(...)`: the path a pack declared, such as
+     * `process.stdout`. Null when it is a stream and the source does not
+     * settle which one, and undefined when nothing says it is a stream.
+     *
+     * A receiver the source does not spell as a stream is looked up in
+     * one answer worked out for the whole run, so a question is never
+     * asked per call. A parameter nothing in the run passes a stream to
+     * is still a stream when it is annotated as one of `streamTypes`.
+     */
+    streamPathOf(receiver: Node, streamTypes: readonly string[]): string | null | undefined;
+    private streamAnswers;
+    /**
+     * The environment's loop for the streams: ask, read the callee of every
+     * call that hands a stream on, and ask again until no new call turns up.
+     */
+    private followStreams;
+    private askStreams;
+    /**
+     * The functions whose return becomes the process's exit code, asked
+     * once from the files that end the process or set its exit code. Each
+     * value that ends up as the code seeds the walk; DESIGN.md in the
+     * resolution package says how it gets from there to a function.
+     */
+    exitCodeFunctions(project: Project): readonly Node[];
+    /** The values that end up as the exit code: an exit call's first argument, or what is assigned to the code. */
+    private exitSinks;
+    /** Whether the parameter a name refers to is annotated as one of these types. */
+    private annotatedAsOneOf;
     /**
      * Whether running this function hands back that call: returned
      * outright, written into a name and returned, or a shorthand body.
@@ -220,6 +346,13 @@ declare class ResolutionStore {
      * what keeps a wrapper's own result apart from the library's.
      */
     returnsCall(func: Node, call: Node): boolean;
+    /**
+     * What the reads of a local do with it, when `receiver` is a local a
+     * function declares once as `construction`. Null for anything else,
+     * such as a module-level value, which some other file may serve.
+     */
+    usesOfLocal(receiver: Node, construction: Node): ValueUses | null;
+    private askLocalUses;
     /**
      * Files a later question about a parameter may find a caller in.
      * Without this the search falls back to every file the project has
@@ -255,7 +388,8 @@ declare class ResolutionStore {
      * declared name.
      */
     private constructionComesFrom;
-    private calleeNameOf;
+    /** The callee of a call, as written. */
+    private calleeTextOf;
     /**
      * 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
@@ -295,6 +429,12 @@ declare class ResolutionStore {
     private lookupImportOrigins;
     private lookupImportedNames;
     private askAbout;
+    /**
+     * One question about several values: one demand set, one round of
+     * extraction and one derivation shared by all of them. Asking each
+     * alone pays the rounds, the clear and the allocation once per value.
+     */
+    private askAboutAll;
     /**
      * Extract the seed files, then every module the rules ask for, until
      * they ask for nothing new. The files a question reads are then fixed
@@ -331,7 +471,12 @@ declare class ResolutionStore {
      */
     private seedValue;
     private lookupObject;
+    /**
+     * A factory returning a wrapper's call gives back the wrapper's own
+     * closure and the function it unwraps. The unwrapped one wins.
+     */
     private lookupReturned;
+    private singleFunctionIn;
     /**
      * Two candidates give null, since ambiguity is nothing. The value
      * itself is never a result either, or an identifier whose chain went
@@ -341,6 +486,8 @@ declare class ResolutionStore {
      * construction makes an instance of. The README says why.
      */
     private lookupWritten;
+    /** The one class among what a value is written as, under the same policy. */
+    private lookupWrittenClass;
     /**
      * Read these files' facts now, before anything asks a question.
      *
@@ -388,6 +535,66 @@ declare class ResolutionStore {
     private extractFile;
 }
 
+/**
+ * The path an application puts in front of every route it serves.
+ *
+ * NestJS serves each decorated route under whatever the bootstrap's
+ * `app.setGlobalPrefix("api")` says, in a file with no controller in it.
+ * A call counts when the store says its receiver is the app the
+ * framework's factory made, following a parameter to every caller. The
+ * prefix and its exclusions are read through the value evaluator, and
+ * every call in the run has to agree, or no prefix is applied.
+ */
+
+/** A route the prefix leaves out. A null method leaves out every verb. */
+interface ExcludedRoute {
+    path: string;
+    method: string | null;
+}
+interface GlobalPrefix {
+    prefix: string;
+    excluded: ExcludedRoute[];
+}
+
+/**
+ * The API versions a decorated route serves, and the paths they put it at.
+ *
+ * NestJS reads `@Controller({ version })` and `@Version()` only after the
+ * bootstrap calls `app.enableVersioning()`, usually in a file with no
+ * controller in it. URI versioning puts `v1` in the path after the global
+ * prefix and before the controller's path. Header, media type and custom
+ * versioning leave the path alone, so every version of a route shares it.
+ *
+ * When the run cannot read how the application serves versions, a route
+ * that states a version claims no path. Any path it claimed could pair it
+ * with a client or a document for another version.
+ */
+
+/** The versions a route or an application states. Null in the list means every version. */
+type StatedVersion = {
+    kind: "unstated";
+} | {
+    kind: "unread";
+} | {
+    kind: "listed";
+    versions: ReadonlyArray<string | null>;
+};
+/**
+ * How an application serves versions. `off` means the run read the
+ * application and nothing turns versioning on, so Nest ignores every
+ * version a route states.
+ */
+type AppVersioning = {
+    kind: "off";
+} | {
+    kind: "unread";
+} | {
+    kind: "on";
+    placement: VersionPlacement;
+    pathPrefix: string;
+    defaultVersion: StatedVersion;
+};
+
 type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | MethodDeclaration;
 /**
  * Public API: returns RawCondition[] with structured: null.
@@ -564,6 +771,21 @@ interface DiscoveredUnit {
         method: string | null;
         path: string | null;
     };
+    /**
+     * The file a file convention found this unit in. Its path and export
+     * name decide the route, even when the function it exports was written
+     * in another module or returned by a factory.
+     */
+    routeFile?: SourceFile;
+    /**
+     * The status the framework sends for a response this unit's body
+     * states none for, when the route declares one: `@HttpCode(204)`, or
+     * the 201 NestJS sends for `@Post`. It replaces the default on the
+     * pack's response terminals for this unit alone.
+     */
+    defaultStatusCode?: number;
+    /** Statuses the route's own decorators list as possible responses. */
+    declaredStatuses?: number[];
     /**
      * Populated by a pack's `discoverUnits` callback for a message-bus
      * consumer whose channel the code gives (a handler factory whose
@@ -651,6 +873,13 @@ interface MountPrefixIndex {
      * re-checks a stored prefix against a rebuilt index this way).
      */
     prefixForId?(childId: string): string;
+    /**
+     * The prefix the calls keyed by `globalPrefixKey` agree an application
+     * puts in front of its routes. A key with no entry has none.
+     */
+    globalPrefixes?: ReadonlyMap<string, GlobalPrefix>;
+    /** How the run's applications serve API versions, keyed by `routeVersioningKey`. */
+    versionings?: ReadonlyMap<string, AppVersioning>;
 }
 /**
  * What the project helper index says it has already expanded, which the
@@ -666,6 +895,18 @@ interface ExpandedRegistrations {
  */
 declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPattern[], resolution?: ResolutionStore, mountPrefixes?: MountPrefixIndex, expandedElsewhere?: ExpandedRegistrations): DiscoveredUnit[];
 
+/**
+ * What every unit is read with beyond its own pack's patterns, whichever
+ * pack discovered it: the terminals a runtime ends the process with, and
+ * the command-line parsers it provides. A pack's recognizers reach every
+ * unit the same way, and are collected on their own.
+ */
+
+interface EveryUnitDeclarations {
+    terminals: readonly TerminalPattern[];
+    argumentParsers: readonly ArgumentParser[];
+}
+
 /**
  * Nested function nodes a pack claimed as sub-units. The unit-body
  * walkers stop at these so the sub-unit's behavior isn't double-counted
@@ -680,6 +921,71 @@ declare const NO_BARRIERS: DescentBarriers;
  */
 declare function startsItsOwnScope(node: Node): boolean;
 
+/**
+ * What this adapter can tell a declared pack about a call.
+ *
+ * Every question here was already worked out somewhere in this adapter,
+ * once per pack that needed it. Collecting them behind the one
+ * interface `@suss/extractor` declares is what lets a pack stop being a
+ * walk over ts-morph and start being data.
+ *
+ * Two of the receiver origins are implemented. The migration plan for
+ * #542 lists four more, and each one adds an entry to `ORIGIN` beside
+ * the union member it matches.
+ */
+
+/**
+ * A call, a construction, or a tagged template, which all ask the same
+ * questions. A tagged template is a call the source wrote without
+ * parentheses: the tag is the callee and the template is the one
+ * argument, which is how a pack reaches a statement written that way
+ * without a second grammar for it.
+ */
+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 the ops read a call through. A reading left out reads only what
+ * the source spells at the call.
+ */
+interface CallReading {
+    /** One-hop lookup from a written name to the value it was bound to. */
+    readonly resolve?: Resolve;
+    readonly originatesFrom?: OriginatesFrom | undefined;
+    readonly anchorCallsOf?: AnchorCallsOf | undefined;
+    /** The run's store, which the value evaluator follows names through. */
+    readonly resolution?: ResolutionStore | undefined;
+    /**
+     * The arguments of the walk this call was visited by. A value is read
+     * through it in place of `resolve`, and it asks the store about any
+     * value it has no answer for.
+     */
+    readonly walk?: WalkArguments | undefined;
+    /** Where a recognizer's `statesSlots` goes, when somebody listens. */
+    readonly statesSlots?: ((effect: Effect, slots: readonly StatedSlot[]) => void) | undefined;
+}
+/**
+ * The arguments of every call one walk visits. A chain that steps to
+ * every argument would otherwise ask the store about each one at each
+ * call, and each question runs and clears the rules once.
+ */
+interface WalkArguments {
+    /** Ask about these positions of every call in the walk, in one question. */
+    settle(first: number, last?: number): void;
+    /**
+     * Ask about the receiver of every call in the walk whose method is one
+     * of these, in one question.
+     */
+    settleReceivers(methods: ReadonlySet<string>): void;
+    /**
+     * What a value was written as: the walk's own answer for an argument
+     * a `settle` covered, and the store's for anything else.
+     */
+    writtenValueOf(value: Node): Node | null;
+}
+/** What a declared pack can ask about one TypeScript call. */
+declare function callOpsFor(call: Called, reading?: CallReading): AstCapableOps;
+
 /**
  * invocationEffects.ts: capture every call in a unit's body as an
  * `invocation` RawEffect, wherever the call is written: a statement of
@@ -695,6 +1001,24 @@ declare function startsItsOwnScope(node: Node): boolean;
  * ordered and what `async` means.
  */
 
+/** A column a recognized effect writes or picks rows by, and its value. */
+interface SlotValue {
+    slot: StatedSlot["slot"];
+    name: string;
+    value: Node;
+}
+/**
+ * What a recognizer says about each effect it built at one call, kept
+ * until the dispatch loop knows which effects the recognizer returned.
+ */
+declare class SlotsStated {
+    private readonly byEffect;
+    readonly listen: (effect: Effect, slots: readonly StatedSlot[]) => void;
+    /** The slots stated for an effect, ready to spread onto its location. */
+    of(effect: Effect): {
+        slots?: SlotValue[];
+    };
+}
 /**
  * Context handed to TypeScript-adapter access recognizers: sister
  * to TsInvocationRecognizerContext but for property-access nodes.
@@ -790,7 +1114,7 @@ interface TsInvocationRecognizerContext {
  * 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, resolution?: ResolutionStore, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf): TsInvocationRecognizerContext;
+declare function invocationContextFor(call: CallExpression, resolution?: ResolutionStore, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf, walk?: WalkArguments, stated?: SlotsStated): 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
@@ -823,7 +1147,7 @@ type Accessed = PropertyAccessExpression | CallExpression | TaggedTemplateExpres
  * 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, resolution?: ResolutionStore, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf): TsAccessRecognizerContext;
+declare function accessContextFor(node: Accessed, sourceFile: SourceFile, resolution?: ResolutionStore, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf, walk?: WalkArguments, stated?: SlotsStated): TsAccessRecognizerContext;
 
 /** Resolves a helper callee to its declaration; the adapter binds the store's ask. */
 type ResolveCallee = (callee: Node) => Node | null;
@@ -843,7 +1167,7 @@ type ResolveCallee = (callee: Node) => Node | null;
  * framework or a runtime belongs to a pack.
  */
 
-declare function extractCodeStructure(unit: DiscoveredUnit, pack: PatternPack, invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers, resolution?: ResolutionStore, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf, resolveCallee?: ResolveCallee): RawCodeStructure;
+declare function extractCodeStructure(unit: DiscoveredUnit, pack: PatternPack, invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers, resolution?: ResolutionStore, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf, resolveCallee?: ResolveCallee, everyUnit?: EveryUnitDeclarations): RawCodeStructure;
 interface TypeScriptAdapterConfig {
     tsConfigFilePath?: string;
     /**
@@ -862,14 +1186,46 @@ interface TypeScriptAdapterConfig {
     onCacheDiagnostic?: (diagnostic: CacheDiagnostic) => void;
     /** Not called on a cache hit, where no stage ran. */
     onExtractionReport?: (report: ExtractionReport) => void;
-    /** Absolute. `.suss/cache/` beside the tsconfig; `null` turns it off. */
+    /**
+     * Absolute. `.suss/cache/` in `walkedDirectory` when set, otherwise
+     * beside the tsconfig; `null` turns it off.
+     */
     cacheDir?: string | null;
+    /** The modules the project lists in `suss.json`, with absolute paths. */
+    modules?: readonly DeclaredModule[];
+    /**
+     * Absolute. Walks only the tsconfig's files under this directory, for a
+     * tsconfig found above the directory a run was pointed at.
+     */
+    walkedDirectory?: string;
 }
 interface TypeScriptAdapter extends LanguageAdapter {
     /** Kept off `LanguageAdapter`, so a caller needing ts-morph asks for it. */
     readonly tsProject: Project;
     extractFromFiles(filePaths: string[]): Promise<BehavioralSummary[]>;
     extractAll(): Promise<BehavioralSummary[]>;
+    /**
+     * Re-reads the files that changed on disk since the last `extractAll`,
+     * so the next one describes the tree as it is now and keeps the parse
+     * of every other file. A process that keeps the adapter between runs
+     * calls this before each one. `changedPaths` are files the caller knows
+     * were written; the rest are found by their stamps.
+     */
+    refresh(changedPaths?: readonly string[]): RefreshReport;
+    /**
+     * Loads the files a run walks and everything they import, and builds
+     * the compiler's program, without extracting. A run served whole from
+     * the cache loads nothing, so a process that keeps the adapter calls
+     * this once while nobody is waiting, and the first edit after that
+     * finds the program built.
+     */
+    loadProgram(): Promise<void>;
+}
+interface RefreshReport {
+    /** Files parsed again because their text changed. */
+    changed: string[];
+    /** Why the adapter started over with a new project, or null. */
+    startedOver: string | null;
 }
 declare function createTypeScriptAdapter(suppliedConfig: TypeScriptAdapterConfig): TypeScriptAdapter;
 
@@ -909,6 +1265,31 @@ interface FoundTerminal {
  */
 declare function findTerminals(func: FunctionRoot, patterns: TerminalPattern[], barriers?: DescentBarriers, resolution?: ResolutionStore, originatesFrom?: OriginatesFrom, resolveCallee?: ResolveCallee): FoundTerminal[];
 
+/**
+ * Reads a project function a client caller hands its response to as part
+ * of the caller.
+ *
+ *   const response = await fetch(`/api/orders/${id}`);
+ *   return readOrder(response);
+ *
+ * `readOrder` throws on `!response.ok`. Read alone, the caller tests
+ * nothing, so every failure looks unhandled. The helper's paths are read
+ * the way the caller's were, with each parameter replaced by what the
+ * caller passed, and each becomes a path of the caller. A helper is
+ * followed only when one of its paths tests the response or its parsed
+ * body, so a call that logs the response leaves the caller as it was.
+ */
+
+interface ResponseHandOffOptions {
+    /** The callee text the caller's own conditions use for the response. */
+    responseCallee: string;
+    /** The callee texts they use for its parsed body, such as `res.json`. */
+    bodyCallees: readonly string[];
+    /** The pack's response members, to tell a body field from a status read. */
+    responseSemantics: ResponsePropertyMapping[] | undefined;
+    resolution: ResolutionStore;
+}
+
 /**
  * Turns one function into the list of branches a summary is built from.
  *
@@ -958,8 +1339,29 @@ 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, resolution?: ResolutionStore, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf, resolveCallee?: ResolveCallee, collectCallAccounting?: boolean): RawBranchResult;
+declare function extractRawBranches(func: FunctionRoot, terminalPatterns: TerminalPattern[], invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers, resolution?: ResolutionStore, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf, resolveCallee?: ResolveCallee, collectCallAccounting?: boolean, keepsArms?: KeepsArms<Expression>, handOff?: ResponseHandOffOptions): RawBranchResult;
+
+/**
+ * Picks the files a run walks, and gets the compiler ahead of the
+ * import graph before anything asks it a question.
+ *
+ * `createLazyProject` reads the tsconfig's file list and keeps the
+ * files whose imports match some active pack's `requiresImport` gate.
+ * Those candidates are what the run walks; everything else is loaded
+ * later, one file at a time, by `lazyAddSourceFile` when symbol
+ * resolution points at it.
+ *
+ * The rest of the module is about load order. TypeScript follows a
+ * re-export chain by recursing, so a barrel chain a few hundred files
+ * deep runs the call stack out. `loadImportGraphsDepthFirst` loads each
+ * file after everything it imports. The README says why that matters.
+ */
+
+/** Reads no source, so a cache hit never pays for the bootstrap. */
+declare function readTsconfigFileList(tsConfigFilePath: string): string[];
 
+/** The suffixes this adapter reads, JavaScript included. */
+declare const SOURCE_SUFFIXES: readonly [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
 /**
  * A Project covering `rootDir`, for a codebase with no tsconfig to read.
  * Returns the project and the files it loaded.
@@ -1135,6 +1537,12 @@ declare function namedImportsOf(sourceFile: SourceFile, modules: readonly string
 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>;
+/**
+ * The specifier, as written, of the import that binds this local name,
+ * whether as a named, default or namespace import. Null when no import
+ * in the file binds it.
+ */
+declare function specifierImportedAs(sourceFile: SourceFile, local: string): string | null;
 /** Every import declaration in the file that names one of `modules`. */
 declare function importDeclarationsOf(sourceFile: SourceFile, modules: readonly string[], options?: ImportScanOptions): ImportDeclaration[];
 
@@ -1220,6 +1628,8 @@ declare function writtenNodeOf(value: Node, resolution: ResolutionStore | undefi
  * empty" from "could not read" (#123).
  */
 declare function stringValueOf(value: Node, resolution: ResolutionStore | undefined): string | null;
+/** The number this value comes to, or null when it does not settle to one. */
+declare function numberValueOf(value: Node, resolution: ResolutionStore | undefined): number | null;
 /**
  * The string a named property of an object is set to, with the object
  * and the value each read through whatever name they were given.
@@ -1285,6 +1695,8 @@ declare function createTsDiscoveryContext(resolution?: ResolutionStore): TsDisco
 interface WhySessionOptions {
     /** The project root, which paths in every answer come out relative to. */
     dir: string;
+    /** The packs the extraction ran with, for the wrappers and environment objects they declare. */
+    packs?: readonly PatternPack[];
 }
 declare class TypeScriptWhySession {
     private readonly project;
@@ -1343,32 +1755,6 @@ declare function resolveAliasedSymbol(symbol: Symbol): Symbol | undefined;
  */
 declare function parseConditionExpression(expr: Expression, depth?: number): Predicate | null;
 
-/**
- * What this adapter can tell a declared pack about a call.
- *
- * Every question here was already worked out somewhere in this adapter,
- * once per pack that needed it. Collecting them behind the one
- * interface `@suss/extractor` declares is what lets a pack stop being a
- * walk over ts-morph and start being data.
- *
- * Two of the receiver origins are implemented. The migration plan for
- * #542 lists four more, and each one adds an entry to `ORIGIN` beside
- * the union member it matches.
- */
-
-/**
- * A call, a construction, or a tagged template, which all ask the same
- * questions. A tagged template is a call the source wrote without
- * parentheses: the tag is the callee and the template is the one
- * argument, which is how a pack reaches a statement written that way
- * without a second grammar for it.
- */
-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, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf): AstCapableOps;
-
 /**
  * The one resolver from a reference to the function behind it.
  *
@@ -1589,6 +1975,57 @@ declare function createTsSubUnitContext(): TsSubUnitContext;
  * way twice.
  */
 declare function workspaceRootFor(anchor: string): string;
+/**
+ * What a project calls itself.
+ *
+ * Its package.json name is what a person would say and what a sibling
+ * package already imports it by. A project without one falls back to
+ * the folder, which is at least what somebody typed.
+ */
+declare function workspaceNameFor(root: string | undefined): string | null;
+
+/** What a call writes out, and whether it was serialized as JSON first. */
+interface WrittenPayload {
+    shape: TypeShape | null;
+    serialized: "json" | "text";
+}
+/**
+ * What a call writes, for a pack recording a write to a stream.
+ * `JSON.stringify(report)` writes the report as JSON, and so does a
+ * template that puts nothing but whitespace around one such call, the
+ * way a command ends its report with a newline. Several arguments are
+ * written one after another, so their shapes come back keyed by position.
+ */
+declare function writtenPayloadOf(args: readonly Node[]): WrittenPayload;
+
+/**
+ * The named types behind a node's type, for a pack that recognizes a
+ * call by what its receiver is rather than by what it is called.
+ *
+ * A library rarely hands back its type bare. A client factory can return
+ * the library's class joined with an extra field (`Db & { $client: Pool }`),
+ * and a project can declare the client as optional (`Db | undefined`), alias
+ * it, subclass it, or pass it through a type parameter. A union or an
+ * intersection has no symbol of its own, so this looks through each of
+ * those to the named types underneath, and the pack tests each one.
+ *
+ * When the checker cannot resolve the type because the library is not
+ * installed, the names come from the written type, with no declaring file.
+ */
+
+/** One named type a receiver is, and the files that declare it. */
+interface ReceiverType {
+    name: string;
+    declaredIn: readonly string[];
+    /**
+     * The base each declaring class is written as extending. When the
+     * library is not installed the checker cannot see past a project's
+     * `class Db extends Client`, and a pack asks where the base came from.
+     */
+    extendsWritten: readonly Node[];
+}
+/** Every named type the node's type is, nearest first. */
+declare function receiverTypesOf(node: Node): ReceiverType[];
 
 /**
  * version.ts: this adapter's own half of the cache key.
@@ -1619,19 +2056,23 @@ declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
 /**
  * defaulted.ts: whether a read has something behind it.
  *
- * `??` and `||` are ECMAScript, not anything a pack defines, so the
- * packs that record a read ask here instead of each spelling the
- * operators out. This is a separate file from unwrap.ts because that
- * one is about wrappers, and a fallback is not one.
+ * A read is defaulted when the program still works where the value is
+ * missing. Either a `??` or `||` supplies a fallback value, or the
+ * program tests the value for presence, only uses it where the test
+ * passed, and the path a missing value takes does not end in a throw.
+ * The test can be on the read itself or on a local the read
+ * initializes: a truthiness check, a comparison with `undefined` or
+ * `null`, or an `in` membership test.
+ *
+ * All of this is ECMAScript, so the packs that record a read ask here
+ * instead of each spelling the forms out. The Python and Ruby adapters
+ * define the same rule for their own syntax.
  */
 
 /**
- * Whether something else supplies a value when this read comes back
- * empty. `env.X ?? "default"` and `env.X || other` both do, and so does
- * the middle of a chain: in `env.A || env.B || undefined`, B's fallback
- * is the chain's tail. The climb stops when the read is the final
- * operand (`getDefault() ?? env.X`), where the read is itself the
- * fallback and its absence propagates.
+ * Whether the program copes with this read coming back empty: something
+ * falls back from it, or every use of its value runs only after a
+ * presence test has passed.
  */
 declare function isDefaultedAt(node: Node): boolean;
 
@@ -1658,4 +2099,4 @@ declare function climbSyntax(node: Node): Node;
  */
 declare function peelValue(node: Node): Node;
 
-export { ADAPTER_VERSION, type Accessed, type CallAccountingEntry, type CallAccountingOutcome, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DescentBarriers, type DiscoveredUnit, type EnvironmentNamers, type ExplainCallableOptions, type ExplainedResolution, type FoundTerminal, type FunctionRoot, GENERIC_TERMINALS, type ImportScanOptions, NO_BARRIERS, type ObservedStubCall, type RawBranchResult, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, TSCONFIG_NAMES, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, TypeScriptWhySession, type WhySessionOptions, accessContextFor, arrayLiteralOf, buildProjectHelperIndex, callOpsFor, climbSyntax, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, couldNameAValue, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, declarationsBehind, discoverUnits, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findEnclosingFunction, findNearestTsconfig, findTerminals, functionTargetOf, functionValueOf, hasBody, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isDefaultedAt, isImportedFrom, methodDeclaredIn, namedImportsOf, objectLiteralOf, parseConditionExpression, peelSyntax, peelValue, propertiesOf, propertyFunctionOf, propertyNameOf, propertyOf, propertyValueOf, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, startsItsOwnScope, stringPropertyOf, stringValueOf, stubEvidence, stubEvidenceIn, symbolBehind, toFunctionRoot, workspaceRootFor, writtenNodeOf };
+export { ADAPTER_VERSION, type Accessed, type CallAccountingEntry, type CallAccountingOutcome, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DescentBarriers, type DiscoveredUnit, type EnvironmentNamers, type ExplainCallableOptions, type ExplainedResolution, type FoundTerminal, type FunctionRoot, GENERIC_TERMINALS, type ImportScanOptions, NO_BARRIERS, type ObservedStubCall, type RawBranchResult, type ReadNameOptions, type ReceiverType, type RefreshReport, ResolutionStore, SOURCE_SUFFIXES, type StubCallEvidence, type StubEvidenceOptions, TSCONFIG_NAMES, type TsAccessRecognizerContext, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, TypeScriptWhySession, type WhySessionOptions, type WrittenPayload, accessContextFor, arrayLiteralOf, buildProjectHelperIndex, callOpsFor, climbSyntax, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, couldNameAValue, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, declarationsBehind, discoverUnits, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findEnclosingFunction, findNearestTsconfig, findTerminals, functionTargetOf, functionValueOf, hasBody, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isDefaultedAt, isImportedFrom, methodDeclaredIn, namedImportsOf, numberValueOf, objectLiteralOf, parseConditionExpression, peelSyntax, peelValue, propertiesOf, propertyFunctionOf, propertyNameOf, propertyOf, propertyValueOf, readConfiguredCall, readContract, readContractForClientCall, readName, readTsconfigFileList, receiverTypesOf, resolveAliasedSymbol, resolveSubject, rootIdentifier, specifierImportedAs, startsItsOwnScope, stringPropertyOf, stringValueOf, stubEvidence, stubEvidenceIn, symbolBehind, toFunctionRoot, workspaceNameFor, workspaceRootFor, writtenNodeOf, writtenPayloadOf };