@suss/adapter-typescript 0.29.0 → 0.31.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, PropertyAccessExpression, TaggedTemplateExpression, Project, ImportDeclaration, Symbol, Expression, NewExpression, Identifier } from 'ts-morph';
+import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, PropertyAccessExpression, TaggedTemplateExpression, Project, ImportDeclaration, ArrayLiteralExpression, ObjectLiteralExpression, ObjectLiteralElementLike, Symbol, Expression, NewExpression, Identifier } from 'ts-morph';
 import { TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, EffectArg, CallOps, LanguageAdapter, PatternPack, ExtractorOptions, TimingReport, CacheDiagnostic, ExtractionReport, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, configuredCallOption, RawDeclaredContract, ContractPattern, AstCapableOps, ResponsePropertyMapping } from '@suss/extractor';
 export { EmptyStage, ExtractionReport, PackFunnel, Timer, TimingReport, computeContentHash } from '@suss/extractor';
 import { MessageBusSemantics, DeployableUnit, UnfollowedCall, WrapperReference, BehavioralSummary, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
@@ -14,18 +14,17 @@ interface FileSetQuery {
 }
 
 /**
- * The resolution store, and the three questions callers ask it.
+ * The resolution store, and the questions callers ask it.
  *
  * `resolveCallable` says which function a value comes down to, through
  * any depth of aliasing, imports, re-export barrels, wrapper factories
  * and `.bind`. `resolveWrittenValue` says which expression a value is
  * written as, for callers chasing something that is neither a function
- * nor an object. `filesImportingTransitively` says which of a set of
- * files reach any of a set of packages, which a per-file import check
- * misses whenever a local barrel re-exports the SDK.
- *
- * A query extracts the modules the rules ask for while answering it,
- * so the files a question reads do not depend on what was asked before.
+ * nor an object. `argumentsPassedTo` and `callsPassing` go from a
+ * parameter to the calls that filled it, or the ones it hands to.
+ * `filesImportingTransitively` says which of a set of files reach any
+ * of a set of packages, which a per-file import check misses whenever a
+ * local barrel re-exports the SDK.
  */
 
 interface ExplainCallableOptions {
@@ -42,6 +41,11 @@ interface ExplainedResolution {
     nodeFor: (atom: Atom) => Node | undefined;
     stats: ExplainStats;
 }
+/** One call of a function, and what it wrote at one parameter. */
+interface PassedArgument {
+    call: Node;
+    argument: Node;
+}
 declare class ResolutionStore {
     private readonly db;
     private readonly table;
@@ -57,10 +61,16 @@ declare class ResolutionStore {
      * extraction elsewhere cannot change an entry.
      */
     private readonly exportTables;
+    /** Keyed by value and site both, since one value differs per site. */
+    private readonly writtenUnderSite;
+    private readonly constructionSites;
     /** Files the most recent query read, for the memo to keep. */
     private lastQueryWalked;
     private readonly declarations;
     private readonly graph;
+    /** See `notePossibleCallers`. */
+    private readonly possibleCallers;
+    private readonly callerFilesRead;
     private stale;
     constructor(wrappers?: TransparentWrapper[]);
     /**
@@ -101,6 +111,54 @@ declare class ResolutionStore {
      * GraphQL document kept in a constant in another file.
      */
     resolveWrittenValue(value: Node): Node | null;
+    /**
+     * The same question under one construction site: what the value is
+     * when the receiver behind it is the instance that site made. A field
+     * two constructions fill differently settles here and not context
+     * free, where two answers are ambiguity.
+     */
+    resolveWrittenValueUnder(value: Node, site: string): Node | null;
+    /**
+     * Every construction of this class the run can see, as fact keys, for
+     * a caller about to ask a value question under each. A class nothing
+     * constructs has none.
+     */
+    constructionSitesOf(cls: Node): string[];
+    /**
+     * Every call of the function this parameter belongs to, with the
+     * argument that call wrote at it, as the caller wrote it. The reading
+     * is left to the asker, who knows what kind of value it is after.
+     *
+     * The callers are in files that import the parameter's own, so they
+     * are read into the store first; no query starting at the parameter
+     * arrives at them.
+     */
+    argumentsPassedTo(parameter: Node): PassedArgument[];
+    /**
+     * The other direction from `argumentsPassedTo`: every call in this
+     * parameter's own function, or a closure nested inside it, that hands
+     * the parameter to something else. `callArg` keeps the argument as a
+     * bare reference, so the join is against `binds` rather than the
+     * parameter's own key; a reference only binds to a parameter in scope
+     * where it is written, which already keeps the answer inside the
+     * parameter's own function with no join against `bodyCalls` needed.
+     */
+    callsPassing(parameter: Node): PassedArgument[];
+    /**
+     * Whether running this function hands back that call: returned
+     * outright, written into a name and returned, or a shorthand body.
+     * A call whose own callee the rules cannot follow is not, which is
+     * what keeps a wrapper's own result apart from the library's.
+     */
+    returnsCall(func: Node, call: Node): boolean;
+    /**
+     * Files a later question about a parameter may find a caller in.
+     * Without this the search falls back to every file the project has
+     * loaded, which reads more of the import graph than a run needs.
+     */
+    notePossibleCallers(sourceFiles: Iterable<SourceFile>): void;
+    private readPossibleCallersOf;
+    private callerCandidates;
     /**
      * The construction behind a registration subject: the call or `new`
      * this value is written as, kept only when its callee comes from
@@ -285,6 +343,12 @@ interface ClientCallSite {
     callExpression: CallExpression;
     /** Method name on the client object (e.g. "getUser"), null for bare calls like fetch() */
     methodName: string | null;
+    /**
+     * The construction of the surrounding class to read the request
+     * under, for a call whose path or method a constructor argument
+     * states. Absent for a call that says what it reaches on its own.
+     */
+    under?: string;
 }
 interface DiscoveredUnit {
     /**
@@ -388,6 +452,8 @@ interface DiscoveredUnit {
         rootFields: string[];
         /** Spreads in `document` with no definition in it: read partially. */
         unresolvedFragments?: string[];
+        /** Spreads the project defines more than once, with different bodies. */
+        ambiguousFragments?: string[];
         unresolved?: {
             reference: string;
             reason: string;
@@ -482,6 +548,8 @@ interface DiscoveredUnit {
      */
     routeUnfollowed?: UnfollowedCall[];
 }
+/** Walk to the nearest enclosing function-shaped node, or null if none. */
+declare function findEnclosingFunction(node: Node): FunctionRoot | null;
 
 /**
  * What a route's path should be composed with once mount discovery has
@@ -564,6 +632,12 @@ interface TsAccessRecognizerContext {
      * and the recognizer's own pattern match runs on the raw node.
      */
     resolveWrittenValue: (value: Node) => Node | null;
+    /**
+     * The run's store, for a recognizer reading a value through the
+     * adapter's shared resolvers rather than one hop at a time.
+     * Undefined when the run has no store.
+     */
+    resolution?: ResolutionStore;
     /**
      * What a declared pack asks about this node, when the node is a call
      * or a tagged template. This walk visits property accesses as well,
@@ -617,6 +691,12 @@ interface TsInvocationRecognizerContext {
      * binding is correct.
      */
     resolveWrittenValue(value: Node): Node | null;
+    /**
+     * The run's store, for a recognizer reading a value through the
+     * adapter's shared resolvers rather than one hop at a time.
+     * Undefined when the run has no store.
+     */
+    resolution?: ResolutionStore;
     /**
      * What a declared pack asks about this call, in the vocabulary
      * `@suss/extractor` defines. A pack written as a chain of data links
@@ -631,7 +711,7 @@ interface TsInvocationRecognizerContext {
  * A pack's tests build it here too, so a pack that passes them has run
  * against the context extraction gives it.
  */
-declare function invocationContextFor(call: CallExpression, resolveWrittenValue?: (value: Node) => Node | null, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf): TsInvocationRecognizerContext;
+declare function invocationContextFor(call: CallExpression, resolution?: ResolutionStore, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf): TsInvocationRecognizerContext;
 /**
  * Whether a value's chain reaches the module, asked of the store. The
  * adapter binds it; a context built bare falls back to the checker's
@@ -664,7 +744,7 @@ type Accessed = PropertyAccessExpression | CallExpression | TaggedTemplateExpres
  * A pack's tests build it here too, so a pack that passes them has run
  * against the context extraction gives it.
  */
-declare function accessContextFor(node: Accessed, sourceFile: SourceFile, resolveWrittenValue?: (value: Node) => Node | null, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf): TsAccessRecognizerContext;
+declare function accessContextFor(node: Accessed, sourceFile: SourceFile, resolution?: ResolutionStore, originatesFrom?: OriginatesFrom, anchorCallsOf?: AnchorCallsOf): TsAccessRecognizerContext;
 
 /** Resolves a helper callee to its declaration; the adapter binds the store's ask. */
 type ResolveCallee = (callee: Node) => Node | null;
@@ -979,7 +1059,104 @@ declare function importedRootsOf(sourceFile: SourceFile, modules: readonly strin
 /** Every import declaration in the file that names one of `modules`. */
 declare function importDeclarationsOf(sourceFile: SourceFile, modules: readonly string[], options?: ImportScanOptions): ImportDeclaration[];
 
+/**
+ * What a value at a discovery site turns out to be, whether it was
+ * written out there or referred to by name.
+ *
+ * A recognizer reading an argument, a property or a loop's iterable is
+ * asking one of two things: which function is this, and which object is
+ * this. The resolution store settles both over the fact layer, which
+ * follows a name through a property read, an array element, an alias, an
+ * import and a barrel. A recognizer that reads the syntax at the
+ * position instead sees an identifier and gets no further.
+ */
+
+/**
+ * Whether a value is a name rather than something written out where it
+ * is used. A route's path argument is a string, and asking the fact
+ * layer about that pulls in the file's import closure to produce a null
+ * that was never in doubt.
+ */
+declare function couldNameAValue(value: Node): boolean;
+/**
+ * The expression a property of an object literal is set to, when it has
+ * one. A shorthand property is set to whatever its name refers to, so
+ * the name node is the expression.
+ */
+declare function propertyValueOf(property: Node): Node | null;
+/**
+ * The function this value is, whether it was written out here or
+ * referred to by name.
+ *
+ * A value the rules can reach two different functions from returns null,
+ * because picking one would report a boundary's behaviour from a
+ * function that may not be the one that runs. So does a handler that
+ * 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
+ * or a call is followed the way `functionValueOf` follows any value.
+ */
+declare function propertyFunctionOf(property: Node, resolution: ResolutionStore | undefined): FunctionRoot | null;
+/** The object literal this value is, written out here or named. */
+declare function objectLiteralOf(value: Node, resolution: ResolutionStore | undefined): ObjectLiteralExpression | null;
+/**
+ * The properties of an object literal, with a spread replaced by the
+ * properties of whatever it spreads.
+ *
+ * A spread is a name in property position, so it is the same question
+ * `objectLiteralOf` settles. A spread of something the rules cannot
+ * reach an object from contributes nothing, the same as a property whose
+ * value nothing resolves. An object that spreads its way back to itself
+ * is walked once.
+ */
+declare function propertiesOf(object: ObjectLiteralExpression, resolution: ResolutionStore | undefined): ObjectLiteralElementLike[];
+/**
+ * What an object sets one named property to, with a spread walked and
+ * a shorthand giving back the name it forwards. Null when nothing in
+ * the object sets that name.
+ */
+declare function propertyOf(object: ObjectLiteralExpression, name: string, resolution: ResolutionStore | undefined): Node | null;
+/**
+ * The expression `value` comes down to, whatever kind of expression that
+ * turns out to be, whether it was a name or written out where it is
+ * used. A mount call's target argument is sometimes a call or `new`
+ * expression right there (`app.use("/x", Router())`) and sometimes a
+ * name imported from wherever the sub-router is declared. A caller
+ * comparing that against another value's creation site does not care
+ * which.
+ */
+declare function writtenNodeOf(value: Node, resolution: ResolutionStore | undefined): Node | null;
+/**
+ * The string this value comes to, with every name the evaluator can
+ * follow folded in. Null rather than the empty string when the value
+ * does not settle to one string, so a caller can tell "stated as
+ * empty" from "could not read" (#123).
+ */
+declare function stringValueOf(value: Node, resolution: ResolutionStore | undefined): string | null;
+/**
+ * The string a named property of an object is set to, with the object
+ * and the value each read through whatever name they were given.
+ * `fetch(url, { method })`, `fetch(url, opts)` and `{ ...base, method }`
+ * are all read here. Null when the property is absent or not a string.
+ */
+declare function stringPropertyOf(object: Node, name: string, resolution: ResolutionStore | undefined, site?: string): string | null;
+/** The array literal this value is, written out here or named. */
+declare function arrayLiteralOf(value: Node, resolution: ResolutionStore | undefined): ArrayLiteralExpression | null;
+
 interface TsDiscoveryContext {
+    /**
+     * The run's store, for a pack reading a value through the adapter's
+     * shared resolvers rather than the syntax at the position.
+     */
+    resolution: ResolutionStore;
     /** Full filesystem path of the source file. Useful for excluding
      *  test / story files via the pack's own regex. */
     getFilePath(sourceFile: SourceFile): string;
@@ -1126,6 +1303,12 @@ declare function callOpsFor(call: Called, resolveWrittenValue?: Resolve, origina
  * closure takes `resolveDecl` for the function root itself.
  */
 
+/**
+ * The symbol a reference resolves to. A shorthand property
+ * (`{ roomId }`) gives its identifier the property's symbol, and the
+ * local binding it reads is behind `getValueSymbol`.
+ */
+declare function symbolBehind(node: Identifier): Symbol | undefined;
 /**
  * The function an identifier refers to, as its declaration's file and
  * name, for joins that never walk the body. Null when the reference
@@ -1354,4 +1537,46 @@ declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     version?: string;
 }>): string;
 
-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, TSCONFIG_NAMES, 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 };
+/**
+ * defaulted.ts: whether a read has something behind it.
+ *
+ * `??` and `||` are ECMAScript, not anything a pack defines, so the
+ * packs that record a read ask here instead of each spelling the
+ * operators out. This is a separate file from unwrap.ts because that
+ * one is about wrappers, and a fallback is not one.
+ */
+
+/**
+ * Whether something else supplies a value when this read comes back
+ * empty. `env.X ?? "default"` and `env.X || other` both do, and so does
+ * the middle of a chain: in `env.A || env.B || undefined`, B's fallback
+ * is the chain's tail. The climb stops when the read is the final
+ * operand (`getDefault() ?? env.X`), where the read is itself the
+ * fallback and its absence propagates.
+ */
+declare function isDefaultedAt(node: Node): boolean;
+
+/**
+ * The expression inside any type-level wrappers: `as` and
+ * angle-bracket assertions, parentheses, non-null `!`, and `satisfies`.
+ * The `await` is left in place, so the caller can still ask TypeScript
+ * for the awaited type.
+ */
+declare function peelSyntax(node: Node): Node;
+/**
+ * The outermost node wrapping this one through the same type-level
+ * wrappers `peelSyntax` sees through, or the node itself when nothing
+ * wraps it. Ask the result for its parent to get the node that consumes
+ * the value, and compare the result against that parent's operands to
+ * find out which operand this was.
+ */
+declare function climbSyntax(node: Node): Node;
+/**
+ * The expression inside every value-preserving wrapper, `await`
+ * included, for a pass asking "what value flows here". A pass reading
+ * types off the checker wants `peelSyntax` instead, so the await stays
+ * where TypeScript reports the resolved type.
+ */
+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 ExplainCallableOptions, type ExplainedResolution, type FoundTerminal, type FunctionRoot, GENERIC_TERMINALS, type ImportScanOptions, NO_BARRIERS, type ObservedStubCall, type RawBranchResult, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, TSCONFIG_NAMES, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, TypeScriptWhySession, type WhySessionOptions, accessContextFor, arrayLiteralOf, buildProjectHelperIndex, callOpsFor, climbSyntax, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, couldNameAValue, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findEnclosingFunction, findNearestTsconfig, findTerminals, functionTargetOf, functionValueOf, hasBody, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isDefaultedAt, isImportedFrom, methodDeclaredIn, namedImportsOf, objectLiteralOf, parseConditionExpression, peelSyntax, peelValue, propertiesOf, propertyFunctionOf, propertyNameOf, propertyOf, propertyValueOf, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, startsItsOwnScope, stringPropertyOf, stringValueOf, stubEvidence, stubEvidenceIn, symbolBehind, workspaceRootFor, writtenNodeOf };