@suss/adapter-typescript 0.1.0 → 0.1.1

package/dist/index.d.cts

@@ -1,54 +1,27 @@
-import { Node, SourceFile, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, Project, Expression } from 'ts-morph';
+import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, Project, Expression } from 'ts-morph';
 import { TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, EffectArg, RawDeclaredContract, ContractPattern, ResponsePropertyMapping } from '@suss/extractor';
-import { BehavioralSummary, MessageBusSemantics, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
+import { BehavioralSummary, MessageBusSemantics, DeployableUnit, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
 
-/**
- * Reported by `lookup`. Surfaces what the cache decided and, for
- * partial-hits, the file-churn breakdown so callers can render a
- * diagnostic.
- */
+/** Reported by `lookup`: what the cache decided, and why. */
 interface CacheDiagnostic {
-    kind: "hit" | "partial-hit" | "miss";
-    /** Reason the lookup missed (only set when kind === "miss"). */
-    missReason?: "no-manifest" | "schema-mismatch" | "packs-changed" | "tsconfig-changed";
-    /**
-     * Counts describing the file churn that produced a partial hit.
-     * Only populated when kind === "partial-hit".
-     */
-    partial?: {
-        /** Cached summaries whose location.file is in the unchanged set. */
-        reusedSummaries: number;
-        /** Files the adapter needs to re-extract per-file from. */
-        filesToReExtract: number;
-        /** Files added to the include set since the cached run. */
-        addedFiles: number;
-        /** Files removed from the include set since the cached run. */
-        removedFiles: number;
-        /** Files whose mtime/size differs (excludes added/removed). */
-        changedFiles: number;
-    };
+    kind: "hit" | "miss";
+    /**
+     * Reason the lookup missed (only set when kind === "miss").
+     * `key-changed` means the cache directory holds entries, but none
+     * under this run's schema, adapter, packs and tsconfig path.
+     * `files-changed` means the include set is not the one the entry
+     * was written from.
+     */
+    missReason?: "no-manifest" | "key-changed" | "tsconfig-changed" | "files-changed";
 }
 /**
- * Result of a cache lookup. The adapter dispatches on `kind`:
- *
- *   - "hit"          — the entire summary set is valid; return it
- *                      verbatim, skip extraction.
- *   - "partial-hit"  — `kept` is correct as far as their location.file
- *                      went; re-extract `filesToExtract` per-file and
- *                      re-run the closure / rethrow passes over the
- *                      merged set.
- *   - "miss"         — manifest absent or coarse keys (schema, packs,
- *                      tsconfig) changed; full re-extract.
+ * Result of a cache lookup. A hit carries the whole summary set; a miss
+ * says why, so a caller can render the reason.
  */
 type CacheLookup = {
     kind: "hit";
     summaries: BehavioralSummary[];
     diagnostic: CacheDiagnostic;
-} | {
-    kind: "partial-hit";
-    kept: BehavioralSummary[];
-    filesToExtract: string[];
-    diagnostic: CacheDiagnostic;
 } | {
     kind: "miss";
     diagnostic: CacheDiagnostic;
@@ -57,6 +30,25 @@ type CacheLookup = {
 /** One pack's path through the funnel. */
 interface PackFunnel {
     pack: string;
+    /**
+     * What the pack calls this build of itself, or null when it declares
+     * nothing. The cache keys on it, so a pack that never changes its
+     * stamp can answer a later run with an earlier build's results.
+     */
+    version: string | null;
+    /**
+     * Whether the pack looks for units of its own at all. A pack made
+     * only of recognisers contributes effects to units other packs found,
+     * so discovering nothing is how it always behaves and says nothing
+     * about whether it is working.
+     */
+    discovers: boolean;
+    /**
+     * Whether the pack carries recognisers. Those fire inside units other
+     * packs discovered, so a pack made only of them contributes effects
+     * and never a summary.
+     */
+    recognizes: boolean;
     /**
      * Import specifiers that make a file relevant to this pack. Empty
      * for an ungated pack, which walks every file.
@@ -74,8 +66,51 @@ interface PackFunnel {
     candidateFiles: number;
     /** Units discovered across those files. */
     unitsDiscovered: number;
+    /**
+     * Unit bodies any pack walked in the files this pack's gate selected.
+     *
+     * This is what a recogniser pack had the chance to fire on. Its own
+     * discovery count says nothing, since it discovers nothing by design,
+     * and its candidate-file count says nothing either, because a
+     * recogniser only runs where some pack found a unit to walk.
+     */
+    unitsInGatedFiles: number;
+    /** Effects this pack's recognisers returned. */
+    effectsRecognized: number;
+    /**
+     * Units this pack kept. A unit an earlier pack already claimed is
+     * dropped here, so a pack can discover plenty and keep none when it
+     * sits behind a pack that recognises the same code.
+     */
+    unitsClaimed: number;
+    /**
+     * Units this pack discovered twice over. Cross-pack dedup is the
+     * point of the claim set, but a pack colliding with itself means its
+     * own discovery patterns overlap and one of the two is being thrown
+     * away without anybody deciding which.
+     */
+    selfCollisions: number;
     /** Summaries built from those units. */
     summariesProduced: number;
+    /** Summaries in the finished run that name this pack as what recognised them. */
+    summariesBound: number;
+    /**
+     * Bound summaries on the provider side of their boundary.
+     *
+     * Transitions say what a unit does with a request, which is a
+     * question only a provider answers. A consumer records what it reads
+     * back from the response instead, and that lives on the summary's
+     * metadata. Measuring a client pack against transitions would report
+     * every working one as extracting nothing.
+     */
+    providerSummaries: number;
+    /** Provider summaries carrying at least one transition. */
+    summariesWithBehavior: number;
+    /**
+     * Where one of this pack's hooks threw. Every count above is a floor
+     * while this is non-empty.
+     */
+    failures: PackFailure[];
 }
 interface ExtractionReport {
     /** Files in the tsconfig include set, or null when the caller supplied a Project. */
@@ -91,15 +126,35 @@ interface ExtractionReport {
     emptyStage: EmptyStage | null;
 }
 type EmptyStage = "tsconfig" | "gateResolution" | "candidateFiles" | "discovery" | "assembly";
+/**
+ * A pack's hook throwing on one file.
+ *
+ * The run carries on with the other files, so every count for that pack
+ * afterwards is a floor rather than a total. Somebody reading those
+ * counts has to be told, or a pack that broke reads the same as a pack
+ * that looked and found nothing.
+ */
+interface PackFailure {
+    /** The hook that threw, named as a pack author would know it. */
+    hook: string;
+    /** The file the pack was reading. */
+    file: string;
+    message: string;
+}
+
+/** One question: do these files reach any of these packages. */
+interface FileSetQuery {
+    sourceFiles: ReadonlyArray<SourceFile>;
+    packages: ReadonlyArray<string>;
+}
 
 declare class ResolutionStore {
     private readonly db;
     private readonly table;
     private readonly fullyExtracted;
     private readonly seededValues;
-    private readonly gateAnswers;
-    private resolvedBySource;
-    private comesToBySource;
+    private readonly importedNames;
+    private readonly graph;
     private stale;
     constructor(wrappers?: TransparentWrapper[]);
     /**
@@ -119,7 +174,73 @@ declare class ResolutionStore {
      * another file, and this is how discovery reads it back.
      */
     resolveObject(value: Node): Node | null;
+    /**
+     * The expression `value` is written as, or null. Unlike the other two
+     * questions this one does not care what kind of expression it lands
+     * on, so it answers for values that are neither functions nor
+     * objects: a GraphQL document held in a named constant in another
+     * file comes back as the template literal or tag call that built it.
+     *
+     * A value the code computes has no written form to report, so the
+     * answer is the computing expression itself and the caller gets
+     * nothing it can use, which is the point.
+     */
+    resolveWrittenValue(value: Node): Node | null;
+    /**
+     * The names from `modules` this value stands for. A value stands for
+     * a library name two ways, and a caller asking which library concept
+     * something is wants both:
+     *
+     *   - it is that name, under whatever local spelling. `import
+     *     { Controller as Resource }` makes `Resource` the library's
+     *     `Controller`.
+     *   - calling it calls that name. A project decorator written as
+     *     `(path) => Controller(path)` marks a controller, and so does
+     *     one written as `applyDecorators(Controller(path))`.
+     *
+     * Several names is the normal answer rather than an ambiguity, since
+     * a wrapper composing two library decorators applies both. The caller
+     * asks whether the name it cares about is among them.
+     *
+     * One wrapper is applied across hundreds of files, so the answer is
+     * memoized against the declaration it was asked about. Without that,
+     * every use site seeds a fresh value and pays another fixpoint.
+     */
+    importedNamesOf(value: Node, modules: string[]): string[];
+    /**
+     * The names from `modules` this value stands for, or null while the
+     * walk should keep widening.
+     *
+     * The distinction is what keeps the cost down. A value that has
+     * arrived at a package has nothing more to give, because a library's
+     * own body is not here to read, so a decorator from a library the
+     * caller did not ask about stops on the first wave rather than
+     * running out the import closure looking for a match it will never
+     * find. A value that has only arrived at another file in the project
+     * keeps going, since the wrapper it names is declared somewhere the
+     * walk has not reached yet.
+     */
+    private lookupImportedNames;
     private resolveByWaves;
+    private walkForAnswer;
+    /**
+     * The answer has been read, so the question and the chain that
+     * answered it can go. What the query extracted stays: files are the
+     * expensive part and the next query reads the same facts.
+     *
+     * Nothing is owed after this. The rules have seen every fact the
+     * database holds and concluded what the demand still present asks
+     * for, which is none, so the next query starts from its own asking
+     * fact.
+     */
+    private forgetQuery;
+    /**
+     * Somebody asked about this value, which is what the rules follow
+     * chains for. Separate from `seedValue`, which only speaks for values
+     * that are expressions; a caller can ask about a declaration too, and
+     * the answer is still owed.
+     */
+    private wantValue;
     /**
      * Facts for the queried value itself. File extraction only reaches
      * values that hang off exports, and a query can be rooted anywhere:
@@ -129,14 +250,19 @@ declare class ResolutionStore {
     private seedValue;
     private lookupObject;
     /**
-     * Whether `file` reaches any of `packages` through its imports,
-     * following project-local re-export chains.
-     *
-     * A walk rather than a rule: the answer is one boolean per file, and
-     * deriving the full reachable-module relation for every file in a
-     * large repo costs far more than the question is worth.
+     * Reaching two different expressions means the rules cannot tell
+     * which one the value is written as, and the same reasoning applies
+     * as for the other two questions: ambiguity is nothing. The value
+     * itself is not an answer, or every identifier would answer with
+     * itself the moment its chain went nowhere.
      */
-    importsTransitively(sourceFile: SourceFile, packages: string[]): boolean;
+    private lookupWritten;
+    /**
+     * For each set of files and packages, which of those files reach any
+     * of those packages through their imports, following project-local
+     * re-export chains.
+     */
+    filesImportingTransitively(fileSets: ReadonlyArray<FileSetQuery>): ReadonlyArray<ReadonlySet<SourceFile>>;
     /**
      * The one function this value resolves to. Several rules can reach
      * the same answer, which is fine, but reaching two different
@@ -145,11 +271,17 @@ declare class ResolutionStore {
      * answer depend on the order facts arrived in. Ambiguity is nothing.
      */
     private lookup;
+    /** Run the rules to fixpoint. */
+    private derive;
     /**
-     * Run the rules to fixpoint and index `resolves` by its source, so
-     * a lookup is a map hit rather than a scan of every derived tuple.
+     * The second column of an answer relation, for the value asked about.
+     * The database indexes a column the first time somebody looks it up
+     * and keeps that index as facts arrive, so this is a map hit and the
+     * answers a query never asks about cost nothing.
      */
-    private derive;
+    private answersFor;
+    /** The trailing pair of a three-column answer relation, joined. */
+    private answerPairsFor;
     /** Emit a file's facts, unless some earlier query already did. */
     private extractFile;
 }
@@ -167,7 +299,18 @@ interface ClientCallSite {
     methodName: string | null;
 }
 interface DiscoveredUnit {
-    func: FunctionRoot;
+    /**
+     * The function this unit is. Null when a registration announced a
+     * boundary and the handler it names comes from outside everything
+     * this run reads, in which case `announcedAt` is where the unit is
+     * and the summary describes a boundary with nothing behind it.
+     */
+    func: FunctionRoot | null;
+    /**
+     * The registration that announced a boundary whose handler was never
+     * reached. Set exactly when `func` is null, and the unit's location.
+     */
+    announcedAt?: Node;
     kind: string;
     name: string;
     callSite?: ClientCallSite;
@@ -284,6 +427,8 @@ interface DiscoveredUnit {
         messageBus: MessageBusSemantics["messageBus"];
         channel: string;
     };
+    /** The thing that gets deployed and runs this unit, when known. */
+    deployableUnit?: DeployableUnit;
     /**
      * Metadata merged onto the assembled summary's `metadata` field.
      * Populated when a pack's `discoverUnits` callback stamps provenance
@@ -323,7 +468,7 @@ interface Timer {
  */
 type DescentBarriers = ReadonlySet<Node>;
 
-declare function extractCodeStructure(unit: DiscoveredUnit, pack: PatternPack, filePath: string, invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers): RawCodeStructure;
+declare function extractCodeStructure(unit: DiscoveredUnit, pack: PatternPack, invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers): RawCodeStructure;
 interface TypeScriptAdapterConfig {
     tsConfigFilePath?: string;
     project?: Project;
@@ -367,13 +512,15 @@ interface TypeScriptAdapterConfig {
      */
     onExtractionReport?: (report: ExtractionReport) => void;
     /**
-     * On-disk cache directory for the coarse-key extraction cache.
-     * Pass an absolute path; defaults to `.suss/cache/` next to the
-     * tsconfig (or under cwd when no tsconfig path is supplied).
-     * Pass `null` to disable caching entirely. The cache stores one
-     * `manifest.json` keyed against (adapter version, pack versions,
-     * sorted file mtime/size stamps); on a warm run with no changes
-     * the lookup is stat-only and skips extraction.
+     * On-disk cache directory for the extraction cache. Pass an absolute
+     * path; defaults to `.suss/cache/` next to the tsconfig, and to no
+     * cache at all when no tsconfig path is supplied. Pass `null` to turn
+     * caching off. A warm run with nothing changed costs one stat per
+     * file and returns the previous run's summaries whole.
+     *
+     * A process that loaded the adapter from source gets no cache
+     * whatever this says, because a key made there cannot tell one build
+     * of the adapter from another.
      */
     cacheDir?: string | null;
 }
@@ -404,6 +551,16 @@ interface FoundTerminal {
      * Anything downstream that guessed instead got it wrong.
      */
     source?: Node;
+    /**
+     * A test that also has to hold for this terminal to be the one that
+     * fires, on top of whatever the path to it required.
+     *
+     * One call site answers with more than one status when the status is
+     * written as a choice, and the arms are told apart by nothing else:
+     * they share a node, so the path engine gives them the same
+     * conditions.
+     */
+    whenAlso?: RawCondition;
 }
 
 /**
@@ -516,7 +673,7 @@ interface ContractReadResult {
  * Returns null if the handler wasn't registered with a contract or the contract
  * can't be resolved.
  */
-declare function readContract(unit: DiscoveredUnit, pattern: ContractPattern): ContractReadResult | null;
+declare function readContract(unit: DiscoveredUnit, pattern: ContractPattern, framework: string): ContractReadResult | null;
 /**
  * Resolve the contract for a consumer call site.
  *
@@ -524,7 +681,7 @@ declare function readContract(unit: DiscoveredUnit, pattern: ContractPattern): C
  * call to find the contract, then extracts the endpoint definition for the
  * matched method name (e.g. "getUser").
  */
-declare function readContractForClientCall(callExpression: Node, methodName: string, pattern: ContractPattern): ContractReadResult | null;
+declare function readContractForClientCall(callExpression: Node, methodName: string, pattern: ContractPattern, framework: string): ContractReadResult | null;
 
 interface TsDiscoveryContext {
     /** Full filesystem path of the source file. Useful for excluding
@@ -548,11 +705,18 @@ interface TsDiscoveryContext {
         isDefault: boolean;
     }>;
     /**
-     * For an export whose declaration is a call to one of `callees`,
-     * read the string a property of the call's config object holds:
-     * `export const handler = createEventHandler({ expected: "a.b" }, ...)`
-     * with `{ callees: ["createEventHandler"], argIndex: 0, property:
-     * "expected" }` answers `"a.b"`.
+     * For an export the project builds by calling a factory, the string a
+     * property of that call's config object holds:
+     * `export const handler = makeWidgetHandler({ subject: "a.b" }, ...)`
+     * with `{ property: "subject" }` answers `"a.b"`.
+     *
+     * Which function was called and which argument carried the config are
+     * questions the caller does not have to answer. Every object argument
+     * is read. Naming the callee or fixing the argument position narrows
+     * that, for a project whose factories would otherwise collide.
+     *
+     * Two arguments holding the property under different values answers
+     * null, since nothing says which one was meant.
      *
      * The config argument is usually an object literal at the call site;
      * a variable or import is followed to the literal it resolves to.
@@ -562,8 +726,8 @@ interface TsDiscoveryContext {
      * rather than guessing.
      */
     exportedCallConfigString(sourceFile: SourceFile, exportName: string, spec: {
-        callees: string[];
-        argIndex: number;
+        callees?: string[];
+        argIndex?: number;
         property: string;
     }): string | null;
     /**
@@ -580,6 +744,50 @@ interface TsDiscoveryContext {
 }
 declare function createTsDiscoveryContext(resolution?: ResolutionStore): TsDiscoveryContext;
 
+/** One thing that looks wrong, in the same shape the dogfood invariants report. */
+interface HealthViolation {
+    label: string;
+    detail: string;
+}
+interface HealthCheck {
+    /** The property, as something that either holds or does not. */
+    name: string;
+    /**
+     * The heading printed when this check finds something.
+     *
+     * The property reads as an assertion, so printing `name` above the
+     * violations of it says "no pack collides with itself" and then lists
+     * a pack colliding with itself.
+     */
+    whenBroken: string;
+    /**
+     * Who the finding is addressed to.
+     *
+     * A `run` check found something about the code in front of it, and
+     * the person who started the run can do something about it: drop a
+     * pack, install a dependency, open an issue with the file that
+     * broke. A `pack` check found something about how a pack was built,
+     * which only whoever ships that pack can fix. Printing the second
+     * kind on every run would teach people to skim past the first.
+     */
+    audience: "run" | "pack";
+    violations: HealthViolation[];
+}
+/**
+ * Run every health check over one extraction report and return what
+ * fired, grouped by which check caught it.
+ */
+declare function evaluatePackHealth(report: ExtractionReport): HealthCheck[];
+/**
+ * The health checks that fired, as lines for a terminal.
+ *
+ * `audiences` is who the caller is printing for, and it is required
+ * because there is no answer that suits every caller: a CLI run prints
+ * what the person who started it can act on, and a run whose reader is
+ * a pack author wants both.
+ */
+declare function formatPackHealth(checks: ReadonlyArray<HealthCheck>, audiences: ReadonlyArray<HealthCheck["audience"]>): string;
+
 /**
  * Parse a ts-morph Expression into a structured Predicate.
  * Returns null when the expression can't be decomposed cleanly.
@@ -695,15 +903,34 @@ interface TsJsxAttributeLocation {
 declare function createTsSubUnitContext(): TsSubUnitContext;
 
 declare const ADAPTER_VERSION = "0.2.0";
+/**
+ * Content hash of the given files, in the order they arrive. Empty when
+ * the list is empty or a file cannot be read, so a caller that could not
+ * place a file gets the same "no stamp" answer as a run from source
+ * rather than a hash of a shorter list.
+ *
+ * The caller resolves the paths, because who a specifier resolves to
+ * depends on which package is asking.
+ */
+declare function computeContentHash(paths: readonly string[]): string;
 /**
  * Compute a cache-friendly identity for an adapter+packs combination.
  * Stable across processes given the same inputs; bumps when any pack
- * declares a new version, the adapter version changes, or the loaded
- * adapter dist file changes (dev-mode rebuild auto-invalidation).
+ * arrives with a new version stamp, the adapter version changes, or the
+ * loaded adapter dist file changes (dev-mode rebuild auto-invalidation).
+ *
+ * A pack's stamp is whatever the caller that loaded the pack put there.
+ * The adapter takes packs as plain objects and cannot tell where one
+ * came from, so folding the config and the code into the stamp is the
+ * loader's job.
+ *
+ * A source run says so in the digest rather than leaving the adapter
+ * out of it. Nothing writes under that digest today, and a key that
+ * names the mode cannot be mistaken for a key that named the code.
  */
 declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     name: string;
     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 PackFunnel, type Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, isImportedFrom, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, resolveSubject };
+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 Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, isImportedFrom, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, resolveSubject };