@suss/adapter-typescript 0.34.1 → 0.35.0

package/dist/index.d.cts

@@ -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,
@@ -835,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.
@@ -1188,7 +1236,8 @@ interface TypeScriptAdapterConfig {
     onExtractionReport?: (report: ExtractionReport) => void;
     /**
      * Absolute. `.suss/cache/` in `walkedDirectory` when set, otherwise
-     * beside the tsconfig; `null` turns it off.
+     * 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. */
@@ -1546,6 +1595,12 @@ declare function specifierImportedAs(sourceFile: SourceFile, local: string): str
 /** 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.
@@ -1581,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
@@ -1983,6 +2033,31 @@ declare function workspaceRootFor(anchor: string): string;
  * 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 {
@@ -2034,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.
  */
@@ -2099,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, 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 };
+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 };

package/dist/index.d.ts

@@ -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,
@@ -835,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.
@@ -1188,7 +1236,8 @@ interface TypeScriptAdapterConfig {
     onExtractionReport?: (report: ExtractionReport) => void;
     /**
      * Absolute. `.suss/cache/` in `walkedDirectory` when set, otherwise
-     * beside the tsconfig; `null` turns it off.
+     * 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. */
@@ -1546,6 +1595,12 @@ declare function specifierImportedAs(sourceFile: SourceFile, local: string): str
 /** 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.
@@ -1581,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
@@ -1983,6 +2033,31 @@ declare function workspaceRootFor(anchor: string): string;
  * 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 {
@@ -2034,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.
  */
@@ -2099,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, 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 };
+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 };