@suss/adapter-typescript 0.32.0 → 0.33.1

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, Project, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, Symbol, CallExpression, PropertyAccessExpression, TaggedTemplateExpression, 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>;
 }
 
 /**
@@ -80,8 +86,8 @@ declare class ResolutionStore {
     private lastQueryWalked;
     /** See `environmentSiteFiles`; null until the first env question. */
     private envSiteFiles;
-    private envNamersAnswer;
-    private envNamersExtractedAt;
+    /** See `environmentAnswers`; null until the first env question. */
+    private envAnswers;
     private readonly declarations;
     private readonly graph;
     /** See `notePossibleCallers`. */
@@ -160,29 +166,50 @@ 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's answer depends on its callers, so it comes from the
+     * parameters the environment reaches, worked out once per run.
+     */
+    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.
+     * each callee to its callers. The facts README says which files that
+     * reads and why it is asked once.
      */
-    envNamers(definedIn: SourceFile): EnvironmentNamers;
+    envNamers(project: Project): EnvironmentNamers;
+    private environmentAnswers;
+    /**
+     * Ask until every call handing the environment on has had its callee
+     * read, one hop a round, so the answer covers each parameter it lands in.
+     */
+    private followEnvironment;
+    private readCalleeOf;
+    /** The files the parameters an answer is keyed by are declared in. */
+    private filesOf;
     private sitesNamedBy;
     /**
-     * Seed every read the store knows of, 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.
+     * Seed every expression that spells the environment, derive, and take
+     * back the read sites per parameter and the parameters the object is
+     * handed to. 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;
+    private askEnvironment;
     /**
-     * The project's files that spell an environment read with a computed
-     * index, 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
+     * 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;
@@ -381,7 +408,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;
@@ -592,6 +626,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;
 
@@ -1623,4 +1658,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, 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, Project, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, Symbol, CallExpression, PropertyAccessExpression, TaggedTemplateExpression, 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>;
 }
 
 /**
@@ -80,8 +86,8 @@ declare class ResolutionStore {
     private lastQueryWalked;
     /** See `environmentSiteFiles`; null until the first env question. */
     private envSiteFiles;
-    private envNamersAnswer;
-    private envNamersExtractedAt;
+    /** See `environmentAnswers`; null until the first env question. */
+    private envAnswers;
     private readonly declarations;
     private readonly graph;
     /** See `notePossibleCallers`. */
@@ -160,29 +166,50 @@ 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's answer depends on its callers, so it comes from the
+     * parameters the environment reaches, worked out once per run.
+     */
+    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.
+     * each callee to its callers. The facts README says which files that
+     * reads and why it is asked once.
      */
-    envNamers(definedIn: SourceFile): EnvironmentNamers;
+    envNamers(project: Project): EnvironmentNamers;
+    private environmentAnswers;
+    /**
+     * Ask until every call handing the environment on has had its callee
+     * read, one hop a round, so the answer covers each parameter it lands in.
+     */
+    private followEnvironment;
+    private readCalleeOf;
+    /** The files the parameters an answer is keyed by are declared in. */
+    private filesOf;
     private sitesNamedBy;
     /**
-     * Seed every read the store knows of, 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.
+     * Seed every expression that spells the environment, derive, and take
+     * back the read sites per parameter and the parameters the object is
+     * handed to. 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;
+    private askEnvironment;
     /**
-     * The project's files that spell an environment read with a computed
-     * index, 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
+     * 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;
@@ -381,7 +408,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;
@@ -592,6 +626,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;
 
@@ -1623,4 +1658,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, 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 };