@suss/adapter-typescript 0.34.0 → 0.35.0

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';
@@ -104,6 +104,15 @@ interface PassedArgument {
     call: Node;
     argument: Node;
 }
+/** What a call that takes its function out of a table may run. */
+interface DispatchedCall {
+    /** Every function it may run. */
+    functions: readonly Node[];
+    /** True when the source narrows the call to one entry that is one function. */
+    certain: boolean;
+    /** How many entries came to no function this run read. */
+    unresolved: number;
+}
 /** See `ResolutionStore.envNamers`. */
 interface EnvironmentNamers {
     /**
@@ -149,6 +158,8 @@ declare class ResolutionStore {
     /** See `notePossibleCallers`. */
     private readonly possibleCallers;
     private readonly callerFilesRead;
+    /** Containers whose writes `dispatchedFunctions` has already stated. */
+    private readonly containersRead;
     private stale;
     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. */
@@ -252,6 +263,21 @@ declare class ResolutionStore {
      * arrives at them.
      */
     argumentsPassedTo(parameter: Node): PassedArgument[];
+    /**
+     * What each call may run when it takes its function out of a table or
+     * a map. The writes into each table are read before the answer is,
+     * since a registry fills one from a body no question passes through.
+     * A call that takes no function from a table is left out.
+     */
+    dispatchedFunctions(calls: readonly Node[]): Map<Node, DispatchedCall>;
+    private askDispatch;
+    private nodesFor;
+    /**
+     * States the writes into each container not read before, and reads the
+     * files that may call a function writing one, since a registry is
+     * usually filled by a function its callers pass handlers to.
+     */
+    private readContainerWrites;
     /**
      * The other direction from `argumentsPassedTo`: every call in this
      * parameter's own function, or a closure nested inside it, that hands
@@ -346,6 +372,20 @@ declare class ResolutionStore {
      * what keeps a wrapper's own result apart from the library's.
      */
     returnsCall(func: Node, call: Node): boolean;
+    /**
+     * Each expression a function's returns hand back, as written. Unlike
+     * `returnsCall`, a call into a library comes back too, since a caller
+     * asking this wants to see where the project's own code stops.
+     */
+    returnedValuesOf(func: Node): Node[];
+    /**
+     * Every call made through this parameter, in its own function or in
+     * a closure written inside it, which is how a wrapper runs the
+     * handler it was given.
+     */
+    callsThrough(parameter: Node): Node[];
+    /** Every name the facts record as referring to this declaration. */
+    referencesTo(declaration: Node): Node[];
     /**
      * What the reads of a local do with it, when `receiver` is a local a
      * function declares once as `construction`. Null for anything else,
@@ -556,6 +596,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 +811,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 +824,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
@@ -788,13 +875,21 @@ interface DiscoveredUnit {
      */
     unfollowed?: UnfollowedCall;
     /**
-     * The functions the registration call lists before this handler,
-     * `router.post("/", validate, handler)`, in the order they run. Each
-     * is a unit of its own in the same file, and these references point
-     * the handler at them. They run inside whatever the app registers
-     * for every route, so they are applied after those.
+     * The functions that run around this handler on its route alone, in
+     * the order they run: the ones `router.post("/", validate, handler)`
+     * lists before it, or the layers a route export written as
+     * `withAuth(handler)` puts around it. A reference points at the
+     * layer's own summary, and a layer the run could not read has none.
+     * They run inside whatever the app registers for every route, so they
+     * are applied after those.
      */
     routeWrappers?: WrapperReference[];
+    /**
+     * Set on the closure a wrapper factory hands back: the position of the
+     * factory's parameter it calls to run the handler it was given. That
+     * call is the closure's continuation.
+     */
+    factoryContinuation?: number;
     /**
      * The functions listed before this handler that a project factory
      * returned and the store could not follow, one stop per call.
@@ -831,6 +926,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 +1234,19 @@ 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, or under `SUSS_CACHE_DIR` when that is set;
+     * `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 +1314,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 +1388,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,9 +1586,21 @@ 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[];
 
+/**
+ * The name a property of an object literal is written under, or null
+ * for a spread, which has none, and for a computed key.
+ */
+declare function propertyNameOf(property: Node): string | null;
+
 /**
  * What a value at a discovery site turns out to be, whether it was
  * written out there or referred to by name.
@@ -1472,11 +1636,6 @@ declare function propertyValueOf(property: Node): Node | null;
  * arrives as a parameter, which nothing here can follow.
  */
 declare function functionValueOf(value: Node, resolution: ResolutionStore | undefined): FunctionRoot | null;
-/**
- * The name a property of an object literal is written under, or null
- * for a spread, which has none.
- */
-declare function propertyNameOf(property: Node): string | null;
 /**
  * The function a property of an object literal is set to. A method
  * written into the literal is that function; a property set to a name
@@ -1866,6 +2025,39 @@ 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;
+/** A file as a summary records it: the project it is in, and its path from that project's root. */
+interface FilePlace {
+    /** Absolute. */
+    root: string;
+    workspace: string | null;
+    file: string;
+}
+/**
+ * Where a file belongs when it is read as part of its own project: the
+ * root an extract of that project measures from, the project's name, and
+ * the file's path from that root.
+ */
+declare function projectPlaceOf(file: string): FilePlace;
+/**
+ * Where a file outside the run's root belongs, such as a sibling package
+ * reached through a workspace link, or null for a file under the root.
+ * The path the link leads to never appears, so every checkout agrees.
+ */
+declare function placeOutsideRun(file: string, runRoot: string): FilePlace | null;
+/**
+ * How a summary writes a path on disk that it mentions, such as an
+ * import: its path from the run's root, or the other project's name and
+ * the path from that project's root for a file outside the run.
+ */
+declare function pathFromRun(file: string, runRoot: string): string;
 
 /** What a call writes out, and whether it was serialized as JSON first. */
 interface WrittenPayload {
@@ -1917,7 +2109,7 @@ declare function receiverTypesOf(node: Node): ReceiverType[];
  * that affects extraction output: IR shape, discovery semantics,
  * terminal classification, anything that would invalidate previously
  * cached summaries. `createAdapterStamp` (from `@suss/extractor`) folds
- * it together with a hash of this adapter's own loaded code, so a
+ * it together with a hash of the code this adapter loads, so a
  * rebuilt dev build invalidates the cache even when nobody remembered
  * to bump the constant. See that package's README for the full design.
  */
@@ -1982,4 +2174,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 FilePlace, 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, pathFromRun, peelSyntax, peelValue, placeOutsideRun, projectPlaceOf, 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 };