dsh-plugin-codegraph-tree-sitter 0.1.7 → 0.2.0

package/lib/cache.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Parse-result cache: the extraction this package computed for each file on the previous run, so a
+ * repeat index of an unchanged workspace can skip the read, the parse, and the tree walk for every
+ * file whose content did not change.
+ *
+ * The cache is an accelerator with no authority. It is read only as a hint — anything missing,
+ * unreadable, corrupt, written by another version, or shaped unexpectedly is discarded and the file
+ * is parsed again, so losing it costs time and never correctness. That is what lets
+ * {@link readParseCache} swallow every failure and {@link writeParseCache} tolerate a workspace this
+ * process may not write to.
+ * @module dsh-plugin-codegraph-tree-sitter/cache
+ */
+import type { FileExtraction } from './extract.ts';
+import type { ExtractedFile } from './resolve.ts';
+/**
+ * Version of the extraction semantics this cache records. Bump it by hand whenever `extract.ts` (or
+ * a grammar that feeds it) starts producing a different result for the same source text: a stale
+ * entry would otherwise be reused as if it were current, and the graph would silently keep the old
+ * shape.
+ */
+export declare const EXTRACTION_CACHE_VERSION = 1;
+/** Path of the parse cache, relative to a project root. */
+export declare const EXTRACTION_CACHE_RELATIVE_PATH = ".codegraph/cache/extractions.json";
+/** One file's cached extraction, together with the identity it was computed from. */
+export interface CachedFile {
+    /** Epoch milliseconds of the file's modification time when its extraction was produced. */
+    readonly modifiedAt: number;
+    /** File size in bytes at that same moment. */
+    readonly size: number;
+    /** SHA-256 of the content the extraction was produced from, hex-encoded. */
+    readonly contentHash: string;
+    /** Line count of that content, recorded so a reused file still gets a correct span. */
+    readonly lineCount: number;
+    /** Seam language label the extraction was produced for. */
+    readonly language: string;
+    /** The extraction itself. */
+    readonly extraction: FileExtraction;
+}
+/**
+ * Load the previous run's extractions for `projectRoot`.
+ *
+ * Never throws: a cache that cannot be read, parsed, or trusted yields an empty map, which makes the
+ * caller parse everything. A single malformed entry discards the whole file — an entry is either a
+ * complete record this package wrote or evidence the document was damaged, and reasoning about
+ * partial reuse is not worth the risk of a graph built from a half-written entry.
+ * @param projectRoot - absolute path of the workspace whose cache to load.
+ * @returns the cached extractions keyed by project-relative path, empty when none can be trusted.
+ */
+export declare function readParseCache(projectRoot: string): Promise<Map<string, CachedFile>>;
+/**
+ * Record this run's extractions as the next run's cache.
+ *
+ * Written through a sibling temporary name and `rename`d into place, the same way `./schema.ts`
+ * replaces its status sidecar, so a reader never sees half a document. The temporary name is fixed
+ * rather than unique: a write interrupted before its rename is overwritten by the next attempt
+ * instead of accumulating, and a torn leftover is rejected by {@link readParseCache} at the cost of
+ * one run's reuse.
+ *
+ * A failure is swallowed on purpose. A read-only workspace, a full disk, or a locked directory must
+ * still be indexable; the cache is the optimization, never the product.
+ * @param projectRoot - absolute path of the workspace to record the cache for.
+ * @param files - every file this run produced an extraction for.
+ */
+export declare function writeParseCache(projectRoot: string, files: readonly ExtractedFile[]): Promise<void>;
+//# sourceMappingURL=cache.d.ts.map

package/lib/cache.js

@@ -0,0 +1,142 @@
+/**
+ * Parse-result cache: the extraction this package computed for each file on the previous run, so a
+ * repeat index of an unchanged workspace can skip the read, the parse, and the tree walk for every
+ * file whose content did not change.
+ *
+ * The cache is an accelerator with no authority. It is read only as a hint — anything missing,
+ * unreadable, corrupt, written by another version, or shaped unexpectedly is discarded and the file
+ * is parsed again, so losing it costs time and never correctness. That is what lets
+ * {@link readParseCache} swallow every failure and {@link writeParseCache} tolerate a workspace this
+ * process may not write to.
+ * @module dsh-plugin-codegraph-tree-sitter/cache
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/**
+ * Version of the extraction semantics this cache records. Bump it by hand whenever `extract.ts` (or
+ * a grammar that feeds it) starts producing a different result for the same source text: a stale
+ * entry would otherwise be reused as if it were current, and the graph would silently keep the old
+ * shape.
+ */
+export const EXTRACTION_CACHE_VERSION = 1;
+/** Path of the parse cache, relative to a project root. */
+export const EXTRACTION_CACHE_RELATIVE_PATH = '.codegraph/cache/extractions.json';
+/**
+ * Whether `value` is a plain JSON object. Arrays are deliberately included: every caller still
+ * validates the fields it needs, and an array simply carries none of them.
+ * @param value - the parsed JSON value to test.
+ * @returns whether it is a non-null object.
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Whether `value` is a usable extraction. Deliberately shallow past the four arrays: those are what
+ * `resolveWorkspace` indexes into, and the only expected producer is this package's own writer.
+ * @param value - the value to test.
+ * @returns whether it has the four collections an extraction consists of.
+ */
+function isFileExtraction(value) {
+    return isRecord(value)
+        && Array.isArray(value.definitions)
+        && Array.isArray(value.calls)
+        && Array.isArray(value.imports)
+        && Array.isArray(value.heritage);
+}
+/**
+ * Whether `value` is a complete cache entry.
+ * @param value - the value to test.
+ * @returns whether every field is present and of the type a reader will use it as.
+ */
+function isCachedFile(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.modifiedAt === 'number'
+        && typeof value.size === 'number'
+        && typeof value.contentHash === 'string'
+        && typeof value.lineCount === 'number'
+        && typeof value.language === 'string'
+        && isFileExtraction(value.extraction);
+}
+/**
+ * Load the previous run's extractions for `projectRoot`.
+ *
+ * Never throws: a cache that cannot be read, parsed, or trusted yields an empty map, which makes the
+ * caller parse everything. A single malformed entry discards the whole file — an entry is either a
+ * complete record this package wrote or evidence the document was damaged, and reasoning about
+ * partial reuse is not worth the risk of a graph built from a half-written entry.
+ * @param projectRoot - absolute path of the workspace whose cache to load.
+ * @returns the cached extractions keyed by project-relative path, empty when none can be trusted.
+ */
+export async function readParseCache(projectRoot) {
+    const cachePath = join(projectRoot, EXTRACTION_CACHE_RELATIVE_PATH);
+    let raw;
+    try {
+        raw = await readFile(cachePath, 'utf8');
+    }
+    catch {
+        // The ordinary first run has no cache file yet; an unreadable one is the same answer to the
+        // caller — nothing to reuse — and must not fail an index that can still parse the workspace.
+        return new Map();
+    }
+    let document;
+    try {
+        document = JSON.parse(raw);
+    }
+    catch {
+        return new Map();
+    }
+    if (!isRecord(document))
+        return new Map();
+    if (document.cacheVersion !== EXTRACTION_CACHE_VERSION)
+        return new Map();
+    const entries = document.files;
+    if (!isRecord(entries))
+        return new Map();
+    const cache = new Map();
+    for (const [path, entry] of Object.entries(entries)) {
+        if (!isCachedFile(entry))
+            return new Map();
+        cache.set(path, entry);
+    }
+    return cache;
+}
+/**
+ * Record this run's extractions as the next run's cache.
+ *
+ * Written through a sibling temporary name and `rename`d into place, the same way `./schema.ts`
+ * replaces its status sidecar, so a reader never sees half a document. The temporary name is fixed
+ * rather than unique: a write interrupted before its rename is overwritten by the next attempt
+ * instead of accumulating, and a torn leftover is rejected by {@link readParseCache} at the cost of
+ * one run's reuse.
+ *
+ * A failure is swallowed on purpose. A read-only workspace, a full disk, or a locked directory must
+ * still be indexable; the cache is the optimization, never the product.
+ * @param projectRoot - absolute path of the workspace to record the cache for.
+ * @param files - every file this run produced an extraction for.
+ */
+export async function writeParseCache(projectRoot, files) {
+    const cachePath = join(projectRoot, EXTRACTION_CACHE_RELATIVE_PATH);
+    const tempPath = `${cachePath}.tmp`;
+    try {
+        const entries = {};
+        for (const file of files) {
+            entries[file.path] = {
+                modifiedAt: file.modifiedAt,
+                size: file.size,
+                contentHash: file.contentHash,
+                lineCount: file.lineCount,
+                language: file.language,
+                extraction: file.extraction,
+            };
+        }
+        const document = { cacheVersion: EXTRACTION_CACHE_VERSION, files: entries };
+        await mkdir(dirname(cachePath), { recursive: true });
+        await writeFile(tempPath, JSON.stringify(document));
+        await rename(tempPath, cachePath);
+    }
+    catch {
+        // See above: an unusable cache location only means the next run parses everything again.
+    }
+}
+//# sourceMappingURL=cache.js.map

package/lib/index.d.ts

@@ -10,6 +10,11 @@
  * runs implicitly from a query — it is a caller-initiated, potentially multi-minute operation, kept
  * out of the seam's read-only query path on purpose.
  *
+ * Watching a root runs through `ctx.fs` (see `./watcher.ts`): the package observes each in-scope
+ * directory through the host's filesystem seam rather than opening paths itself, so a workspace a
+ * backend serves from another execution world is watched where it actually lives, and a backend that
+ * cannot watch at all degrades to explicit indexing instead of failing the plugin.
+ *
  * Namespace plugin (named exports, no default export). Grammars load lazily, one per language, on
  * first sight of a matching file, and stay cached for the process — never eagerly for every grammar
  * this package ships with.
@@ -28,10 +33,12 @@ export type { ExtractedFile, GraphEdge, GraphNode, ResolvedGraph, UnresolvedRef
 export { isMinifiedName, looksMinified, measureText, MINIFIED_AVERAGE_LINE_LENGTH } from './minified.ts';
 export type { TextShape } from './minified.ts';
 export { SCHEMA_VERSION, writeGraph } from './schema.ts';
+export { EXTRACTION_CACHE_RELATIVE_PATH, EXTRACTION_CACHE_VERSION, readParseCache, writeParseCache } from './cache.ts';
+export type { CachedFile } from './cache.ts';
 export { isExcluded, walkAndExtract } from './walk.ts';
 export type { WalkConfig, WalkResult } from './walk.ts';
-export { createWatcher, nodeWatch } from './watcher.ts';
-export type { DegradeReason, WatchConfig, WatchHandle, WatchPrimitive, Watcher } from './watcher.ts';
+export { createWatcher } from './watcher.ts';
+export type { DegradeReason, WatchConfig, WatchDirEntry, WatchFileSystem, WatchTarget, Watcher, } from './watcher.ts';
 export { decideWatch, readProcVersion } from './watch-policy.ts';
 export type { WatchDecision, WatchPolicyInput } from './watch-policy.ts';
 export { detectWorktree, execGit } from './worktree.ts';
@@ -60,7 +67,7 @@ export declare const DEFAULT_MAX_FILES = 50000;
 export declare const DEFAULT_CONCURRENCY = 4;
 /** Default quiet period after the last change before a watch-triggered refresh runs. */
 export declare const DEFAULT_WATCH_DEBOUNCE_MS = 2000;
-/** Default cap on directories watched individually, on platforms without a recursive `fs.watch`. */
+/** Default cap on directories watched individually, one watch each, by the fs seam. */
 export declare const DEFAULT_MAX_WATCHED_DIRECTORIES = 4000;
 /** Plugin configuration: the indexer's identity and every deployment-varying bound on a run. */
 export interface Config {
@@ -100,6 +107,22 @@ export interface Config {
     maxFiles?: number;
     /** Files parsed concurrently (default 4). */
     concurrency?: number;
+    /**
+     * Reuse the extraction a previous run cached for every file whose content is unchanged (default
+     * true), so a repeat index — or a watch rebuild after one edit — parses only what actually changed
+     * instead of the whole workspace. The cache lives at
+     * {@link EXTRACTION_CACHE_RELATIVE_PATH} and is rewritten after each successful run. Set false to
+     * parse every file every time, at the cost of the full parse each run.
+     */
+    reuseParsedCache?: boolean;
+    /**
+     * How a cached file's unchanged content is confirmed before its extraction is reused (default
+     * `'stat'`): `stat` compares the modification time and size the cache recorded and reads nothing;
+     * `hash` re-reads the file and compares a SHA-256, which also catches a rewrite that preserved both
+     * mtime and size (a checkout restoring an older file over a newer one). Hash mode still skips the
+     * parse and the tree walk, which dominate the per-file cost.
+     */
+    cacheVerify?: 'stat' | 'hash';
     /**
      * Watch the workspace for file changes and refresh the index automatically after a successful
      * `index()` call establishes a baseline (default true). Set `watch: false` to keep indexing purely
@@ -114,16 +137,17 @@ export interface Config {
     /** Quiet period after the last change before a watch-triggered refresh runs, in ms (default 2000). */
     watchDebounceMs?: number;
     /**
-     * Hard cap on directories watched individually (default 4000). Only relevant on platforms without a
-     * recursive `fs.watch` (Linux); exceeding it degrades that root's watcher rather than covering only
-     * part of the tree.
+     * Hard cap on directories watched individually (default 4000). Watching goes through the host's
+     * filesystem seam, whose `watch` covers one directory's direct entries, so a workspace costs one
+     * watch per in-scope directory; exceeding this cap degrades that root's watcher rather than
+     * covering only part of the tree.
      */
     maxWatchedDirectories?: number;
 }
 export declare const Config: z<Config>;
 /**
  * Register the tree-sitter indexer.
- * @param ctx - the plugin context (must inject `codegraph`).
+ * @param ctx - the plugin context (must inject `codegraph` and `fs`).
  * @param config - the resolved plugin configuration.
  */
 export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -10,6 +10,11 @@
  * runs implicitly from a query — it is a caller-initiated, potentially multi-minute operation, kept
  * out of the seam's read-only query path on purpose.
  *
+ * Watching a root runs through `ctx.fs` (see `./watcher.ts`): the package observes each in-scope
+ * directory through the host's filesystem seam rather than opening paths itself, so a workspace a
+ * backend serves from another execution world is watched where it actually lives, and a backend that
+ * cannot watch at all degrades to explicit indexing instead of failing the plugin.
+ *
  * Namespace plugin (named exports, no default export). Grammars load lazily, one per language, on
  * first sight of a matching file, and stay cached for the process — never eagerly for every grammar
  * this package ships with.
@@ -21,6 +26,7 @@ import z from '@deepseek-ai/schemastery';
 import { CodegraphIndexerId } from 'dsh-plugin-codegraph-service';
 import { LANGUAGE_TABLE } from "./languages.js";
 import { walkAndExtract } from "./walk.js";
+import { writeParseCache } from "./cache.js";
 import { resolveWorkspace } from "./resolve.js";
 import { writeGraph } from "./schema.js";
 import { createWatcher } from "./watcher.js";
@@ -31,15 +37,16 @@ export { loadGitignore, matchesGitignore, parseGitignore } from "./gitignore.js"
 export { resolveWorkspace } from "./resolve.js";
 export { isMinifiedName, looksMinified, measureText, MINIFIED_AVERAGE_LINE_LENGTH } from "./minified.js";
 export { SCHEMA_VERSION, writeGraph } from "./schema.js";
+export { EXTRACTION_CACHE_RELATIVE_PATH, EXTRACTION_CACHE_VERSION, readParseCache, writeParseCache } from "./cache.js";
 export { isExcluded, walkAndExtract } from "./walk.js";
-export { createWatcher, nodeWatch } from "./watcher.js";
+export { createWatcher } from "./watcher.js";
 export { decideWatch, readProcVersion } from "./watch-policy.js";
 export { detectWorktree, execGit } from "./worktree.js";
 export { HOOK_MARKER_BEGIN, HOOK_MARKER_END, installGitHooks, uninstallGitHooks } from "./git-hooks.js";
 /** Cordis plugin name for loader diagnostics. */
 export const name = 'codegraph-tree-sitter';
 /** Services required by this plugin. */
-export const inject = ['codegraph'];
+export const inject = ['codegraph', 'fs'];
 /** Path of the on-disk graph this package writes, relative to a project root. */
 export const DATABASE_RELATIVE_PATH = '.codegraph/codegraph.db';
 /** Default branded identity this indexer reserves on the seam. */
@@ -58,7 +65,7 @@ export const DEFAULT_MAX_FILES = 50_000;
 export const DEFAULT_CONCURRENCY = 4;
 /** Default quiet period after the last change before a watch-triggered refresh runs. */
 export const DEFAULT_WATCH_DEBOUNCE_MS = 2_000;
-/** Default cap on directories watched individually, on platforms without a recursive `fs.watch`. */
+/** Default cap on directories watched individually, one watch each, by the fs seam. */
 export const DEFAULT_MAX_WATCHED_DIRECTORIES = 4_000;
 export const Config = z.object({
     indexerId: z.string().default(DEFAULT_INDEXER_ID),
@@ -69,13 +76,15 @@ export const Config = z.object({
     maxFileBytes: z.number().default(DEFAULT_MAX_FILE_BYTES),
     maxFiles: z.number().default(DEFAULT_MAX_FILES),
     concurrency: z.number().default(DEFAULT_CONCURRENCY),
+    reuseParsedCache: z.boolean().default(true),
+    cacheVerify: z.union([z.const('stat'), z.const('hash')]).default('stat'),
     watch: z.boolean().default(true),
     watchDebounceMs: z.number().default(DEFAULT_WATCH_DEBOUNCE_MS),
     maxWatchedDirectories: z.number().default(DEFAULT_MAX_WATCHED_DIRECTORIES),
 });
 /**
  * Register the tree-sitter indexer.
- * @param ctx - the plugin context (must inject `codegraph`).
+ * @param ctx - the plugin context (must inject `codegraph` and `fs`).
  * @param config - the resolved plugin configuration.
  */
 export function apply(ctx, config) {
@@ -85,6 +94,13 @@ export function apply(ctx, config) {
     assertPositiveInteger('concurrency', resolved.concurrency);
     assertPositiveInteger('watchDebounceMs', resolved.watchDebounceMs);
     assertPositiveInteger('maxWatchedDirectories', resolved.maxWatchedDirectories);
+    // Watching goes through the host's filesystem seam rather than `node:fs`, so it follows the same
+    // execution world the rest of the harness reads: a remote or confined backend watches its own paths.
+    // The `fs` service is a declared dependency (see `inject`), so it is present whenever `apply` runs.
+    // It is read structurally instead of importing `@deepseek-ai/dsh-fs`: that package is not a
+    // dependency here, and its `watch` method only exists from host 0.2 onward, while this package
+    // supports older peers that have no such member to import.
+    const fileSystem = ctx.fs;
     // Keyed by project root, private to this plugin instance: never registered on `ctx`, so there is no
     // cross-plugin relation here for an invariant to describe — just process-local bookkeeping this
     // effect's cleanup below tears down on unload.
@@ -115,7 +131,7 @@ export function apply(ctx, config) {
                 console.error(`codegraph-tree-sitter: file watching for "${projectRoot}" stopped permanently (${reason.code}); ` +
                     'the index will no longer refresh on its own — run codegraph_index manually to update it.');
             },
-        });
+        }, fileSystem);
         watchers.set(projectRoot, watcher);
         watcher.start();
     }
@@ -169,7 +185,7 @@ async function runSync(projectRoot, config) {
  * @returns the run's report.
  */
 async function runIndex(projectRoot, config, signal) {
-    const { files, filesSkipped, filesMinified } = await walkAndExtract(projectRoot, {
+    const { files, filesSkipped, filesMinified, filesReused } = await walkAndExtract(projectRoot, {
         exclude: config.exclude,
         respectGitignore: config.respectGitignore,
         skipMinified: config.skipMinified,
@@ -177,13 +193,21 @@ async function runIndex(projectRoot, config, signal) {
         maxFiles: config.maxFiles,
         concurrency: config.concurrency,
         languages: config.languages,
+        reuseParsedCache: config.reuseParsedCache,
+        cacheVerify: config.cacheVerify,
     }, signal);
     signal?.throwIfAborted();
     const indexedAt = Date.now();
     const graph = resolveWorkspace(files, indexedAt);
     signal?.throwIfAborted();
     const databasePath = join(projectRoot, DATABASE_RELATIVE_PATH);
-    await writeGraph(databasePath, { files, nodes: graph.nodes, edges: graph.edges, unresolved: graph.unresolved, indexedAt });
+    await writeGraph(databasePath, {
+        files, nodes: graph.nodes, edges: graph.edges, unresolved: graph.unresolved, filesMinified, indexedAt,
+    });
+    // Only after the graph is in place: the cache records the extractions this run actually committed,
+    // so a run that failed before writing its graph leaves the previous cache — and the mtimes it was
+    // built from — alone instead of vouching for a graph that was never written.
+    await writeParseCache(projectRoot, files);
     const languageCounts = new Map();
     for (const file of files)
         languageCounts.set(file.language, (languageCounts.get(file.language) ?? 0) + 1);
@@ -195,6 +219,7 @@ async function runIndex(projectRoot, config, signal) {
         filesIndexed: files.length,
         filesSkipped,
         filesMinified,
+        filesReused,
         nodeCount: graph.nodes.length,
         edgeCount: graph.edges.length,
         unresolvedCount: graph.unresolved.length,

package/lib/schema.d.ts

@@ -19,6 +19,8 @@ export interface WriteInput {
     readonly nodes: readonly GraphNode[];
     readonly edges: readonly GraphEdge[];
     readonly unresolved: readonly UnresolvedRef[];
+    /** Generated artifacts this run left out of the graph, carried into the status sidecar. */
+    readonly filesMinified: number;
     readonly indexedAt: number;
 }
 /**

package/lib/schema.js

@@ -10,10 +10,11 @@
  * naive "delete then recreate" leaves open between `CREATE TABLE` and the first `COMMIT`.
  * @module dsh-plugin-codegraph-tree-sitter/schema
  */
-import { mkdir, rename, rm } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { randomUUID } from 'node:crypto';
+import { INDEX_STATUS_RELATIVE_PATH } from 'dsh-plugin-codegraph-service';
 /** The schema version this package writes, matching the format `dsh-codegraph-sqlite` reads. */
 export const SCHEMA_VERSION = 4;
 /**
@@ -122,5 +123,29 @@ export async function writeGraph(databasePath, input) {
     // rename() only moves the main file; the temp name's own sidecars (should the driver have left any)
     // never travel with it and would otherwise linger under the temp name forever.
     await removeGraphFiles(tempPath);
+    await writeStatusFile(dirname(databasePath), {
+        indexedAt: input.indexedAt,
+        filesIndexed: input.files.length,
+        filesMinified: input.filesMinified,
+        nodeCount: input.nodes.length,
+        edgeCount: input.edges.length,
+        unresolvedCount: input.unresolved.length,
+        unresolvedLikelyInternalCount: input.unresolved.filter(ref => !ref.likelyExternal).length,
+    });
+}
+/**
+ * Write the prompt-time status sidecar beside the graph, replacing it atomically.
+ *
+ * Deliberately after the graph's own rename: a reader that sees this file can trust that the graph it
+ * summarizes is already in place, which is what lets a prompt line report "336 files, built 12s ago"
+ * without opening SQLite on every model request.
+ * @param directory - the graph's directory (`.codegraph`).
+ * @param status - this run's summary.
+ */
+async function writeStatusFile(directory, status) {
+    const target = join(directory, basename(INDEX_STATUS_RELATIVE_PATH));
+    const temp = `${target}.tmp`;
+    await writeFile(temp, JSON.stringify(status));
+    await rename(temp, target);
 }
 //# sourceMappingURL=schema.js.map

package/lib/walk.d.ts

@@ -46,6 +46,21 @@ export interface WalkConfig {
      * workspace-wide name wins" call resolution would pick between them arbitrarily.
      */
     readonly respectGitignore: boolean;
+    /**
+     * Reuse the extraction a previous run cached for every file whose content is unchanged, instead of
+     * reading and parsing it again. The cache lives under `<projectRoot>/.codegraph/cache` and is
+     * written by the indexer after a run succeeds; a missing or unusable cache simply means every file
+     * is parsed.
+     */
+    readonly reuseParsedCache: boolean;
+    /**
+     * How a cached file is confirmed unchanged before its extraction is reused. `'stat'` compares the
+     * modification time and size the cache recorded — no read at all, and enough for a watcher rebuild,
+     * whose changes always move mtime. `'hash'` reads the file and compares a SHA-256, which also
+     * catches a rewrite that preserved both mtime and size (a checkout restoring an old file) at the
+     * cost of the read it would otherwise save.
+     */
+    readonly cacheVerify: 'stat' | 'hash';
 }
 /** What the walk produced. */
 export interface WalkResult {
@@ -55,13 +70,21 @@ export interface WalkResult {
     readonly filesSkipped: number;
     /** Candidates skipped because they are generated output — see {@link WalkConfig.skipMinified}. */
     readonly filesMinified: number;
+    /**
+     * Files whose extraction came from the parse cache instead of a fresh parse. These are still
+     * present in {@link files} and still indexed — the count says how much work the cache saved, not
+     * how much of the workspace was left out.
+     */
+    readonly filesReused: number;
 }
 /**
- * Walk `projectRoot` and parse every candidate file it finds.
+ * Walk `projectRoot` and parse every candidate file it finds — or reuse the extraction a previous
+ * run cached for it.
  * @param projectRoot - absolute path of the workspace to index.
  * @param config - the walk's bounds.
  * @param signal - aborts the walk.
- * @returns the parsed files and how many candidates were skipped (over size, or past `maxFiles`).
+ * @returns the parsed files, how many candidates were skipped (over size, or past `maxFiles`), and
+ *   how many files reused a cached extraction.
  */
 export declare function walkAndExtract(projectRoot: string, config: WalkConfig, signal?: AbortSignal): Promise<WalkResult>;
 //# sourceMappingURL=walk.d.ts.map