@suss/adapter-typescript 0.12.0 → 0.13.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, Project, Symbol, Expression } from 'ts-morph';
+import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, Project, Symbol, Expression, NewExpression, TaggedTemplateExpression, PropertyAccessExpression } from 'ts-morph';
 import { PackDeclarations, TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, LanguageAdapter, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, EffectArg, RawDeclaredContract, ContractPattern, ResponsePropertyMapping } from '@suss/extractor';
 import { BehavioralSummary, MessageBusSemantics, DeployableUnit, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
 import { Proof, Atom } from '@suss/datalog';
@@ -307,6 +307,9 @@ declare class ResolutionStore {
      * Two candidates give null, since ambiguity is nothing. The value
      * itself is never a result either, or an identifier whose chain went
      * nowhere would come back as itself.
+     *
+     * An answer has to be an expression, which leaves out the class a
+     * construction makes an instance of. The README says why.
      */
     private lookupWritten;
     /**
@@ -1019,11 +1022,43 @@ declare function parseConditionExpression(expr: Expression, depth?: number): Pre
  * the union member it matches.
  */
 
+/**
+ * A call, a construction, or a tagged template, which all ask the same
+ * questions. A tagged template is a call the source wrote without
+ * parentheses: the tag is the callee and the template is the one
+ * argument, which is how a pack reaches a statement written that way
+ * without a second grammar for it.
+ */
+type Called = CallExpression | NewExpression | TaggedTemplateExpression;
 /** One-hop lookup from a written name to the value it was bound to. */
 type Resolve = (value: Node) => Node | null;
 /** What a declared pack can ask about one TypeScript call. */
-declare function callOpsFor(call: CallExpression, resolveWrittenValue?: Resolve): AstCapableOps;
+declare function callOpsFor(call: Called, resolveWrittenValue?: Resolve): AstCapableOps;
 
+/**
+ * Context handed to TypeScript-adapter access recognizers: sister
+ * to TsInvocationRecognizerContext but for property-access nodes.
+ * No `extractArgs` since property accesses don't take arguments.
+ */
+interface TsAccessRecognizerContext {
+    /** The property-access expression itself. */
+    access: Node;
+    /** Source file the access lives in. */
+    sourceFile: SourceFile;
+    /**
+     * One-hop lookup from a written name to the value it was bound to,
+     * from the run's facts (#300). Gives null when the run has no store,
+     * and the recognizer's own pattern match runs on the raw node.
+     */
+    resolveWrittenValue: (value: Node) => Node | null;
+    /**
+     * 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,
+     * and there is no call there to ask about, so a declared pack
+     * standing on one is handed nothing and matches nothing.
+     */
+    ops?: CallOps;
+}
 /**
  * Context handed to TypeScript-adapter recognizers. Recognizers in
  * `@suss/framework-prisma` (and other packs) receive this and use
@@ -1077,6 +1112,13 @@ interface TsInvocationRecognizerContext {
      */
     ops: CallOps;
 }
+/**
+ * Everything a recognizer may ask about one call site.
+ *
+ * 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): TsInvocationRecognizerContext;
 declare function isImportedFrom(identifier: Node, expectedModule: string): boolean;
 /**
  * Whether `expectedModule` declares the method a call goes to. A pack
@@ -1091,6 +1133,17 @@ declare function isImportedFrom(identifier: Node, expectedModule: string): boole
  * from it.
  */
 declare function methodDeclaredIn(callee: Node, expectedModule: string, resolve?: (value: Node) => Node | null): boolean;
+/** The nodes this walk stops at, which is every shape a pack can guard. */
+type Accessed = PropertyAccessExpression | CallExpression | TaggedTemplateExpression;
+/**
+ * What one node is handed. The ops are built on the first read rather
+ * than up front, the way the invocation walk builds them: most nodes
+ * reach no declared pack, and a pack written as code never asks.
+ *
+ * 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): TsAccessRecognizerContext;
 
 /**
  * What a name-valued expression says, as fixed text with a hole for
@@ -1279,4 +1332,4 @@ declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     version?: string;
 }>): string;
 
-export { ADAPTER_VERSION, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExplainCallableOptions, type ExplainStats, type ExplainedResolution, type ExtractionReport, type FoundTerminal, type FunctionRoot, type HealthCheck, type HealthViolation, type PackFunnel, type PackGradient, type ReadNameOptions, ResolutionStore, type Timer, type TimingReport, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, type ValueLocation, type WhyExplained, WhySession, type WhySessionOptions, callOpsFor, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, isImportedFrom, methodDeclaredIn, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, workspaceRootFor };
+export { ADAPTER_VERSION, type Accessed, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExplainCallableOptions, type ExplainStats, type ExplainedResolution, type ExtractionReport, type FoundTerminal, type FunctionRoot, type HealthCheck, type HealthViolation, type PackFunnel, type PackGradient, type ReadNameOptions, ResolutionStore, type Timer, type TimingReport, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, type ValueLocation, type WhyExplained, WhySession, type WhySessionOptions, accessContextFor, callOpsFor, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, invocationContextFor, isImportedFrom, methodDeclaredIn, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, workspaceRootFor };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, Project, Symbol, Expression } from 'ts-morph';
+import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, Project, Symbol, Expression, NewExpression, TaggedTemplateExpression, PropertyAccessExpression } from 'ts-morph';
 import { PackDeclarations, TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, LanguageAdapter, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, EffectArg, RawDeclaredContract, ContractPattern, ResponsePropertyMapping } from '@suss/extractor';
 import { BehavioralSummary, MessageBusSemantics, DeployableUnit, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
 import { Proof, Atom } from '@suss/datalog';
@@ -307,6 +307,9 @@ declare class ResolutionStore {
      * Two candidates give null, since ambiguity is nothing. The value
      * itself is never a result either, or an identifier whose chain went
      * nowhere would come back as itself.
+     *
+     * An answer has to be an expression, which leaves out the class a
+     * construction makes an instance of. The README says why.
      */
     private lookupWritten;
     /**
@@ -1019,11 +1022,43 @@ declare function parseConditionExpression(expr: Expression, depth?: number): Pre
  * the union member it matches.
  */
 
+/**
+ * A call, a construction, or a tagged template, which all ask the same
+ * questions. A tagged template is a call the source wrote without
+ * parentheses: the tag is the callee and the template is the one
+ * argument, which is how a pack reaches a statement written that way
+ * without a second grammar for it.
+ */
+type Called = CallExpression | NewExpression | TaggedTemplateExpression;
 /** One-hop lookup from a written name to the value it was bound to. */
 type Resolve = (value: Node) => Node | null;
 /** What a declared pack can ask about one TypeScript call. */
-declare function callOpsFor(call: CallExpression, resolveWrittenValue?: Resolve): AstCapableOps;
+declare function callOpsFor(call: Called, resolveWrittenValue?: Resolve): AstCapableOps;
 
+/**
+ * Context handed to TypeScript-adapter access recognizers: sister
+ * to TsInvocationRecognizerContext but for property-access nodes.
+ * No `extractArgs` since property accesses don't take arguments.
+ */
+interface TsAccessRecognizerContext {
+    /** The property-access expression itself. */
+    access: Node;
+    /** Source file the access lives in. */
+    sourceFile: SourceFile;
+    /**
+     * One-hop lookup from a written name to the value it was bound to,
+     * from the run's facts (#300). Gives null when the run has no store,
+     * and the recognizer's own pattern match runs on the raw node.
+     */
+    resolveWrittenValue: (value: Node) => Node | null;
+    /**
+     * 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,
+     * and there is no call there to ask about, so a declared pack
+     * standing on one is handed nothing and matches nothing.
+     */
+    ops?: CallOps;
+}
 /**
  * Context handed to TypeScript-adapter recognizers. Recognizers in
  * `@suss/framework-prisma` (and other packs) receive this and use
@@ -1077,6 +1112,13 @@ interface TsInvocationRecognizerContext {
      */
     ops: CallOps;
 }
+/**
+ * Everything a recognizer may ask about one call site.
+ *
+ * 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): TsInvocationRecognizerContext;
 declare function isImportedFrom(identifier: Node, expectedModule: string): boolean;
 /**
  * Whether `expectedModule` declares the method a call goes to. A pack
@@ -1091,6 +1133,17 @@ declare function isImportedFrom(identifier: Node, expectedModule: string): boole
  * from it.
  */
 declare function methodDeclaredIn(callee: Node, expectedModule: string, resolve?: (value: Node) => Node | null): boolean;
+/** The nodes this walk stops at, which is every shape a pack can guard. */
+type Accessed = PropertyAccessExpression | CallExpression | TaggedTemplateExpression;
+/**
+ * What one node is handed. The ops are built on the first read rather
+ * than up front, the way the invocation walk builds them: most nodes
+ * reach no declared pack, and a pack written as code never asks.
+ *
+ * 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): TsAccessRecognizerContext;
 
 /**
  * What a name-valued expression says, as fixed text with a hole for
@@ -1279,4 +1332,4 @@ declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     version?: string;
 }>): string;
 
-export { ADAPTER_VERSION, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExplainCallableOptions, type ExplainStats, type ExplainedResolution, type ExtractionReport, type FoundTerminal, type FunctionRoot, type HealthCheck, type HealthViolation, type PackFunnel, type PackGradient, type ReadNameOptions, ResolutionStore, type Timer, type TimingReport, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, type ValueLocation, type WhyExplained, WhySession, type WhySessionOptions, callOpsFor, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, isImportedFrom, methodDeclaredIn, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, workspaceRootFor };
+export { ADAPTER_VERSION, type Accessed, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExplainCallableOptions, type ExplainStats, type ExplainedResolution, type ExtractionReport, type FoundTerminal, type FunctionRoot, type HealthCheck, type HealthViolation, type PackFunnel, type PackGradient, type ReadNameOptions, ResolutionStore, type Timer, type TimingReport, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, type ValueLocation, type WhyExplained, WhySession, type WhySessionOptions, accessContextFor, callOpsFor, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, invocationContextFor, isImportedFrom, methodDeclaredIn, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, workspaceRootFor };