gitnexus 1.2.7 → 1.2.9

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

@@ -228,8 +228,10 @@ export class LocalBackend {
         switch (method) {
             case 'query':
                 return this.query(repo, params);
-            case 'cypher':
-                return this.cypher(repo, params);
+            case 'cypher': {
+                const raw = await this.cypher(repo, params);
+                return this.formatCypherAsMarkdown(raw);
+            }
             case 'context':
                 return this.context(repo, params);
             case 'impact':
@@ -326,16 +328,18 @@ export class LocalBackend {
         `);
             }
             catch { /* symbol might not be in any process */ }
-            // Get cluster cohesion as internal ranking signal (never exposed)
+            // Get cluster membership + cohesion (cohesion used as internal ranking signal)
             let cohesion = 0;
+            let module;
             try {
                 const cohesionRows = await executeQuery(repo.id, `
           MATCH (n {id: '${escaped}'})-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
-          RETURN c.cohesion AS cohesion
+          RETURN c.cohesion AS cohesion, c.heuristicLabel AS module
           LIMIT 1
         `);
                 if (cohesionRows.length > 0) {
                     cohesion = (cohesionRows[0].cohesion ?? cohesionRows[0][0]) || 0;
+                    module = cohesionRows[0].module ?? cohesionRows[0][1];
                 }
             }
             catch { /* no cluster info */ }
@@ -360,6 +364,7 @@ export class LocalBackend {
                 filePath: sym.filePath,
                 startLine: sym.startLine,
                 endLine: sym.endLine,
+                ...(module ? { module } : {}),
                 ...(includeContent && content ? { content } : {}),
             };
             if (processRows.length === 0) {
@@ -497,6 +502,10 @@ export class LocalBackend {
      */
     async semanticSearch(repo, query, limit) {
         try {
+            // Check if embedding table exists before loading the model (avoids heavy model init when embeddings are off)
+            const tableCheck = await executeQuery(repo.id, `MATCH (e:CodeEmbedding) RETURN COUNT(*) AS cnt LIMIT 1`);
+            if (!tableCheck.length || (tableCheck[0].cnt ?? tableCheck[0][0]) === 0)
+                return [];
             const queryVec = await embedQuery(query);
             const dims = getEmbeddingDims();
             const queryVecStr = `[${queryVec.join(',')}]`;
@@ -544,11 +553,15 @@ export class LocalBackend {
             }
             return results;
         }
-        catch (err) {
-            console.error('GitNexus: Semantic search unavailable -', err.message);
+        catch {
+            // Expected when embeddings are disabled — silently fall back to BM25-only
             return [];
         }
     }
+    async executeCypher(repoName, query) {
+        const repo = await this.resolveRepo(repoName);
+        return this.cypher(repo, { query });
+    }
     async cypher(repo, params) {
         await this.ensureInitialized(repo.id);
         if (!isKuzuReady(repo.id)) {
@@ -562,6 +575,34 @@ export class LocalBackend {
             return { error: err.message || 'Query failed' };
         }
     }
+    /**
+     * Format raw Cypher result rows as a markdown table for LLM readability.
+     * Falls back to raw result if rows aren't tabular objects.
+     */
+    formatCypherAsMarkdown(result) {
+        if (!Array.isArray(result) || result.length === 0)
+            return result;
+        const firstRow = result[0];
+        if (typeof firstRow !== 'object' || firstRow === null)
+            return result;
+        const keys = Object.keys(firstRow);
+        if (keys.length === 0)
+            return result;
+        const header = '| ' + keys.join(' | ') + ' |';
+        const separator = '| ' + keys.map(() => '---').join(' | ') + ' |';
+        const dataRows = result.map((row) => '| ' + keys.map(k => {
+            const v = row[k];
+            if (v === null || v === undefined)
+                return '';
+            if (typeof v === 'object')
+                return JSON.stringify(v);
+            return String(v);
+        }).join(' | ') + ' |');
+        return {
+            markdown: [header, separator, ...dataRows].join('\n'),
+            row_count: result.length,
+        };
+    }
     /**
      * Aggregate same-named clusters: group by heuristicLabel, sum symbols,
      * weighted-average cohesion, filter out tiny clusters (<5 symbols).
@@ -1151,6 +1192,64 @@ export class LocalBackend {
                 grouped[item.depth] = [];
             grouped[item.depth].push(item);
         }
+        // ── Enrichment: affected processes, modules, risk ──────────────
+        const directCount = (grouped[1] || []).length;
+        let affectedProcesses = [];
+        let affectedModules = [];
+        if (impacted.length > 0) {
+            const allIds = impacted.map(i => `'${i.id.replace(/'/g, "''")}'`).join(', ');
+            const d1Ids = (grouped[1] || []).map((i) => `'${i.id.replace(/'/g, "''")}'`).join(', ');
+            // Affected processes: which execution flows are broken and at which step
+            const [processRows, moduleRows, directModuleRows] = await Promise.all([
+                executeQuery(repo.id, `
+          MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+          WHERE s.id IN [${allIds}]
+          RETURN p.heuristicLabel AS name, COUNT(DISTINCT s.id) AS hits, MIN(r.step) AS minStep, p.stepCount AS stepCount
+          ORDER BY hits DESC
+          LIMIT 20
+        `).catch(() => []),
+                executeQuery(repo.id, `
+          MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+          WHERE s.id IN [${allIds}]
+          RETURN c.heuristicLabel AS name, COUNT(DISTINCT s.id) AS hits
+          ORDER BY hits DESC
+          LIMIT 20
+        `).catch(() => []),
+                d1Ids ? executeQuery(repo.id, `
+          MATCH (s)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+          WHERE s.id IN [${d1Ids}]
+          RETURN DISTINCT c.heuristicLabel AS name
+        `).catch(() => []) : Promise.resolve([]),
+            ]);
+            affectedProcesses = processRows.map((r) => ({
+                name: r.name || r[0],
+                hits: r.hits || r[1],
+                broken_at_step: r.minStep ?? r[2],
+                step_count: r.stepCount ?? r[3],
+            }));
+            const directModuleSet = new Set(directModuleRows.map((r) => r.name || r[0]));
+            affectedModules = moduleRows.map((r) => {
+                const name = r.name || r[0];
+                return {
+                    name,
+                    hits: r.hits || r[1],
+                    impact: directModuleSet.has(name) ? 'direct' : 'indirect',
+                };
+            });
+        }
+        // Risk scoring
+        const processCount = affectedProcesses.length;
+        const moduleCount = affectedModules.length;
+        let risk = 'LOW';
+        if (directCount >= 30 || processCount >= 5 || moduleCount >= 5 || impacted.length >= 200) {
+            risk = 'CRITICAL';
+        }
+        else if (directCount >= 15 || processCount >= 3 || moduleCount >= 3 || impacted.length >= 100) {
+            risk = 'HIGH';
+        }
+        else if (directCount >= 5 || impacted.length >= 30) {
+            risk = 'MEDIUM';
+        }
         return {
             target: {
                 id: symId,
@@ -1160,6 +1259,14 @@ export class LocalBackend {
             },
             direction,
             impactedCount: impacted.length,
+            risk,
+            summary: {
+                direct: directCount,
+                processes_affected: processCount,
+                modules_affected: moduleCount,
+            },
+            affected_processes: affectedProcesses,
+            affected_modules: affectedModules,
             byDepth: grouped,
         };
     }

package/dist/mcp/tools.js

@@ -32,7 +32,7 @@ AFTER THIS: Use context() on a specific symbol for 360-degree view (callers, cal
 
 Returns results grouped by process (execution flow):
 - processes: ranked execution flows with relevance priority
-- process_symbols: all symbols in those flows with file locations
+- process_symbols: all symbols in those flows with file locations and module (functional area)
 - definitions: standalone types/interfaces not in any process
 
 Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank Fusion.`,
@@ -74,6 +74,8 @@ EXAMPLES:
 • Trace a process:
   MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process) WHERE p.heuristicLabel = "UserLogin" RETURN s.name, r.step ORDER BY r.step
 
+OUTPUT: Returns { markdown, row_count } — results formatted as a Markdown table for easy reading.
+
 TIPS:
 - All relationships use single CodeRelation table — filter with {type: 'CALLS'} etc.
 - Community = auto-detected functional area (Leiden algorithm)
@@ -155,10 +157,17 @@ Each edit is tagged with confidence:
     {
         name: 'impact',
         description: `Analyze the blast radius of changing a code symbol.
-Returns all symbols affected by modifying the target, grouped by depth with edge types and confidence.
+Returns affected symbols grouped by depth, plus risk assessment, affected execution flows, and affected modules.
 
 WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
-AFTER THIS: Review d=1 items (WILL BREAK). READ gitnexus://repo/{name}/processes to check affected execution flows.
+AFTER THIS: Review d=1 items (WILL BREAK). Use context() on high-risk symbols.
+
+Output includes:
+- risk: LOW / MEDIUM / HIGH / CRITICAL
+- summary: direct callers, processes affected, modules affected
+- affected_processes: which execution flows break and at which step
+- affected_modules: which functional areas are hit (direct vs indirect)
+- byDepth: all affected symbols grouped by traversal depth
 
 Depth groups:
 - d=1: WILL BREAK (direct callers/importers)

package/dist/server/api.d.ts

@@ -1,6 +1,8 @@
 /**
- * HTTP API Server
+ * HTTP API Server (Multi-Repo)
  *
- * REST API for browser-based clients to query the local .gitnexus/ index.
+ * REST API for browser-based clients to query indexed repositories.
+ * Uses LocalBackend for multi-repo support via the global registry —
+ * the same backend the MCP server uses.
  */
 export declare const createServer: (port: number) => Promise<void>;

package/dist/server/api.js

@@ -1,20 +1,21 @@
 /**
- * HTTP API Server
+ * HTTP API Server (Multi-Repo)
  *
- * REST API for browser-based clients to query the local .gitnexus/ index.
+ * REST API for browser-based clients to query indexed repositories.
+ * Uses LocalBackend for multi-repo support via the global registry —
+ * the same backend the MCP server uses.
  */
 import express from 'express';
 import cors from 'cors';
 import path from 'path';
 import fs from 'fs/promises';
-import { findRepo } from '../storage/repo-manager.js';
-import { initKuzu, executeQuery } from '../core/kuzu/kuzu-adapter.js';
+import { LocalBackend } from '../mcp/local/local-backend.js';
 import { NODE_TABLES } from '../core/kuzu/schema.js';
-import { searchFTSFromKuzu } from '../core/search/bm25-index.js';
-import { hybridSearch } from '../core/search/hybrid-search.js';
-import { semanticSearch } from '../core/embeddings/embedding-pipeline.js';
-import { isEmbedderReady } from '../core/embeddings/embedder.js';
-const buildGraph = async () => {
+/**
+ * Build the full knowledge graph for a repo by querying each node table
+ * and all relationships via the backend's cypher tool.
+ */
+const buildGraph = async (backend, repoName) => {
     const nodes = [];
     for (const table of NODE_TABLES) {
         try {
@@ -34,7 +35,9 @@ const buildGraph = async () => {
             else {
                 query = `MATCH (n:${table}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine, n.content AS content`;
             }
-            const rows = await executeQuery(query);
+            const result = await backend.executeCypher(repoName, query);
+            // cypher returns the rows directly (array), or { error } on failure
+            const rows = Array.isArray(result) ? result : [];
             for (const row of rows) {
                 nodes.push({
                     id: row.id ?? row[0],
@@ -62,95 +65,262 @@ const buildGraph = async () => {
         }
     }
     const relationships = [];
-    const relRows = await executeQuery(`MATCH (a)-[r:CodeRelation]->(b) RETURN a.id AS sourceId, b.id AS targetId, r.type AS type, r.confidence AS confidence, r.reason AS reason, r.step AS step`);
-    for (const row of relRows) {
-        relationships.push({
-            id: `${row.sourceId}_${row.type}_${row.targetId}`,
-            type: row.type,
-            sourceId: row.sourceId,
-            targetId: row.targetId,
-            confidence: row.confidence,
-            reason: row.reason,
-            step: row.step,
-        });
+    try {
+        const relResult = await backend.executeCypher(repoName, `MATCH (a)-[r:CodeRelation]->(b) RETURN a.id AS sourceId, b.id AS targetId, r.type AS type, r.confidence AS confidence, r.reason AS reason, r.step AS step`);
+        const relRows = Array.isArray(relResult) ? relResult : [];
+        for (const row of relRows) {
+            relationships.push({
+                id: `${row.sourceId}_${row.type}_${row.targetId}`,
+                type: row.type,
+                sourceId: row.sourceId,
+                targetId: row.targetId,
+                confidence: row.confidence,
+                reason: row.reason,
+                step: row.step,
+            });
+        }
+    }
+    catch (err) {
+        console.warn('GitNexus: relationship query failed:', err?.message);
     }
     return { nodes, relationships };
 };
+const httpStatus = (err) => {
+    const msg = err?.message ?? '';
+    if (msg.includes('not found') || msg.includes('No indexed'))
+        return 404;
+    if (msg.includes('Multiple repositories'))
+        return 400;
+    return 500;
+};
 export const createServer = async (port) => {
+    const backend = new LocalBackend();
+    const hasRepos = await backend.init();
+    if (!hasRepos) {
+        console.warn('GitNexus: No indexed repositories found. The server will start but most endpoints will return errors.');
+        console.warn('Run "gitnexus analyze" in a repository to index it first.');
+    }
     const app = express();
-    app.use(cors());
+    app.use(cors({
+        origin: (origin, callback) => {
+            // Allow requests with no origin (curl, server-to-server), localhost, and the deployed site.
+            // The server binds to 127.0.0.1 so only the local machine can reach it — CORS just gates
+            // which browser-tab origins may issue the request.
+            if (!origin
+                || origin.startsWith('http://localhost:')
+                || origin.startsWith('http://127.0.0.1:')
+                || origin === 'https://gitnexus.vercel.app') {
+                callback(null, true);
+            }
+            else {
+                callback(new Error('Not allowed by CORS'));
+            }
+        }
+    }));
     app.use(express.json({ limit: '10mb' }));
-    // Get repo info
-    app.get('/api/repo', async (_req, res) => {
-        const repo = await findRepo(process.cwd());
-        if (!repo) {
-            res.status(404).json({ error: 'Repository not indexed. Run: gitnexus analyze' });
-            return;
-        }
-        res.json({
-            repoPath: repo.repoPath,
-            indexedAt: repo.meta.indexedAt,
-            stats: repo.meta.stats || {},
-        });
+    // ─── GET /api/repos ─────────────────────────────────────────────
+    // List all indexed repositories
+    app.get('/api/repos', async (_req, res) => {
+        try {
+            const repos = await backend.listRepos();
+            res.json(repos);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message || 'Failed to list repos' });
+        }
+    });
+    // ─── GET /api/repo?repo=X ──────────────────────────────────────
+    // Get metadata for a specific repo
+    app.get('/api/repo', async (req, res) => {
+        try {
+            const repoName = req.query.repo;
+            const repo = await backend.resolveRepo(repoName);
+            res.json({
+                name: repo.name,
+                path: repo.repoPath,
+                indexedAt: repo.indexedAt,
+                lastCommit: repo.lastCommit,
+                stats: repo.stats || {},
+            });
+        }
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Repository not found' });
+        }
     });
-    // Get full graph
-    app.get('/api/graph', async (_req, res) => {
-        const repo = await findRepo(process.cwd());
-        if (!repo) {
-            res.status(404).json({ error: 'Repository not indexed' });
-            return;
-        }
-        await initKuzu(repo.kuzuPath);
-        const graph = await buildGraph();
-        res.json(graph);
+    // ─── GET /api/graph?repo=X ─────────────────────────────────────
+    // Full knowledge graph (all nodes + relationships)
+    app.get('/api/graph', async (req, res) => {
+        try {
+            const repoName = req.query.repo;
+            // Resolve repo to validate it exists and get the name
+            const repo = await backend.resolveRepo(repoName);
+            const graph = await buildGraph(backend, repo.name);
+            res.json(graph);
+        }
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Failed to build graph' });
+        }
     });
-    // Execute Cypher query
+    // ─── POST /api/query ───────────────────────────────────────────
+    // Execute a raw Cypher query.
+    // This endpoint is intentionally unrestricted (no query validation) because
+    // the server binds to 127.0.0.1 only — it exposes full graph query
+    // capabilities to local clients by design.
     app.post('/api/query', async (req, res) => {
-        const repo = await findRepo(process.cwd());
-        if (!repo) {
-            res.status(404).json({ error: 'Repository not indexed' });
-            return;
-        }
-        await initKuzu(repo.kuzuPath);
-        const result = await executeQuery(req.body.cypher);
-        res.json({ result });
+        try {
+            const repoName = (req.body.repo ?? req.query.repo);
+            const cypher = req.body.cypher;
+            if (!cypher) {
+                res.status(400).json({ error: 'Missing "cypher" in request body' });
+                return;
+            }
+            const result = await backend.executeCypher(repoName, cypher);
+            if (result && !Array.isArray(result) && result.error) {
+                res.status(500).json({ error: result.error });
+                return;
+            }
+            res.json({ result });
+        }
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Query failed' });
+        }
     });
-    // Search
+    // ─── POST /api/search ──────────────────────────────────────────
+    // Process-grouped semantic search
     app.post('/api/search', async (req, res) => {
-        const repo = await findRepo(process.cwd());
-        if (!repo) {
-            res.status(404).json({ error: 'Repository not indexed' });
-            return;
-        }
-        await initKuzu(repo.kuzuPath);
-        const query = req.body.query ?? '';
-        const limit = req.body.limit ?? 10;
-        if (isEmbedderReady()) {
-            const results = await hybridSearch(query, limit, executeQuery, semanticSearch);
+        try {
+            const repoName = (req.body.repo ?? req.query.repo);
+            const query = (req.body.query ?? '').trim();
+            const limit = req.body.limit;
+            if (!query) {
+                res.status(400).json({ error: 'Missing "query" in request body' });
+                return;
+            }
+            const results = await backend.callTool('query', {
+                repo: repoName,
+                query,
+                limit,
+            });
             res.json({ results });
-            return;
         }
-        // FTS-only fallback when embeddings aren't loaded
-        const results = await searchFTSFromKuzu(query, limit);
-        res.json({ results });
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Search failed' });
+        }
     });
-    // Read file
+    // ─── GET /api/file?repo=X&path=Y ──────────────────────────────
+    // Read a file from a resolved repo path on disk
     app.get('/api/file', async (req, res) => {
-        const repo = await findRepo(process.cwd());
-        if (!repo) {
-            res.status(404).json({ error: 'Repository not indexed' });
-            return;
-        }
-        const filePath = req.query.path;
-        if (!filePath) {
-            res.status(400).json({ error: 'Missing path' });
-            return;
-        }
-        const fullPath = path.join(repo.repoPath, filePath);
-        const content = await fs.readFile(fullPath, 'utf-8');
-        res.json({ content });
+        try {
+            const repoName = req.query.repo;
+            const filePath = req.query.path;
+            if (!filePath) {
+                res.status(400).json({ error: 'Missing "path" query parameter' });
+                return;
+            }
+            const repo = await backend.resolveRepo(repoName);
+            // Resolve the full path and validate it stays within the repo root
+            const repoRoot = path.resolve(repo.repoPath);
+            const fullPath = path.resolve(repoRoot, filePath);
+            if (!fullPath.startsWith(repoRoot + path.sep) && fullPath !== repoRoot) {
+                res.status(403).json({ error: 'Path traversal denied: path escapes repo root' });
+                return;
+            }
+            const content = await fs.readFile(fullPath, 'utf-8');
+            res.json({ content });
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                res.status(404).json({ error: 'File not found' });
+            }
+            else {
+                res.status(httpStatus(err))
+                    .json({ error: err.message || 'Failed to read file' });
+            }
+        }
+    });
+    // ─── GET /api/processes?repo=X ─────────────────────────────────
+    // List all processes for a repo
+    app.get('/api/processes', async (req, res) => {
+        try {
+            const repoName = req.query.repo;
+            const result = await backend.queryProcesses(repoName);
+            res.json(result);
+        }
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Failed to query processes' });
+        }
+    });
+    // ─── GET /api/process?repo=X&name=Y ───────────────────────────
+    // Get detailed process info including steps
+    app.get('/api/process', async (req, res) => {
+        try {
+            const repoName = req.query.repo;
+            const name = req.query.name;
+            if (!name) {
+                res.status(400).json({ error: 'Missing "name" query parameter' });
+                return;
+            }
+            const result = await backend.queryProcessDetail(name, repoName);
+            if (result.error) {
+                res.status(404).json({ error: result.error });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Failed to query process detail' });
+        }
+    });
+    // ─── GET /api/clusters?repo=X ─────────────────────────────────
+    // List all clusters for a repo
+    app.get('/api/clusters', async (req, res) => {
+        try {
+            const repoName = req.query.repo;
+            const result = await backend.queryClusters(repoName);
+            res.json(result);
+        }
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Failed to query clusters' });
+        }
+    });
+    // ─── GET /api/cluster?repo=X&name=Y ───────────────────────────
+    // Get detailed cluster info including members
+    app.get('/api/cluster', async (req, res) => {
+        try {
+            const repoName = req.query.repo;
+            const name = req.query.name;
+            if (!name) {
+                res.status(400).json({ error: 'Missing "name" query parameter' });
+                return;
+            }
+            const result = await backend.queryClusterDetail(name, repoName);
+            if (result.error) {
+                res.status(404).json({ error: result.error });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res.status(httpStatus(err))
+                .json({ error: err.message || 'Failed to query cluster detail' });
+        }
     });
-    app.listen(port, () => {
+    const server = app.listen(port, '127.0.0.1', () => {
         console.log(`GitNexus server running on http://localhost:${port}`);
+        console.log(`Serving ${hasRepos ? 'all indexed repositories' : 'no repositories (run gitnexus analyze first)'}`);
     });
+    const shutdown = async () => {
+        server.close();
+        await backend.disconnect();
+        process.exit(0);
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "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",