dsh-plugin-codegraph-tree-sitter 0.1.0

package/lib/walk.js

@@ -0,0 +1,146 @@
+/**
+ * Workspace directory walk: find every file this package can extract from, parse it, and hand back
+ * one {@link ExtractedFile} per file that was actually indexed.
+ *
+ * The walk is deliberately simple: `exclude` entries name directory segments to never descend into
+ * (not wildcard globs — the default set needs none), and every bound (`maxFileBytes`, `maxFiles`) is
+ * a config field the deployment can retune rather than a constant, per the same-name entries this
+ * package's `Config` exposes.
+ * @module dsh-plugin-codegraph-tree-sitter/walk
+ */
+import { createHash } from 'node:crypto';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { posix } from 'node:path';
+import { createParser } from "./grammar.js";
+import { extractFile } from "./extract.js";
+import { loadGitignore, matchesGitignore } from "./gitignore.js";
+import { languageFor } from "./languages.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
+ * drift apart.
+ * @param name - the entry's own name (not a path), matched against `excluded` verbatim.
+ * @param relativePath - the entry's project-relative path, matched against the `.gitignore` rules.
+ * @param isDirectory - whether the entry is a directory, for `.gitignore`'s directory-only rules.
+ * @param excluded - directory/file segment names never descended into.
+ * @param gitignoreRules - the project's parsed `.gitignore`, or empty when not respected.
+ */
+export function isExcluded(name, relativePath, isDirectory, excluded, gitignoreRules) {
+    return excluded.has(name) || matchesGitignore(gitignoreRules, relativePath, isDirectory);
+}
+/**
+ * Recursively list every candidate file under `projectRoot`, honoring `exclude` and `maxFiles`.
+ * @param projectRoot - absolute path of the root to scan.
+ * @param config - the walk's bounds.
+ * @param signal - aborts the scan.
+ * @returns the candidates found, and how many further candidates `maxFiles` cut off.
+ */
+async function discover(projectRoot, config, signal) {
+    const excluded = new Set(config.exclude);
+    const gitignoreRules = config.respectGitignore ? await loadGitignore(projectRoot) : [];
+    const candidates = [];
+    let overflow = 0;
+    async function scan(relativeDir) {
+        signal?.throwIfAborted();
+        const entries = await readdir(posix.join(projectRoot, relativeDir), { withFileTypes: true });
+        for (const entry of entries) {
+            const relativePath = relativeDir === '' ? entry.name : `${relativeDir}/${entry.name}`;
+            if (isExcluded(entry.name, relativePath, entry.isDirectory(), excluded, gitignoreRules))
+                continue;
+            if (entry.isDirectory()) {
+                await scan(relativePath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const extension = posix.extname(entry.name);
+            const spec = languageFor(extension);
+            if (spec === undefined)
+                continue;
+            if (config.languages !== undefined && !config.languages.includes(spec.language))
+                continue;
+            if (candidates.length >= config.maxFiles) {
+                overflow++;
+                continue;
+            }
+            candidates.push({ path: relativePath, absolute: posix.join(projectRoot, relativePath), language: spec.language });
+        }
+    }
+    await scan('');
+    return { candidates, overflow };
+}
+/** Parse one candidate, or return `undefined` when it is over {@link WalkConfig.maxFileBytes}. */
+async function parseCandidate(candidate, config, signal) {
+    const stats = await stat(candidate.absolute);
+    if (stats.size > config.maxFileBytes)
+        return undefined;
+    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');
+    const parser = await createParser(spec);
+    try {
+        signal?.throwIfAborted();
+        const tree = parser.parse(text);
+        /* 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;
+        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,
+        };
+    }
+    finally {
+        parser.delete();
+    }
+}
+/** Run `tasks` with at most `concurrency` in flight at once, preserving input order in the result. */
+async function mapWithConcurrency(items, concurrency, task) {
+    const results = new Array(items.length);
+    let next = 0;
+    async function worker() {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            // `index < items.length` above guarantees a defined element; `noUncheckedIndexedAccess` just
+            // cannot express that.
+            const item = items[index];
+            /* v8 ignore next */
+            if (item === undefined)
+                continue;
+            results[index] = await task(item);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+    return results;
+}
+/**
+ * Walk `projectRoot` and parse every candidate file it finds.
+ * @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`).
+ */
+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 files = [];
+    let filesSkipped = overflow;
+    for (const file of parsed) {
+        if (file === undefined)
+            filesSkipped++;
+        else
+            files.push(file);
+    }
+    return { files, filesSkipped };
+}
+//# sourceMappingURL=walk.js.map

package/lib/watch-policy.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Whether to actually start watching a root, on top of whether `Config.watch` asked for it.
+ *
+ * WSL2 mounts a Windows drive over 9P (`/mnt/<drive>/...`), and that filesystem does not deliver
+ * inotify events reliably — a watcher that looks alive there silently misses edits, which is worse
+ * than not watching at all (the caller believes the index stays fresh and never falls back to a
+ * manual `codegraph_index`). This module decides, from injected environment/platform/proc-version
+ * probes only, whether to override the user's own `watch: true` for that one case.
+ * @module dsh-plugin-codegraph-tree-sitter/watch-policy
+ */
+/** Whether watching should actually start, and why it was overridden when it should not. */
+export type WatchDecision = {
+    readonly enabled: true;
+} | {
+    readonly enabled: false;
+    readonly reason: 'ENV_DISABLED' | 'WSL2_MOUNT';
+};
+/** Everything {@link decideWatch} needs, all injected so no test touches the real environment. */
+export interface WatchPolicyInput {
+    /** The already-resolved `Config.watch` value; a policy override never turns this on when it is off. */
+    readonly configuredWatch: boolean;
+    /** Absolute workspace root being considered for watching. */
+    readonly root: string;
+    /** Process environment to read `CODEGRAPH_NO_WATCH`/`CODEGRAPH_FORCE_WATCH` from. */
+    readonly env: NodeJS.ProcessEnv;
+    /** `process.platform`, injected so the WSL2 check is only ever exercised via a fake `'linux'`. */
+    readonly platform: NodeJS.Platform;
+    /** Reads `/proc/version` (or an equivalent), returning `undefined` on any failure. */
+    readonly procVersion: () => string | undefined;
+}
+/**
+ * Decide whether to start watching `input.root`.
+ *
+ * Precedence: `CODEGRAPH_NO_WATCH=1` is a total kill switch that never lets any root watch, regardless
+ * of `configuredWatch` or the WSL2 heuristic. Otherwise, watching stays off unless `configuredWatch` is
+ * `true` — this function only ever narrows an on request, never widens an off one. With watching
+ * requested, a WSL2 kernel watching a path under a `/mnt/<drive>` 9P mount is disabled by default,
+ * since inotify there does not reliably deliver events; `CODEGRAPH_FORCE_WATCH=1` is the escape hatch
+ * for a caller who has verified their own WSL2 setup delivers events anyway.
+ */
+export declare function decideWatch(input: WatchPolicyInput): WatchDecision;
+/**
+ * The real {@link WatchPolicyInput.procVersion}: reads `/proc/version`, `undefined` on any failure.
+ * @param path - overridable only so tests can force both the success and failure path deterministically
+ * on any OS — whether the real `/proc/version` exists depends on the platform running the test, which
+ * would otherwise make one of these two branches uncovered depending on where CI happens to run.
+ */
+export declare function readProcVersion(path?: string): string | undefined;
+//# sourceMappingURL=watch-policy.d.ts.map

package/lib/watch-policy.js

@@ -0,0 +1,64 @@
+/**
+ * Whether to actually start watching a root, on top of whether `Config.watch` asked for it.
+ *
+ * WSL2 mounts a Windows drive over 9P (`/mnt/<drive>/...`), and that filesystem does not deliver
+ * inotify events reliably — a watcher that looks alive there silently misses edits, which is worse
+ * than not watching at all (the caller believes the index stays fresh and never falls back to a
+ * manual `codegraph_index`). This module decides, from injected environment/platform/proc-version
+ * probes only, whether to override the user's own `watch: true` for that one case.
+ * @module dsh-plugin-codegraph-tree-sitter/watch-policy
+ */
+import { readFileSync } from 'node:fs';
+import { posix, sep } from 'node:path';
+/** Matches the "Microsoft"/"microsoft-standard" marker WSL2 kernels put in `/proc/version`. */
+const WSL_KERNEL_MARKER = /microsoft/i;
+/**
+ * Decide whether to start watching `input.root`.
+ *
+ * Precedence: `CODEGRAPH_NO_WATCH=1` is a total kill switch that never lets any root watch, regardless
+ * of `configuredWatch` or the WSL2 heuristic. Otherwise, watching stays off unless `configuredWatch` is
+ * `true` — this function only ever narrows an on request, never widens an off one. With watching
+ * requested, a WSL2 kernel watching a path under a `/mnt/<drive>` 9P mount is disabled by default,
+ * since inotify there does not reliably deliver events; `CODEGRAPH_FORCE_WATCH=1` is the escape hatch
+ * for a caller who has verified their own WSL2 setup delivers events anyway.
+ */
+export function decideWatch(input) {
+    if (input.env.CODEGRAPH_NO_WATCH === '1')
+        return { enabled: false, reason: 'ENV_DISABLED' };
+    if (!input.configuredWatch)
+        return { enabled: false, reason: 'ENV_DISABLED' };
+    if (input.env.CODEGRAPH_FORCE_WATCH === '1')
+        return { enabled: true };
+    if (isWsl2MountedRoot(input))
+        return { enabled: false, reason: 'WSL2_MOUNT' };
+    return { enabled: true };
+}
+/** Whether `input.root` is a WSL2 process watching a path mounted in from the Windows host. */
+function isWsl2MountedRoot(input) {
+    if (input.platform !== 'linux')
+        return false;
+    const version = input.procVersion();
+    if (version === undefined || !WSL_KERNEL_MARKER.test(version))
+        return false;
+    return isDrvfsMountPath(input.root);
+}
+/** Whether an absolute path sits under WSL2's `/mnt/<single-letter-drive>/...` DrvFs mount convention. */
+function isDrvfsMountPath(root) {
+    const normalized = root.split(sep).join(posix.sep);
+    return /^\/mnt\/[a-z](\/|$)/i.test(normalized);
+}
+/**
+ * The real {@link WatchPolicyInput.procVersion}: reads `/proc/version`, `undefined` on any failure.
+ * @param path - overridable only so tests can force both the success and failure path deterministically
+ * on any OS — whether the real `/proc/version` exists depends on the platform running the test, which
+ * would otherwise make one of these two branches uncovered depending on where CI happens to run.
+ */
+export function readProcVersion(path = '/proc/version') {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=watch-policy.js.map

package/lib/watcher.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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:
+ *
+ *  - 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.
+ *
+ * `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.
+ * @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;
+}
+/**
+ * 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}.
+ */
+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;
+/** 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: 'SYNC_FAILURE_LIMIT';
+    readonly cause: unknown;
+};
+/** Configuration a watcher needs to run: scope, timing, and the sync it drives. */
+export interface WatchConfig {
+    /** Absolute path of the workspace root to watch. */
+    readonly root: string;
+    /** Directory/file segment names never watched, mirroring the indexer's own exclusion. */
+    readonly exclude: readonly string[];
+    /** Also exclude whatever the project root's `.gitignore` names, matching the indexer's own scope. */
+    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. */
+    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
+     * whole graph.
+     */
+    readonly sync: (paths?: readonly string[]) => Promise<{
+        filesChanged: number;
+        durationMs: number;
+    }>;
+    /** Fired once, the first time live watching degrades permanently. */
+    readonly onDegraded?: (reason: DegradeReason) => void;
+}
+/** A running (or stopped) file watcher for one workspace root. */
+export interface Watcher {
+    /** Begin watching. Idempotent while already running; clears a prior degradation and retries. */
+    start(): void;
+    /** Stop watching and release every OS-level watch. Does not itself count as degradation. */
+    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. */
+    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`.
+ */
+export declare function createWatcher(config: WatchConfig, primitive?: WatchPrimitive): Watcher;
+//# sourceMappingURL=watcher.d.ts.map

package/lib/watcher.js

@@ -0,0 +1,299 @@
+/**
+ * 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:
+ *
+ *  - 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.
+ *
+ * `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.
+ * @module dsh-plugin-codegraph-tree-sitter/watcher
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { join, sep } from 'node:path';
+import * as fs from 'node:fs';
+import { loadGitignore } from "./gitignore.js";
+import { isExcluded } from "./walk.js";
+/** The real `fs.watch`-backed primitive. */
+export const nodeWatch = (path, options, onEvent, onError) => {
+    const watcher = fs.watch(path, { recursive: options.recursive, persistent: true }, onEvent);
+    watcher.on('error', onError);
+    return { close: () => watcher.close() };
+};
+/** Error codes that mean "the OS ran out of watch resources", across the platforms that report them. */
+const RESOURCE_EXHAUSTION_CODES = new Set(['EMFILE', 'ENFILE', 'ENOSPC']);
+/** Consecutive sync failures tolerated before a watcher gives up and degrades. */
+const SYNC_FAILURE_LIMIT = 3;
+/**
+ * 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`.
+ */
+export function createWatcher(config, primitive = nodeWatch) {
+    const excluded = new Set(config.exclude);
+    let gitignoreRules = [];
+    const watchedDirs = new Set();
+    const handles = [];
+    const pendingPaths = new Set();
+    let running = false;
+    let degraded = false;
+    let debounceTimer;
+    let syncing = false;
+    let rerunNeeded = false;
+    let syncFailureCount = 0;
+    /** One-way: once degraded, only a fresh `start()` clears it. */
+    function degrade(reason) {
+        if (degraded)
+            return;
+        degraded = true;
+        teardown();
+        config.onDegraded?.(reason);
+    }
+    /** Close every live watch and clear the debounce timer, without touching `degraded`. */
+    function teardown() {
+        running = false;
+        for (const handle of handles.splice(0))
+            handle.close();
+        watchedDirs.clear();
+        if (debounceTimer !== undefined) {
+            clearTimeout(debounceTimer);
+            debounceTimer = undefined;
+        }
+    }
+    function errorCode(error) {
+        return typeof error === 'object' && error !== null && 'code' in error
+            ? String(error.code)
+            : undefined;
+    }
+    function handleWatchError(error) {
+        if (!running || degraded)
+            return;
+        const code = errorCode(error);
+        if (code !== undefined && RESOURCE_EXHAUSTION_CODES.has(code)) {
+            degrade({ code: 'RESOURCE_EXHAUSTED', cause: error });
+        }
+        // An error this watcher doesn't recognize as resource exhaustion is left to the OS-level watch's
+        // own reporting; it doesn't by itself prove live watching can no longer make progress.
+    }
+    function scheduleSync() {
+        if (debounceTimer !== undefined)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(runSync, config.debounceMs);
+    }
+    function runSync() {
+        // Also called directly (not just as the timer callback) when a queued rerun fires immediately;
+        // clear any timer a later event armed in the meantime so it can't fire a redundant, empty sync.
+        if (debounceTimer !== undefined) {
+            clearTimeout(debounceTimer);
+            debounceTimer = undefined;
+        }
+        if (syncing) {
+            // A sync already in flight will miss whatever just fired this timer; ask for one more round
+            // once it settles rather than starting a second sync concurrently.
+            rerunNeeded = true;
+            return;
+        }
+        const batch = [...pendingPaths];
+        pendingPaths.clear();
+        syncing = true;
+        // `batch` is never actually empty here: the only two ways into this function are the debounce
+        // timer (armed exclusively by handleChange(), right after it adds to pendingPaths) and a queued
+        // rerun (only set when handleChange() re-armed the timer while a sync was already in flight,
+        // which itself added to pendingPaths). The `undefined` branch is API contract, not reachable code.
+        /* v8 ignore next */
+        config.sync(batch.length === 0 ? undefined : batch)
+            .then(() => {
+            syncFailureCount = 0;
+        })
+            .catch((cause) => {
+            // The sync never committed anything for this batch — put it back so the next run retries it,
+            // exactly like a fresh set of events for the same paths would.
+            for (const path of batch)
+                pendingPaths.add(path);
+            syncFailureCount++;
+            if (syncFailureCount >= SYNC_FAILURE_LIMIT)
+                degrade({ code: 'SYNC_FAILURE_LIMIT', cause });
+        })
+            .finally(() => {
+            syncing = false;
+            if (rerunNeeded) {
+                rerunNeeded = false;
+                // Immediate, not another scheduleSync(): the paths behind this round already sat through a
+                // full debounce window once (that's what set rerunNeeded), so making them wait out a second
+                // one would only delay a sync that's already due.
+                runSync();
+            }
+        });
+    }
+    /**
+     * Whether one path segment, already known to sit inside in-scope ancestors, is itself in scope.
+     * Used while recursing the initial watch tree, where every ancestor was already checked on the way
+     * down — checking only the leaf segment here is enough, and cheaper than re-testing the whole path.
+     */
+    function segmentInScope(name, relativePath, isDirectory) {
+        return !isExcluded(name, relativePath, isDirectory, excluded, gitignoreRules);
+    }
+    /**
+     * Whether a path an `fs.watch` event named — possibly several segments deep, with no guarantee any
+     * ancestor was checked first (the recursive macOS/Windows watch reports the whole subtree in one
+     * stream) — is in scope. Walks every prefix from the root down, exactly like the initial directory
+     * walk would if it descended this far, so `node_modules/dep/index.js` is excluded by its
+     * `node_modules` ancestor even though the leaf name itself is unremarkable.
+     */
+    function pathInScope(relativePath, leafIsDirectory) {
+        const segments = relativePath.split('/');
+        let prefix = '';
+        for (const [index, name] of segments.entries()) {
+            prefix = index === 0 ? name : `${prefix}/${name}`;
+            const isDirectory = index < segments.length - 1 || leafIsDirectory;
+            if (!segmentInScope(name, prefix, isDirectory))
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Record one in-scope change and arm the debounce. Also picks up a directory created after startup
+     * so Linux's per-directory watch tree grows with the workspace instead of only covering what existed
+     * at `start()`.
+     */
+    function handleChange(relativePath) {
+        if (!running || degraded)
+            return;
+        if (relativePath === '')
+            return;
+        if (!pathInScope(relativePath, false))
+            return;
+        pendingPaths.add(relativePath);
+        scheduleSync();
+        if (process.platform !== 'darwin' && process.platform !== 'win32' && !watchedDirs.has(relativePath)) {
+            // Fire-and-forget: a directory that turns out not to exist (a file event, or something already
+            // removed again) simply fails the stat and watchDirectory() is never called.
+            void maybeWatchNewDirectory(relativePath);
+        }
+    }
+    async function maybeWatchNewDirectory(relativePath) {
+        let isDirectory;
+        try {
+            isDirectory = (await stat(join(config.root, relativePath))).isDirectory();
+        }
+        catch {
+            return;
+        }
+        // `running`/`degraded` are re-checked inside watchDirectory() itself; no need to duplicate that
+        // check here too.
+        if (!isDirectory || watchedDirs.has(relativePath) || !pathInScope(relativePath, true))
+            return;
+        await watchDirectory(relativePath);
+    }
+    /** Normalize an `fs.watch` filename (native separators, possibly nested under `recursive`) to posix. */
+    function toRelativePosix(filename) {
+        return filename.split(sep).join('/');
+    }
+    function startRecursive() {
+        try {
+            const handle = primitive(config.root, { recursive: true }, (_eventType, filename) => {
+                if (filename === null)
+                    return;
+                handleChange(toRelativePosix(filename));
+            }, handleWatchError);
+            handles.push(handle);
+        }
+        catch (error) {
+            handleWatchError(error);
+            // A platform that claims to support recursive watch but rejects this call outright (not just an
+            // ENOSYS at the fs.watch layer, which never reaches here) has nothing more this watcher can try.
+        }
+    }
+    /**
+     * Install one inotify watch on `relativePath` (project-relative; `''` is the root) and recurse into
+     * its non-excluded subdirectories. Degrades the whole watcher, rather than silently covering only
+     * part of the tree, once {@link WatchConfig.maxWatchedDirectories} is reached.
+     */
+    async function watchDirectory(relativePath) {
+        if (!running || degraded || watchedDirs.has(relativePath))
+            return;
+        if (watchedDirs.size >= config.maxWatchedDirectories) {
+            degrade({ code: 'WATCH_LIMIT_EXCEEDED' });
+            return;
+        }
+        const absolute = join(config.root, relativePath);
+        let handle;
+        try {
+            handle = primitive(absolute, { recursive: false }, (_eventType, filename) => {
+                if (filename === null)
+                    return;
+                const childPosix = toRelativePosix(filename);
+                handleChange(relativePath === '' ? childPosix : `${relativePath}/${childPosix}`);
+            }, handleWatchError);
+        }
+        catch (error) {
+            handleWatchError(error);
+            return;
+        }
+        handles.push(handle);
+        watchedDirs.add(relativePath);
+        let entries;
+        try {
+            entries = await readdir(absolute, { withFileTypes: true });
+        }
+        catch {
+            // The directory disappeared between being discovered and being listed; its own watch (or the
+            // parent's) already reported enough to trigger a sync that reconciles this.
+            return;
+        }
+        for (const entry of entries) {
+            // Not re-checking `running`/`degraded` here: a stop/degrade mid-loop just means the recursive
+            // watchDirectory() call below no-ops immediately (same check, at the top of that call).
+            if (!entry.isDirectory())
+                continue;
+            const childPath = relativePath === '' ? entry.name : `${relativePath}/${entry.name}`;
+            if (!segmentInScope(entry.name, childPath, true))
+                continue;
+            await watchDirectory(childPath);
+        }
+    }
+    return {
+        start() {
+            if (running)
+                return;
+            running = true;
+            degraded = false;
+            syncFailureCount = 0;
+            pendingPaths.clear();
+            if (process.platform === 'darwin' || process.platform === 'win32') {
+                startRecursive();
+                return;
+            }
+            void (async () => {
+                gitignoreRules = config.respectGitignore ? await loadGitignore(config.root) : [];
+                if (!running)
+                    return;
+                await watchDirectory('');
+            })();
+        },
+        stop() {
+            teardown();
+        },
+        isDegraded() {
+            return degraded;
+        },
+        getPendingFiles() {
+            return [...pendingPaths];
+        },
+    };
+}
+//# sourceMappingURL=watcher.js.map