@veewo/gitnexus 1.3.11 → 1.4.6-rc

package/dist/mcp/core/{kuzu-adapter.d.ts → lbug-adapter.d.ts}

@@ -1,34 +1,35 @@
 /**
- * KuzuDB Adapter (Connection Pool)
+ * LadybugDB Adapter (Connection Pool)
  *
- * Manages a pool of KuzuDB databases keyed by repoId, each with
+ * Manages a pool of LadybugDB databases keyed by repoId, each with
  * multiple Connection objects for safe concurrent query execution.
  *
- * KuzuDB Connections are NOT thread-safe — a single Connection
+ * LadybugDB Connections are NOT thread-safe — a single Connection
  * segfaults if concurrent .query() calls hit it simultaneously.
  * This adapter provides a checkout/return connection pool so each
  * concurrent query gets its own Connection from the same Database.
  *
- * @see https://docs.kuzudb.com/concurrency — multiple Connections
+ * @see https://docs.ladybugdb.com/concurrency — multiple Connections
  * from the same Database is the officially supported concurrency pattern.
  */
 /**
  * Initialize (or reuse) a Database + connection pool for a specific repo.
  * Retries on lock errors (e.g., when `gitnexus analyze` is running).
  */
-export declare const initKuzu: (repoId: string, dbPath: string) => Promise<void>;
+export declare const initLbug: (repoId: string, dbPath: string) => Promise<void>;
+export declare const executeQuery: (repoId: string, cypher: string) => Promise<any[]>;
 /**
- * Execute a query on a specific repo's connection pool.
- * Automatically checks out a connection, runs the query, and returns it.
+ * Execute a parameterized query on a specific repo's connection pool.
+ * Uses prepare/execute pattern to prevent Cypher injection.
  */
-export declare const executeQuery: (repoId: string, cypher: string) => Promise<any[]>;
+export declare const executeParameterized: (repoId: string, cypher: string, params: Record<string, any>) => Promise<any[]>;
 /**
  * Close one or all repo pools.
  * If repoId is provided, close only that repo's connections.
  * If omitted, close all repos.
  */
-export declare const closeKuzu: (repoId?: string) => Promise<void>;
+export declare const closeLbug: (repoId?: string) => Promise<void>;
 /**
  * Check if a specific repo's pool is active
  */
-export declare const isKuzuReady: (repoId: string) => boolean;
+export declare const isLbugReady: (repoId: string) => boolean;

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

@@ -0,0 +1,327 @@
+/**
+ * LadybugDB Adapter (Connection Pool)
+ *
+ * Manages a pool of LadybugDB databases keyed by repoId, each with
+ * multiple Connection objects for safe concurrent query execution.
+ *
+ * LadybugDB Connections are NOT thread-safe — a single Connection
+ * segfaults if concurrent .query() calls hit it simultaneously.
+ * This adapter provides a checkout/return connection pool so each
+ * concurrent query gets its own Connection from the same Database.
+ *
+ * @see https://docs.ladybugdb.com/concurrency — multiple Connections
+ * from the same Database is the officially supported concurrency pattern.
+ */
+import fs from 'fs/promises';
+import lbug from '@ladybugdb/core';
+import { getOpenLbugDatabase } from '../../core/lbug/lbug-adapter.js';
+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;
+/** Saved real stdout.write — used to silence LadybugDB native output without race conditions */
+const realStdoutWrite = process.stdout.write.bind(process.stdout);
+let stdoutSilenceCount = 0;
+/**
+ * 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.
+ *
+ * LadybugDB's native .closeSync() triggers N-API destructor hooks that
+ * segfault on Linux/macOS.  Pool databases are opened read-only, so
+ * there is no WAL to flush — just deleting the pool entry and letting
+ * the GC (or process exit) reclaim native resources 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);
+}
+/**
+ * Create a new Connection from a repo's Database.
+ * Silences stdout to prevent native module output from corrupting MCP stdio.
+ */
+function silenceStdout() {
+    if (stdoutSilenceCount++ === 0) {
+        process.stdout.write = (() => true);
+    }
+}
+function restoreStdout() {
+    if (--stdoutSilenceCount <= 0) {
+        stdoutSilenceCount = 0;
+        process.stdout.write = realStdoutWrite;
+    }
+}
+function createConnection(db) {
+    silenceStdout();
+    try {
+        return new lbug.Connection(db);
+    }
+    finally {
+        restoreStdout();
+    }
+}
+/** 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;
+const CYPHER_WRITE_RE = /\b(CREATE|DELETE|SET|MERGE|REMOVE|DROP|ALTER|COPY|DETACH)\b/i;
+function assertReadOnlyQuery(cypher) {
+    if (CYPHER_WRITE_RE.test(cypher)) {
+        throw new Error('Write operations are not allowed. The knowledge graph is read-only.');
+    }
+}
+/**
+ * Initialize (or reuse) a Database + connection pool for a specific repo.
+ * Retries on lock errors (e.g., when `gitnexus 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: gitnexus analyze`);
+    }
+    evictLRU();
+    // Reuse an existing native Database if another repoId already opened this path.
+    // This prevents buffer manager exhaustion from multiple mmap regions on the same file.
+    let shared = dbCache.get(dbPath);
+    if (!shared) {
+        const coreDb = getOpenLbugDatabase(dbPath);
+        if (coreDb) {
+            shared = { db: coreDb, refCount: 0, ftsLoaded: true };
+            dbCache.set(dbPath, shared);
+        }
+    }
+    if (!shared) {
+        // Open in read-only mode — MCP server never writes to the database.
+        // This allows multiple MCP server instances to read concurrently, and
+        // avoids lock conflicts when `gitnexus analyze` is writing.
+        let lastError = null;
+        for (let attempt = 1; attempt <= LOCK_RETRY_ATTEMPTS; attempt++) {
+            silenceStdout();
+            try {
+                const db = new lbug.Database(dbPath, 0, // bufferManagerSize (default)
+                false, // enableCompression (default)
+                true);
+                restoreStdout();
+                shared = { db, refCount: 0, ftsLoaded: false };
+                dbCache.set(dbPath, shared);
+                break;
+            }
+            catch (err) {
+                restoreStdout();
+                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 extension 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
+        }
+    }
+};
+/**
+ * Checkout a connection from the pool.
+ * Returns an available connection, or creates a new one if under the cap.
+ * If all connections are busy and at cap, 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.
+ * If there are queued waiters, hand the connection directly to the next one
+ * instead of putting it back in the available array (avoids 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);
+    }
+}
+/**
+ * Execute a query on a specific repo's connection pool.
+ * Automatically checks out a connection, runs the query, and returns it.
+ */
+/** 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) => {
+    assertReadOnlyQuery(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 on a specific repo's connection pool.
+ * Uses prepare/execute pattern to prevent Cypher injection.
+ */
+export const executeParameterized = async (repoId, cypher, params) => {
+    assertReadOnlyQuery(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 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.
+ * If repoId is provided, close only that repo's connections.
+ * If omitted, close all repos.
+ */
+export const closeLbug = async (repoId) => {
+    if (repoId) {
+        closeOne(repoId);
+        return;
+    }
+    for (const id of [...pool.keys()]) {
+        closeOne(id);
+    }
+    if (idleTimer) {
+        clearInterval(idleTimer);
+        idleTimer = null;
+    }
+};
+/**
+ * Check if a specific repo's pool is active
+ */
+export const isLbugReady = (repoId) => pool.has(repoId);

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

@@ -3,16 +3,29 @@
  *
  * Provides tool implementations using local .gitnexus/ indexes.
  * Supports multiple indexed repositories via a global registry.
- * KuzuDB connections are opened lazily per repo on first query.
+ * LadybugDB connections are opened lazily per repo on first query.
  */
-import { type ResolvedUnityBinding } from '../../core/unity/resolver.js';
-import { type UnityContextPayload, type UnityHydrationMeta } from './unity-enrichment.js';
+import type { ResolvedUnityBinding } from '../../core/unity/resolver.js';
+import type { UnityContextPayload, UnityHydrationMeta } from './unity-enrichment.js';
 import { type RegistryEntry } from '../../storage/repo-manager.js';
+/**
+ * Quick test-file detection for filtering impact results.
+ * Matches common test file patterns across all supported languages.
+ */
+export declare function isTestFilePath(filePath: string): boolean;
 export declare function mergeUnityBindings(baseBindings: ResolvedUnityBinding[], resolvedByPath: Map<string, ResolvedUnityBinding[]>): ResolvedUnityBinding[];
 export declare function mergeParityUnityBindings(baseNonLightweightBindings: ResolvedUnityBinding[], resolvedBindings: ResolvedUnityBinding[]): ResolvedUnityBinding[];
 export declare function attachUnityHydrationMeta(payload: UnityContextPayload, input: Pick<UnityHydrationMeta, 'requestedMode' | 'effectiveMode' | 'elapsedMs' | 'fallbackToCompact'> & {
     hasExpandableBindings: boolean;
 }): UnityContextPayload;
+/** 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: {
@@ -27,7 +40,7 @@ interface RepoHandle {
     name: string;
     repoPath: string;
     storagePath: string;
-    kuzuPath: string;
+    lbugPath: string;
     indexedAt: string;
     lastCommit: string;
     stats?: RegistryEntry['stats'];
@@ -44,7 +57,7 @@ export declare class LocalBackend {
     /**
      * Re-read the global registry and update the in-memory repo map.
      * New repos are added, existing repos are updated, removed repos are pruned.
-     * KuzuDB connections for removed repos are NOT closed (they idle-timeout naturally).
+     * LadybugDB connections for removed repos are NOT closed (they idle-timeout naturally).
      */
     private refreshRepos;
     /**
@@ -94,7 +107,7 @@ export declare class LocalBackend {
      */
     private query;
     /**
-     * BM25 keyword search helper - uses KuzuDB FTS for always-fresh results
+     * BM25 keyword search helper - uses LadybugDB FTS for always-fresh results
      */
     private bm25Search;
     /**
@@ -111,7 +124,7 @@ export declare class LocalBackend {
     /**
      * Aggregate same-named clusters: group by heuristicLabel, sum symbols,
      * weighted-average cohesion, filter out tiny clusters (<5 symbols).
-     * Raw communities stay intact in KuzuDB for Cypher queries.
+     * Raw communities stay intact in LadybugDB for Cypher queries.
      */
     private aggregateClusters;
     private overview;
@@ -126,15 +139,6 @@ export declare class LocalBackend {
      * Routes cluster/process types to direct graph queries.
      */
     private explore;
-    private hydrateUnityContext;
-    private buildParityWarmupKey;
-    private scheduleParityWarmup;
-    private shouldEnableParityWarmup;
-    private getOrRunParityHydration;
-    private computeParityPayload;
-    private hydrateUnityContextParity;
-    private hydrateUnityContextCompact;
-    private toUnityContextPayload;
     /**
      * Detect changes — git-diff based impact analysis.
      * Maps changed lines to indexed symbols, then finds affected processes.
@@ -147,6 +151,7 @@ export declare class LocalBackend {
      */
     private rename;
     private impact;
+    private _impactImpl;
     /**
      * Query clusters (communities) directly from graph.
      * Used by getClustersResource — avoids legacy overview() dispatch.