@suss/adapter-typescript 0.22.3 → 0.23.0

package/dist/index.d.cts

@@ -87,6 +87,15 @@ declare class ResolutionStore {
      */
     explainCallable(value: Node, options?: ExplainCallableOptions): ExplainedResolution | null;
     resolveObject(value: Node): Node | null;
+    /**
+     * The function a call returns: `app.use(requireCaller(config))`
+     * registers what the factory gives back. A separate question from
+     * `resolveCallable`, which keeps a call unresolved on purpose so an
+     * unwrapping answer wins; this one is asked only after that has
+     * declined. Two returned functions give null, like every other
+     * single-answer question here.
+     */
+    resolveReturnedCallable(call: Node): Node | null;
     /**
      * For a value that is neither a function nor an object, such as a
      * GraphQL document kept in a constant in another file.
@@ -193,6 +202,7 @@ declare class ResolutionStore {
      */
     private seedValue;
     private lookupObject;
+    private lookupReturned;
     /**
      * Two candidates give null, since ambiguity is nothing. The value
      * itself is never a result either, or an identifier whose chain went
@@ -256,6 +266,21 @@ type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | M
  */
 declare function collectAncestorBranches(terminalNode: Node, functionRoot: FunctionRoot): RawCondition[];
 
+/**
+ * unfollowedCall.ts: naming the calls the reachable closure stops at.
+ *
+ * The closure follows a call by resolving its callee to a function with a
+ * body. When that fails the edge is dropped, and a unit whose body is full
+ * of dropped edges produces the same empty summary as a unit that does
+ * nothing. This module says which kind of stop a call site is. The
+ * reasons, and the gap each one leaves, are shared with every adapter.
+ *
+ * The README beside this file explains where that line is drawn, and why
+ * a call into a dependency stays on the other side of it.
+ */
+
+declare function hasBody(fn: FunctionRoot): boolean;
+
 interface ClientCallSite {
     callExpression: CallExpression;
     /** Method name on the client object (e.g. "getUser"), null for bare calls like fetch() */
@@ -487,6 +512,13 @@ declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPatter
  * on the parent.
  */
 type DescentBarriers = ReadonlySet<Node>;
+declare const NO_BARRIERS: DescentBarriers;
+/**
+ * Does this node return for itself rather than for whatever encloses
+ * it? An accessor and a constructor do, the same way a callback does,
+ * so a getter inside a returned object returns for the getter.
+ */
+declare function startsItsOwnScope(node: Node): boolean;
 
 /**
  * invocationEffects.ts: capture every call in a unit's body as an
@@ -715,15 +747,37 @@ declare function findTerminals(func: FunctionRoot, patterns: TerminalPattern[],
  * attached to the branch they fire on.
  */
 
+/**
+ * Where one call the invocation walk visited ended up. `terminal` is a
+ * call folded into a terminal's own shape (`res.json(body)`).
+ * `invocation` is a call that fires as an effect on at least one
+ * branch. `unreachable` is a call no branch's terminal runs at or
+ * after, so nothing on any path can reach it: dead code below a
+ * `return`, not a gap. `unrecorded` is everything else: a call the
+ * walk saw, that wrote no terminal, and that fires on no branch
+ * despite sitting before one. That last case is a call this pass
+ * dropped.
+ */
+type CallAccountingOutcome = "invocation" | "terminal" | "unreachable" | "unrecorded";
+/** One call the invocation walk visited, and where it ended up. */
+interface CallAccountingEntry {
+    readonly node: CallExpression;
+    readonly callee: string;
+    readonly line: number;
+    readonly outcome: CallAccountingOutcome;
+}
 /**
  * The branches a function produces, alongside the terminals they came
  * from. A caller that wants to know which returns went unclaimed needs
  * the terminals, and searching for them a second time costs about as
- * much as this whole pass.
+ * much as this whole pass. `callAccounting` is present only when a
+ * caller asked for it: a test wanting to assert that every call the
+ * walk visited landed somewhere, rather than a value every run pays for.
  */
 interface RawBranchResult {
     branches: RawBranch[];
     terminals: FoundTerminal[];
+    callAccounting?: CallAccountingEntry[];
 }
 /**
  * Every branch a function produces: one per path that reaches a
@@ -732,7 +786,7 @@ 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): RawBranchResult;
+declare function extractRawBranches(func: FunctionRoot, terminalPatterns: TerminalPattern[], invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers, resolution?: ResolutionStore, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf, resolveCallee?: ResolveCallee, collectCallAccounting?: boolean): RawBranchResult;
 
 /**
  * A Project covering `rootDir`, for a codebase with no tsconfig to read.
@@ -1062,6 +1116,14 @@ declare function functionTargetOf(node: Identifier): {
     name: string;
 } | null;
 
+/**
+ * The three terminal shapes any function has, whatever pack discovered
+ * it: a `return`, a `throw`, or falling off the end. The call-accounting
+ * check classifies a call against these, since it reads arbitrary
+ * source with no pack in front of it.
+ */
+declare const GENERIC_TERMINALS: TerminalPattern[];
+
 /**
  * What a name-valued expression says, as fixed text with a hole for
  * each part built at run time. A table name, a bucket, a queue URL and
@@ -1271,4 +1333,4 @@ declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     version?: string;
 }>): string;
 
-export { ADAPTER_VERSION, type Accessed, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type ExplainCallableOptions, type ExplainedResolution, type FoundTerminal, type FunctionRoot, type ImportScanOptions, type ObservedStubCall, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, TypeScriptWhySession, type WhySessionOptions, accessContextFor, buildProjectHelperIndex, callOpsFor, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, functionTargetOf, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isImportedFrom, methodDeclaredIn, namedImportsOf, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, stubEvidence, stubEvidenceIn, workspaceRootFor };
+export { ADAPTER_VERSION, type Accessed, type CallAccountingEntry, type CallAccountingOutcome, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DescentBarriers, type DiscoveredUnit, type ExplainCallableOptions, type ExplainedResolution, type FoundTerminal, type FunctionRoot, GENERIC_TERMINALS, type ImportScanOptions, NO_BARRIERS, type ObservedStubCall, type RawBranchResult, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, TypeScriptWhySession, type WhySessionOptions, accessContextFor, buildProjectHelperIndex, callOpsFor, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, functionTargetOf, hasBody, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isImportedFrom, methodDeclaredIn, namedImportsOf, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, startsItsOwnScope, stubEvidence, stubEvidenceIn, workspaceRootFor };

package/dist/index.d.ts

@@ -87,6 +87,15 @@ declare class ResolutionStore {
      */
     explainCallable(value: Node, options?: ExplainCallableOptions): ExplainedResolution | null;
     resolveObject(value: Node): Node | null;
+    /**
+     * The function a call returns: `app.use(requireCaller(config))`
+     * registers what the factory gives back. A separate question from
+     * `resolveCallable`, which keeps a call unresolved on purpose so an
+     * unwrapping answer wins; this one is asked only after that has
+     * declined. Two returned functions give null, like every other
+     * single-answer question here.
+     */
+    resolveReturnedCallable(call: Node): Node | null;
     /**
      * For a value that is neither a function nor an object, such as a
      * GraphQL document kept in a constant in another file.
@@ -193,6 +202,7 @@ declare class ResolutionStore {
      */
     private seedValue;
     private lookupObject;
+    private lookupReturned;
     /**
      * Two candidates give null, since ambiguity is nothing. The value
      * itself is never a result either, or an identifier whose chain went
@@ -256,6 +266,21 @@ type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | M
  */
 declare function collectAncestorBranches(terminalNode: Node, functionRoot: FunctionRoot): RawCondition[];
 
+/**
+ * unfollowedCall.ts: naming the calls the reachable closure stops at.
+ *
+ * The closure follows a call by resolving its callee to a function with a
+ * body. When that fails the edge is dropped, and a unit whose body is full
+ * of dropped edges produces the same empty summary as a unit that does
+ * nothing. This module says which kind of stop a call site is. The
+ * reasons, and the gap each one leaves, are shared with every adapter.
+ *
+ * The README beside this file explains where that line is drawn, and why
+ * a call into a dependency stays on the other side of it.
+ */
+
+declare function hasBody(fn: FunctionRoot): boolean;
+
 interface ClientCallSite {
     callExpression: CallExpression;
     /** Method name on the client object (e.g. "getUser"), null for bare calls like fetch() */
@@ -487,6 +512,13 @@ declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPatter
  * on the parent.
  */
 type DescentBarriers = ReadonlySet<Node>;
+declare const NO_BARRIERS: DescentBarriers;
+/**
+ * Does this node return for itself rather than for whatever encloses
+ * it? An accessor and a constructor do, the same way a callback does,
+ * so a getter inside a returned object returns for the getter.
+ */
+declare function startsItsOwnScope(node: Node): boolean;
 
 /**
  * invocationEffects.ts: capture every call in a unit's body as an
@@ -715,15 +747,37 @@ declare function findTerminals(func: FunctionRoot, patterns: TerminalPattern[],
  * attached to the branch they fire on.
  */
 
+/**
+ * Where one call the invocation walk visited ended up. `terminal` is a
+ * call folded into a terminal's own shape (`res.json(body)`).
+ * `invocation` is a call that fires as an effect on at least one
+ * branch. `unreachable` is a call no branch's terminal runs at or
+ * after, so nothing on any path can reach it: dead code below a
+ * `return`, not a gap. `unrecorded` is everything else: a call the
+ * walk saw, that wrote no terminal, and that fires on no branch
+ * despite sitting before one. That last case is a call this pass
+ * dropped.
+ */
+type CallAccountingOutcome = "invocation" | "terminal" | "unreachable" | "unrecorded";
+/** One call the invocation walk visited, and where it ended up. */
+interface CallAccountingEntry {
+    readonly node: CallExpression;
+    readonly callee: string;
+    readonly line: number;
+    readonly outcome: CallAccountingOutcome;
+}
 /**
  * The branches a function produces, alongside the terminals they came
  * from. A caller that wants to know which returns went unclaimed needs
  * the terminals, and searching for them a second time costs about as
- * much as this whole pass.
+ * much as this whole pass. `callAccounting` is present only when a
+ * caller asked for it: a test wanting to assert that every call the
+ * walk visited landed somewhere, rather than a value every run pays for.
  */
 interface RawBranchResult {
     branches: RawBranch[];
     terminals: FoundTerminal[];
+    callAccounting?: CallAccountingEntry[];
 }
 /**
  * Every branch a function produces: one per path that reaches a
@@ -732,7 +786,7 @@ 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): RawBranchResult;
+declare function extractRawBranches(func: FunctionRoot, terminalPatterns: TerminalPattern[], invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers, resolution?: ResolutionStore, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf, resolveCallee?: ResolveCallee, collectCallAccounting?: boolean): RawBranchResult;
 
 /**
  * A Project covering `rootDir`, for a codebase with no tsconfig to read.
@@ -1062,6 +1116,14 @@ declare function functionTargetOf(node: Identifier): {
     name: string;
 } | null;
 
+/**
+ * The three terminal shapes any function has, whatever pack discovered
+ * it: a `return`, a `throw`, or falling off the end. The call-accounting
+ * check classifies a call against these, since it reads arbitrary
+ * source with no pack in front of it.
+ */
+declare const GENERIC_TERMINALS: TerminalPattern[];
+
 /**
  * What a name-valued expression says, as fixed text with a hole for
  * each part built at run time. A table name, a bucket, a queue URL and
@@ -1271,4 +1333,4 @@ declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     version?: string;
 }>): string;
 
-export { ADAPTER_VERSION, type Accessed, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type ExplainCallableOptions, type ExplainedResolution, type FoundTerminal, type FunctionRoot, type ImportScanOptions, type ObservedStubCall, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, TypeScriptWhySession, type WhySessionOptions, accessContextFor, buildProjectHelperIndex, callOpsFor, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, functionTargetOf, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isImportedFrom, methodDeclaredIn, namedImportsOf, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, stubEvidence, stubEvidenceIn, workspaceRootFor };
+export { ADAPTER_VERSION, type Accessed, type CallAccountingEntry, type CallAccountingOutcome, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DescentBarriers, type DiscoveredUnit, type ExplainCallableOptions, type ExplainedResolution, type FoundTerminal, type FunctionRoot, GENERIC_TERMINALS, type ImportScanOptions, NO_BARRIERS, type ObservedStubCall, type RawBranchResult, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, TypeScriptWhySession, type WhySessionOptions, accessContextFor, buildProjectHelperIndex, callOpsFor, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, functionTargetOf, hasBody, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isImportedFrom, methodDeclaredIn, namedImportsOf, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, startsItsOwnScope, stubEvidence, stubEvidenceIn, workspaceRootFor };