@suss/adapter-typescript 0.8.0 → 0.10.0

package/dist/index.d.cts

@@ -2,17 +2,41 @@ import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunctio
 import { 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';
 
+/**
+ * cache.ts: the on-disk extraction cache.
+ *
+ * A run reuses the previous one's summaries whole when nothing
+ * changed, and per file when some files did. The entry directory is
+ * named after everything that has to agree before any reuse is sound:
+ * schema version, adapter version and code hash, pack versions, the
+ * extraction config stamp and the tsconfig path. Inside it, the
+ * manifest records a stamp and content hash per file, each summary's
+ * owning files, and per owning file the other files its walk read, so
+ * a change to any of those re-extracts the owner instead of serving a
+ * stale answer. The full design, including what per-file reuse can
+ * and cannot promise, is in this package's README.
+ */
+
 /** Reported by `lookup`: what the cache decided, and why. */
 interface CacheDiagnostic {
-    kind: "hit" | "miss";
+    kind: "hit" | "miss" | "partial";
     /**
      * Reason the lookup missed (only set when kind === "miss").
-     * `key-changed` means the cache directory holds entries, but none
+     * `key-changed` means the cache directory contains 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";
+    /** Set when kind === "partial". */
+    partial?: {
+        filesChanged: number;
+        filesRemoved: number;
+        rootsReused: number;
+        rootsReextracted: number;
+        rootsDeclined: number;
+        summariesReused: number;
+    };
 }
 /**
  * Result of a cache lookup. A hit gives back the whole summary set; a miss
@@ -21,6 +45,7 @@ interface CacheDiagnostic {
 type CacheLookup = {
     kind: "hit";
     summaries: BehavioralSummary[];
+    projectRoot?: string;
     diagnostic: CacheDiagnostic;
 } | {
     kind: "miss";
@@ -180,6 +205,8 @@ declare class ResolutionStore {
     private readonly fullyExtracted;
     private readonly seededValues;
     private readonly importedNames;
+    /** Files the most recent wave walk entered, for the memo to keep. */
+    private lastQueryWalked;
     private readonly declarations;
     private readonly graph;
     private stale;
@@ -313,17 +340,19 @@ interface DiscoveredUnit {
      * path.
      *
      * `schemaSdl` is the typeDefs string captured from the same
-     * ApolloServer config object the resolver map came from, when
-     * we can statically resolve it (string literal or gql-tagged
-     * template, inline or const-bound). Surfaced on the summary so
-     * the checker's nested-selection pairing can look up return-type
-     * fields without needing a separate schema provenance.
+     * ApolloServer config object the resolver map came from, when we can
+     * statically resolve it (string literal or gql-tagged template,
+     * inline or const-bound). The adapter puts it on one summary
+     * standing for that schema, and `schemaDocument` is the label
+     * pointing every resolver at it.
      */
     resolverInfo?: {
         /** Null when the source never says which type the resolver attaches to. */
         typeName: string | null;
         fieldName: string;
         schemaSdl?: string;
+        /** The file whose server config declares the schema. */
+        schemaDocument?: string;
     };
     /**
      * Populated by `graphqlHookCall` discovery (GraphQL consumer side).
@@ -438,6 +467,12 @@ interface MountPrefixIndex {
      * couldn't be resolved to a literal prefix and a concrete router.
      */
     effectivePrefixFor(routerNode: Node): string;
+    /**
+     * The same resolution by a router's node id, for callers replaying a
+     * recorded consumption without the node in hand (the per-file cache
+     * re-checks a stored prefix against a rebuilt index this way).
+     */
+    prefixForId?(childId: string): string;
 }
 
 /**
@@ -846,9 +881,8 @@ declare function methodDeclaredIn(callee: Node, expectedModule: string): boolean
 interface ReadNameOptions {
     /**
      * What to say about a name nothing here settles. `"nothing"` gives
-     * null. `"reference"` gives a hole named after what the source asked
-     * for, `{location.bucket}`, which says which value to go and ask
-     * about rather than which bucket this is.
+     * null. `"reference"` gives `{location.bucket}`, which says which
+     * value to go and ask about rather than which bucket this is.
      */
     unsettled?: "nothing" | "reference";
     /**

package/dist/index.d.ts

@@ -2,17 +2,41 @@ import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunctio
 import { 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';
 
+/**
+ * cache.ts: the on-disk extraction cache.
+ *
+ * A run reuses the previous one's summaries whole when nothing
+ * changed, and per file when some files did. The entry directory is
+ * named after everything that has to agree before any reuse is sound:
+ * schema version, adapter version and code hash, pack versions, the
+ * extraction config stamp and the tsconfig path. Inside it, the
+ * manifest records a stamp and content hash per file, each summary's
+ * owning files, and per owning file the other files its walk read, so
+ * a change to any of those re-extracts the owner instead of serving a
+ * stale answer. The full design, including what per-file reuse can
+ * and cannot promise, is in this package's README.
+ */
+
 /** Reported by `lookup`: what the cache decided, and why. */
 interface CacheDiagnostic {
-    kind: "hit" | "miss";
+    kind: "hit" | "miss" | "partial";
     /**
      * Reason the lookup missed (only set when kind === "miss").
-     * `key-changed` means the cache directory holds entries, but none
+     * `key-changed` means the cache directory contains 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";
+    /** Set when kind === "partial". */
+    partial?: {
+        filesChanged: number;
+        filesRemoved: number;
+        rootsReused: number;
+        rootsReextracted: number;
+        rootsDeclined: number;
+        summariesReused: number;
+    };
 }
 /**
  * Result of a cache lookup. A hit gives back the whole summary set; a miss
@@ -21,6 +45,7 @@ interface CacheDiagnostic {
 type CacheLookup = {
     kind: "hit";
     summaries: BehavioralSummary[];
+    projectRoot?: string;
     diagnostic: CacheDiagnostic;
 } | {
     kind: "miss";
@@ -180,6 +205,8 @@ declare class ResolutionStore {
     private readonly fullyExtracted;
     private readonly seededValues;
     private readonly importedNames;
+    /** Files the most recent wave walk entered, for the memo to keep. */
+    private lastQueryWalked;
     private readonly declarations;
     private readonly graph;
     private stale;
@@ -313,17 +340,19 @@ interface DiscoveredUnit {
      * path.
      *
      * `schemaSdl` is the typeDefs string captured from the same
-     * ApolloServer config object the resolver map came from, when
-     * we can statically resolve it (string literal or gql-tagged
-     * template, inline or const-bound). Surfaced on the summary so
-     * the checker's nested-selection pairing can look up return-type
-     * fields without needing a separate schema provenance.
+     * ApolloServer config object the resolver map came from, when we can
+     * statically resolve it (string literal or gql-tagged template,
+     * inline or const-bound). The adapter puts it on one summary
+     * standing for that schema, and `schemaDocument` is the label
+     * pointing every resolver at it.
      */
     resolverInfo?: {
         /** Null when the source never says which type the resolver attaches to. */
         typeName: string | null;
         fieldName: string;
         schemaSdl?: string;
+        /** The file whose server config declares the schema. */
+        schemaDocument?: string;
     };
     /**
      * Populated by `graphqlHookCall` discovery (GraphQL consumer side).
@@ -438,6 +467,12 @@ interface MountPrefixIndex {
      * couldn't be resolved to a literal prefix and a concrete router.
      */
     effectivePrefixFor(routerNode: Node): string;
+    /**
+     * The same resolution by a router's node id, for callers replaying a
+     * recorded consumption without the node in hand (the per-file cache
+     * re-checks a stored prefix against a rebuilt index this way).
+     */
+    prefixForId?(childId: string): string;
 }
 
 /**
@@ -846,9 +881,8 @@ declare function methodDeclaredIn(callee: Node, expectedModule: string): boolean
 interface ReadNameOptions {
     /**
      * What to say about a name nothing here settles. `"nothing"` gives
-     * null. `"reference"` gives a hole named after what the source asked
-     * for, `{location.bucket}`, which says which value to go and ask
-     * about rather than which bucket this is.
+     * null. `"reference"` gives `{location.bucket}`, which says which
+     * value to go and ask about rather than which bucket this is.
      */
     unsettled?: "nothing" | "reference";
     /**