@zuvia-software-solutions/code-mapper 1.4.0

package/dist/mcp/core/lbug-adapter.js

@@ -0,0 +1,330 @@
+// code-mapper/src/mcp/core/lbug-adapter.ts
+/** @file lbug-adapter.ts
+ *  @description LadybugDB connection pool adapter keyed by repoId
+ *  Provides checkout/return pool so each concurrent query gets its own Connection
+ *  from the same Database (Connections are NOT thread-safe)
+ *  @see https://docs.ladybugdb.com/concurrency */
+import fs from 'fs/promises';
+import lbug from '@ladybugdb/core';
+const pool = new Map();
+const dbCache = new Map();
+/** Max repos in the pool (LRU eviction) */
+const MAX_POOL_SIZE = 5;
+/** Idle timeout before closing a repo's connections */
+const IDLE_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+/** Max connections per repo (caps concurrent queries per repo) */
+const MAX_CONNS_PER_REPO = 8;
+/** Connections created eagerly on init */
+const INITIAL_CONNS_PER_REPO = 2;
+let idleTimer = null;
+/** Start the idle cleanup timer (runs every 60s) */
+function ensureIdleTimer() {
+    if (idleTimer)
+        return;
+    idleTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [repoId, entry] of pool) {
+            if (now - entry.lastUsed > IDLE_TIMEOUT_MS && entry.checkedOut === 0) {
+                closeOne(repoId);
+            }
+        }
+    }, 60_000);
+    if (idleTimer && typeof idleTimer === 'object' && 'unref' in idleTimer) {
+        idleTimer.unref();
+    }
+}
+/** Evict the least-recently-used repo if pool is at capacity */
+function evictLRU() {
+    if (pool.size < MAX_POOL_SIZE)
+        return;
+    let oldestId = null;
+    let oldestTime = Infinity;
+    for (const [id, entry] of pool) {
+        if (entry.checkedOut === 0 && entry.lastUsed < oldestTime) {
+            oldestTime = entry.lastUsed;
+            oldestId = id;
+        }
+    }
+    if (oldestId) {
+        closeOne(oldestId);
+    }
+}
+/**
+ * Remove a repo from the pool and release its shared Database ref
+ * Skips .closeSync() which triggers N-API segfaults on Linux/macOS;
+ * pools are read-only so GC reclamation is safe
+ */
+function closeOne(repoId) {
+    const entry = pool.get(repoId);
+    if (entry) {
+        const shared = dbCache.get(entry.dbPath);
+        if (shared && shared.refCount > 0) {
+            shared.refCount--;
+        }
+    }
+    pool.delete(repoId);
+}
+function createConnection(db) {
+    return new lbug.Connection(db);
+}
+/** Query timeout in milliseconds */
+const QUERY_TIMEOUT_MS = 30_000;
+/** Waiter queue timeout in milliseconds */
+const WAITER_TIMEOUT_MS = 15_000;
+const LOCK_RETRY_ATTEMPTS = 3;
+const LOCK_RETRY_DELAY_MS = 2000;
+/**
+ * Initialize (or reuse) a Database + connection pool for a specific repo
+ * Retries on lock errors (e.g., when `code-mapper analyze` is running)
+ */
+export const initLbug = async (repoId, dbPath) => {
+    const existing = pool.get(repoId);
+    if (existing) {
+        existing.lastUsed = Date.now();
+        return;
+    }
+    // Check if database exists
+    try {
+        await fs.stat(dbPath);
+    }
+    catch {
+        throw new Error(`LadybugDB not found at ${dbPath}. Run: code-mapper analyze`);
+    }
+    evictLRU();
+    // Reuse an existing native Database if another repoId already opened this path
+    // Prevents buffer manager exhaustion from multiple mmap regions on the same file
+    let shared = dbCache.get(dbPath);
+    if (!shared) {
+        // Open read-write so incremental refresh can write through the same handle.
+        // Lock conflicts with `code-mapper analyze` are handled by retry logic.
+        let lastError = null;
+        for (let attempt = 1; attempt <= LOCK_RETRY_ATTEMPTS; attempt++) {
+            try {
+                const db = new lbug.Database(dbPath, 0, // bufferManagerSize (default)
+                false, // enableCompression (default)
+                false);
+                shared = { db, refCount: 0, ftsLoaded: false };
+                dbCache.set(dbPath, shared);
+                break;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                const isLockError = lastError.message.includes('Could not set lock')
+                    || lastError.message.includes('lock');
+                if (!isLockError || attempt === LOCK_RETRY_ATTEMPTS)
+                    break;
+                await new Promise(resolve => setTimeout(resolve, LOCK_RETRY_DELAY_MS * attempt));
+            }
+        }
+        if (!shared) {
+            throw new Error(`LadybugDB unavailable for ${repoId}. Another process may be rebuilding the index. ` +
+                `Retry later. (${lastError?.message || 'unknown error'})`);
+        }
+    }
+    shared.refCount++;
+    const db = shared.db;
+    // Pre-create a small pool of connections
+    const available = [];
+    for (let i = 0; i < INITIAL_CONNS_PER_REPO; i++) {
+        available.push(createConnection(db));
+    }
+    pool.set(repoId, { db, available, checkedOut: 0, waiters: [], lastUsed: Date.now(), dbPath });
+    ensureIdleTimer();
+    // Load FTS + VECTOR extensions once per shared Database
+    if (!shared.ftsLoaded) {
+        try {
+            await available[0].query('LOAD EXTENSION fts');
+            shared.ftsLoaded = true;
+        }
+        catch {
+            // Extension may not be installed — FTS queries will fail gracefully
+        }
+    }
+    // Load VECTOR extension for semantic search (HNSW index queries)
+    try {
+        await available[0].query('LOAD EXTENSION vector');
+    }
+    catch {
+        // Extension may not be installed — vector queries will fall back to BM25-only
+    }
+};
+/**
+ * Checkout a connection from the pool
+ * Returns an available connection, creates a new one if under cap,
+ * or queues the caller until one is returned
+ */
+function checkout(entry) {
+    // Fast path: grab an available connection
+    if (entry.available.length > 0) {
+        entry.checkedOut++;
+        return Promise.resolve(entry.available.pop());
+    }
+    // Grow the pool if under the cap
+    const totalConns = entry.available.length + entry.checkedOut;
+    if (totalConns < MAX_CONNS_PER_REPO) {
+        entry.checkedOut++;
+        return Promise.resolve(createConnection(entry.db));
+    }
+    // At capacity — queue the caller with a timeout.
+    return new Promise((resolve, reject) => {
+        const waiter = (conn) => {
+            clearTimeout(timer);
+            resolve(conn);
+        };
+        const timer = setTimeout(() => {
+            const idx = entry.waiters.indexOf(waiter);
+            if (idx !== -1)
+                entry.waiters.splice(idx, 1);
+            reject(new Error(`Connection pool exhausted: timed out after ${WAITER_TIMEOUT_MS}ms waiting for a free connection`));
+        }, WAITER_TIMEOUT_MS);
+        entry.waiters.push(waiter);
+    });
+}
+/**
+ * Return a connection to the pool after use
+ * Hands directly to queued waiters to avoid race conditions
+ */
+function checkin(entry, conn) {
+    if (entry.waiters.length > 0) {
+        // Hand directly to the next waiter (no intermediate available state)
+        const waiter = entry.waiters.shift();
+        waiter(conn);
+    }
+    else {
+        entry.checkedOut--;
+        entry.available.push(conn);
+    }
+}
+/** Race a promise against a timeout */
+function withTimeout(promise, ms, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+export const executeQuery = async (repoId, cypher) => {
+    const entry = pool.get(repoId);
+    if (!entry) {
+        throw new Error(`LadybugDB not initialized for repo "${repoId}". Call initLbug first.`);
+    }
+    entry.lastUsed = Date.now();
+    const conn = await checkout(entry);
+    try {
+        const queryResult = await withTimeout(conn.query(cypher), QUERY_TIMEOUT_MS, 'Query');
+        const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
+        const rows = await result.getAll();
+        return rows;
+    }
+    finally {
+        checkin(entry, conn);
+    }
+};
+/** Execute a parameterized query using prepare/execute to prevent Cypher injection */
+export const executeParameterized = async (repoId, cypher, params) => {
+    const entry = pool.get(repoId);
+    if (!entry) {
+        throw new Error(`LadybugDB not initialized for repo "${repoId}". Call initLbug first.`);
+    }
+    entry.lastUsed = Date.now();
+    const conn = await checkout(entry);
+    try {
+        const stmt = await withTimeout(conn.prepare(cypher), QUERY_TIMEOUT_MS, 'Prepare');
+        if (!stmt.isSuccess()) {
+            const errMsg = await stmt.getErrorMessage();
+            throw new Error(`Prepare failed: ${errMsg}`);
+        }
+        const queryResult = await withTimeout(conn.execute(stmt, params), QUERY_TIMEOUT_MS, 'Execute');
+        const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
+        const rows = await result.getAll();
+        return rows;
+    }
+    finally {
+        checkin(entry, conn);
+    }
+};
+/** Close one or all repo pools (provide repoId for single, omit for all) */
+export const closeLbug = async (repoId) => {
+    if (repoId) {
+        closeOne(repoId);
+        return;
+    }
+    for (const id of [...pool.keys()]) {
+        closeOne(id);
+    }
+    if (idleTimer) {
+        clearInterval(idleTimer);
+        idleTimer = null;
+    }
+};
+/** Invalidate a repo's pool and shared DB cache, forcing fresh connections on next init.
+ *  Closes the native Database handle to release the file lock so a child process
+ *  can open the DB in read-write mode for incremental refresh.
+ *  Used before AND after the incremental refresh child process writes to the DB. */
+export const invalidateAndReopen = async (repoId) => {
+    const entry = pool.get(repoId);
+    if (!entry)
+        return;
+    const entryDbPath = entry.dbPath;
+    closeOne(repoId);
+    // Close and remove the native Database handle to release the file lock.
+    // Without this, the child process cannot acquire a write lock on the DB file.
+    const shared = dbCache.get(entryDbPath);
+    if (shared && shared.refCount <= 0) {
+        try {
+            await shared.db.close();
+            console.error('Code Mapper: Native DB handle closed successfully');
+        }
+        catch (err) {
+            console.error(`Code Mapper: DB close failed (may still release lock on GC): ${err instanceof Error ? err.message : err}`);
+        }
+        dbCache.delete(entryDbPath);
+    }
+    else if (shared) {
+        console.error(`Code Mapper: Cannot close DB — ${shared.refCount} other refs still active`);
+    }
+};
+/** Check if a specific repo's pool is active */
+export const isLbugReady = (repoId) => pool.has(repoId);
+/** Write-connection retry config */
+const WRITE_RETRY_ATTEMPTS = 3;
+const WRITE_RETRY_DELAY_MS = 1500;
+/**
+ * Open a short-lived read-write connection, execute the callback, then close.
+ * The read-only pool must be invalidated BEFORE calling this to avoid lock
+ * conflicts. Retries on lock errors (e.g., concurrent `code-mapper analyze`).
+ */
+export const withWriteConnection = async (dbPath, fn) => {
+    let lastError = null;
+    for (let attempt = 1; attempt <= WRITE_RETRY_ATTEMPTS; attempt++) {
+        let db = null;
+        let conn = null;
+        try {
+            db = new lbug.Database(dbPath);
+            conn = new lbug.Connection(db);
+            const result = await fn(conn);
+            return result;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            const isLockError = lastError.message.includes('Could not set lock') ||
+                lastError.message.includes('lock');
+            if (!isLockError || attempt === WRITE_RETRY_ATTEMPTS)
+                break;
+            await new Promise((resolve) => setTimeout(resolve, WRITE_RETRY_DELAY_MS * attempt));
+        }
+        finally {
+            try {
+                if (conn)
+                    await conn.close();
+            }
+            catch { }
+            try {
+                if (db)
+                    await db.close();
+            }
+            catch { }
+        }
+    }
+    throw lastError ?? new Error('withWriteConnection failed');
+};

package/dist/mcp/local/local-backend.d.ts

@@ -0,0 +1,188 @@
+/** @file local-backend.ts
+ *  @description Tool implementations using local .code-mapper/ indexes
+ *  Supports multiple indexed repositories via a global registry
+ *  LadybugDB connections are opened lazily per repo on first query */
+import { type RegistryEntry } from '../../storage/repo-manager.js';
+/** Quick test-file detection for filtering impact results across all supported languages */
+export declare function isTestFilePath(filePath: string): boolean;
+/** Valid LadybugDB node labels for safe Cypher query construction */
+export declare const VALID_NODE_LABELS: Set<string>;
+/** Valid relation types for impact analysis filtering */
+export declare const VALID_RELATION_TYPES: Set<string>;
+/** Regex to detect write operations in user-supplied Cypher queries */
+export declare const CYPHER_WRITE_RE: RegExp;
+/** Check if a Cypher query contains write operations */
+export declare function isWriteQuery(query: string): boolean;
+export interface CodebaseContext {
+    projectName: string;
+    stats: {
+        fileCount: number;
+        functionCount: number;
+        communityCount: number;
+        processCount: number;
+    };
+}
+interface RepoHandle {
+    id: string;
+    name: string;
+    repoPath: string;
+    storagePath: string;
+    lbugPath: string;
+    indexedAt: string;
+    lastCommit: string;
+    stats?: RegistryEntry['stats'];
+}
+export declare class LocalBackend {
+    private repos;
+    private contextCache;
+    private initializedRepos;
+    private watchers;
+    /** Per-repo promise chain that serializes ensureFresh calls.
+     *  Prevents race: Call 2 skipping refresh while Call 1 is still writing. */
+    private refreshLocks;
+    /** Hard ceiling — beyond this, incremental is unreliable, warn prominently */
+    private static readonly MAX_INCREMENTAL_FILES;
+    /** Optional tsgo LSP service for confidence-1.0 semantic resolution */
+    private tsgoEnabled;
+    /** Start file system watcher for a repo to detect source changes */
+    private startWatcher;
+    /**
+     * Seed the watcher with file changes that happened while the MCP server was
+     * not running. Compares meta.json lastCommit against current git HEAD and
+     * injects any changed files as dirty entries.
+     */
+    private seedWatcherFromGit;
+    /**
+     * Serialized entry point — ensures only one refresh runs per repo at a time.
+     * Call 2 waits for Call 1 to finish, then re-checks the watcher.
+     */
+    private ensureFresh;
+    /** Check for file changes and refresh the DB + embeddings before a tool call */
+    private doEnsureFresh;
+    /**
+     * Tables that are global metadata — NOT deleted per-file during incremental refresh.
+     */
+    private static readonly SKIP_DELETE_TABLES;
+    /** Tables requiring backtick-quoting in Cypher (reserved words) */
+    private static readonly BACKTICK_TABLES;
+    private static quoteTable;
+    private static escapeCypher;
+    /**
+     * In-process incremental refresh — parses dirty files with tree-sitter and
+     * writes directly to the DB through the existing connection pool.
+     *
+     * This avoids the LadybugDB lock conflict that prevented the child-process
+     * approach from working: LadybugDB on macOS holds an exclusive file lock
+     * even for read-only connections, and db.close() segfaults via N-API.
+     */
+    private inProcessRefresh;
+    /**
+     * Update CodeEmbedding rows for dirty files so semantic search is never stale.
+     *
+     * Runs ONLY when the repo previously had embeddings (stats.embeddings > 0).
+     * Steps:
+     *   1. Delete stale CodeEmbedding rows for all dirty file paths (always)
+     *   2. Query new embeddable nodes for modified/created files
+     *   3. Generate text → batch embed using the warm MCP singleton model
+     *   4. Insert new CodeEmbedding rows
+     *   5. Drop + recreate HNSW vector index
+     *
+     * If the embedding model fails to load, stale rows are still deleted —
+     * semantic search returns fewer results but never wrong ones.
+     */
+    private refreshEmbeddings;
+    private rebuildVectorIndex;
+    /**
+     * Initialize from the global registry, returns true if at least one repo is available.
+     * @param opts.tsgo — Enable tsgo semantic resolution (confidence-1.0 call edges)
+     */
+    init(opts?: {
+        tsgo?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Re-read the global registry and update the in-memory repo map
+     * LadybugDB connections for removed repos idle-timeout naturally
+     */
+    private refreshRepos;
+    /** Generate a stable repo ID from name + path (appends hash on collision) */
+    private repoId;
+    /**
+     * Resolve which repo to use (by name, path, or single-repo default)
+     * Re-reads the registry once on miss in case a new repo was indexed
+     */
+    resolveRepo(repoParam?: string): Promise<RepoHandle>;
+    /** Try to resolve a repo from the in-memory cache, returns null on miss */
+    private resolveRepoFromCache;
+    private ensureInitialized;
+    /** Get context for a specific repo (or the single repo if only one) */
+    getContext(repoId?: string): CodebaseContext | null;
+    /** List all registered repos, re-reading the registry to discover new ones */
+    listRepos(): Promise<Array<{
+        name: string;
+        path: string;
+        indexedAt: string;
+        lastCommit: string;
+        stats?: any;
+    }>>;
+    /** Extract signature from content: the declaration line(s), not the full body */
+    private extractSignature;
+    /** Short file path: strip common prefix if all paths share it */
+    private shortPath;
+    /** C2: Count how many initial steps two flows share (by symbol name) */
+    private sharedPrefixLength;
+    /** D1: Generate a readable flow description from step names */
+    /** Generate readable flow description from step names.
+     *  Uses step 2 (first dispatch point) as the middle — it's where the entry
+     *  point specializes and is the most discriminating step in most flows. */
+    private describeFlow;
+    private formatQueryAsText;
+    private formatContextAsText;
+    private formatImpactAsText;
+    private formatDetectChangesAsText;
+    /** C3: Check if index is behind HEAD and return a warning prefix */
+    private getStalenessWarning;
+    callTool(method: string, params: any): Promise<any>;
+    /**
+     * Query tool: process-grouped search
+     * Hybrid BM25+semantic search, trace to processes, rank by relevance + cohesion
+     */
+    private query;
+    /**
+     * BM25 keyword search helper - uses LadybugDB FTS for always-fresh results
+     */
+    private bm25Search;
+    /**
+     * Semantic vector search helper
+     */
+    private semanticSearch;
+    executeCypher(repoName: string, query: string): Promise<any>;
+    private cypher;
+    /** Format raw Cypher result rows as a markdown table, with raw fallback */
+    private formatCypherAsMarkdown;
+    /** Aggregate same-named clusters by heuristicLabel, filtering tiny clusters (<5 symbols) */
+    private aggregateClusters;
+    private overview;
+    /** Context tool: 360-degree symbol view with categorized refs and disambiguation */
+    private context;
+    /** Legacy explore for backwards compatibility with resources.ts */
+    private explore;
+    /** Detect changes: git-diff impact analysis mapping changed lines to symbols and processes */
+    private detectChanges;
+    /** Rename tool: multi-file coordinated rename using graph (high confidence) + text search */
+    private rename;
+    private impact;
+    /** Query clusters (communities) directly from graph for getClustersResource */
+    queryClusters(repoName?: string, limit?: number): Promise<{
+        clusters: any[];
+    }>;
+    /** Query processes directly from graph for getProcessesResource */
+    queryProcesses(repoName?: string, limit?: number): Promise<{
+        processes: any[];
+    }>;
+    /** Query cluster detail (members) for getClusterDetailResource */
+    queryClusterDetail(name: string, repoName?: string): Promise<any>;
+    /** Query process detail (steps) for getProcessDetailResource */
+    queryProcessDetail(name: string, repoName?: string): Promise<any>;
+    disconnect(): Promise<void>;
+}
+export {};