codedeep-mcp 0.1.0

package/dist/indexer/watcher.js

@@ -0,0 +1,353 @@
+// Debounced fs.watch wrapper driving live incremental re-indexing.
+//
+// Platform notes (fs.watch recursive): native on macOS (FSEvents) and
+// Windows (ReadDirectoryChangesW); on Linux, Node >= 20 emulates it with
+// one inotify watch per directory, so very large trees can exhaust
+// fs.inotify.max_user_watches — that surfaces as an 'error' event, which
+// disables the watcher while the server keeps serving from the existing
+// index (indexChanged heals on next start). The `watchFactory` seam is
+// the swap point for a chokidar backend if that ever bites in practice.
+//
+// Persistence: the design notes suggested a 5-minute save timer; this saves once
+// per debounced flush instead — data loss is bounded by one debounce
+// window rather than five minutes, there is no extra keep-alive timer to
+// manage, and saves are event-driven (no disk writes when idle).
+// CodeIndex.save is mutexed and atomic, so per-flush saves are safe.
+import { realpathSync, watch as fsWatch } from 'node:fs';
+import { lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { errMsg, log } from '../logger.js';
+import { compileExcludeMatcher, isBinaryByExtension, toPosix } from './scanner.js';
+// On Windows, fs.watch (ReadDirectoryChangesW) aborts the whole PROCESS with a
+// libuv assertion (`!_wcsnicmp(filename, dir, dirlen)`, src/win/fs-event.c)
+// when the watched directory is opened through a non-canonical path — most
+// commonly an 8.3 short name like C:\Users\ADMINI~1\... that os.tmpdir() can
+// hand back, but any case/junction-spelling mismatch trips it: libuv compares
+// the kernel-reported filename against the watched-dir prefix and asserts on
+// the difference. Resolving to the real on-disk path first keeps the two
+// consistent. POSIX has no such bug, so leave its paths (and symlinks) alone.
+export function canonicalWatchPath(dir) {
+    if (process.platform !== 'win32')
+        return dir;
+    try {
+        return realpathSync.native(dir);
+    }
+    catch (err) {
+        // MUST NOT fall back to the raw `dir` here: if it is an 8.3 short name
+        // (or case/junction mismatch) and is still PRESENT — which a transient
+        // realpath failure like EMFILE/EACCES leaves it — fs.watch SUCCEEDS, then
+        // aborts the whole process via the libuv `!_wcsnicmp` assertion on the
+        // first event. That abort bypasses the start() try/catch (it is not a JS
+        // throw) and kills the stdio server. Throwing instead lets start() degrade
+        // to "no live updates", which is strictly better than a process abort.
+        // (When the dir is genuinely gone, fs.watch would have failed catchably
+        // anyway — so nothing is lost in that case either.)
+        throw new Error(`cannot canonicalize watch path ${dir}: ${errMsg(err)}`);
+    }
+}
+const defaultWatchFactory = (root, onEvent, onError) => {
+    const w = fsWatch(canonicalWatchPath(root), { recursive: true });
+    w.on('change', onEvent);
+    w.on('error', onError);
+    // The stdio transport governs process lifetime. Without unref, the
+    // watcher's libuv handle would keep the process alive forever after
+    // the MCP client closes stdin.
+    w.unref();
+    return w;
+};
+const DEFAULT_DEBOUNCE_MS = 100;
+const DEFAULT_RETRY_MS = 250;
+const DEFAULT_MAX_FLUSH_DELAY_MS = 1000;
+// Each incomplete rescan costs a full scanProject walk; bound the retries
+// so a permanently unreadable subdirectory degrades gracefully.
+const MAX_INCOMPLETE_RESCANS = 5;
+export class Watcher {
+    indexer;
+    index;
+    config;
+    matchExclude;
+    debounceMs;
+    retryMs;
+    maxFlushDelayMs;
+    watchFactory;
+    // Canonical project-relative POSIX paths awaiting a flush.
+    pending = new Set();
+    rescanPending = false;
+    // Consecutive rescans that completed but saw a PARTIAL scan (transient
+    // readdir failures). Bounded so a permanently unreadable subdirectory
+    // can't turn the retry tick into a full-scan-every-250ms loop.
+    incompleteRescans = 0;
+    // Wall-clock bound for the current accumulation window (max-wait).
+    flushDeadline = null;
+    timer = null;
+    flushPromise = Promise.resolve();
+    backend = null;
+    closed = false;
+    constructor(indexer, index, config, options = {}) {
+        this.indexer = indexer;
+        this.index = index;
+        this.config = config;
+        this.matchExclude = compileExcludeMatcher(config.exclude);
+        this.debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+        this.retryMs = options.retryMs ?? DEFAULT_RETRY_MS;
+        this.maxFlushDelayMs = options.maxFlushDelayMs ?? DEFAULT_MAX_FLUSH_DELAY_MS;
+        this.watchFactory = options.watchFactory ?? defaultWatchFactory;
+    }
+    // Never throws: a watcher failure must degrade to "no live updates",
+    // not crash the server.
+    start() {
+        if (this.backend || this.closed)
+            return;
+        try {
+            this.backend = this.watchFactory(this.config.projectRoot, (eventType, filename) => {
+                try {
+                    this.handleEvent(eventType, filename);
+                }
+                catch (err) {
+                    log.warn(`watcher: event handling failed: ${errMsg(err)}`);
+                }
+            }, (err) => {
+                // e.g. Linux inotify watch exhaustion (ENOSPC).
+                log.warn(`watcher: backend error (${errMsg(err)}); live re-indexing disabled`);
+                this.backend?.close();
+                this.backend = null;
+            });
+            log.debug(`watcher: watching ${this.config.projectRoot} (recursive)`);
+        }
+        catch (err) {
+            log.warn(`watcher: fs.watch unavailable (${errMsg(err)}); live re-indexing disabled`);
+            this.backend = null;
+        }
+    }
+    // Stops the event source, waits for any in-flight drain, then runs one
+    // FINAL drain of whatever is still pending so the last debounce batch is
+    // not discarded (it saves through the normal per-flush path, so close()
+    // leaves the on-disk cache current). Idempotent: a concurrent second
+    // close() awaits the same final drain rather than resolving early.
+    async close() {
+        if (this.closed)
+            return this.settle();
+        this.closed = true;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.backend?.close();
+        this.backend = null;
+        // Chaining serializes after any in-flight drain; a final drain over
+        // an empty state is a no-op, so no pre-check is needed.
+        this.flush(true);
+        await this.settle();
+    }
+    // Awaits the current flush chain (drains already started or chained;
+    // NOT timers still pending). Used by close() and tests.
+    async settle() {
+        await this.flushPromise;
+    }
+    // Public so unit tests can drive events without a real fs.watch.
+    // Must stay cheap and exception-free — it runs on every OS event.
+    handleEvent(eventType, filename) {
+        if (this.closed)
+            return;
+        const name = typeof filename === 'string'
+            ? filename
+            : filename instanceof Buffer
+                ? filename.toString('utf8')
+                : null;
+        if (name === null || name === '') {
+            // Some platforms emit events without a filename; the only safe
+            // recovery is a full incremental rescan.
+            this.rescanPending = true;
+            this.scheduleDebounced();
+            return;
+        }
+        const rel = toPosix(name);
+        // Pre-debounce storm filter (node_modules churn, binary assets).
+        // indexFile re-checks everything; this only keeps the pending set
+        // small. Unknown-language files are NOT filtered — they are
+        // legitimately indexed for overview's "Other files" count.
+        if (this.matchExclude(rel) || isBinaryByExtension(rel))
+            return;
+        // 'rename' and 'change' are handled identically: indexFile stats the
+        // path and treats a missing file as a deletion, which also covers
+        // renames (one event per old/new name).
+        this.pending.add(rel);
+        this.scheduleDebounced();
+    }
+    // Trailing debounce capped by the max-wait deadline: each event pushes
+    // the flush out by debounceMs, but never past maxFlushDelayMs after the
+    // window's first event.
+    scheduleDebounced() {
+        this.flushDeadline ??= Date.now() + this.maxFlushDelayMs;
+        const remaining = Math.max(0, this.flushDeadline - Date.now());
+        this.schedule(Math.min(this.debounceMs, remaining));
+    }
+    schedule(delayMs) {
+        if (this.closed)
+            return;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.flush();
+        }, delayMs);
+        this.timer.unref?.();
+    }
+    // Chains drains on flushPromise so they never overlap — watcher updates
+    // are processed sequentially, and close() can await the tail.
+    flush(final = false) {
+        this.flushPromise = this.flushPromise
+            .then(() => this.drain(final))
+            .catch((err) => {
+            log.error(`watcher: flush failed: ${errMsg(err)}`);
+        });
+    }
+    // `final` is the close()-time last pass: it ignores the closed flag,
+    // never re-arms timers, and skips the rescan (indexChanged heals on
+    // next start) in favor of flushing the per-file batch.
+    async drain(final = false) {
+        if (this.closed && !final)
+            return;
+        // Until the startup indexAll/indexChanged completes, indexFile would
+        // race the cache load (updates discarded by the load's Map swap, and
+        // a premature save could clobber the populated on-disk cache) or be
+        // dropped by the run guard — defer until the index is ready.
+        if (this.indexer.isIndexing || !this.indexer.ready) {
+            // Reset the max-wait window: nothing can flush while deferred, and
+            // an expired deadline would turn every incoming event into an
+            // immediate schedule(0), clobbering the retryMs backoff with
+            // per-event timer churn for the rest of the busy period.
+            this.flushDeadline = null;
+            if (!final)
+                this.schedule(this.retryMs);
+            return;
+        }
+        // Snapshot: events arriving mid-drain re-enter pending and re-arm
+        // the timer via handleEvent.
+        const batch = [...this.pending];
+        this.pending.clear();
+        const rescan = this.rescanPending;
+        this.rescanPending = false;
+        this.flushDeadline = null;
+        if (rescan && !final) {
+            // The rescan covers the batched paths too — but only when its scan
+            // completes, which a successful indexChanged does not guarantee
+            // (a transiently unreadable directory yields a partial scan).
+            // Re-queue the batch: paths the rescan DID cover become hash
+            // no-ops in indexFile, while edits a partial scan missed stay
+            // queued instead of being silently lost. A partial scan also
+            // re-arms the rescan itself (bounded retries) — its trigger may
+            // have had no batch representation (directory deletions).
+            try {
+                const ran = await this.indexer.indexChanged();
+                if (!ran) {
+                    this.rescanPending = true;
+                }
+                else if (!this.indexer.lastScanComplete) {
+                    this.incompleteRescans++;
+                    if (this.incompleteRescans <= MAX_INCOMPLETE_RESCANS) {
+                        this.rescanPending = true;
+                    }
+                    else {
+                        log.error(`watcher: rescan saw ${this.incompleteRescans} consecutive partial scans; giving up until the next event (exclude the unreadable directory to silence this)`);
+                        this.incompleteRescans = 0;
+                    }
+                }
+                else {
+                    this.incompleteRescans = 0;
+                }
+            }
+            catch (err) {
+                // Restore the flag so the retry tick heals a transient failure.
+                this.rescanPending = true;
+                log.error(`watcher: rescan failed: ${errMsg(err)}`);
+            }
+            for (const rel of batch)
+                this.pending.add(rel);
+            this.rearmIfNeeded();
+            return;
+        }
+        // Stat phase: classify so deletions process before creations — at
+        // the maxFiles cap, a rename's delete must free its slot before the
+        // create claims one. Stats are independent; issue them concurrently
+        // (threadpool-capped) so large batches on slow filesystems don't
+        // serialize the flush.
+        const stats = await Promise.all(batch.map((rel) => lstat(join(this.config.projectRoot, rel)).catch(() => null)));
+        const deleted = [];
+        const present = [];
+        for (let i = 0; i < batch.length; i++) {
+            if (stats[i] === null)
+                deleted.push(batch[i]);
+            else if (!stats[i].isDirectory())
+                present.push(batch[i]);
+            // A created/moved-in directory emits one event — its children may
+            // emit none. Only a rescan finds them.
+            else
+                this.rescanPending = true;
+        }
+        if (!this.rescanPending) {
+            // Deleted/moved-out directory: fs.watch gives no per-child events,
+            // so indexed children need a rescan to prune — UNLESS this very
+            // batch already carries every child's deletion (the common case:
+            // per-child events land in the same window as the dir's), in
+            // which case the per-file deletions below fully cover it.
+            const deletedSet = new Set(deleted);
+            for (const rel of deleted) {
+                const children = this.index.filesUnder(`${rel}/`);
+                if (children.length > 0 && children.some((c) => !deletedSet.has(c))) {
+                    this.rescanPending = true;
+                    break;
+                }
+            }
+        }
+        let mutated = false;
+        let freedSlot = false;
+        const capSkipped = [];
+        for (const rel of [...deleted, ...present]) {
+            if (this.closed && !final) {
+                // close() mid-drain: keep the remainder queued for the final
+                // drain that close() runs after this one settles.
+                this.pending.add(rel);
+                continue;
+            }
+            try {
+                const outcome = await this.indexer.indexFile(rel);
+                if (outcome === 'indexed' || outcome === 'removed')
+                    mutated = true;
+                if (outcome === 'removed')
+                    freedSlot = true;
+                else if (outcome === 'dropped')
+                    this.pending.add(rel); // guard drop — retry
+                else if (outcome === 'cap-skipped')
+                    capSkipped.push(rel);
+            }
+            catch (err) {
+                log.warn(`watcher: failed to index ${rel}: ${errMsg(err)}`);
+            }
+        }
+        // Cap-skipped creations get ONE retry when this same batch freed a
+        // slot (rename-at-cap whose delete was racing behind the create) —
+        // re-queueing unconditionally would retry forever while at the cap.
+        if (freedSlot) {
+            for (const rel of capSkipped)
+                this.pending.add(rel);
+        }
+        if (mutated) {
+            try {
+                await this.index.save(this.indexer.cachePath);
+                log.debug(`watcher: saved cache after flush (${batch.length} paths)`);
+            }
+            catch (err) {
+                log.error(`watcher: failed to save cache: ${errMsg(err)}`);
+            }
+        }
+        if (!final)
+            this.rearmIfNeeded();
+    }
+    rearmIfNeeded() {
+        // schedule() no-ops once closed; no second lifecycle guard here.
+        if (this.pending.size > 0 || this.rescanPending) {
+            this.schedule(this.retryMs);
+        }
+    }
+}

package/dist/logger.js

@@ -0,0 +1,16 @@
+// stderr-only logging. console.log would corrupt stdio JSON-RPC.
+const DEBUG_ENABLED = process.env.CODEDEEP_DEBUG === '1';
+function write(level, msg) {
+    process.stderr.write(`[codedeep-mcp ${level}] ${msg}\n`);
+}
+export const log = {
+    error: (msg) => write('error', msg),
+    warn: (msg) => write('warn', msg),
+    debug: (msg) => {
+        if (DEBUG_ENABLED)
+            write('debug', msg);
+    },
+};
+export function errMsg(err) {
+    return err?.message ?? String(err);
+}

package/dist/server.js

@@ -0,0 +1,170 @@
+// SDK v1.29 takes `inputSchema` as a RAW Zod shape ({ k: z.string() }), not
+// `z.object({...})`. The v2 alpha uses the wrapped form — do not confuse them.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { runFindReferences } from "./tools/find-references.js";
+import { runFindSymbol } from "./tools/find-symbol.js";
+import { runGetContext } from "./tools/get-context.js";
+import { runImpact } from "./tools/impact.js";
+import { runOverview } from "./tools/overview.js";
+import { runSearchStructure } from "./tools/search-structure.js";
+const SHARED_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+export function createServer(deps) {
+    const server = new McpServer({
+        name: "codedeep-mcp",
+        version: "0.1.0",
+    });
+    server.registerTool("overview", {
+        description: "Get a structural overview of the codebase: language breakdown, top-level directories, entry points, and symbol counts — plus branch summary, git hotspots, and risk hotspots (churn × call-graph coupling) when in a git repo.",
+        inputSchema: {
+            path: z.string().optional().describe("Project root (default: cwd)"),
+        },
+        annotations: SHARED_ANNOTATIONS,
+    }, async (args) => runOverview(args, deps));
+    server.registerTool("find_symbol", {
+        description: "AST-aware symbol lookup. Returns definitions matching a name (exact, prefix, or fuzzy), each with fan-in (references), fan-out (callees), and complexity — cyclomatic and cognitive, available for all 14 supported languages. Optional kind/scope/limit filters.",
+        inputSchema: {
+            name: z.string().describe("Symbol name (exact, prefix, or fuzzy)"),
+            kind: z
+                .enum([
+                "function",
+                "class",
+                "interface",
+                "type",
+                "variable",
+                "method",
+                "module",
+                "enum",
+            ])
+                .optional()
+                .describe("Filter by symbol kind"),
+            scope: z
+                .string()
+                .optional()
+                .describe("File path prefix to narrow search (e.g., 'src/auth/')"),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Max results (default: 10)"),
+        },
+        annotations: SHARED_ANNOTATIONS,
+    }, async (args) => runFindSymbol(args, deps));
+    server.registerTool("get_context", {
+        description: "Return everything needed to understand a symbol: full body, within-file callers/callees, coupling (fan-in/fan-out/cyclomatic+cognitive complexity/blast radius), and imports — plus co-change partners and recent commits when git is available.",
+        inputSchema: {
+            file: z.string().describe("File path (relative to project root)"),
+            symbol: z
+                .string()
+                .optional()
+                .describe("Symbol name within the file (omit for file-level context)"),
+            line: z
+                .number()
+                .int()
+                .optional()
+                .describe("Disambiguate when multiple symbols share a name"),
+            max_tokens: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Soft response budget (default: 3000)"),
+            include: z
+                .array(z.string())
+                .optional()
+                .describe("Sections to include: body, callers, callees, coupling, imports, co_changes, git"),
+        },
+        annotations: SHARED_ANNOTATIONS,
+    }, async (args) => runGetContext(args, deps));
+    server.registerTool("find_references", {
+        description: "Cross-file usage navigation. Returns approximate AST name-matched callers for a symbol, ranked by directory and import proximity — plus co-change partners from git history when available. LSP-precise tiers ship in Phase 2.",
+        inputSchema: {
+            file: z.string().describe("File containing the symbol (relative to project root)"),
+            symbol: z.string().describe("Symbol name"),
+            line: z
+                .number()
+                .int()
+                .optional()
+                .describe("Disambiguate when multiple symbols share a name"),
+            kind: z
+                .enum([
+                "callers",
+                "callees",
+                "implementations",
+                "type_references",
+                "all",
+            ])
+                .optional()
+                .describe("Result kind (default: 'all')"),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Max results per section (default: 20, max: 100)"),
+        },
+        annotations: SHARED_ANNOTATIONS,
+    }, async (args) => runFindReferences(args, deps));
+    server.registerTool("impact", {
+        description: "Trace the transitive blast radius of changing a symbol: upstream callers grouped by hop (depth 1, 2, …), with co-change partners from git history. Edges are AST name-matches, not compiler-verified; downstream callees and inheritance ship with LSP in Phase 2.",
+        inputSchema: {
+            file: z
+                .string()
+                .describe("File containing the symbol (relative to project root)"),
+            symbol: z.string().describe("Symbol name"),
+            line: z
+                .number()
+                .int()
+                .optional()
+                .describe("Disambiguate when multiple symbols share a name"),
+            depth: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Caller hops to trace upstream (default: 3, max: 5)"),
+            max_tokens: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Soft response budget (default: 3000); deeper hops drop first"),
+            include_weak: z
+                .boolean()
+                .optional()
+                .describe("Expand weak edges — unresolved member calls (obj.method()) and low-confidence deep chains; noisier. Default: false"),
+        },
+        annotations: SHARED_ANNOTATIONS,
+    }, async (args) => runImpact(args, deps));
+    server.registerTool("search_structure", {
+        description: "Keyword and structural code search. Fuzzy-matches symbol names, signatures, and docstrings; with `pattern`, runs an ast-grep structural query instead (TypeScript/TSX/JavaScript only for now).",
+        inputSchema: {
+            query: z
+                .string()
+                .optional()
+                .describe("Keywords matched fuzzily against symbol names, signatures, and docstrings (required unless `pattern` is set)"),
+            pattern: z
+                .string()
+                .optional()
+                .describe("ast-grep pattern, e.g. 'app.use($HANDLER)'. Takes precedence over `query`. TS/TSX/JS only."),
+            language: z
+                .string()
+                .optional()
+                .describe("Filter to one language: typescript, tsx, javascript, python, java, go, rust, swift, kotlin, dart, csharp, php, ruby, cpp, c, objc"),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Max results (default: 10, max: 100)"),
+        },
+        annotations: SHARED_ANNOTATIONS,
+    }, async (args) => runSearchStructure(args, deps));
+    return server;
+}