@suss/adapter-typescript 0.3.2 → 0.5.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, Project, Expression } from 'ts-morph';
-import { TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, EffectArg, RawDeclaredContract, ContractPattern, ResponsePropertyMapping } from '@suss/extractor';
+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';
 
 /** Reported by `lookup`: what the cache decided, and why. */
@@ -15,7 +15,7 @@ interface CacheDiagnostic {
     missReason?: "no-manifest" | "key-changed" | "tsconfig-changed" | "files-changed";
 }
 /**
- * Result of a cache lookup. A hit carries the whole summary set; a miss
+ * Result of a cache lookup. A hit gives back the whole summary set; a miss
  * says why, so a caller can render the reason.
  */
 type CacheLookup = {
@@ -33,18 +33,18 @@ interface PackFunnel {
     /**
      * What the pack calls this build of itself, or null when it declares
      * nothing. The cache keys on it, so a pack that never changes its
-     * stamp can answer a later run with an earlier build's results.
+     * stamp can serve a later run with an earlier build's results.
      */
     version: string | null;
     /**
-     * Whether the pack looks for units of its own at all. A pack made
-     * only of recognisers contributes effects to units other packs found,
-     * so discovering nothing is how it always behaves and says nothing
-     * about whether it is working.
+     * Whether the pack looks for units of its own at all. A pack made only
+     * of recognisers contributes effects to units other packs found, so it
+     * always discovers nothing, and that tells you nothing about whether
+     * it is working.
      */
     discovers: boolean;
     /**
-     * Whether the pack carries recognisers. Those fire inside units other
+     * Whether the pack has any recognisers. Those fire inside units other
      * packs discovered, so a pack made only of them contributes effects
      * and never a summary.
      */
@@ -70,8 +70,8 @@ interface PackFunnel {
      * Unit bodies any pack walked in the files this pack's gate selected.
      *
      * This is what a recogniser pack had the chance to fire on. Its own
-     * discovery count says nothing, since it discovers nothing by design,
-     * and its candidate-file count says nothing either, because a
+     * discovery count tells you nothing, since it discovers nothing by
+     * design, and neither does its candidate-file count, because a
      * recogniser only runs where some pack found a unit to walk.
      */
     unitsInGatedFiles: number;
@@ -80,7 +80,7 @@ interface PackFunnel {
     /**
      * Units this pack kept. A unit an earlier pack already claimed is
      * dropped here, so a pack can discover plenty and keep none when it
-     * sits behind a pack that recognises the same code.
+     * comes after a pack that recognises the same code.
      */
     unitsClaimed: number;
     /**
@@ -92,19 +92,19 @@ interface PackFunnel {
     selfCollisions: number;
     /** Summaries built from those units. */
     summariesProduced: number;
-    /** Summaries in the finished run that name this pack as what recognised them. */
+    /** Summaries in the finished run that credit this pack for finding them. */
     summariesBound: number;
     /**
      * Bound summaries on the provider side of their boundary.
      *
-     * Transitions say what a unit does with a request, which is a
-     * question only a provider answers. A consumer records what it reads
-     * back from the response instead, and that lives on the summary's
-     * metadata. Measuring a client pack against transitions would report
-     * every working one as extracting nothing.
+     * Transitions say what a unit does with a request, which only a
+     * provider can say. A consumer records what it reads back from the
+     * response instead, and that goes on the summary's metadata. Measuring
+     * a client pack against transitions would report every working one as
+     * having extracted nothing.
      */
     providerSummaries: number;
-    /** Provider summaries carrying at least one transition. */
+    /** Provider summaries with at least one transition. */
     summariesWithBehavior: number;
     /**
      * Where one of this pack's hooks threw. Every count above is a floor
@@ -119,6 +119,17 @@ interface ExtractionReport {
     filesWalked: number;
     packs: PackFunnel[];
     summaries: number;
+    /**
+     * Files whose exports the checker could not follow, so the run read
+     * them as exporting nothing.
+     *
+     * Without this the artifact cannot tell the two apart: a module whose
+     * barrel chain outran the call stack and a module that really does
+     * export nothing both produce no summaries and exit 0.
+     * Anything reachable only through these files is missing, and every
+     * count below is a floor while this is non-empty.
+     */
+    filesWithUnreadableExports: string[];
     /**
      * The first stage whose count was zero, when the run produced
      * nothing. Null when the run produced summaries.
@@ -129,13 +140,13 @@ type EmptyStage = "tsconfig" | "gateResolution" | "candidateFiles" | "discovery"
 /**
  * A pack's hook throwing on one file.
  *
- * The run carries on with the other files, so every count for that pack
+ * The run continues with the other files, so every count for that pack
  * afterwards is a floor rather than a total. Somebody reading those
- * counts has to be told, or a pack that broke reads the same as a pack
+ * counts has to be told, or a pack that broke looks the same as a pack
  * that looked and found nothing.
  */
 interface PackFailure {
-    /** The hook that threw, named as a pack author would know it. */
+    /** The hook that threw, called what a pack author would call it. */
     hook: string;
     /** The file the pack was reading. */
     file: string;
@@ -148,147 +159,98 @@ interface FileSetQuery {
     packages: ReadonlyArray<string>;
 }
 
+/**
+ * The resolution store, and the three questions callers ask it.
+ *
+ * `resolveCallable` says which function a value comes down to, through
+ * any depth of aliasing, imports, re-export barrels, wrapper factories
+ * and `.bind`. `resolveWrittenValue` says which expression a value is
+ * written as, for callers chasing something that is neither a function
+ * nor an object. `filesImportingTransitively` says which of a set of
+ * files reach any of a set of packages, which a per-file import check
+ * misses whenever a local barrel re-exports the SDK.
+ *
+ * Facts are extracted per file on demand and only along the module
+ * edges a query follows, so cost tracks how indirect the code is.
+ */
+
 declare class ResolutionStore {
     private readonly db;
     private readonly table;
     private readonly fullyExtracted;
     private readonly seededValues;
     private readonly importedNames;
+    private readonly declarations;
     private readonly graph;
     private stale;
     constructor(wrappers?: TransparentWrapper[]);
-    /**
-     * The function `value` resolves to, or null when no chain reaches
-     * one. The result is a ts-morph node in whatever file the function
-     * actually lives.
-     *
-     * Facts come in waves: extract the file the value lives in, ask, and
-     * only widen to the files it imports when the answer is still
-     * missing. A value that resolves without leaving its own file costs
-     * one file of extraction, not the whole import closure.
-     */
     resolveCallable(value: Node): Node | null;
-    /**
-     * The object literal `value` ends up being, or null. The route a
-     * registration call names often lives on a shared object built in
-     * another file, and this is how discovery reads it back.
-     */
     resolveObject(value: Node): Node | null;
     /**
-     * The expression `value` is written as, or null. Unlike the other two
-     * questions this one does not care what kind of expression it lands
-     * on, so it answers for values that are neither functions nor
-     * objects: a GraphQL document held in a named constant in another
-     * file comes back as the template literal or tag call that built it.
-     *
-     * A value the code computes has no written form to report, so the
-     * answer is the computing expression itself and the caller gets
-     * nothing it can use, which is the point.
+     * 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;
     /**
-     * The names from `modules` this value stands for. A value stands for
-     * a library name two ways, and a caller asking which library concept
-     * something is wants both:
-     *
-     *   - it is that name, under whatever local spelling. `import
-     *     { Controller as Resource }` makes `Resource` the library's
-     *     `Controller`.
-     *   - calling it calls that name. A project decorator written as
-     *     `(path) => Controller(path)` marks a controller, and so does
-     *     one written as `applyDecorators(Controller(path))`.
-     *
-     * Several names is the normal answer rather than an ambiguity, since
-     * a wrapper composing two library decorators applies both. The caller
-     * asks whether the name it cares about is among them.
-     *
-     * One wrapper is applied across hundreds of files, so the answer is
-     * memoized against the declaration it was asked about. Without that,
-     * every use site seeds a fresh value and pays another fixpoint.
+     * 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
+     * several back is normal, since a wrapper can compose two library
+     * decorators.
      */
     importedNamesOf(value: Node, modules: string[]): string[];
     /**
-     * The names from `modules` this value stands for, or null while the
-     * walk should keep widening.
-     *
-     * The distinction is what keeps the cost down. A value that has
-     * arrived at a package has nothing more to give, because a library's
-     * own body is not here to read, so a decorator from a library the
-     * caller did not ask about stops on the first wave rather than
-     * running out the import closure looking for a match it will never
-     * find. A value that has only arrived at another file in the project
-     * keeps going, since the wrapper it names is declared somewhere the
-     * walk has not reached yet.
+     * Null tells the walk to keep widening. A value that landed in a
+     * package returns empty instead, because a library's own body is not
+     * here to read and widening would never find anything.
      */
     private lookupImportedNames;
     private resolveByWaves;
     private walkForAnswer;
     /**
-     * The answer has been read, so the question and the chain that
-     * answered it can go. What the query extracted stays: files are the
-     * expensive part and the next query reads the same facts.
-     *
-     * Nothing is owed after this. The rules have seen every fact the
-     * database holds and concluded what the demand still present asks
-     * for, which is none, so the next query starts from its own asking
-     * fact.
+     * The question and the chain that settled it are dropped. The files
+     * the query extracted stay, since the next query reads the same facts.
+     * Nothing is left half-done, so the store is not stale afterwards.
      */
     private forgetQuery;
-    /**
-     * Somebody asked about this value, which is what the rules follow
-     * chains for. Separate from `seedValue`, which only speaks for values
-     * that are expressions; a caller can ask about a declaration too, and
-     * the answer is still owed.
-     */
     private wantValue;
     /**
-     * Facts for the queried value itself. File extraction only reaches
-     * values that hang off exports, and a query can be rooted anywhere:
-     * a registration call passes `routes.provision` as an argument, and
-     * nothing else ever emits facts for that expression.
+     * File extraction only reaches values hanging off exports, and a query
+     * can be rooted anywhere, so the queried value gets its own facts.
      */
     private seedValue;
     private lookupObject;
     /**
-     * Reaching two different expressions means the rules cannot tell
-     * which one the value is written as, and the same reasoning applies
-     * as for the other two questions: ambiguity is nothing. The value
-     * itself is not an answer, or every identifier would answer with
-     * itself the moment its chain went nowhere.
+     * Two candidates give null, since ambiguity is nothing. The value
+     * itself is never a result either, or an identifier whose chain went
+     * nowhere would come back as itself.
      */
     private lookupWritten;
     /**
-     * For each set of files and packages, which of those files reach any
-     * of those packages through their imports, following project-local
-     * re-export chains.
+     * Which of these files reach any of these packages, following
+     * project-local re-export chains. A barrel package that re-exports an
+     * SDK defeats a per-file import check and does not defeat this.
      */
     filesImportingTransitively(fileSets: ReadonlyArray<FileSetQuery>): ReadonlyArray<ReadonlySet<SourceFile>>;
     /**
-     * The one function this value resolves to. Several rules can reach
-     * the same answer, which is fine, but reaching two different
-     * functions means the rules cannot tell which one the value is, and
-     * picking whichever landed in the relation first would make the
-     * answer depend on the order facts arrived in. Ambiguity is nothing.
+     * Two candidates give null. Picking whichever arrived first would make
+     * the result depend on the order the facts came in.
      */
     private lookup;
-    /** Run the rules to fixpoint. */
     private derive;
+    private answersFor;
     /**
-     * The second column of an answer relation, for the value asked about.
-     * The database indexes a column the first time somebody looks it up
-     * and keeps that index as facts arrive, so this is a map hit and the
-     * answers a query never asks about cost nothing.
+     * The trailing pair of a three-column relation, joined so a Set dedupes
+     * on both halves. The join uses the database's own tuple encoding,
+     * since a specifier or an identifier can contain any separator
+     * character.
      */
-    private answersFor;
-    /** The trailing pair of a three-column answer relation, joined. */
     private answerPairsFor;
-    /** Emit a file's facts, unless some earlier query already did. */
     private extractFile;
 }
 
 type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | MethodDeclaration;
 /**
- * Public API — returns RawCondition[] with structured: null.
+ * Public API: returns RawCondition[] with structured: null.
  * Use collectAncestorConditionInfos when you need the Expression nodes.
  */
 declare function collectAncestorBranches(terminalNode: Node, functionRoot: FunctionRoot): RawCondition[];
@@ -313,6 +275,12 @@ interface DiscoveredUnit {
     announcedAt?: Node;
     kind: string;
     name: string;
+    /**
+     * "label" when the name was coined for the reader rather than
+     * naming a binding other code can call, the way a registration
+     * verb identifies its handler. Absent means the name is a binding.
+     */
+    nameKind?: "binding" | "label";
     callSite?: ClientCallSite;
     /** The discovery pattern that produced this unit. Set by discoverUnits. */
     pattern?: DiscoveryPattern;
@@ -345,13 +313,14 @@ interface DiscoveredUnit {
      * fields without needing a separate schema provenance.
      */
     resolverInfo?: {
-        typeName: string;
+        /** Null when the source never says which type the resolver attaches to. */
+        typeName: string | null;
         fieldName: string;
         schemaSdl?: string;
     };
     /**
      * Populated by `graphqlHookCall` discovery (GraphQL consumer side).
-     * Carries the operation shape the adapter uses to build a
+     * Has the operation shape the adapter uses to build a
      * `graphql-operation` binding. `operationName` is absent for
      * anonymous operations (`gql\`query { ... }\``, no identifier).
      *
@@ -360,7 +329,7 @@ interface DiscoveredUnit {
      * alongside the parsed shape so downstream tools can re-parse if
      * they need additional detail beyond what we surface here. Absent
      * when the document body wasn't statically readable and the header
-     * was recovered from `TypedDocumentNode` type arguments — a
+     * was recovered from `TypedDocumentNode` type arguments: a
      * cross-module codegen reference to a document produced by a helper.
      *
      * `variables` list the `$name: Type` declarations at the operation
@@ -368,7 +337,7 @@ interface DiscoveredUnit {
      * pairing layers can match against resolver args. Empty when the
      * document body wasn't read.
      *
-     * `rootFields` is the list of root-level selection names — the
+     * `rootFields` is the list of root-level selection names: the
      * fields the operation actually selects under Query / Mutation /
      * Subscription. Used by the checker's pairing pass. Empty when the
      * document body wasn't read.
@@ -395,9 +364,9 @@ interface DiscoveredUnit {
         };
     };
     /**
-     * Populated by `packageExports` discovery. Carries the package
-     * identity the adapter uses to build a `function-call` binding
-     * with `package` + `exportPath` fields — i.e. a provider summary
+     * Populated by `packageExports` discovery. Has the package identity
+     * the adapter uses to build a `function-call` binding
+     * with `package` + `exportPath` fields: i.e. a provider summary
      * for a publicly-exported library function.
      */
     packageExportInfo?: {
@@ -409,7 +378,7 @@ interface DiscoveredUnit {
      * controllers). The adapter uses it to build a `rest` binding
      * with `(method, path)` directly, bypassing the
      * `bindingExtraction` config used by Express / Fastify (which
-     * extract from `app.get(...)` registration calls — the wrong
+     * extract from `app.get(...)` registration calls: the wrong
      * shape for decorator-driven controllers).
      */
     routeInfo?: {
@@ -418,8 +387,8 @@ interface DiscoveredUnit {
     };
     /**
      * Populated by a pack's `discoverUnits` callback for a message-bus
-     * consumer whose channel the code names (a handler factory whose
-     * config carries the expected subject). The adapter uses it to build
+     * consumer whose channel the code gives (a handler factory whose
+     * config includes the expected subject). The adapter uses it to build
      * a `message-bus` binding directly, which pairs with producers
      * sending on the same channel.
      */
@@ -433,16 +402,41 @@ interface DiscoveredUnit {
      * Metadata merged onto the assembled summary's `metadata` field.
      * Populated when a pack's `discoverUnits` callback stamps provenance
      * on the units it returns (the discovery-layer sibling of the
-     * per-sub-unit `metadata` the `subUnits` hook carries).
+     * per-sub-unit `metadata` the `subUnits` hook returns).
      */
     metadata?: Record<string, unknown>;
+    /**
+     * What a discovery handler could not read about the boundary this
+     * unit is on. A route whose path is computed is still a route
+     * somebody declared, so the unit goes out with no path claimed and
+     * this sentence saying which part went unread. It ends up on the
+     * summary as an `unreadOutcome` gap.
+     */
+    unreadBinding?: string;
+}
+
+/**
+ * What a route's path should be composed with once mount discovery has
+ * run: the prefix a router was mounted under, following however many
+ * routers it was mounted onto in turn. Built once per extraction by
+ * `buildMountPrefixIndex`, over every mount call the active packs'
+ * `DiscoveryPattern.mount` config recognizes.
+ */
+interface MountPrefixIndex {
+    /**
+     * The prefix routes on `routerNode` (a registration subject's own
+     * creation site, e.g. a `Router()` call) were mounted under. Empty
+     * when nothing mounts it, or when a mount call along the way
+     * couldn't be resolved to a literal prefix and a concrete router.
+     */
+    effectivePrefixFor(routerNode: Node): string;
 }
 
 /**
  * Discover code units in `sourceFile` by running all patterns.
  * Deduplicates entries with the same function node and kind.
  */
-declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPattern[], resolution?: ResolutionStore): DiscoveredUnit[];
+declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPattern[], resolution?: ResolutionStore, mountPrefixes?: MountPrefixIndex): DiscoveredUnit[];
 
 interface TimingReport {
     totalMs: number;
@@ -455,7 +449,7 @@ interface TimingReport {
 interface Timer {
     /** Run `fn`, accumulate wall time under `label`, return its result. */
     time<T>(label: string, fn: () => T): T;
-    /** Async variant — same accumulation rule. */
+    /** Async variant: same accumulation rule. */
     timeAsync<T>(label: string, fn: () => Promise<T>): Promise<T>;
     /** Snapshot of all accumulated phases, ordered by total time descending. */
     report(): TimingReport;
@@ -468,82 +462,42 @@ interface Timer {
  */
 type DescentBarriers = ReadonlySet<Node>;
 
-declare function extractCodeStructure(unit: DiscoveredUnit, pack: PatternPack, invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers): RawCodeStructure;
+/**
+ * The whole extraction, from a tsconfig to a set of behavioral
+ * summaries. `createTypeScriptAdapter` is what a caller uses;
+ * everything else here is a stage of the run it drives.
+ *
+ * A run loads the project, asks each pack which files it cares about,
+ * discovers units in those files, walks each unit's body for terminals
+ * and effects, works out the boundary the unit is on, and assembles a
+ * summary. Several passes then run over the finished set: mount
+ * prefixes, module-load behavior, the reachable closure, rethrow
+ * sources, wrapper expansion, sub-units, and naming. The adapter owns
+ * what TypeScript and ECMAScript define; what a call means to a
+ * framework or a runtime belongs to a pack.
+ */
+
+declare function extractCodeStructure(unit: DiscoveredUnit, pack: PatternPack, invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers, resolveWrittenValue?: (value: Node) => Node | null): RawCodeStructure;
 interface TypeScriptAdapterConfig {
     tsConfigFilePath?: string;
-    /**
-     * What the project being read calls itself, so a summary can carry a
-     * name nothing else in a run shares.
-     *
-     * Two services in one repository both hold `src/handlers.ts`, and a
-     * summary named after the file and the export is the same on both
-     * sides until something says which project it came from. Worked out
-     * from the project's own package.json when nobody says.
-     */
+    /** Separates two services in one repository whose file names match. */
     workspace?: string;
     project?: Project;
     frameworks: PatternPack[];
     extractorOptions?: ExtractorOptions;
-    /**
-     * Include library summaries for every function reachable through a
-     * static call edge from a pack-discovered unit. Defaults to `true` —
-     * internal orchestrators, helpers, and utilities that frameworks
-     * don't recognise become `library`-kind summaries with
-     * `recognition: "reachable"` so readers can see their behaviour.
-     * Set to `false` for pack-only extraction (smaller output; only the
-     * units packs explicitly claim).
-     */
+    /** A `library` summary per function reachable by a static call edge. */
     includeReachable?: boolean;
-    /**
-     * Called once at the end of each `extractAll` / `extractFromFiles`
-     * with the wall-clock breakdown of the major extraction phases.
-     * Always-on instrumentation cost is negligible (millisecond-scale
-     * `performance.now()` calls); the callback is the opt-in for
-     * surfacing it. CLI uses this to render the per-extract summary
-     * line and the `--timing` breakdown.
-     */
     onTiming?: (report: TimingReport) => void;
-    /**
-     * Called once per extract with the cache hit/miss decision and the
-     * partial-reuse diagnostic — counts of cached summaries that fine-
-     * grained invalidation would have salvaged on a coarse miss.
-     * Phase 4a uses this to validate the dep-tracking model before
-     * activating partial-reuse.
-     */
     onCacheDiagnostic?: (diagnostic: CacheDiagnostic) => void;
-    /**
-     * Called once per `extractAll` with the funnel: files in the
-     * tsconfig, files walked, and per-pack gate / candidate / unit /
-     * summary counts. The CLI renders it when a run produces nothing,
-     * so "wrote 0 summaries" can say which stage the count died at
-     * instead of leaving the user to guess.
-     *
-     * Not called on a cache hit, where no stage ran.
-     */
+    /** Not called on a cache hit, where no stage ran. */
     onExtractionReport?: (report: ExtractionReport) => void;
-    /**
-     * On-disk cache directory for the extraction cache. Pass an absolute
-     * path; defaults to `.suss/cache/` next to the tsconfig, and to no
-     * cache at all when no tsconfig path is supplied. Pass `null` to turn
-     * caching off. A warm run with nothing changed costs one stat per
-     * file and returns the previous run's summaries whole.
-     *
-     * A process that loaded the adapter from source gets no cache
-     * whatever this says, because a key made there cannot tell one build
-     * of the adapter from another.
-     */
+    /** Absolute. `.suss/cache/` beside the tsconfig; `null` turns it off. */
     cacheDir?: string | null;
 }
-interface TypeScriptAdapter {
-    project: Project;
-    /**
-     * Extract summaries from a specific list of files. Returns a
-     * Promise so the implementation can do concurrent I/O during
-     * the pre-filter / lazy-load phases without bottlenecking on
-     * sync `fs.readFileSync`.
-     */
+interface TypeScriptAdapter extends LanguageAdapter {
+    /** Kept off `LanguageAdapter`, so a caller needing ts-morph asks for it. */
+    readonly tsProject: Project;
     extractFromFiles(filePaths: string[]): Promise<BehavioralSummary[]>;
-    /** Extract summaries from every (non-declaration) file the Project knows about. */
     extractAll(): Promise<BehavioralSummary[]>;
 }
 declare function createTypeScriptAdapter(config: TypeScriptAdapterConfig): TypeScriptAdapter;
@@ -556,19 +510,18 @@ interface FoundTerminal {
      * of an arrow that returns without writing `return`. Absent when the
      * terminal is not a return at all, as a throw is not.
      *
-     * The matcher is the only thing that knows, because `node` is
-     * wherever the matcher stopped looking, which differs by matcher.
-     * Anything downstream that guessed instead got it wrong.
+     * Only the matcher knows this, because `node` is wherever that
+     * matcher stopped looking, which differs from matcher to matcher.
+     * Anything downstream that tried to guess got it wrong.
      */
     source?: Node;
     /**
-     * A test that also has to hold for this terminal to be the one that
+     * A test that also has to be true for this terminal to be the one that
      * fires, on top of whatever the path to it required.
      *
-     * One call site answers with more than one status when the status is
-     * written as a choice, and the arms are told apart by nothing else:
-     * they share a node, so the path engine gives them the same
-     * conditions.
+     * One call site produces more than one status when the status is
+     * written as a choice, and nothing else tells the arms apart: they
+     * share a node, so the path engine gives them the same conditions.
      */
     whenAlso?: RawCondition;
 }
@@ -581,24 +534,20 @@ interface FoundTerminal {
  * terminal output is produced inside a Promise executor or `.then`
  * callback (`res.json(data)` on the unit's own `res` parameter) is still
  * discovered. Inside a nested function only escaping terminals are
- * matched — see `NESTED_ESCAPING_MATCH_TYPES`.
+ * matched: see `NESTED_ESCAPING_MATCH_TYPES`.
  */
 declare function findTerminals(func: FunctionRoot, patterns: TerminalPattern[], barriers?: DescentBarriers): FoundTerminal[];
 
 /**
- * Extract all raw branches from a function, composing:
- *   1. findTerminals, to locate terminal nodes
- *   2. computePathConditions, for the conditions on each path (CFG
- *      enumeration; declined shapes degrade to sound
- *      under-specification)
- *   3. parseConditionExpression, turning an Expression into a Predicate
- *   4. extractInvocationEffects, for bare expression-statement calls,
- *      attached to the default branch so handler and useEffect bodies
- *      carry their side-effect set
+ * Turns one function into the list of branches a summary is built from.
  *
- * `isDefault` is true when the branch has no conditions, or all
- * conditions come from early returns or throws.
+ * Terminal matching, path-condition enumeration, predicate parsing and
+ * effect capture each live in their own module. This one runs them over
+ * the same function and lines the results up: every terminal gets the
+ * conditions on each path that reaches it, and the calls in the body get
+ * attached to the branch they fire on.
  */
+
 /**
  * The branches a function produces, alongside the terminals they came
  * from. A caller that wants to know which returns went unclaimed needs
@@ -609,7 +558,14 @@ interface RawBranchResult {
     branches: RawBranch[];
     terminals: FoundTerminal[];
 }
-declare function extractRawBranches(func: FunctionRoot, terminalPatterns: TerminalPattern[], invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers): RawBranchResult;
+/**
+ * Every branch a function produces: one per path that reaches a
+ * terminal, with the conditions on that path and the effects that fire
+ * along it. A branch is `isDefault` when it has no conditions at all,
+ * or when every condition on it came from an early return or throw,
+ * since those are the paths that run when no guard fired.
+ */
+declare function extractRawBranches(func: FunctionRoot, terminalPatterns: TerminalPattern[], invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers, resolveWrittenValue?: (value: Node) => Node | null): RawBranchResult;
 
 /**
  * A Project covering `rootDir`, for a codebase with no tsconfig to read.
@@ -623,14 +579,30 @@ declare function createProjectWithoutTsconfig(rootDir: string): {
 declare function findNearestTsconfig(startDir: string): string | null;
 
 /**
- * A call a project names as its own dispatcher.
+ * Reads a method call whose receiver has a type the project's config
+ * points at.
  *
- * `receiver` is the type name, not the variable: a service holds its
- * dispatcher in a field, a closure, or a constructor parameter, and
- * only the type is stable across those.
+ * A pack recognizes library calls by their command class, so it only
+ * sees the libraries it was built with. A project that sends every
+ * message through a wrapper of its own writes no such call, and the pack
+ * sees nothing. This lets the project describe the wrapper instead:
+ * which module declares it, which type the receiver has, which method
+ * does the sending, and which arguments the subject and body are in.
+ *
+ * A call on a typed receiver is something TypeScript already tells us,
+ * so reading it belongs to the adapter. What the call means on the bus
+ * is the pack's judgment, so the pack builds the effect from this.
+ */
+
+/**
+ * A call the project has declared to be its own dispatcher.
+ *
+ * `receiver` is the type name rather than the variable: a service keeps
+ * its dispatcher in a field, a closure or a constructor parameter, and
+ * the type is the only thing stable across all three.
  */
 interface ConfiguredCallSpec {
-    /** Module the receiver's type is declared in. */
+    /** Module that declares the receiver's type. */
     module: string;
     /** Type name of the receiver, as exported from that module. */
     receiver: string;
@@ -639,14 +611,14 @@ interface ConfiguredCallSpec {
     /** Argument index carrying the subject. */
     subjectArg: number;
     /**
-     * Argument index carrying the message body. Left out when the
-     * method takes no single body argument (a batch method takes a
-     * list of entries), and then the read carries no body.
+     * Which argument the message body is. Left out when the method has no
+     * single body argument, as a batch method taking a list of entries
+     * does, and then no body is reported.
      */
     bodyArg?: number;
 }
 interface ConfiguredCallRead {
-    /** The subject the call names, always a string the source states. */
+    /** The subject the call sends to, always a literal string. */
     subject: string;
     /** The body argument's extracted shape, or null when none applies. */
     body: EffectArg | null;
@@ -659,13 +631,12 @@ interface ConfiguredCallContext {
     extractArgs(): EffectArg[];
 }
 /**
- * Read `call` as the configured send, or answer null.
+ * Read `call` as the configured send, or return null.
  *
- * A subject that is not a string the source states (a variable built
- * at runtime, a template with substitutions, a computed key) answers
- * null, and the pack emits nothing. Naming a channel we cannot read
- * would pair a producer against the wrong consumer, which is worse
- * than not seeing the producer at all.
+ * A subject that is not a literal string (a value built at runtime, a
+ * template with substitutions, a computed key) returns null and the pack
+ * emits nothing. Guessing a channel we cannot read would pair a producer
+ * with the wrong consumer, which is worse than missing the producer.
  */
 declare function readConfiguredCall(call: CallExpression, ctx: ConfiguredCallContext, spec: ConfiguredCallSpec): ConfiguredCallRead | null;
 
@@ -699,11 +670,11 @@ interface TsDiscoveryContext {
     getFilePath(sourceFile: SourceFile): string;
     /**
      * Yield every export from the source file whose declaration is a
-     * function — function declarations, arrow / function-expression
+     * function: function declarations, arrow / function-expression
      * variable initializers, and re-exports of either. Skips
      * non-function exports (constants, classes, types).
      *
-     * Each entry carries the exported name (the binding the consumer
+     * Each entry has the exported name (the binding the consumer
      * uses), the function root, and whether the export is the file's
      * default export. `default` is included; the pack decides whether
      * to handle it (typically the data-driven `namedExport(["default"])`
@@ -715,24 +686,24 @@ interface TsDiscoveryContext {
         isDefault: boolean;
     }>;
     /**
-     * For an export the project builds by calling a factory, the string a
-     * property of that call's config object holds:
+     * For an export the project builds by calling a factory, the string
+     * under a property of that call's config object:
      * `export const handler = makeWidgetHandler({ subject: "a.b" }, ...)`
-     * with `{ property: "subject" }` answers `"a.b"`.
+     * with `{ property: "subject" }` gives back `"a.b"`.
      *
-     * Which function was called and which argument carried the config are
-     * questions the caller does not have to answer. Every object argument
-     * is read. Naming the callee or fixing the argument position narrows
-     * that, for a project whose factories would otherwise collide.
+     * The caller does not have to say which function was called or which
+     * argument the config was in. Every object argument is read. Giving the
+     * callee or fixing the argument position narrows that down, for a
+     * project whose factories would otherwise collide.
      *
-     * Two arguments holding the property under different values answers
+     * Two arguments with the property set to different values give back
      * null, since nothing says which one was meant.
      *
      * The config argument is usually an object literal at the call site;
      * a variable or import is followed to the literal it resolves to.
      * `as const` and parentheses around the property value are peeled.
      * Anything but a string literal underneath (a computed subject, a
-     * template, a call) answers null — the caller attaches nothing
+     * template, a call) gives back null, and the caller attaches nothing
      * rather than guessing.
      */
     exportedCallConfigString(sourceFile: SourceFile, exportName: string, spec: {
@@ -744,30 +715,61 @@ interface TsDiscoveryContext {
      * Walk a function's body for return statements whose value is a
      * JSX element / fragment / self-closing tag. Returns true on the
      * first match; false otherwise. Skips into nested function bodies
-     * — nested arrow returning JSX is its own component, not part of
+     *: nested arrow returning JSX is its own component, not part of
      * this function's output.
      *
-     * Concise-arrow bodies (`() => <X/>`) are handled — the body IS
+     * Concise-arrow bodies (`() => <X/>`) are handled: the body IS
      * the implicit return.
      */
     hasJsxReturn(func: FunctionRoot): boolean;
 }
 declare function createTsDiscoveryContext(resolution?: ResolutionStore): TsDiscoveryContext;
 
-/** One thing that looks wrong, in the same shape the dogfood invariants report. */
+type ExportedDeclarationMap = ReturnType<SourceFile["getExportedDeclarations"]>;
+/**
+ * What a module exports, by exported name. Cached, because ts-morph
+ * rebuilds the map from scratch on every `getExportedDeclarations` call
+ * and callee resolution asks the same file the same thing once per
+ * import site.
+ */
+declare function exportedDeclarationsOf(sourceFile: SourceFile): ExportedDeclarationMap;
+/**
+ * `Symbol.getAliasedSymbol`, with the re-export chains warmed first so
+ * that an import sitting at the top of a deep chain still resolves
+ * instead of running the call stack out.
+ */
+declare function resolveAliasedSymbol(symbol: Symbol): Symbol | undefined;
+
+/**
+ * Checks that tell you a pack is probably not working.
+ *
+ * The funnel shows where a run's counts dropped to zero. These checks
+ * ask something narrower of each pack on its own: did this pack lose
+ * everything at some stage, when the stage before it had something?
+ *
+ * A pack that finds nothing in a codebase that does not use its library
+ * is working correctly, so a count of zero on its own is never the
+ * signal. What makes zero a signal is the count before it. A pack whose
+ * import gate picked forty files and whose discovery then found no unit
+ * in any of them said "look here" and failed to look. Every later stage
+ * works the same way, which is why these checks are one comparison run
+ * over a list of pairs rather than one check written per stage.
+ */
+
+/** One thing that looks wrong, reported the way the dogfood invariants are. */
 interface HealthViolation {
     label: string;
     detail: string;
 }
 interface HealthCheck {
-    /** The property, as something that either holds or does not. */
+    /** The property being checked, as something either true or false. */
     name: string;
     /**
      * The heading printed when this check finds something.
      *
-     * The property reads as an assertion, so printing `name` above the
-     * violations of it says "no pack collides with itself" and then lists
-     * a pack colliding with itself.
+     * `name` is written as an assertion, so printing it above the
+     * violations would say "no pack collides with itself" and then list a
+     * pack colliding with itself.
      */
     whenBroken: string;
     /**
@@ -775,10 +777,10 @@ interface HealthCheck {
      *
      * A `run` check found something about the code in front of it, and
      * the person who started the run can do something about it: drop a
-     * pack, install a dependency, open an issue with the file that
-     * broke. A `pack` check found something about how a pack was built,
-     * which only whoever ships that pack can fix. Printing the second
-     * kind on every run would teach people to skim past the first.
+     * pack, install a dependency, open an issue with the file that broke.
+     * A `pack` check found something about how a pack was built, which
+     * only whoever ships that pack can fix. Printing the second kind on
+     * every run would teach people to skim past the first.
      */
     audience: "run" | "pack";
     violations: HealthViolation[];
@@ -791,10 +793,10 @@ declare function evaluatePackHealth(report: ExtractionReport): HealthCheck[];
 /**
  * The health checks that fired, as lines for a terminal.
  *
- * `audiences` is who the caller is printing for, and it is required
- * because there is no answer that suits every caller: a CLI run prints
- * what the person who started it can act on, and a run whose reader is
- * a pack author wants both.
+ * `audiences` is who the caller is printing for. It is required because
+ * no single choice suits every caller: a CLI run prints what the person
+ * who started it can act on, while a run a pack author is reading wants
+ * both kinds.
  */
 declare function formatPackHealth(checks: ReadonlyArray<HealthCheck>, audiences: ReadonlyArray<HealthCheck["audience"]>): string;
 
@@ -813,7 +815,7 @@ declare function parseConditionExpression(expr: Expression, depth?: number): Pre
 declare function isImportedFrom(identifier: Node, expectedModule: string): boolean;
 
 interface BranchFieldAccesses {
-    /** Terminal location (start, end lines) — used to match back to transitions */
+    /** Terminal location (start, end lines): used to match back to transitions */
     terminalLocation: {
         start: number;
         end: number;
@@ -828,7 +830,7 @@ interface BranchFieldAccesses {
  * @param callExpr The API call expression (fetch(), client.getUser())
  * @param func The enclosing function
  * @param branchLocations Terminal locations from the extracted branches
- * @param responseSemantics Optional response property mappings from the pack —
+ * @param responseSemantics Optional response property mappings from the pack ,
  *   used to filter non-body properties instead of a hardcoded list
  */
 declare function collectClientFieldAccesses(callExpr: CallExpression, func: Node, branchLocations: Array<{
@@ -838,7 +840,7 @@ declare function collectClientFieldAccesses(callExpr: CallExpression, func: Node
 
 /**
  * Resolve a ts-morph Expression node to a structured ValueRef.
- * Uses only expr.getSymbol()?.getDeclarations()[0] for symbol lookup —
+ * Uses only expr.getSymbol()?.getDeclarations()[0] for symbol lookup ,
  * never findReferencesAsNodes() which is project-wide and quadratic.
  *
  * Follows intermediate variable assignments (const data = result.body)
@@ -854,7 +856,7 @@ declare function resolveSubject(expr: Expression, depth?: number): ValueRef;
  * bodies and source text.
  *
  * All walks are scoped to the parent function and deliberately do NOT
- * recurse into nested function bodies — sub-units of nested functions
+ * recurse into nested function bodies, sub-units of nested functions
  * belong to those functions' summaries, not to the enclosing parent.
  */
 interface TsSubUnitContext {
@@ -867,7 +869,7 @@ interface TsSubUnitContext {
     findJsxAttributes(parent: FunctionRoot): TsJsxAttributeLocation[];
     /**
      * Yield every call expression matching `name` (bare identifier
-     * callee only — e.g. `useEffect(...)`, not `React.useEffect(...)`).
+     * callee only: e.g. `useEffect(...)`, not `React.useEffect(...)`).
      * Nested function bodies are skipped.
      */
     findCallExpressionsByName(parent: FunctionRoot, name: string): CallExpression[];
@@ -912,14 +914,14 @@ interface TsJsxAttributeLocation {
 }
 declare function createTsSubUnitContext(): TsSubUnitContext;
 
-declare const ADAPTER_VERSION = "0.2.0";
+declare const ADAPTER_VERSION = "0.2.1";
 /**
  * Content hash of the given files, in the order they arrive. Empty when
  * the list is empty or a file cannot be read, so a caller that could not
- * place a file gets the same "no stamp" answer as a run from source
+ * locate a file gets the same "no stamp" result as a run from source
  * rather than a hash of a shorter list.
  *
- * The caller resolves the paths, because who a specifier resolves to
+ * The caller resolves the paths, because where a specifier resolves to
  * depends on which package is asking.
  */
 declare function computeContentHash(paths: readonly string[]): string;
@@ -934,13 +936,13 @@ declare function computeContentHash(paths: readonly string[]): string;
  * came from, so folding the config and the code into the stamp is the
  * loader's job.
  *
- * A source run says so in the digest rather than leaving the adapter
- * out of it. Nothing writes under that digest today, and a key that
- * names the mode cannot be mistaken for a key that named the code.
+ * A source run says as much in the digest rather than leaving the
+ * adapter out of it. Nothing writes under that digest today, and a key
+ * that says "source" cannot be mistaken for one built from the code.
  */
 declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     name: string;
     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 Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, isImportedFrom, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, resolveSubject };
+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, 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, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, resolveAliasedSymbol, resolveSubject };