@suss/adapter-typescript 0.32.0 → 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>;
 }
 
 /**
@@ -160,6 +166,18 @@ 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
@@ -174,15 +192,19 @@ declare class ResolutionStore {
     envNamers(definedIn: SourceFile): EnvironmentNamers;
     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
+     * 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 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 +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;
@@ -592,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;
 
@@ -1623,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 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, 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>;
 }
 
 /**
@@ -160,6 +166,18 @@ 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
@@ -174,15 +192,19 @@ declare class ResolutionStore {
     envNamers(definedIn: SourceFile): EnvironmentNamers;
     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
+     * 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 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 +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;
@@ -592,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;
 
@@ -1623,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 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 };