@suss/adapter-typescript 0.33.0 → 0.34.0

package/dist/index.d.ts

@@ -1,22 +1,64 @@
-import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, Symbol, CallExpression, PropertyAccessExpression, TaggedTemplateExpression, Project, 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, ImportDeclaration, ArrayLiteralExpression, ObjectLiteralExpression, ObjectLiteralElementLike, Expression, Identifier } from 'ts-morph';
+import { PatternPack, TransparentWrapper, ParameterSupplier, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, ArgumentParser, StatedSlot, AstCapableOps, CallOps, EffectArg, LanguageAdapter, ExtractorOptions, TimingReport, CacheDiagnostic, ExtractionReport, DeclaredModule, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, configuredCallOption, RawDeclaredContract, ContractPattern, ResponsePropertyMapping } 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;
-    private envNamersAnswer;
-    private envNamersExtractedAt;
+    /** 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
@@ -171,10 +267,8 @@ declare class ResolutionStore {
      * a pack spells it, a name declared as that, or a parameter some
      * caller hands one to, however many calls deep.
      *
-     * A parameter is the only shape whose answer can change once its
-     * callers are in, and reading those means reading every file that
-     * imports this one, so a value that is not one is answered from what
-     * the store already has.
+     * A parameter's answer depends on its callers, so it comes from the
+     * parameters the environment reaches, worked out once per run.
      */
     isEnvironmentValue(value: Node): boolean;
     private hasAnswer;
@@ -183,24 +277,31 @@ declare class ResolutionStore {
      * from, for a reader standing at a call. One question covers the
      * whole project: a project has a handful of environment reads and
      * thousands of parameters, and with the read bound the rules run from
-     * each callee to its callers.
-     *
-     * `definedIn` is the callee's own file, read into the store before
-     * the question so a helper nothing had extracted yet is among the
-     * facts the rules run over.
+     * each callee to its callers. The facts README says which files that
+     * reads and why it is asked once.
      */
-    envNamers(definedIn: SourceFile): EnvironmentNamers;
+    envNamers(project: Project): EnvironmentNamers;
+    private environmentAnswers;
+    /**
+     * Ask until every call handing the environment on has had its callee
+     * read, one hop a round, so the answer covers each parameter it lands in.
+     */
+    private followEnvironment;
+    private readCalleeOf;
+    /** The files the parameters an answer is keyed by are declared in. */
+    private filesOf;
     private sitesNamedBy;
     /**
      * Seed every expression that spells the environment, derive, and take
-     * the sites back per parameter. The question is dropped afterwards, so
-     * a later ask over a larger fact set derives it again.
+     * back the read sites per parameter and the parameters the object is
+     * handed to. The question is dropped afterwards, so a later ask over a
+     * larger fact set derives it again.
      *
      * The reads themselves cannot be the seed: one written through a
      * parameter is off an object a scan of the source has no way to pick
      * out, and the whole point of asking is to find those.
      */
-    private askEnvNamers;
+    private askEnvironment;
     /**
      * The project's files that hand the environment object somewhere,
      * read into the store. Which files those are cannot depend on what a
@@ -208,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.
@@ -215,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
@@ -250,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
@@ -290,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
@@ -326,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
@@ -336,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.
      *
@@ -383,6 +535,27 @@ 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[];
+}
+
 type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | MethodDeclaration;
 /**
  * Public API: returns RawCondition[] with structured: null.
@@ -559,6 +732,13 @@ interface DiscoveredUnit {
         method: string | null;
         path: string | null;
     };
+    /**
+     * 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;
     /**
      * Populated by a pack's `discoverUnits` callback for a message-bus
      * consumer whose channel the code gives (a handler factory whose
@@ -646,6 +826,11 @@ 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>;
 }
 /**
  * What the project helper index says it has already expanded, which the
@@ -661,6 +846,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
@@ -675,6 +872,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
@@ -690,6 +952,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.
@@ -785,7 +1065,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
@@ -818,7 +1098,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;
@@ -838,7 +1118,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;
     /**
@@ -859,12 +1139,36 @@ interface TypeScriptAdapterConfig {
     onExtractionReport?: (report: ExtractionReport) => void;
     /** Absolute. `.suss/cache/` beside the tsconfig; `null` turns it off. */
     cacheDir?: string | null;
+    /** The modules the project lists in `suss.json`, with absolute paths. */
+    modules?: readonly DeclaredModule[];
 }
 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;
 
@@ -1215,6 +1519,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.
@@ -1280,6 +1586,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;
@@ -1338,32 +1646,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.
  *
@@ -1585,6 +1867,49 @@ declare function createTsSubUnitContext(): TsSubUnitContext;
  */
 declare function workspaceRootFor(anchor: string): string;
 
+/** 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.
  *
@@ -1614,19 +1939,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;
 
@@ -1653,4 +1982,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, 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, receiverTypesOf, resolveAliasedSymbol, resolveSubject, rootIdentifier, startsItsOwnScope, stringPropertyOf, stringValueOf, stubEvidence, stubEvidenceIn, symbolBehind, toFunctionRoot, workspaceRootFor, writtenNodeOf, writtenPayloadOf };