@suss/adapter-typescript 0.35.1 → 0.37.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { SourceFile, Node, Project, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, Symbol, CallExpression, NewExpression, TaggedTemplateExpression, PropertyAccessExpression, Expression, ImportDeclaration, ArrayLiteralExpression, ObjectLiteralExpression, ObjectLiteralElementLike, Identifier } from 'ts-morph';
+import { Node, SourceFile, Project, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, ConstructorDeclaration, 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';
@@ -13,6 +13,11 @@ interface RuntimeSpellings {
     exitCalls: readonly string[];
     exitCodeWrites: readonly string[];
 }
+/**
+ * The dotted path an expression spells, when every part of it is an
+ * identifier or it starts at `import.meta`, as `import.meta.env` does.
+ */
+declare function dottedPathOf(expression: Node): string | null;
 
 /**
  * A library's own module, written into the project by that library's
@@ -635,7 +640,12 @@ type AppVersioning = {
     defaultVersion: StatedVersion;
 };
 
-type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | MethodDeclaration;
+/**
+ * A function a unit is built on. A constructor is one, since `new
+ * Client()` runs its body and its parameters' defaults the way a call
+ * runs a function's.
+ */
+type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | MethodDeclaration | ConstructorDeclaration;
 /**
  * Public API: returns RawCondition[] with structured: null.
  * Use collectAncestorConditionInfos when you need the Expression nodes.
@@ -664,6 +674,34 @@ declare function hasBody(fn: Node): boolean;
  */
 declare function declarationsBehind(symbol: Symbol | undefined): Node[];
 
+/**
+ * graphqlCallClient.ts: the client an operation's own call passes, read
+ * at that one call.
+ *
+ * Apollo sends a hook's operation through the client the app provides,
+ * unless the call passes a `client` option, and an imperative
+ * `client.query` goes through the client it is called on. A project
+ * hook that picks the client from an option of its own decides per
+ * caller, so the caller's arguments are bound before the choice is
+ * read. Each client construction the packs describe is replaced by a
+ * token of its own, and the evaluator says which token the choice comes
+ * out as. The README beside this file says what becomes of an operation
+ * whose choice stays open.
+ */
+
+/** Where one operation's call takes its client. */
+interface GraphqlCallSite {
+    /** The library call that sends the operation. */
+    call: CallExpression;
+    /** The project's own wrapper calls between the unit and `call`, innermost first. */
+    through: CallExpression[];
+    /** The client is the receiver of `call`, or an option in one of its arguments. */
+    client: "receiver" | {
+        argument: number;
+        property: string;
+    };
+}
+
 interface ClientCallSite {
     callExpression: CallExpression;
     /** Method name on the client object (e.g. "getUser"), null for bare calls like fetch() */
@@ -784,6 +822,8 @@ interface DiscoveredUnit {
             reason: string;
         };
     };
+    /** Where the operation's call takes its client, read once the pack's client constructions are known. */
+    graphqlCall?: GraphqlCallSite;
     /**
      * Populated by `packageExports` discovery. Has the package identity
      * the adapter uses to build a `function-call` binding
@@ -1363,7 +1403,7 @@ interface ResponseHandOffOptions {
 type CallAccountingOutcome = "invocation" | "terminal" | "unreachable" | "unrecorded";
 /** One call the invocation walk visited, and where it ended up. */
 interface CallAccountingEntry {
-    readonly node: CallExpression;
+    readonly node: CallExpression | NewExpression;
     readonly callee: string;
     readonly line: number;
     readonly outcome: CallAccountingOutcome;
@@ -1685,6 +1725,8 @@ declare function writtenNodeOf(value: Node, resolution: ResolutionStore | undefi
  * empty" from "could not read" (#123).
  */
 declare function stringValueOf(value: Node, resolution: ResolutionStore | undefined): string | null;
+/** The one string, number or boolean this value comes to, or null when it does not settle to one. */
+declare function scalarValueOf(value: Node, resolution: ResolutionStore | undefined): string | number | boolean | null;
 /** The number this value comes to, or null when it does not settle to one. */
 declare function numberValueOf(value: Node, resolution: ResolutionStore | undefined): number | null;
 /**
@@ -2157,6 +2199,13 @@ declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
  * presence test has passed.
  */
 declare function isDefaultedAt(node: Node): boolean;
+/**
+ * The expression that supplies a value when the read comes back empty:
+ * the right side of the `??` or `||` the read falls back through, or a
+ * destructured read's own default, as in `const { X = "d" } = env`.
+ * Null when nothing falls back from the read itself.
+ */
+declare function fallbackOf(read: Node): Node | null;
 
 /**
  * The expression inside any type-level wrappers: `as` and
@@ -2181,4 +2230,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 FilePlace, type FoundTerminal, type FunctionRoot, GENERIC_TERMINALS, type ImportScanOptions, NO_BARRIERS, type ObservedStubCall, type RawBranchResult, type ReadNameOptions, type ReceiverType, type RefreshReport, ResolutionStore, SKIP_DIRECTORIES, 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 };
+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, SKIP_DIRECTORIES, 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, dottedPathOf, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, fallbackOf, 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, scalarValueOf, specifierImportedAs, startsItsOwnScope, stringPropertyOf, stringValueOf, stubEvidence, stubEvidenceIn, symbolBehind, toFunctionRoot, workspaceNameFor, workspaceRootFor, writtenNodeOf, writtenPayloadOf };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SourceFile, Node, Project, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, Symbol, CallExpression, NewExpression, TaggedTemplateExpression, PropertyAccessExpression, Expression, ImportDeclaration, ArrayLiteralExpression, ObjectLiteralExpression, ObjectLiteralElementLike, Identifier } from 'ts-morph';
+import { Node, SourceFile, Project, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, ConstructorDeclaration, 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';
@@ -13,6 +13,11 @@ interface RuntimeSpellings {
     exitCalls: readonly string[];
     exitCodeWrites: readonly string[];
 }
+/**
+ * The dotted path an expression spells, when every part of it is an
+ * identifier or it starts at `import.meta`, as `import.meta.env` does.
+ */
+declare function dottedPathOf(expression: Node): string | null;
 
 /**
  * A library's own module, written into the project by that library's
@@ -635,7 +640,12 @@ type AppVersioning = {
     defaultVersion: StatedVersion;
 };
 
-type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | MethodDeclaration;
+/**
+ * A function a unit is built on. A constructor is one, since `new
+ * Client()` runs its body and its parameters' defaults the way a call
+ * runs a function's.
+ */
+type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | MethodDeclaration | ConstructorDeclaration;
 /**
  * Public API: returns RawCondition[] with structured: null.
  * Use collectAncestorConditionInfos when you need the Expression nodes.
@@ -664,6 +674,34 @@ declare function hasBody(fn: Node): boolean;
  */
 declare function declarationsBehind(symbol: Symbol | undefined): Node[];
 
+/**
+ * graphqlCallClient.ts: the client an operation's own call passes, read
+ * at that one call.
+ *
+ * Apollo sends a hook's operation through the client the app provides,
+ * unless the call passes a `client` option, and an imperative
+ * `client.query` goes through the client it is called on. A project
+ * hook that picks the client from an option of its own decides per
+ * caller, so the caller's arguments are bound before the choice is
+ * read. Each client construction the packs describe is replaced by a
+ * token of its own, and the evaluator says which token the choice comes
+ * out as. The README beside this file says what becomes of an operation
+ * whose choice stays open.
+ */
+
+/** Where one operation's call takes its client. */
+interface GraphqlCallSite {
+    /** The library call that sends the operation. */
+    call: CallExpression;
+    /** The project's own wrapper calls between the unit and `call`, innermost first. */
+    through: CallExpression[];
+    /** The client is the receiver of `call`, or an option in one of its arguments. */
+    client: "receiver" | {
+        argument: number;
+        property: string;
+    };
+}
+
 interface ClientCallSite {
     callExpression: CallExpression;
     /** Method name on the client object (e.g. "getUser"), null for bare calls like fetch() */
@@ -784,6 +822,8 @@ interface DiscoveredUnit {
             reason: string;
         };
     };
+    /** Where the operation's call takes its client, read once the pack's client constructions are known. */
+    graphqlCall?: GraphqlCallSite;
     /**
      * Populated by `packageExports` discovery. Has the package identity
      * the adapter uses to build a `function-call` binding
@@ -1363,7 +1403,7 @@ interface ResponseHandOffOptions {
 type CallAccountingOutcome = "invocation" | "terminal" | "unreachable" | "unrecorded";
 /** One call the invocation walk visited, and where it ended up. */
 interface CallAccountingEntry {
-    readonly node: CallExpression;
+    readonly node: CallExpression | NewExpression;
     readonly callee: string;
     readonly line: number;
     readonly outcome: CallAccountingOutcome;
@@ -1685,6 +1725,8 @@ declare function writtenNodeOf(value: Node, resolution: ResolutionStore | undefi
  * empty" from "could not read" (#123).
  */
 declare function stringValueOf(value: Node, resolution: ResolutionStore | undefined): string | null;
+/** The one string, number or boolean this value comes to, or null when it does not settle to one. */
+declare function scalarValueOf(value: Node, resolution: ResolutionStore | undefined): string | number | boolean | null;
 /** The number this value comes to, or null when it does not settle to one. */
 declare function numberValueOf(value: Node, resolution: ResolutionStore | undefined): number | null;
 /**
@@ -2157,6 +2199,13 @@ declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
  * presence test has passed.
  */
 declare function isDefaultedAt(node: Node): boolean;
+/**
+ * The expression that supplies a value when the read comes back empty:
+ * the right side of the `??` or `||` the read falls back through, or a
+ * destructured read's own default, as in `const { X = "d" } = env`.
+ * Null when nothing falls back from the read itself.
+ */
+declare function fallbackOf(read: Node): Node | null;
 
 /**
  * The expression inside any type-level wrappers: `as` and
@@ -2181,4 +2230,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 FilePlace, type FoundTerminal, type FunctionRoot, GENERIC_TERMINALS, type ImportScanOptions, NO_BARRIERS, type ObservedStubCall, type RawBranchResult, type ReadNameOptions, type ReceiverType, type RefreshReport, ResolutionStore, SKIP_DIRECTORIES, 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 };
+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, SKIP_DIRECTORIES, 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, dottedPathOf, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, fallbackOf, 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, scalarValueOf, specifierImportedAs, startsItsOwnScope, stringPropertyOf, stringValueOf, stubEvidence, stubEvidenceIn, symbolBehind, toFunctionRoot, workspaceNameFor, workspaceRootFor, writtenNodeOf, writtenPayloadOf };