@suss/adapter-typescript 0.9.0 → 0.10.0

package/README.md

@@ -34,6 +34,42 @@ Two passes get ahead of the compiler. Both walk the graph iteratively, starting
 
 If the warmed compiler still cannot follow a chain, we record that rather than throwing. A provider whose exports we could not read would otherwise look exactly like one that exports nothing, so we note the file in the extraction report and let the run finish with the summaries it has.
 
+## Extraction cache
+
+A second run over an unchanged repository returns the first run's summaries from disk, and a run after an edit re-extracts only the files the edit can affect. The cache lives in `.suss/cache/` beside the tsconfig, is off for caller-supplied projects, and `--no-cache` skips it for one run. `cache.ts` implements it; this section is the design.
+
+### The key
+
+An entry is only readable by a run that agrees with the one that wrote it on everything that changes what extraction produces. The entry directory's name hashes: the cache schema version, the adapter version plus a content hash of the loaded adapter and analysis bundles, each pack's name, declared version, code hash and config digest, the extraction config (`includeReachable`, `gapHandling`), and the tsconfig path. Inside the entry, the tsconfig's own stamp and a stamp per project file guard the rest. A run built from source instead of a bundle has no code hash, and declines to cache at all.
+
+### Whole reuse, then per-file reuse
+
+The fast path compares stats alone: same mtime and size on the tsconfig and every file means the previous summaries come back verbatim, with no parse and no hashing. When stats moved, the run hashes the moved files' content; a touch that changed nothing becomes a hit. When content did change, the per-file layer takes over: the manifest records, for every walked file, which summaries its walk produced (wherever those summaries' functions live), and which other files that walk read. A file whose own hash and whose recorded reads are all unchanged gets its summaries served from the manifest; everything else is re-extracted with the full project loaded, and the results merge.
+
+### What "which other files" means
+
+Cross-file reads are recorded from several directions at once:
+
+- The files the walked file references directly, which covers the types and helpers it imports itself. The whole import closure was measured and rejected: on a repository with import cycles through its app module, one edited controller invalidated a third of the tree.
+- Every file the resolution store walked while answering a question asked during the file's walk, hop by hop, which covers re-export chains the store followed and values wired up outside the import graph, an injected class constructed in another file among them.
+- The files of every function the reachable closure entered from the file's units, plus one import hop past each, plus what the store answered during those scans.
+- Export tables read and aliases resolved through the module-exports helpers, wherever the resolution landed.
+- The file that claimed a unit this file's walk would otherwise have claimed, since the claim decided what this file's output leaves out.
+- The mount prefixes the walk consumed, re-checked by id against the rebuilt index on every partial run, so a mount added or changed in a file the router never imports still invalidates its routes.
+- The packs that applied to the file, re-checked against the fresh gate on every partial run, so a barrel that starts re-exporting a framework flips the file back to walked.
+
+A file declines caching when one of its summaries takes part in a run-level GraphQL join: it has a document label (schema lifting moves SDL between summaries sharing one) or it is an operation (client stamping writes the project-wide sole client onto every one). A code-first resolver joins with nothing and stays cacheable. Summaries built by run-level passes (wrapper-caller expansion, library env-read markers, schema documents) belong to no file and are recomputed on every partial run. Units the cache serves are excluded from closure emission the way a cold run's seeds are, so a re-walked file reaching a cached unit never duplicates it.
+
+### What stage one does not promise
+
+A type read more than one import hop away, through a chain no recorded mechanism followed, can change a summary's printed types without invalidating it. The middle file of a deep re-export chain has the same hole when the compiler, not the store, resolved the chain. A dependency upgrade under `node_modules` invalidates nothing (the pack and adapter hashes carry library knowledge instead). Recording what each answer read, per answer, is stage two of #422 and closes these.
+
+A re-extracted summary can also differ from a cache-free run in one representational way: type-shape expansion shares a per-run memo, so a run that walks five files can expand a shape to a different depth than a run that walks a thousand, and the shape digest moves with it. The summary was computed fresh either way; nothing served is stale.
+
+### Invalidation, wholesale
+
+The schema version is part of the entry directory's name, so a format change makes every old entry unreachable rather than misread, and the eviction pass deletes it in time. `MAX_ENTRIES` bounds a cache directory at two entries.
+
 ## Status
 
 Stable. Public API: `createTypeScriptAdapter` returns an adapter with `extractFromFiles` and `extractAll` methods. Provider-side extraction (handlers, terminals, contracts, body shapes) and client-side extraction (call sites, response field tracking) are both supported. See [`docs/extraction-algorithm.md`](../../../docs/extraction-algorithm.md) for the algorithm and [`docs/internal/status.md`](../../../docs/internal/status.md) for the capability matrix.