gitnexus 1.4.6 → 1.4.7

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

@@ -22,12 +22,12 @@ const MAX_POOL_SIZE = 5;
 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);
+export const realStdoutWrite = process.stdout.write.bind(process.stdout);
 let stdoutSilenceCount = 0;
+/** True while pre-warming connections — prevents watchdog from prematurely restoring stdout */
+let preWarmActive = false;
 /**
  * Start the idle cleanup timer (runs every 60s)
  */
@@ -65,19 +65,42 @@ function evictLRU() {
     }
 }
 /**
- * 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.
+ * Remove a repo from the pool, close its connections, and release its
+ * shared Database ref.  Only closes the Database when no other repoIds
+ * reference it (refCount === 0).
  */
 function closeOne(repoId) {
     const entry = pool.get(repoId);
-    if (entry) {
-        const shared = dbCache.get(entry.dbPath);
-        if (shared && shared.refCount > 0) {
-            shared.refCount--;
+    if (!entry)
+        return;
+    entry.closed = true;
+    // Close available connections — fire-and-forget with .catch() to prevent
+    // unhandled rejections.  Native close() returns Promise<void> but can crash
+    // the N-API destructor on macOS/Windows; deferring to process exit lets
+    // dangerouslyIgnoreUnhandledErrors absorb the crash.
+    for (const conn of entry.available) {
+        conn.close().catch(() => { });
+    }
+    entry.available.length = 0;
+    // Checked-out connections can't be closed here — they're in-flight.
+    // The checkin() function detects entry.closed and closes them on return.
+    // Only close the Database when no other repoIds reference it.
+    // External databases (injected via initLbugWithDb) are never closed here —
+    // the core adapter owns them and handles their lifecycle.
+    const shared = dbCache.get(entry.dbPath);
+    if (shared) {
+        shared.refCount--;
+        if (shared.refCount === 0) {
+            if (shared.external) {
+                // External databases are owned by the core adapter — don't close
+                // or remove from cache.  Keep the entry so future initLbug() calls
+                // for the same dbPath reuse it instead of hitting a file lock.
+                shared.refCount = 0;
+            }
+            else {
+                shared.db.close().catch(() => { });
+                dbCache.delete(entry.dbPath);
+            }
         }
     }
     pool.delete(repoId);
@@ -97,6 +120,14 @@ function restoreStdout() {
         process.stdout.write = realStdoutWrite;
     }
 }
+// Safety watchdog: restore stdout if it gets stuck silenced (e.g. native crash
+// inside createConnection before restoreStdout runs).
+setInterval(() => {
+    if (stdoutSilenceCount > 0 && !preWarmActive) {
+        stdoutSilenceCount = 0;
+        process.stdout.write = realStdoutWrite;
+    }
+}, 1000).unref();
 function createConnection(db) {
     silenceStdout();
     try {
@@ -112,9 +143,14 @@ const QUERY_TIMEOUT_MS = 30_000;
 const WAITER_TIMEOUT_MS = 15_000;
 const LOCK_RETRY_ATTEMPTS = 3;
 const LOCK_RETRY_DELAY_MS = 2000;
+/** Deduplicates concurrent initLbug calls for the same repoId */
+const initPromises = new Map();
 /**
  * Initialize (or reuse) a Database + connection pool for a specific repo.
  * Retries on lock errors (e.g., when `gitnexus analyze` is running).
+ *
+ * Concurrent calls for the same repoId are deduplicated — the second caller
+ * awaits the first's in-progress init rather than starting a redundant one.
  */
 export const initLbug = async (repoId, dbPath) => {
     const existing = pool.get(repoId);
@@ -122,6 +158,27 @@ export const initLbug = async (repoId, dbPath) => {
         existing.lastUsed = Date.now();
         return;
     }
+    // Deduplicate concurrent init calls for the same repoId —
+    // prevents double-init race when multiple parallel tool calls
+    // trigger initialization for the same repo simultaneously.
+    const pending = initPromises.get(repoId);
+    if (pending)
+        return pending;
+    const promise = doInitLbug(repoId, dbPath);
+    initPromises.set(repoId, promise);
+    try {
+        await promise;
+    }
+    finally {
+        initPromises.delete(repoId);
+    }
+};
+/**
+ * Internal init — creates DB, pre-warms connections, loads FTS, then registers pool.
+ * Pool entry is registered LAST so concurrent executeQuery calls see either
+ * "not initialized" (and throw) or a fully ready pool — never a half-built one.
+ */
+async function doInitLbug(repoId, dbPath) {
     // Check if database exists
     try {
         await fs.stat(dbPath);
@@ -166,14 +223,22 @@ export const initLbug = async (repoId, dbPath) => {
     }
     shared.refCount++;
     const db = shared.db;
-    // Pre-create a small pool of connections
+    // Pre-create the full pool upfront so createConnection() (which silences
+    // stdout) is never called lazily during active query execution.
+    // Mark preWarmActive so the watchdog timer doesn't interfere.
+    preWarmActive = true;
     const available = [];
-    for (let i = 0; i < INITIAL_CONNS_PER_REPO; i++) {
-        available.push(createConnection(db));
+    try {
+        for (let i = 0; i < MAX_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
+    finally {
+        preWarmActive = false;
+    }
+    // Load FTS extension once per shared Database.
+    // Done BEFORE pool registration so no concurrent checkout can grab
+    // the connection while the async FTS load is in progress.
     if (!shared.ftsLoaded) {
         try {
             await available[0].query('LOAD EXTENSION fts');
@@ -183,7 +248,67 @@ export const initLbug = async (repoId, dbPath) => {
             // Extension may not be installed — FTS queries will fail gracefully
         }
     }
-};
+    // Register pool entry only after all connections are pre-warmed and FTS is
+    // loaded.  Concurrent executeQuery calls see either "not initialized"
+    // (and throw cleanly) or a fully ready pool — never a half-built one.
+    pool.set(repoId, { db, available, checkedOut: 0, waiters: [], lastUsed: Date.now(), dbPath, closed: false });
+    ensureIdleTimer();
+}
+/**
+ * Initialize a pool entry from a pre-existing Database object.
+ *
+ * Used in tests to avoid the writable→close→read-only cycle that crashes
+ * on macOS due to N-API destructor segfaults.  The pool adapter reuses
+ * the core adapter's writable Database instead of opening a new read-only one.
+ *
+ * The Database is registered in the shared dbCache so closeOne() decrements
+ * the refCount correctly.  If the Database is already cached (e.g. another
+ * repoId already injected it), the existing entry is reused.
+ */
+export async function initLbugWithDb(repoId, existingDb, dbPath) {
+    const existing = pool.get(repoId);
+    if (existing) {
+        existing.lastUsed = Date.now();
+        return;
+    }
+    // Register in dbCache with external: true so other initLbug() calls
+    // for the same dbPath reuse this Database instead of trying to open
+    // a new one (which would fail with a file lock error).
+    // closeOne() respects the external flag and skips db.close().
+    let shared = dbCache.get(dbPath);
+    if (!shared) {
+        shared = { db: existingDb, refCount: 0, ftsLoaded: false, external: true };
+        dbCache.set(dbPath, shared);
+    }
+    shared.refCount++;
+    const available = [];
+    preWarmActive = true;
+    try {
+        for (let i = 0; i < MAX_CONNS_PER_REPO; i++) {
+            available.push(createConnection(existingDb));
+        }
+    }
+    finally {
+        preWarmActive = false;
+    }
+    // Load FTS extension if not already loaded on this Database
+    try {
+        await available[0].query('LOAD EXTENSION fts');
+    }
+    catch {
+        // Extension may already be loaded or not installed
+    }
+    pool.set(repoId, {
+        db: existingDb,
+        available,
+        checkedOut: 0,
+        waiters: [],
+        lastUsed: Date.now(),
+        dbPath,
+        closed: false
+    });
+    ensureIdleTimer();
+}
 /**
  * Checkout a connection from the pool.
  * Returns an available connection, or creates a new one if under the cap.
@@ -195,11 +320,14 @@ function checkout(entry) {
         entry.checkedOut++;
         return Promise.resolve(entry.available.pop());
     }
-    // Grow the pool if under the cap
+    // Pool was pre-warmed to MAX_CONNS_PER_REPO during init.  If we're here
+    // with fewer total connections, something leaked — surface the bug rather
+    // than silently creating a connection (which would silence stdout mid-query).
     const totalConns = entry.available.length + entry.checkedOut;
     if (totalConns < MAX_CONNS_PER_REPO) {
-        entry.checkedOut++;
-        return Promise.resolve(createConnection(entry.db));
+        throw new Error(`Connection pool integrity error: expected ${MAX_CONNS_PER_REPO} ` +
+            `connections but found ${totalConns} (${entry.available.length} available, ` +
+            `${entry.checkedOut} checked out)`);
     }
     // At capacity — queue the caller with a timeout.
     return new Promise((resolve, reject) => {
@@ -218,10 +346,17 @@ function checkout(entry) {
 }
 /**
  * Return a connection to the pool after use.
+ * If the pool entry was closed while the connection was checked out (e.g.
+ * LRU eviction), close the orphaned connection instead of returning it.
  * 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.closed) {
+        // Pool entry was deleted during checkout — close the orphaned connection
+        conn.close().catch(() => { });
+        return;
+    }
     if (entry.waiters.length > 0) {
         // Hand directly to the next waiter — no intermediate available state
         const waiter = entry.waiters.shift();
@@ -249,6 +384,9 @@ export const executeQuery = async (repoId, cypher) => {
     if (!entry) {
         throw new Error(`LadybugDB not initialized for repo "${repoId}". Call initLbug first.`);
     }
+    if (isWriteQuery(cypher)) {
+        throw new Error('Write operations are not allowed. The pool adapter is read-only.');
+    }
     entry.lastUsed = Date.now();
     const conn = await checkout(entry);
     try {
@@ -309,3 +447,9 @@ export const closeLbug = async (repoId) => {
  * Check if a specific repo's pool is active
  */
 export const isLbugReady = (repoId) => pool.has(repoId);
+/** Regex to detect write operations in user-supplied Cypher queries */
+export const CYPHER_WRITE_RE = /\b(CREATE|DELETE|SET|MERGE|REMOVE|DROP|ALTER|COPY|DETACH)\b/i;
+/** Check if a Cypher query contains write operations */
+export function isWriteQuery(query) {
+    return CYPHER_WRITE_RE.test(query);
+}

package/dist/mcp/local/local-backend.js

@@ -37,7 +37,7 @@ export const VALID_NODE_LABELS = new Set([
     'Record', 'Delegate', 'Annotation', 'Constructor', 'Template', 'Module',
 ]);
 /** Valid relation types for impact analysis filtering */
-export const VALID_RELATION_TYPES = new Set(['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'OVERRIDES']);
+export const VALID_RELATION_TYPES = new Set(['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'HAS_PROPERTY', 'OVERRIDES', 'ACCESSES']);
 /** Regex to detect write operations in user-supplied Cypher queries */
 export const CYPHER_WRITE_RE = /\b(CREATE|DELETE|SET|MERGE|REMOVE|DROP|ALTER|COPY|DETACH)\b/i;
 /** Check if a Cypher query contains write operations */
@@ -788,14 +788,14 @@ export class LocalBackend {
         // Categorized incoming refs
         const incomingRows = await executeParameterized(repo.id, `
       MATCH (caller)-[r:CodeRelation]->(n {id: $symId})
-      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS']
+      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'HAS_PROPERTY', 'OVERRIDES', 'ACCESSES']
       RETURN r.type AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath, labels(caller)[0] AS kind
       LIMIT 30
     `, { symId });
         // Categorized outgoing refs
         const outgoingRows = await executeParameterized(repo.id, `
       MATCH (n {id: $symId})-[r:CodeRelation]->(target)
-      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS']
+      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'HAS_METHOD', 'HAS_PROPERTY', 'OVERRIDES', 'ACCESSES']
       RETURN r.type AS relType, target.id AS uid, target.name AS name, target.filePath AS filePath, labels(target)[0] AS kind
       LIMIT 30
     `, { symId });

package/dist/mcp/resources.js

@@ -271,6 +271,13 @@ nodes:
 
 additional_node_types: "Multi-language: Struct, Enum, Macro, Typedef, Union, Namespace, Trait, Impl, TypeAlias, Const, Static, Property, Record, Delegate, Annotation, Constructor, Template, Module (use backticks in queries: \`Struct\`, \`Enum\`, etc.)"
 
+node_properties:
+  common: "name (STRING), filePath (STRING), startLine (INT32), endLine (INT32)"
+  Method: "parameterCount (INT32), returnType (STRING), isVariadic (BOOL)"
+  Function: "parameterCount (INT32), returnType (STRING), isVariadic (BOOL)"
+  Property: "declaredType (STRING) — the field's type annotation (e.g., 'Address', 'City'). Used for field-access chain resolution."
+  Constructor: "parameterCount (INT32)"
+
 relationships:
   - CONTAINS: File/Folder contains child
   - DEFINES: File defines a symbol
@@ -278,6 +285,10 @@ relationships:
   - IMPORTS: Module imports
   - EXTENDS: Class inheritance
   - IMPLEMENTS: Interface implementation
+  - HAS_METHOD: Class/Struct/Interface owns a Method
+  - HAS_PROPERTY: Class/Struct/Interface owns a Property (field)
+  - ACCESSES: Function/Method reads or writes a Property (reason: 'read' or 'write')
+  - OVERRIDES: Method overrides another Method (MRO)
   - MEMBER_OF: Symbol belongs to community
   - STEP_IN_PROCESS: Symbol is step N in process
 

package/dist/mcp/server.js

@@ -15,6 +15,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CompatibleStdioServerTransport } from './compatible-stdio-transport.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { GITNEXUS_TOOLS } from './tools.js';
+import { realStdoutWrite } from './core/lbug-adapter.js';
 import { getResourceDefinitions, getResourceTemplates, readResource } from './resources.js';
 /**
  * Next-step hints appended to tool responses.
@@ -237,12 +238,22 @@ Follow these steps:
  */
 export async function startMCPServer(backend) {
     const server = createMCPServer(backend);
-    // Connect to stdio transport
-    const transport = new CompatibleStdioServerTransport();
+    // Use the shared stdout reference captured at module-load time by the
+    // lbug-adapter.  Avoids divergence if anything patches stdout between
+    // module load and server start.
+    const _safeStdout = new Proxy(process.stdout, {
+        get(target, prop, receiver) {
+            if (prop === 'write')
+                return realStdoutWrite;
+            const val = Reflect.get(target, prop, receiver);
+            return typeof val === 'function' ? val.bind(target) : val;
+        }
+    });
+    const transport = new CompatibleStdioServerTransport(process.stdin, _safeStdout);
     await server.connect(transport);
     // Graceful shutdown helper
     let shuttingDown = false;
-    const shutdown = async () => {
+    const shutdown = async (exitCode = 0) => {
         if (shuttingDown)
             return;
         shuttingDown = true;
@@ -254,11 +265,22 @@ export async function startMCPServer(backend) {
             await server.close();
         }
         catch { }
-        process.exit(0);
+        process.exit(exitCode);
     };
     // Handle graceful shutdown
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
+    // Log crashes to stderr so they aren't silently lost.
+    // uncaughtException is fatal — shut down.
+    // unhandledRejection is logged but kept non-fatal (availability-first):
+    // killing the server for one missed catch would be worse than logging it.
+    process.on('uncaughtException', (err) => {
+        process.stderr.write(`GitNexus MCP uncaughtException: ${err?.stack || err}\n`);
+        shutdown(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        process.stderr.write(`GitNexus MCP unhandledRejection: ${reason?.stack || reason}\n`);
+    });
     // Handle stdio errors — stdin close means the parent process is gone
     process.stdin.on('end', shutdown);
     process.stdin.on('error', () => shutdown());

package/dist/mcp/tools.js

@@ -61,7 +61,7 @@ SCHEMA:
 - Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process
 - Multi-language nodes (use backticks): \`Struct\`, \`Enum\`, \`Trait\`, \`Impl\`, etc.
 - All edges via single CodeRelation table with 'type' property
-- Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, OVERRIDES, MEMBER_OF, STEP_IN_PROCESS
+- Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, ACCESSES, OVERRIDES, MEMBER_OF, STEP_IN_PROCESS
 - Edge properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)
 
 EXAMPLES:
@@ -77,6 +77,12 @@ EXAMPLES:
 • Find all methods of a class:
   MATCH (c:Class {name: "UserService"})-[r:CodeRelation {type: 'HAS_METHOD'}]->(m:Method) RETURN m.name, m.parameterCount, m.returnType
 
+• Find all properties of a class:
+  MATCH (c:Class {name: "User"})-[r:CodeRelation {type: 'HAS_PROPERTY'}]->(p:Property) RETURN p.name, p.declaredType
+
+• Find all writers of a field:
+  MATCH (f:Function)-[r:CodeRelation {type: 'ACCESSES', reason: 'write'}]->(p:Property) WHERE p.name = "address" RETURN f.name, f.filePath
+
 • Find method overrides (MRO resolution):
   MATCH (winner:Method)-[r:CodeRelation {type: 'OVERRIDES'}]->(loser:Method) RETURN winner.name, winner.filePath, loser.filePath, r.reason
 
@@ -102,12 +108,14 @@ TIPS:
     {
         name: 'context',
         description: `360-degree view of a single code symbol.
-Shows categorized incoming/outgoing references (calls, imports, extends, implements), process participation, and file location.
+Shows categorized incoming/outgoing references (calls, imports, extends, implements, methods, properties, overrides), process participation, and file location.
 
 WHEN TO USE: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.
 AFTER THIS: Use impact() if planning changes, or READ gitnexus://repo/{name}/process/{processName} for full execution trace.
 
-Handles disambiguation: if multiple symbols share the same name, returns candidates for you to pick from. Use uid param for zero-ambiguity lookup from prior results.`,
+Handles disambiguation: if multiple symbols share the same name, returns candidates for you to pick from. Use uid param for zero-ambiguity lookup from prior results.
+
+NOTE: ACCESSES edges (field read/write tracking) are included in context results with reason 'read' or 'write'. CALLS edges resolve through field access chains and method-call chains (e.g., user.address.getCity().save() produces CALLS edges at each step).`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -183,7 +191,9 @@ Depth groups:
 - d=2: LIKELY AFFECTED (indirect)
 - d=3: MAY NEED TESTING (transitive)
 
-EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, OVERRIDES
+TIP: Default traversal uses CALLS/IMPORTS/EXTENDS/IMPLEMENTS. For class members, include HAS_METHOD and HAS_PROPERTY in relationTypes. For field access analysis, include ACCESSES in relationTypes.
+
+EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, OVERRIDES, ACCESSES
 Confidence: 1.0 = certain, <0.8 = fuzzy match`,
         inputSchema: {
             type: 'object',
@@ -191,7 +201,7 @@ Confidence: 1.0 = certain, <0.8 = fuzzy match`,
                 target: { type: 'string', description: 'Name of function, class, or file to analyze' },
                 direction: { type: 'string', description: 'upstream (what depends on this) or downstream (what this depends on)' },
                 maxDepth: { type: 'number', description: 'Max relationship depth (default: 3)', default: 3 },
-                relationTypes: { type: 'array', items: { type: 'string' }, description: 'Filter: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, OVERRIDES (default: usage-based)' },
+                relationTypes: { type: 'array', items: { type: 'string' }, description: 'Filter: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, OVERRIDES, ACCESSES (default: usage-based, ACCESSES excluded by default)' },
                 includeTests: { type: 'boolean', description: 'Include test files (default: false)' },
                 minConfidence: { type: 'number', description: 'Minimum confidence 0-1 (default: 0.7)' },
                 repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.4.6",
+  "version": "1.4.7",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -39,9 +39,9 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsx watch src/cli/index.ts",
-    "test": "vitest run test/unit",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit",
     "test:integration": "vitest run test/integration",
-    "test:all": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "prepare": "npm run build",
@@ -59,7 +59,7 @@
     "graphology": "^0.25.4",
     "graphology-indices": "^0.17.0",
     "graphology-utils": "^2.3.0",
-    "@ladybugdb/core": "^0.15.1",
+    "@ladybugdb/core": "^0.15.2",
     "ignore": "^7.0.5",
     "lru-cache": "^11.0.0",
     "mnemonist": "^0.39.0",