@suss/adapter-typescript 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -1,8 +1,10 @@
 import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, Project, Symbol, Expression } from 'ts-morph';
-import { TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, LanguageAdapter, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, EffectArg, RawDeclaredContract, ContractPattern, ResponsePropertyMapping } from '@suss/extractor';
+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';
 import { ResolutionExplanation } from '@suss/resolution';
+import { AstCapableOps } from '@suss/recognize/ast';
+import { CallOps } from '@suss/recognize';
 
 /**
  * cache.ts: the on-disk extraction cache.
@@ -123,20 +125,30 @@ interface PackFunnel {
     /**
      * Bound summaries on the provider side of their boundary.
      *
-     * Transitions say what a unit does with a request, which only a
-     * provider can say. A consumer records what it reads back from the
-     * response instead, and that goes on the summary's metadata. Measuring
-     * a client pack against transitions would report every working one as
-     * having extracted nothing.
+     * Kept apart from the count below because a provider that produced
+     * no transitions is a different problem from a client that produced
+     * none.
      */
     providerSummaries: number;
-    /** Provider summaries with at least one transition. */
+    /**
+     * Summaries with at least one transition, of any role. A provider's
+     * transitions say what it does with a request and a client's say what
+     * it expects back, so a pack whose summaries have none has bound
+     * something and described nothing either way.
+     */
     summariesWithBehavior: number;
     /**
      * Where one of this pack's hooks threw. Every count above is a floor
      * while this is non-empty.
      */
     failures: PackFailure[];
+    /**
+     * What the pack wrote as data rather than as code, or null for a pack
+     * written as a hand-rolled walk. This is the one thing in the funnel
+     * that no run produces: it is the pack's own shape, and it is here so
+     * the migration onto the declared surface can be measured.
+     */
+    declarations: PackDeclarations | null;
 }
 interface ExtractionReport {
     /** Files in the tsconfig include set, or null when the caller supplied a Project. */
@@ -926,13 +938,14 @@ interface HealthCheck {
     /** The property being checked, as something either true or false. */
     name: string;
     /**
-     * The heading printed when this check finds something.
+     * The short word this check reports under, kebab-case.
      *
-     * `name` is written as an assertion, so printing it above the
-     * violations would say "no pack collides with itself" and then list a
-     * pack colliding with itself.
+     * It is the first column of every line the check prints, so a reader
+     * works out what it means once and recognises it after that. `name`
+     * is written as an assertion and would read backwards over a list of
+     * things failing it.
      */
-    whenBroken: string;
+    code: string;
     /**
      * Who the finding is addressed to.
      *
@@ -946,6 +959,26 @@ interface HealthCheck {
     audience: "run" | "pack";
     violations: HealthViolation[];
 }
+/**
+ * What one pack paid for what it matches.
+ *
+ * Expressiveness is bought link by link, and #542 asks for the price to
+ * be printed. A pack with every link written as data runs on any
+ * adapter with the executor ops. A link written as a function runs only
+ * where its own language does, and one that reads the syntax tree is
+ * the floor. All three are allowed, and this says which is which.
+ */
+interface PackGradient {
+    pack: string;
+    /** Links written as data, across every declaration. */
+    dataLinks: number;
+    /** Links written as a function, as "declaration.question". */
+    functionLinks: string[];
+    /** Links whose function reads the adapter's own syntax tree. */
+    astLinks: string[];
+    /** Declarations shipped without a line of code to run against them. */
+    withoutExample: string[];
+}
 /**
  * Run every health check over one extraction report and return what
  * fired, grouped by which check caught it.
@@ -973,6 +1006,77 @@ declare function formatPackHealth(checks: ReadonlyArray<HealthCheck>, audiences:
  */
 declare function parseConditionExpression(expr: Expression, depth?: number): Predicate | null;
 
+/**
+ * What this adapter can tell a declared pack about a call.
+ *
+ * Every question here was already worked out somewhere in this adapter,
+ * once per pack that needed it. Collecting them behind the one
+ * interface `@suss/recognize` declares is what lets a pack stop being a
+ * walk over ts-morph and start being data.
+ *
+ * Two of the receiver origins are implemented. The migration plan for
+ * #542 lists four more, and each one adds an entry to `ORIGIN` beside
+ * the union member it matches.
+ */
+
+/** 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;
+
+/**
+ * Context handed to TypeScript-adapter recognizers. Recognizers in
+ * `@suss/framework-prisma` (and other packs) receive this and use
+ * the type-checker / source-file primitives to decide whether the
+ * call site matches their semantics. `extractArgs` reuses the same
+ * `EffectArg` builder the adapter uses for `invocation` effects, so
+ * recognizers don't have to re-implement literal/object/identifier
+ * shape extraction.
+ */
+interface TsInvocationRecognizerContext {
+    /** The call expression itself (also passed as the first arg). */
+    call: CallExpression;
+    /** Source file the call lives in. Useful for import resolution. */
+    sourceFile: SourceFile;
+    /**
+     * Convert the call's arguments to `EffectArg[]` using the same
+     * literal / object / identifier extraction the adapter applies to
+     * `invocation` effects. Recognizers call this when they want
+     * field-level shape (e.g. Prisma's `select: { id: true }`).
+     */
+    extractArgs(): EffectArg[];
+    /**
+     * Whether `identifier` was introduced by an import of
+     * `expectedModule`. Recognizers use this to tell a library's export
+     * apart from a local class that happens to share its name.
+     *
+     * Named, default, and namespace imports all match. So does an import
+     * through a project-local barrel that re-exports the module: the
+     * aliased symbol is still in the package that declared it.
+     */
+    isImportedFrom(identifier: Node, expectedModule: string): boolean;
+    /**
+     * The expression `value` is written as, followed through const
+     * bindings, imports, and re-export barrels. A recognizer asks this
+     * before claiming the source does not name something:
+     *
+     *   const url = "https://sqs/.../orders";
+     *   client.send(new SendMessageCommand({ QueueUrl: url }));
+     *
+     * Resolving `url` gives back the string literal, and the recognizer's
+     * own pattern match runs on that. Null when the value has no written
+     * form (a parameter, a call result), which is exactly when null on the
+     * binding is correct.
+     */
+    resolveWrittenValue(value: Node): Node | null;
+    /**
+     * What a declared pack asks about this call, in the vocabulary
+     * `@suss/recognize` defines. A pack written as a chain of data links
+     * reads only this; the members above are what a pack written as code
+     * reaches for.
+     */
+    ops: CallOps;
+}
 declare function isImportedFrom(identifier: Node, expectedModule: string): boolean;
 /**
  * Whether `expectedModule` declares the method a call goes to. A pack
@@ -1175,4 +1279,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 ReadNameOptions, ResolutionStore, type Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, type ValueLocation, type WhyExplained, WhySession, type WhySessionOptions, 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 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 };

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, Project, Symbol, Expression } from 'ts-morph';
-import { TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, LanguageAdapter, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, EffectArg, RawDeclaredContract, ContractPattern, ResponsePropertyMapping } from '@suss/extractor';
+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';
 import { ResolutionExplanation } from '@suss/resolution';
+import { AstCapableOps } from '@suss/recognize/ast';
+import { CallOps } from '@suss/recognize';
 
 /**
  * cache.ts: the on-disk extraction cache.
@@ -123,20 +125,30 @@ interface PackFunnel {
     /**
      * Bound summaries on the provider side of their boundary.
      *
-     * Transitions say what a unit does with a request, which only a
-     * provider can say. A consumer records what it reads back from the
-     * response instead, and that goes on the summary's metadata. Measuring
-     * a client pack against transitions would report every working one as
-     * having extracted nothing.
+     * Kept apart from the count below because a provider that produced
+     * no transitions is a different problem from a client that produced
+     * none.
      */
     providerSummaries: number;
-    /** Provider summaries with at least one transition. */
+    /**
+     * Summaries with at least one transition, of any role. A provider's
+     * transitions say what it does with a request and a client's say what
+     * it expects back, so a pack whose summaries have none has bound
+     * something and described nothing either way.
+     */
     summariesWithBehavior: number;
     /**
      * Where one of this pack's hooks threw. Every count above is a floor
      * while this is non-empty.
      */
     failures: PackFailure[];
+    /**
+     * What the pack wrote as data rather than as code, or null for a pack
+     * written as a hand-rolled walk. This is the one thing in the funnel
+     * that no run produces: it is the pack's own shape, and it is here so
+     * the migration onto the declared surface can be measured.
+     */
+    declarations: PackDeclarations | null;
 }
 interface ExtractionReport {
     /** Files in the tsconfig include set, or null when the caller supplied a Project. */
@@ -926,13 +938,14 @@ interface HealthCheck {
     /** The property being checked, as something either true or false. */
     name: string;
     /**
-     * The heading printed when this check finds something.
+     * The short word this check reports under, kebab-case.
      *
-     * `name` is written as an assertion, so printing it above the
-     * violations would say "no pack collides with itself" and then list a
-     * pack colliding with itself.
+     * It is the first column of every line the check prints, so a reader
+     * works out what it means once and recognises it after that. `name`
+     * is written as an assertion and would read backwards over a list of
+     * things failing it.
      */
-    whenBroken: string;
+    code: string;
     /**
      * Who the finding is addressed to.
      *
@@ -946,6 +959,26 @@ interface HealthCheck {
     audience: "run" | "pack";
     violations: HealthViolation[];
 }
+/**
+ * What one pack paid for what it matches.
+ *
+ * Expressiveness is bought link by link, and #542 asks for the price to
+ * be printed. A pack with every link written as data runs on any
+ * adapter with the executor ops. A link written as a function runs only
+ * where its own language does, and one that reads the syntax tree is
+ * the floor. All three are allowed, and this says which is which.
+ */
+interface PackGradient {
+    pack: string;
+    /** Links written as data, across every declaration. */
+    dataLinks: number;
+    /** Links written as a function, as "declaration.question". */
+    functionLinks: string[];
+    /** Links whose function reads the adapter's own syntax tree. */
+    astLinks: string[];
+    /** Declarations shipped without a line of code to run against them. */
+    withoutExample: string[];
+}
 /**
  * Run every health check over one extraction report and return what
  * fired, grouped by which check caught it.
@@ -973,6 +1006,77 @@ declare function formatPackHealth(checks: ReadonlyArray<HealthCheck>, audiences:
  */
 declare function parseConditionExpression(expr: Expression, depth?: number): Predicate | null;
 
+/**
+ * What this adapter can tell a declared pack about a call.
+ *
+ * Every question here was already worked out somewhere in this adapter,
+ * once per pack that needed it. Collecting them behind the one
+ * interface `@suss/recognize` declares is what lets a pack stop being a
+ * walk over ts-morph and start being data.
+ *
+ * Two of the receiver origins are implemented. The migration plan for
+ * #542 lists four more, and each one adds an entry to `ORIGIN` beside
+ * the union member it matches.
+ */
+
+/** 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;
+
+/**
+ * Context handed to TypeScript-adapter recognizers. Recognizers in
+ * `@suss/framework-prisma` (and other packs) receive this and use
+ * the type-checker / source-file primitives to decide whether the
+ * call site matches their semantics. `extractArgs` reuses the same
+ * `EffectArg` builder the adapter uses for `invocation` effects, so
+ * recognizers don't have to re-implement literal/object/identifier
+ * shape extraction.
+ */
+interface TsInvocationRecognizerContext {
+    /** The call expression itself (also passed as the first arg). */
+    call: CallExpression;
+    /** Source file the call lives in. Useful for import resolution. */
+    sourceFile: SourceFile;
+    /**
+     * Convert the call's arguments to `EffectArg[]` using the same
+     * literal / object / identifier extraction the adapter applies to
+     * `invocation` effects. Recognizers call this when they want
+     * field-level shape (e.g. Prisma's `select: { id: true }`).
+     */
+    extractArgs(): EffectArg[];
+    /**
+     * Whether `identifier` was introduced by an import of
+     * `expectedModule`. Recognizers use this to tell a library's export
+     * apart from a local class that happens to share its name.
+     *
+     * Named, default, and namespace imports all match. So does an import
+     * through a project-local barrel that re-exports the module: the
+     * aliased symbol is still in the package that declared it.
+     */
+    isImportedFrom(identifier: Node, expectedModule: string): boolean;
+    /**
+     * The expression `value` is written as, followed through const
+     * bindings, imports, and re-export barrels. A recognizer asks this
+     * before claiming the source does not name something:
+     *
+     *   const url = "https://sqs/.../orders";
+     *   client.send(new SendMessageCommand({ QueueUrl: url }));
+     *
+     * Resolving `url` gives back the string literal, and the recognizer's
+     * own pattern match runs on that. Null when the value has no written
+     * form (a parameter, a call result), which is exactly when null on the
+     * binding is correct.
+     */
+    resolveWrittenValue(value: Node): Node | null;
+    /**
+     * What a declared pack asks about this call, in the vocabulary
+     * `@suss/recognize` defines. A pack written as a chain of data links
+     * reads only this; the members above are what a pack written as code
+     * reaches for.
+     */
+    ops: CallOps;
+}
 declare function isImportedFrom(identifier: Node, expectedModule: string): boolean;
 /**
  * Whether `expectedModule` declares the method a call goes to. A pack
@@ -1175,4 +1279,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 ReadNameOptions, ResolutionStore, type Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, type ValueLocation, type WhyExplained, WhySession, type WhySessionOptions, 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 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 };