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

package/lib/resolve.js

@@ -3,13 +3,20 @@
  *
  * Pass 1 collects every definition into a name index. Pass 2 resolves each call site's callee name,
  * in order: (1) the enclosing file imports that name from a relative specifier resolving to a file
- * this run indexed — that file's matching declaration wins; (2) otherwise exactly one definition
- * workspace-wide carries the name — it wins; (3) otherwise the call is recorded in `unresolved` and no
- * `calls` edge is written. An ambiguous edge is worse than a missing one: the model acts on `callers`
- * output, so a confidently wrong caller sends it to edit the wrong file, while a missing caller merely
- * sends it back to text search.
+ * this run indexed — that file's matching declaration wins; (2) otherwise exactly one definition **in
+ * the calling file itself** carries the name — lexical scope settles it before the workspace gets a
+ * say, which is what keeps a helper declared in two test files (or a `render` in two components) from
+ * being counted as ambiguous; (3) otherwise exactly one definition workspace-wide carries the name —
+ * it wins; (4) otherwise the call is recorded in `unresolved` and no `calls` edge is written. An
+ * ambiguous edge is worse than a missing one: the model acts on `callers` output, so a confidently
+ * wrong caller sends it to edit the wrong file, while a missing caller merely sends it back to text
+ * search.
  *
- * Rule 3's `unresolved` entries are not one uniform signal. Each carries {@link UnresolvedRef.likelyExternal},
+ * Rule 2 is restricted to bare calls. A member call (`x.map()`) names a property of a receiver whose
+ * type this resolver does not track, so a same-named local declaration winning it would be a guess
+ * rather than a scope resolution — exactly the kind of confidently wrong edge rule 4 exists to avoid.
+ *
+ * Rule 4's `unresolved` entries are not one uniform signal. Each carries {@link UnresolvedRef.likelyExternal},
  * which is true for a member call (no type information behind its receiver) or a name the file itself
  * imports (a known external origin the specifier just didn't resolve) — both real code that was never a
  * candidate for a workspace edge, as against a bare, undeclared name, which is the actual gap this
@@ -99,6 +106,22 @@ function buildNameIndex(nodesByFile) {
     }
     return index;
 }
+/**
+ * Group one file's own nodes by declaration name, for the same-file tier of call resolution.
+ * @param nodes - the nodes declared in one file.
+ * @returns every name that file declares, mapped to the nodes carrying it.
+ */
+function indexByName(nodes) {
+    const index = new Map();
+    for (const node of nodes) {
+        const existing = index.get(node.name);
+        if (existing === undefined)
+            index.set(node.name, [node]);
+        else
+            existing.push(node);
+    }
+    return index;
+}
 /**
  * A name index restricted to `class`/`interface` nodes, for `extends`/`implements` resolution.
  * `extractHeritage` only ever names a base class or interface, never a function or variable — indexing
@@ -213,9 +236,10 @@ export function resolveWorkspace(files, now) {
         }
         const keyToId = mustGet(defIdByKey, file.path);
         const importedLocalNames = new Set(file.extraction.imports.map(binding => binding.localName));
+        const localByName = indexByName(mustGet(nodesByFile, file.path));
         for (const call of file.extraction.calls) {
             const callerId = call.callerKey === null ? mustGet(fileNodeId, file.path) : mustGet(keyToId, call.callerKey);
-            const resolved = resolveName(call.calleeName, bindings, nodesByFile, nameIndex);
+            const resolved = resolveName(call.calleeName, bindings, nodesByFile, call.isMemberCall ? undefined : localByName, nameIndex);
             if (resolved === undefined) {
                 const likelyExternal = call.isMemberCall || importedLocalNames.has(call.calleeName);
                 unresolved.push({ source: callerId, filePath: file.path, calleeName: call.calleeName, line: call.line, col: call.column, likelyExternal });
@@ -228,7 +252,7 @@ export function resolveWorkspace(files, now) {
         // on it) is a calibrated signal specifically about call-resolution gaps; folding in a different edge
         // kind would change what that count measures.
         for (const ref of file.extraction.heritage) {
-            const resolved = resolveName(ref.targetName, bindings, nodesByFile, typeNameIndex);
+            const resolved = resolveName(ref.targetName, bindings, nodesByFile, undefined, typeNameIndex);
             if (resolved === undefined)
                 continue;
             edges.push({ source: mustGet(keyToId, ref.sourceKey), target: resolved, kind: ref.relation, provenance: 'tree-sitter' });
@@ -237,13 +261,21 @@ export function resolveWorkspace(files, now) {
     return { nodes, edges, unresolved };
 }
 /**
- * Resolve a bare name to exactly one declaration, or `undefined` per rule 3 — shared by call
+ * Resolve a bare name to exactly one declaration, or `undefined` per rule 4 — shared by call
  * resolution (against the workspace-wide, any-kind `nameIndex`) and `extends`/`implements` resolution
- * (against the `class`/`interface`-only {@link buildTypeNameIndex}); the two-tier rule itself (an
- * imported binding wins if unambiguous in its target file, else a workspace-wide-unique name wins) does
- * not depend on which candidate pool the caller passes in.
+ * (against the `class`/`interface`-only {@link buildTypeNameIndex}); the rule itself (an imported
+ * binding wins if unambiguous in its target file, else a same-file declaration when the caller passes
+ * one, else a workspace-wide-unique name wins) does not depend on which candidate pool the caller
+ * passes in.
+ * @param calleeName - the name at the call or heritage site.
+ * @param bindings - the calling file's resolved import bindings.
+ * @param nodesByFile - every file's declarations, for the import target lookup.
+ * @param localByName - the calling file's own declarations, or `undefined` to skip the same-file tier
+ *   (the caller decides: member calls and heritage references do not get it).
+ * @param nameIndex - the workspace-wide candidate pool this reference resolves against.
+ * @returns the winning declaration's node id, or `undefined` when nothing settles it.
  */
-function resolveName(calleeName, bindings, nodesByFile, nameIndex) {
+function resolveName(calleeName, bindings, nodesByFile, localByName, nameIndex) {
     const bound = bindings.byLocalName.get(calleeName);
     if (bound !== undefined) {
         const targetNodes = mustGet(nodesByFile, bound.targetFile);
@@ -253,6 +285,11 @@ function resolveName(calleeName, bindings, nodesByFile, nameIndex) {
         if (candidates.length === 1)
             return candidates[0]?.id;
     }
+    // Lexical scope before workspace scope: a name this very file declares is the call's declaration
+    // whenever exactly one declaration carries it, no matter how many other files reuse the name.
+    const local = localByName?.get(calleeName);
+    if (local !== undefined && local.length === 1)
+        return local[0]?.id;
     const workspaceWide = nameIndex.get(calleeName) ?? [];
     return workspaceWide.length === 1 ? workspaceWide[0]?.id : undefined;
 }

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

@@ -33,6 +33,12 @@ export interface WalkConfig {
     readonly concurrency: number;
     /** Restrict extraction to these seam language labels when set; every loaded grammar otherwise. */
     readonly languages?: readonly string[];
+    /**
+     * Leave generated (bundled or minified) artifacts out of the index instead of parsing them. See
+     * `./minified.ts` for the two signals; a workspace that commits its build output is the case this
+     * exists for, since such output is neither gitignored nor declared in `exclude`.
+     */
+    readonly skipMinified: boolean;
     /**
      * Also exclude whatever the project root's `.gitignore` names, unioned with `exclude`. A project
      * that compiles to a gitignored directory (`lib`, `dist`, ...) would otherwise hand the same symbol
@@ -40,18 +46,45 @@ 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 {
     readonly files: ExtractedFile[];
+    /** Candidates skipped for a reason other than being generated output: over `maxFileBytes`, or cut
+     * off by `maxFiles`. */
     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

package/lib/walk.js

@@ -11,10 +11,12 @@
 import { createHash } from 'node:crypto';
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { posix } from 'node:path';
+import { readParseCache } from "./cache.js";
 import { createParser } from "./grammar.js";
 import { extractFile } from "./extract.js";
 import { loadGitignore, matchesGitignore } from "./gitignore.js";
 import { languageFor } from "./languages.js";
+import { isMinifiedName, looksMinified, measureText } from "./minified.js";
 /**
  * Whether one directory entry is excluded from both the index and (for `watcher.ts`) the watch tree —
  * the single definition both consult, so "what the index covers" and "what gets watched" can never
@@ -69,16 +71,74 @@ async function discover(projectRoot, config, signal) {
     await scan('');
     return { candidates, overflow };
 }
-/** Parse one candidate, or return `undefined` when it is over {@link WalkConfig.maxFileBytes}. */
-async function parseCandidate(candidate, config, signal) {
+/**
+ * The walk's view of a file whose extraction came from the cache: the same record a fresh parse
+ * would have produced, with the extraction the cache matched.
+ *
+ * The modification time and size come from the stat taken just now, not from the cache entry, because
+ * the graph records them and `status` measures staleness as `file mtime > recorded mtime`. Under
+ * stat verification the two are equal by construction; under hash verification a file whose content
+ * matched but whose mtime was touched would otherwise be recorded with the old mtime and reported
+ * stale on every later status call, even though the graph describes its exact content.
+ * @param path - the candidate's project-relative path, which the cache entry does not store itself.
+ * @param cached - the entry this file's content matched.
+ * @param stats - the file's stat from this run.
+ * @returns the file as the resolver and graph writer expect it.
+ */
+function reusedFile(path, cached, stats) {
+    return {
+        path,
+        language: cached.language,
+        size: stats.size,
+        modifiedAt: stats.mtimeMs,
+        contentHash: cached.contentHash,
+        lineCount: cached.lineCount,
+        extraction: cached.extraction,
+    };
+}
+/**
+ * Parse one candidate, or reuse the extraction a previous run cached for it.
+ * @param candidate - the file to parse.
+ * @param config - the walk's bounds.
+ * @param cache - the previous run's extractions, keyed by project-relative path.
+ * @param signal - aborts the parse.
+ * @returns the extracted file (and whether it came from the cache), `'minified'` when it was skipped
+ *   as generated output, or `'skipped'` when it is over {@link WalkConfig.maxFileBytes}.
+ */
+async function parseCandidate(candidate, config, cache, signal) {
+    // Checked before the stat and read: a `.min.` name settles it with no I/O at all.
+    if (config.skipMinified && isMinifiedName(candidate.path))
+        return { outcome: 'minified' };
     const stats = await stat(candidate.absolute);
     if (stats.size > config.maxFileBytes)
-        return undefined;
+        return { outcome: 'skipped' };
     const spec = languageFor(posix.extname(candidate.path));
     /* v8 ignore next 2 -- discover() only ever produces a candidate whose extension resolved to a spec. */
     if (spec === undefined)
-        return undefined;
-    const text = await readFile(candidate.absolute, 'utf8');
+        return { outcome: 'skipped' };
+    // Verified before the parser is even created: this is the whole point of the cache — an unchanged
+    // file costs one stat when stat verification is configured, and nothing beyond that.
+    const cached = cache.get(candidate.path);
+    let text;
+    if (cached !== undefined) {
+        if (config.cacheVerify === 'stat') {
+            if (cached.modifiedAt === stats.mtimeMs && cached.size === stats.size) {
+                return { outcome: 'extracted', file: reusedFile(candidate.path, cached, stats), reused: true };
+            }
+        }
+        else {
+            // Content is the only thing this mode trusts, so the read it needs to verify is also the read
+            // the parse below would need — a miss here costs nothing extra.
+            text = await readFile(candidate.absolute, 'utf8');
+            if (createHash('sha256').update(text).digest('hex') === cached.contentHash) {
+                return { outcome: 'extracted', file: reusedFile(candidate.path, cached, stats), reused: true };
+            }
+        }
+    }
+    text ??= await readFile(candidate.absolute, 'utf8');
+    const shape = measureText(text);
+    if (config.skipMinified && looksMinified(candidate.path, shape))
+        return { outcome: 'minified' };
     const parser = await createParser(spec);
     try {
         signal?.throwIfAborted();
@@ -86,16 +146,20 @@ async function parseCandidate(candidate, config, signal) {
         /* v8 ignore next 2 -- createParser() always assigns a language before returning; parse() returns
          * null only when the parser has none. */
         if (tree === null)
-            return undefined;
+            return { outcome: 'skipped' };
         const extraction = extractFile(tree, spec);
         return {
-            path: candidate.path,
-            language: spec.language,
-            size: stats.size,
-            modifiedAt: stats.mtimeMs,
-            contentHash: createHash('sha256').update(text).digest('hex'),
-            lineCount: text.split('\n').length,
-            extraction,
+            outcome: 'extracted',
+            reused: false,
+            file: {
+                path: candidate.path,
+                language: spec.language,
+                size: stats.size,
+                modifiedAt: stats.mtimeMs,
+                contentHash: createHash('sha256').update(text).digest('hex'),
+                lineCount: shape.lineCount,
+                extraction,
+            },
         };
     }
     finally {
@@ -124,23 +188,33 @@ async function mapWithConcurrency(items, concurrency, task) {
     return results;
 }
 /**
- * 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 async function walkAndExtract(projectRoot, config, signal) {
     const { candidates, overflow } = await discover(projectRoot, config, signal);
-    const parsed = await mapWithConcurrency(candidates, config.concurrency, candidate => parseCandidate(candidate, config, signal));
+    const cache = config.reuseParsedCache ? await readParseCache(projectRoot) : new Map();
+    const parsed = await mapWithConcurrency(candidates, config.concurrency, candidate => parseCandidate(candidate, config, cache, signal));
     const files = [];
     let filesSkipped = overflow;
-    for (const file of parsed) {
-        if (file === undefined)
+    let filesMinified = 0;
+    let filesReused = 0;
+    for (const result of parsed) {
+        if (result.outcome === 'skipped')
             filesSkipped++;
-        else
-            files.push(file);
+        else if (result.outcome === 'minified')
+            filesMinified++;
+        else {
+            files.push(result.file);
+            if (result.reused)
+                filesReused++;
+        }
     }
-    return { files, filesSkipped };
+    return { files, filesSkipped, filesMinified, filesReused };
 }
 //# sourceMappingURL=walk.js.map

package/lib/watcher.d.ts

@@ -1,52 +1,112 @@
 /**
- * File-watch-driven reindexing: debounce a workspace's file-change events into a bounded number of
- * `sync` calls, using a per-platform strategy chosen to keep the open-descriptor / kernel-watch cost
- * BOUNDED rather than growing with the number of files:
+ * File-watch-driven reindexing over the harness filesystem seam (`ctx.fs`): turn a workspace's
+ * file-change notifications into a bounded number of `sync` calls, using ONE WATCH PER DIRECTORY.
  *
- *  - macOS / Windows: a SINGLE recursive `fs.watch(root, {recursive:true})`. This is the fix for the
- *    macOS file-table exhaustion a reference implementation hit watching one file descriptor per
- *    watched file (tens of thousands of REG fds), which exhausted `kern.maxfiles` and crashed
- *    unrelated processes system-wide (see NOTES.local.md). One recursive stream costs O(1)
- *    descriptors no matter how large the tree.
- *  - Linux: recursive `fs.watch` is unsupported, so one inotify watch is installed per (non-excluded)
- *    directory — O(directories), NOT O(files). New directories are picked up dynamically as events
- *    reveal them, and {@link WatchConfig.maxWatchedDirectories} bounds inotify usage on pathological
- *    monorepos.
+ * Two facts about the seam decide this module's shape. `watch()` reports a directory's DIRECT
+ * entries only (`depth: 0`, so a nested change never arrives on an ancestor's watch), and it never
+ * names the path that changed:
  *
- * `sync` is always a full rebuild in this version: the `paths` a debounce window collected are passed
- * through but never consulted by the caller supplied here (`runIndex` reruns `walkAndExtract` over the
- * whole tree regardless). That keeps this file's only new correctness surface confined to "when do we
- * call sync", not "what does sync do with a subset of files" — the latter is deliberately deferred
- * until a real incremental reindex is built (see NOTES.local.md). Because sync is always full, a
- * directory delete or a `mkdir` immediately followed by writes inside it never needs special-casing:
- * the parent directory's own create event is enough to schedule a rebuild that discovers (or removes)
- * everything under the path from scratch, watched or not.
+ *  - Coverage, therefore, comes from watching every in-scope directory: O(directories) watches, never
+ *    O(files). A directory created after startup is picked up by the same re-listing that a parent's
+ *    event triggers, so the watch tree grows with the workspace instead of freezing at `start()`.
+ *  - A notification is a directory-level invalidation with no filename, so attributing it to paths
+ *    means re-listing that directory and diffing it against the previous listing, using the
+ *    `version`/`size` the listing itself carries. That diff is what keeps a rebuild from being
+ *    scheduled by a change this indexer excludes — notably a change to `.codegraph`, which is what
+ *    stops the watcher from rebuilding forever off its own graph write.
+ *
+ * `sync` is still always a full rebuild: the paths a debounce window collected are passed through but
+ * never consulted by the caller supplied here (see `runSync` in `./index.ts`). That keeps this file's
+ * correctness surface confined to "when do we call sync", not "what does sync do with a subset of
+ * files".
+ *
+ * A change landing between the baseline index that starts the watcher and the listing that arms its
+ * root is in no snapshot and so produces no notification. That window is one directory listing wide,
+ * and the next attributable change — or the next explicit index — covers whatever it missed.
+ *
+ * Resource discipline is explicit. Every watch's disposer is retained and invoked on `stop()` or
+ * permanent degradation, and a watch whose initialization finishes after its watcher was stopped is
+ * closed immediately instead of being adopted — a late init can never leak a live watch. A
+ * generation counter invalidates every in-flight async step of a previous start(), so a restart
+ * cannot inherit state from the session it replaced. {@link WatchConfig.maxWatchedDirectories}
+ * bounds the number of open watches, and reaching it degrades the whole watcher rather than silently
+ * covering only part of the tree.
  * @module dsh-plugin-codegraph-tree-sitter/watcher
  */
-/** One raw watch event, in the shape `node:fs`'s `fs.watch` listener callback receives. */
-export type WatchEventListener = (eventType: 'rename' | 'change', filename: string | null) => void;
-/** A watch error, in the shape `fs.watch`'s `'error'` event delivers. */
-export type WatchErrorListener = (error: unknown) => void;
-/** A live OS-level watch, closeable independent of anything else this module tracks. */
-export interface WatchHandle {
-    close(): void;
+/**
+ * One resolved filesystem target — the opaque identity `ctx.fs` hands back and every other fs call
+ * takes. Only `targetKey` is read here: the module never parses it, and a remote backend's key is
+ * as valid as a local path.
+ */
+export interface WatchTarget {
+    /** Opaque backend identity of the target. */
+    readonly targetKey: string;
+}
+/** One direct child of a listed directory, as `ctx.fs.listDir` reports it. */
+export interface WatchDirEntry {
+    /** Basename of the child inside the listed directory. */
+    readonly name: string;
+    /** Whether the child is a regular file, a directory, or something else. */
+    readonly type: 'file' | 'directory' | 'other';
+    /** Resolved child target, usable for a follow-up `watch`/`listDir`. */
+    readonly target: WatchTarget;
+    /**
+     * Opaque freshness token, when the backend can report one cheaply. Opting into it is what makes a
+     * same-size content change visible to the change diff below, so a backend that omits it can still
+     * attribute creations, removals, and size-changing rewrites — but not a rewrite that preserved the
+     * size, which is then covered by the next attributable change or by the next explicit index.
+     */
+    readonly version?: string;
+    /** Byte size of a regular file, when the backend can report one. */
+    readonly size?: number;
 }
 /**
- * Indirection over `fs.watch` so tests can inject a fake that emits events/errors deterministically —
- * `fs.watch` is a non-configurable module property that can't be spied, and provoking real EMFILE/
- * ENOSPC exhaustion in a test run isn't reliable. Production always uses {@link nodeWatch}.
+ * The narrow slice of `ctx.fs` this module consumes.
+ *
+ * Deliberately structural rather than an import of the host's `FileSystem`: the tree-sitter package
+ * declares no dependency on `@deepseek-ai/dsh-fs`, and `watch` only exists from host 0.2 onward,
+ * while the package's supported peer range starts earlier. Naming the three calls it uses — resolve a
+ * directory, list it, observe it — keeps this module compilable and loadable across that range, and
+ * keeps the port small enough that a test double is a few lines.
  */
-export type WatchPrimitive = (path: string, options: {
-    readonly recursive: boolean;
-}, onEvent: WatchEventListener, onError: WatchErrorListener) => WatchHandle;
-/** The real `fs.watch`-backed primitive. */
-export declare const nodeWatch: WatchPrimitive;
+export interface WatchFileSystem {
+    /**
+     * Resolve a path into a stable backend target.
+     * @param path - the path to resolve; absolute paths are what this module passes.
+     * @param opts - optional resolution base and cancellation signal.
+     * @returns the resolved target.
+     */
+    resolve(path: string, opts?: {
+        readonly cwd?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<WatchTarget>;
+    /**
+     * List one directory's direct children.
+     * @param target - the resolved directory target.
+     * @param signal - aborts the listing.
+     * @returns one entry per direct child.
+     */
+    listDir(target: WatchTarget, signal?: AbortSignal): Promise<readonly WatchDirEntry[]>;
+    /**
+     * Observe one directory's direct entries.
+     * @param target - the resolved directory target.
+     * @param changed - invalidation callback, called with no argument for a change and with an error
+     *   when the backend loses the watch; initialization failures are reported by rejecting instead.
+     * @param signal - cancels initialization only; an initialized watch is released through the
+     *   returned disposer.
+     * @returns the disposer that releases the watch.
+     */
+    watch(target: WatchTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>;
+}
 /** Why live watching was permanently disabled for this watcher instance. */
 export type DegradeReason = {
     readonly code: 'RESOURCE_EXHAUSTED';
     readonly cause: NodeJS.ErrnoException;
 } | {
     readonly code: 'WATCH_LIMIT_EXCEEDED';
+} | {
+    readonly code: 'WATCH_UNAVAILABLE';
+    readonly cause: unknown;
 } | {
     readonly code: 'SYNC_FAILURE_LIMIT';
     readonly cause: unknown;
@@ -61,11 +121,11 @@ export interface WatchConfig {
     readonly respectGitignore: boolean;
     /** Milliseconds of quiet after the last change before `sync` runs. */
     readonly debounceMs: number;
-    /** Hard cap on directories watched individually (Linux only); exceeding it degrades the watcher. */
+    /** Hard cap on directories watched individually; exceeding it degrades the watcher. */
     readonly maxWatchedDirectories: number;
     /**
-     * Run one reindex. `paths` are the project-relative paths a debounce window collected, offered for
-     * a future incremental sync to consult; this version's caller always ignores them and rebuilds the
+     * Run one reindex. `paths` are the project-relative paths of the direct entries whose change the
+     * per-directory watch could attribute; this version's caller always ignores them and rebuilds the
      * whole graph.
      */
     readonly sync: (paths?: readonly string[]) => Promise<{
@@ -83,13 +143,18 @@ export interface Watcher {
     stop(): void;
     /** Whether live watching has permanently degraded (until the next {@link start}). */
     isDegraded(): boolean;
-    /** Project-relative paths seen since the last debounce window fired a sync. */
+    /**
+     * Project-relative paths of the entries whose change is queued for the next sync, collected since
+     * the last debounce window fired one. A path names a direct entry of a watched directory — file or
+     * directory — because that is the finest grain the seam can attribute a change to.
+     */
     getPendingFiles(): readonly string[];
 }
 /**
  * Build a watcher over one workspace root. Nothing runs until {@link Watcher.start} is called.
  * @param config - scope, timing, and the sync callback to drive.
- * @param primitive - the watch primitive to use; defaults to the real `fs.watch`.
+ * @param fs - the filesystem seam to resolve, enumerate, and watch through.
+ * @returns the watcher; every resource it acquires is released by {@link Watcher.stop}.
  */
-export declare function createWatcher(config: WatchConfig, primitive?: WatchPrimitive): Watcher;
+export declare function createWatcher(config: WatchConfig, fs: WatchFileSystem): Watcher;
 //# sourceMappingURL=watcher.d.ts.map