@suss/adapter-typescript 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -1,6 +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.
@@ -45,7 +49,6 @@ interface CacheDiagnostic {
 type CacheLookup = {
     kind: "hit";
     summaries: BehavioralSummary[];
-    projectRoot?: string;
     diagnostic: CacheDiagnostic;
 } | {
     kind: "miss";
@@ -122,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. */
@@ -199,6 +212,28 @@ interface FileSetQuery {
  * edges a query follows, so cost tracks how indirect the code is.
  */
 
+interface ExplainCallableOptions {
+    /** A second file to walk out from; see `resolveCallable`. */
+    alsoFrom?: SourceFile;
+    /** How many derived nodes deep the proof walk goes; see `proofOf`. */
+    maxDepth?: number;
+}
+/** What one witness re-evaluation cost, said rather than hidden. */
+interface ExplainStats {
+    /** Facts the demand walk had extracted, which the proof pass reran. */
+    baseFacts: number;
+    /** Facts the exhaustive pass derived on top of those. */
+    derivedFacts: number;
+    evaluateMs: number;
+}
+interface ExplainedResolution {
+    /** The node the value comes down to. */
+    target: Node;
+    proof: Proof;
+    /** The source node behind a proof atom, when the atom is a node id. */
+    nodeFor: (atom: Atom) => Node | undefined;
+    stats: ExplainStats;
+}
 declare class ResolutionStore {
     private readonly db;
     private readonly table;
@@ -219,6 +254,21 @@ declare class ResolutionStore {
      * the walk never reaches on its own.
      */
     resolveCallable(value: Node, alsoFrom?: SourceFile): Node | null;
+    /**
+     * Every function the value comes down to. One is the answer
+     * `resolveCallable` gives; several is a value with more than one
+     * possible source, which a caller says at the site rather than
+     * folding into the same nothing as a chain that went nowhere.
+     */
+    resolveCallableSources(value: Node, alsoFrom?: SourceFile): Node[];
+    /**
+     * The witness proof behind `resolveCallable`'s answer. Resolves the
+     * value first, which walks files and extracts facts in the usual
+     * waves, then re-evaluates the rules over those base facts under the
+     * witness algebra and rebuilds the proof of the answer. Null when
+     * the value does not resolve at all.
+     */
+    explainCallable(value: Node, options?: ExplainCallableOptions): ExplainedResolution | null;
     resolveObject(value: Node): Node | null;
     /**
      * For a value that is neither a function nor an object, such as a
@@ -266,10 +316,12 @@ declare class ResolutionStore {
      */
     filesImportingTransitively(fileSets: ReadonlyArray<FileSetQuery>): ReadonlyArray<ReadonlySet<SourceFile>>;
     /**
-     * Two candidates give null. Picking whichever arrived first would make
-     * the result depend on the order the facts came in.
+     * Null keeps the wave walk widening; any candidate at all ends it,
+     * since more files can only add candidates, never take one away. The
+     * single-answer policy stays with the callers: picking one of two
+     * would make the result depend on the order the facts came in.
      */
-    private lookup;
+    private lookupSources;
     private derive;
     private answersFor;
     /**
@@ -394,6 +446,8 @@ interface DiscoveredUnit {
             required: boolean;
         }>;
         rootFields: string[];
+        /** Spreads in `document` with no definition in it: read partially. */
+        unresolvedFragments?: string[];
         unresolved?: {
             reference: string;
             reason: string;
@@ -523,6 +577,11 @@ type DescentBarriers = ReadonlySet<Node>;
 declare function extractCodeStructure(unit: DiscoveredUnit, pack: PatternPack, invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers, resolveWrittenValue?: (value: Node) => Node | null): RawCodeStructure;
 interface TypeScriptAdapterConfig {
     tsConfigFilePath?: string;
+    /**
+     * Absolute. Every id's file path is relative to this directory. When
+     * absent, settled by workspaceRootFor from the tsconfig's directory.
+     */
+    projectRoot?: string;
     /** Separates two services in one repository whose file names match. */
     workspace?: string;
     project?: Project;
@@ -774,6 +833,71 @@ interface TsDiscoveryContext {
 }
 declare function createTsDiscoveryContext(resolution?: ResolutionStore): TsDiscoveryContext;
 
+/**
+ * The session behind `suss ask why`: a ts-morph project over the
+ * asked-about source, a way to point at the expression somebody
+ * spelled, and the witness proof of what it resolved to, rendered
+ * through `@suss/resolution`'s phrases.
+ *
+ * The CLI points at values with a file, a line, and the text as
+ * written, because that is what a person has in hand. Everything
+ * ts-morph stays behind this class; callers treat the found nodes as
+ * opaque handles to pass back in.
+ */
+
+interface WhySessionOptions {
+    /** The project root, which paths in every answer come out relative to. */
+    dir: string;
+}
+/** A value or function said the way an answer prints it. */
+interface ValueLocation {
+    name: string;
+    /** Relative to the session root when under it, absolute otherwise. */
+    file: string;
+    line: number;
+}
+interface WhyExplained {
+    explanation: ResolutionExplanation;
+    /** The chain's atoms, each said in source terms. */
+    chain: string[];
+    /** The chain and its reasons as printable lines. */
+    lines: string[];
+    target: ValueLocation;
+    stats: ExplainStats;
+}
+declare class WhySession {
+    private readonly project;
+    private readonly store;
+    private readonly root;
+    constructor(options: WhySessionOptions);
+    /**
+     * The smallest expression on `line` of `file` whose text is exactly
+     * `text`, or null. Spelled from the person's side: the name as
+     * written, not a node id.
+     */
+    findExpression(file: string, line: number, text: string): Node | null;
+    /**
+     * The callee of the call written as `calleeText` between `startLine`
+     * and `endLine` of `file`, or null. This is how a summary's recorded
+     * callee gets back to its node: the summary keeps source text and a
+     * range, not ids.
+     */
+    findCallee(file: string, startLine: number, endLine: number, calleeText: string): Node | null;
+    /**
+     * Why `value` resolves to what it does: the witness proof, flattened
+     * to the chain and rendered. Null when the value does not resolve,
+     * which the caller says in its own words.
+     */
+    explain(value: Node, options?: {
+        maxDepth?: number;
+    }): WhyExplained | null;
+    /** Where a found node is, in the terms an answer prints. */
+    locate(node: Node): ValueLocation;
+    private sourceFileAt;
+    /** A module key: a file path said relative to the root, or a package name. */
+    private displayPath;
+}
+
 type ExportedDeclarationMap = ReturnType<SourceFile["getExportedDeclarations"]>;
 /**
  * What a module exports, by exported name. Cached, because ts-morph
@@ -814,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.
      *
@@ -834,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.
@@ -861,14 +1006,91 @@ 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
  * asks this when the receiver came from somewhere the source does not
  * spell out: `const redis = await this.getClient()` says nothing about
  * ioredis, and the type of `redis.get` says everything.
+ *
+ * A client cached on an untyped global, `global.x || new Redis()`,
+ * types as `any`, so the method has no symbol. With `resolve` supplied,
+ * what the receiver was written as still says which library: the value
+ * comes down to a construction or a factory call of something imported
+ * from it.
  */
-declare function methodDeclaredIn(callee: Node, expectedModule: string): boolean;
+declare function methodDeclaredIn(callee: Node, expectedModule: string, resolve?: (value: Node) => Node | null): boolean;
 
 /**
  * What a name-valued expression says, as fixed text with a hole for
@@ -995,6 +1217,37 @@ interface TsJsxAttributeLocation {
 }
 declare function createTsSubUnitContext(): TsSubUnitContext;
 
+/**
+ * Naming a summary, so that something else can point at it.
+ *
+ * A bare function name is not enough. Reading suss's own source turns up
+ * 404 summaries that share a name with another one, and a large
+ * repository is worse: two services with the same `src/handlers.ts` give
+ * every summary in one an exact twin in the other. Following a call by
+ * matching names was always a guess about which one was meant.
+ *
+ * So the name includes the project the summary came from, the file it is
+ * in, and the path its export is reached by. That is unique across
+ * everything one run can see, and it still looks like something a person
+ * would have written down.
+ */
+
+/**
+ * The one root a run measures its file paths from: the nearest
+ * directory at or above the run's anchor whose package.json has a
+ * name. The anchor is the tsconfig's directory, or the directory a
+ * run without one was pointed at. When no package.json declares a
+ * name above the anchor, the anchor itself is the root.
+ *
+ * The same directory supplies the workspace segment of an id, so both
+ * parts of an id are measured from one place. The walk starts from the
+ * run's configuration, not from whichever files the run loaded, so a
+ * run over one nested tsconfig spells a file the same way a run over
+ * the whole workspace does, and the same command spells it the same
+ * way twice.
+ */
+declare function workspaceRootFor(anchor: string): string;
+
 declare const ADAPTER_VERSION = "0.2.1";
 /**
  * Content hash of the given files, in the order they arrive. Empty when
@@ -1026,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 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, 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 };
+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 };