@suss/adapter-typescript 0.34.0 → 0.34.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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';
+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, Effect, BehavioralSummary, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
 import { ExplainStats, SourceLeaf, ValueUses, WhyExplained, ValueLocation } from '@suss/resolution';
@@ -556,6 +556,45 @@ interface GlobalPrefix {
     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.
@@ -732,6 +771,12 @@ 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
@@ -739,6 +784,8 @@ interface DiscoveredUnit {
      * 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
@@ -831,6 +878,8 @@ interface MountPrefixIndex {
      * 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
@@ -1137,10 +1186,18 @@ 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. */
@@ -1208,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.
  *
@@ -1257,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.
@@ -1434,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[];
 
@@ -1866,6 +1975,14 @@ 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 {
@@ -1982,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, 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 };
+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 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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';
+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, Effect, BehavioralSummary, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
 import { ExplainStats, SourceLeaf, ValueUses, WhyExplained, ValueLocation } from '@suss/resolution';
@@ -556,6 +556,45 @@ interface GlobalPrefix {
     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.
@@ -732,6 +771,12 @@ 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
@@ -739,6 +784,8 @@ interface DiscoveredUnit {
      * 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
@@ -831,6 +878,8 @@ interface MountPrefixIndex {
      * 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
@@ -1137,10 +1186,18 @@ 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. */
@@ -1208,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.
  *
@@ -1257,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.
@@ -1434,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[];
 
@@ -1866,6 +1975,14 @@ 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 {
@@ -1982,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, 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 };
+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 };