@suss/adapter-typescript 0.31.2 → 0.33.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, PropertyAccessExpression, TaggedTemplateExpression, Project, ImportDeclaration, ArrayLiteralExpression, ObjectLiteralExpression, ObjectLiteralElementLike, Symbol, Expression, NewExpression, Identifier } from 'ts-morph';
+import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, Symbol, CallExpression, PropertyAccessExpression, TaggedTemplateExpression, Project, ImportDeclaration, ArrayLiteralExpression, ObjectLiteralExpression, ObjectLiteralElementLike, 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';
@@ -11,6 +11,12 @@ import { z } from 'zod';
 interface FileSetQuery {
     sourceFiles: ReadonlyArray<SourceFile>;
     packages: ReadonlyArray<string>;
+    /**
+     * Files the asking pack's code generator leaves beside a module it
+     * wrote into the project. A relative import into such a directory
+     * counts as an import of the package.
+     */
+    generatedMarkers?: ReadonlyArray<string>;
 }
 
 /**
@@ -46,6 +52,18 @@ interface PassedArgument {
     call: Node;
     argument: Node;
 }
+/** See `ResolutionStore.envNamers`. */
+interface EnvironmentNamers {
+    /**
+     * The environment reads that take their variable's name from this
+     * parameter, however many helpers forward it along the way. Empty for
+     * a parameter no read ever takes a name from, and null where the
+     * rules had nothing to go on: a file that exports nothing states no
+     * facts, so their silence about its parameters means neither yes nor
+     * no, and the asker settles what it can by reading the syntax.
+     */
+    sitesNaming(parameter: Node): readonly Node[] | null;
+}
 declare class ResolutionStore {
     private readonly db;
     private readonly table;
@@ -66,13 +84,17 @@ declare class ResolutionStore {
     private readonly constructionSites;
     /** Files the most recent query read, for the memo to keep. */
     private lastQueryWalked;
+    /** See `environmentSiteFiles`; null until the first env question. */
+    private envSiteFiles;
+    private envNamersAnswer;
+    private envNamersExtractedAt;
     private readonly declarations;
     private readonly graph;
     /** See `notePossibleCallers`. */
     private readonly possibleCallers;
     private readonly callerFilesRead;
     private stale;
-    constructor(wrappers?: TransparentWrapper[]);
+    constructor(wrappers?: TransparentWrapper[], environmentObjects?: readonly string[]);
     /**
      * `alsoFrom` is a second file to walk out from, for a caller that
      * knows where the value it is asking about was set up. The walk
@@ -144,6 +166,48 @@ declare class ResolutionStore {
      * parameter's own function with no join against `bodyCalls` needed.
      */
     callsPassing(parameter: Node): PassedArgument[];
+    /**
+     * Whether this expression's value is the environment object: the way
+     * a pack spells it, a name declared as that, or a parameter some
+     * caller hands one to, however many calls deep.
+     *
+     * A parameter is the only shape whose answer can change once its
+     * callers are in, and reading those means reading every file that
+     * imports this one, so a value that is not one is answered from what
+     * the store already has.
+     */
+    isEnvironmentValue(value: Node): boolean;
+    private hasAnswer;
+    /**
+     * Which parameters an environment read takes its variable's name
+     * from, for a reader standing at a call. One question covers the
+     * whole project: a project has a handful of environment reads and
+     * thousands of parameters, and with the read bound the rules run from
+     * each callee to its callers.
+     *
+     * `definedIn` is the callee's own file, read into the store before
+     * the question so a helper nothing had extracted yet is among the
+     * facts the rules run over.
+     */
+    envNamers(definedIn: SourceFile): EnvironmentNamers;
+    private sitesNamedBy;
+    /**
+     * Seed every expression that spells the environment, derive, and take
+     * the sites back per parameter. The question is dropped afterwards, so
+     * a later ask over a larger fact set derives it again.
+     *
+     * The reads themselves cannot be the seed: one written through a
+     * parameter is off an object a scan of the source has no way to pick
+     * out, and the whole point of asking is to find those.
+     */
+    private askEnvNamers;
+    /**
+     * The project's files that hand the environment object somewhere,
+     * read into the store. Which files those are cannot depend on what a
+     * reader happened to ask about first, so the scan is over the
+     * project's own sources and it happens once.
+     */
+    private environmentSiteFiles;
     /**
      * Whether running this function hands back that call: returned
      * outright, written into a name and returned, or a shorthand body.
@@ -247,6 +311,8 @@ declare class ResolutionStore {
      */
     private forgetQuery;
     private wantValue;
+    /** For a question seeded with a fact key the store read out of the database. */
+    private wantKey;
     private wantExportsOf;
     /**
      * Discovery walks the table in order, and the rounds derive it in
@@ -337,7 +403,14 @@ declare function collectAncestorBranches(terminalNode: Node, functionRoot: Funct
  * a call into a dependency stays on the other side of it.
  */
 
-declare function hasBody(fn: FunctionRoot): boolean;
+declare function hasBody(fn: Node): boolean;
+/**
+ * Every declaration behind a callee, with an imported or re-exported
+ * name followed through to its last one. A barrel that forwards a
+ * dependency's function would otherwise look like project code, because
+ * the only declaration in sight is the import in the calling file.
+ */
+declare function declarationsBehind(symbol: Symbol | undefined): Node[];
 
 interface ClientCallSite {
     callExpression: CallExpression;
@@ -548,6 +621,7 @@ interface DiscoveredUnit {
      */
     routeUnfollowed?: UnfollowedCall[];
 }
+declare function toFunctionRoot(node: Node): FunctionRoot | null;
 /** Walk to the nearest enclosing function-shaped node, or null if none. */
 declare function findEnclosingFunction(node: Node): FunctionRoot | null;
 
@@ -1579,4 +1653,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 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 };
+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, 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, declarationsBehind, 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, toFunctionRoot, workspaceRootFor, writtenNodeOf };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, PropertyAccessExpression, TaggedTemplateExpression, Project, ImportDeclaration, ArrayLiteralExpression, ObjectLiteralExpression, ObjectLiteralElementLike, Symbol, Expression, NewExpression, Identifier } from 'ts-morph';
+import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, Symbol, CallExpression, PropertyAccessExpression, TaggedTemplateExpression, Project, ImportDeclaration, ArrayLiteralExpression, ObjectLiteralExpression, ObjectLiteralElementLike, 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';
@@ -11,6 +11,12 @@ import { z } from 'zod';
 interface FileSetQuery {
     sourceFiles: ReadonlyArray<SourceFile>;
     packages: ReadonlyArray<string>;
+    /**
+     * Files the asking pack's code generator leaves beside a module it
+     * wrote into the project. A relative import into such a directory
+     * counts as an import of the package.
+     */
+    generatedMarkers?: ReadonlyArray<string>;
 }
 
 /**
@@ -46,6 +52,18 @@ interface PassedArgument {
     call: Node;
     argument: Node;
 }
+/** See `ResolutionStore.envNamers`. */
+interface EnvironmentNamers {
+    /**
+     * The environment reads that take their variable's name from this
+     * parameter, however many helpers forward it along the way. Empty for
+     * a parameter no read ever takes a name from, and null where the
+     * rules had nothing to go on: a file that exports nothing states no
+     * facts, so their silence about its parameters means neither yes nor
+     * no, and the asker settles what it can by reading the syntax.
+     */
+    sitesNaming(parameter: Node): readonly Node[] | null;
+}
 declare class ResolutionStore {
     private readonly db;
     private readonly table;
@@ -66,13 +84,17 @@ declare class ResolutionStore {
     private readonly constructionSites;
     /** Files the most recent query read, for the memo to keep. */
     private lastQueryWalked;
+    /** See `environmentSiteFiles`; null until the first env question. */
+    private envSiteFiles;
+    private envNamersAnswer;
+    private envNamersExtractedAt;
     private readonly declarations;
     private readonly graph;
     /** See `notePossibleCallers`. */
     private readonly possibleCallers;
     private readonly callerFilesRead;
     private stale;
-    constructor(wrappers?: TransparentWrapper[]);
+    constructor(wrappers?: TransparentWrapper[], environmentObjects?: readonly string[]);
     /**
      * `alsoFrom` is a second file to walk out from, for a caller that
      * knows where the value it is asking about was set up. The walk
@@ -144,6 +166,48 @@ declare class ResolutionStore {
      * parameter's own function with no join against `bodyCalls` needed.
      */
     callsPassing(parameter: Node): PassedArgument[];
+    /**
+     * Whether this expression's value is the environment object: the way
+     * a pack spells it, a name declared as that, or a parameter some
+     * caller hands one to, however many calls deep.
+     *
+     * A parameter is the only shape whose answer can change once its
+     * callers are in, and reading those means reading every file that
+     * imports this one, so a value that is not one is answered from what
+     * the store already has.
+     */
+    isEnvironmentValue(value: Node): boolean;
+    private hasAnswer;
+    /**
+     * Which parameters an environment read takes its variable's name
+     * from, for a reader standing at a call. One question covers the
+     * whole project: a project has a handful of environment reads and
+     * thousands of parameters, and with the read bound the rules run from
+     * each callee to its callers.
+     *
+     * `definedIn` is the callee's own file, read into the store before
+     * the question so a helper nothing had extracted yet is among the
+     * facts the rules run over.
+     */
+    envNamers(definedIn: SourceFile): EnvironmentNamers;
+    private sitesNamedBy;
+    /**
+     * Seed every expression that spells the environment, derive, and take
+     * the sites back per parameter. The question is dropped afterwards, so
+     * a later ask over a larger fact set derives it again.
+     *
+     * The reads themselves cannot be the seed: one written through a
+     * parameter is off an object a scan of the source has no way to pick
+     * out, and the whole point of asking is to find those.
+     */
+    private askEnvNamers;
+    /**
+     * The project's files that hand the environment object somewhere,
+     * read into the store. Which files those are cannot depend on what a
+     * reader happened to ask about first, so the scan is over the
+     * project's own sources and it happens once.
+     */
+    private environmentSiteFiles;
     /**
      * Whether running this function hands back that call: returned
      * outright, written into a name and returned, or a shorthand body.
@@ -247,6 +311,8 @@ declare class ResolutionStore {
      */
     private forgetQuery;
     private wantValue;
+    /** For a question seeded with a fact key the store read out of the database. */
+    private wantKey;
     private wantExportsOf;
     /**
      * Discovery walks the table in order, and the rounds derive it in
@@ -337,7 +403,14 @@ declare function collectAncestorBranches(terminalNode: Node, functionRoot: Funct
  * a call into a dependency stays on the other side of it.
  */
 
-declare function hasBody(fn: FunctionRoot): boolean;
+declare function hasBody(fn: Node): boolean;
+/**
+ * Every declaration behind a callee, with an imported or re-exported
+ * name followed through to its last one. A barrel that forwards a
+ * dependency's function would otherwise look like project code, because
+ * the only declaration in sight is the import in the calling file.
+ */
+declare function declarationsBehind(symbol: Symbol | undefined): Node[];
 
 interface ClientCallSite {
     callExpression: CallExpression;
@@ -548,6 +621,7 @@ interface DiscoveredUnit {
      */
     routeUnfollowed?: UnfollowedCall[];
 }
+declare function toFunctionRoot(node: Node): FunctionRoot | null;
 /** Walk to the nearest enclosing function-shaped node, or null if none. */
 declare function findEnclosingFunction(node: Node): FunctionRoot | null;
 
@@ -1579,4 +1653,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 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 };
+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, 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, declarationsBehind, 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, toFunctionRoot, workspaceRootFor, writtenNodeOf };