gitnexus 1.2.8 → 1.3.0

package/dist/cli/analyze.js

@@ -4,6 +4,8 @@
  * Indexes a repository and stores the knowledge graph in .gitnexus/
  */
 import path from 'path';
+import { execFileSync } from 'child_process';
+import v8 from 'v8';
 import cliProgress from 'cli-progress';
 import { runPipelineFromRepo } from '../core/ingestion/pipeline.js';
 import { initKuzu, loadGraphToKuzu, getKuzuStats, executeQuery, executeWithReusedStatement, closeKuzu, createFTSIndex, loadCachedEmbeddings } from '../core/kuzu/kuzu-adapter.js';
@@ -14,6 +16,27 @@ import { getCurrentCommit, isGitRepo, getGitRoot } from '../storage/git.js';
 import { generateAIContextFiles } from './ai-context.js';
 import fs from 'fs/promises';
 import { registerClaudeHook } from './claude-hooks.js';
+const HEAP_MB = 8192;
+const HEAP_FLAG = `--max-old-space-size=${HEAP_MB}`;
+/** Re-exec the process with an 8GB heap if we're currently below that. */
+function ensureHeap() {
+    const nodeOpts = process.env.NODE_OPTIONS || '';
+    if (nodeOpts.includes('--max-old-space-size'))
+        return false;
+    const v8Heap = v8.getHeapStatistics().heap_size_limit;
+    if (v8Heap >= HEAP_MB * 1024 * 1024 * 0.9)
+        return false;
+    try {
+        execFileSync(process.execPath, [HEAP_FLAG, ...process.argv.slice(1)], {
+            stdio: 'inherit',
+            env: { ...process.env, NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG}`.trim() },
+        });
+    }
+    catch (e) {
+        process.exitCode = e.status ?? 1;
+    }
+    return true;
+}
 /** Threshold: auto-skip embeddings for repos with more nodes than this */
 const EMBEDDING_NODE_LIMIT = 50_000;
 const PHASE_LABELS = {
@@ -32,6 +55,8 @@ const PHASE_LABELS = {
     done: 'Done',
 };
 export const analyzeCommand = async (inputPath, options) => {
+    if (ensureHeap())
+        return;
     console.log('\n  GitNexus Analyzer\n');
     let repoPath;
     if (inputPath) {
@@ -70,18 +95,47 @@ export const analyzeCommand = async (inputPath, options) => {
         stopOnComplete: false,
     }, cliProgress.Presets.shades_grey);
     bar.start(100, 0, { phase: 'Initializing...' });
+    // Graceful SIGINT handling — clean up resources and exit
+    let aborted = false;
+    const sigintHandler = () => {
+        if (aborted)
+            process.exit(1); // Second Ctrl-C: force exit
+        aborted = true;
+        bar.stop();
+        console.log('\n  Interrupted — cleaning up...');
+        closeKuzu().catch(() => { }).finally(() => process.exit(130));
+    };
+    process.on('SIGINT', sigintHandler);
     // Route all console output through bar.log() so the bar doesn't stamp itself
     // multiple times when other code writes to stdout/stderr mid-render.
     const origLog = console.log.bind(console);
     const origWarn = console.warn.bind(console);
     const origError = console.error.bind(console);
-    const barLog = (...args) => bar.log(args.map(a => (typeof a === 'string' ? a : String(a))).join(' '));
+    const barLog = (...args) => {
+        // Clear the bar line, print the message, then let the next bar.update redraw
+        process.stdout.write('\x1b[2K\r');
+        origLog(args.map(a => (typeof a === 'string' ? a : String(a))).join(' '));
+    };
     console.log = barLog;
     console.warn = barLog;
     console.error = barLog;
-    // Show elapsed seconds for phases that run longer than 3s
+    // Track elapsed time per phase — both updateBar and the interval use the
+    // same format so they don't flicker against each other.
     let lastPhaseLabel = 'Initializing...';
     let phaseStart = Date.now();
+    /** Update bar with phase label + elapsed seconds (shown after 3s). */
+    const updateBar = (value, phaseLabel) => {
+        if (phaseLabel !== lastPhaseLabel) {
+            lastPhaseLabel = phaseLabel;
+            phaseStart = Date.now();
+        }
+        const elapsed = Math.round((Date.now() - phaseStart) / 1000);
+        const display = elapsed >= 3 ? `${phaseLabel} (${elapsed}s)` : phaseLabel;
+        bar.update(value, { phase: display });
+    };
+    // Tick elapsed seconds for phases with infrequent progress callbacks
+    // (e.g. CSV streaming, FTS indexing). Uses the same display format as
+    // updateBar so there's no flickering.
     const elapsedTimer = setInterval(() => {
         const elapsed = Math.round((Date.now() - phaseStart) / 1000);
         if (elapsed >= 3) {
@@ -94,7 +148,7 @@ export const analyzeCommand = async (inputPath, options) => {
     let cachedEmbeddings = [];
     if (options?.embeddings && existingMeta && !options?.force) {
         try {
-            bar.update(0, { phase: 'Caching embeddings...' });
+            updateBar(0, 'Caching embeddings...');
             await initKuzu(kuzuPath);
             const cached = await loadCachedEmbeddings();
             cachedEmbeddingNodeIds = cached.embeddingNodeIds;
@@ -112,16 +166,10 @@ export const analyzeCommand = async (inputPath, options) => {
     const pipelineResult = await runPipelineFromRepo(repoPath, (progress) => {
         const phaseLabel = PHASE_LABELS[progress.phase] || progress.phase;
         const scaled = Math.round(progress.percent * 0.6);
-        if (phaseLabel !== lastPhaseLabel) {
-            lastPhaseLabel = phaseLabel;
-            phaseStart = Date.now();
-        }
-        bar.update(scaled, { phase: phaseLabel });
+        updateBar(scaled, phaseLabel);
     });
     // ── Phase 2: KuzuDB (60–85%) ──────────────────────────────────────
-    lastPhaseLabel = 'Loading into KuzuDB...';
-    phaseStart = Date.now();
-    bar.update(60, { phase: lastPhaseLabel });
+    updateBar(60, 'Loading into KuzuDB...');
     await closeKuzu();
     const kuzuFiles = [kuzuPath, `${kuzuPath}.wal`, `${kuzuPath}.lock`];
     for (const f of kuzuFiles) {
@@ -133,17 +181,15 @@ export const analyzeCommand = async (inputPath, options) => {
     const t0Kuzu = Date.now();
     await initKuzu(kuzuPath);
     let kuzuMsgCount = 0;
-    const kuzuResult = await loadGraphToKuzu(pipelineResult.graph, pipelineResult.fileContents, storagePath, (msg) => {
+    const kuzuResult = await loadGraphToKuzu(pipelineResult.graph, pipelineResult.repoPath, storagePath, (msg) => {
         kuzuMsgCount++;
         const progress = Math.min(84, 60 + Math.round((kuzuMsgCount / (kuzuMsgCount + 10)) * 24));
-        bar.update(progress, { phase: msg });
+        updateBar(progress, msg);
     });
     const kuzuTime = ((Date.now() - t0Kuzu) / 1000).toFixed(1);
     const kuzuWarnings = kuzuResult.warnings;
     // ── Phase 3: FTS (85–90%) ─────────────────────────────────────────
-    lastPhaseLabel = 'Creating search indexes...';
-    phaseStart = Date.now();
-    bar.update(85, { phase: lastPhaseLabel });
+    updateBar(85, 'Creating search indexes...');
     const t0Fts = Date.now();
     try {
         await createFTSIndex('File', 'file_fts', ['name', 'content']);
@@ -158,7 +204,7 @@ export const analyzeCommand = async (inputPath, options) => {
     const ftsTime = ((Date.now() - t0Fts) / 1000).toFixed(1);
     // ── Phase 3.5: Re-insert cached embeddings ────────────────────────
     if (cachedEmbeddings.length > 0) {
-        bar.update(88, { phase: `Restoring ${cachedEmbeddings.length} cached embeddings...` });
+        updateBar(88, `Restoring ${cachedEmbeddings.length} cached embeddings...`);
         const EMBED_BATCH = 200;
         for (let i = 0; i < cachedEmbeddings.length; i += EMBED_BATCH) {
             const batch = cachedEmbeddings.slice(i, i + EMBED_BATCH);
@@ -183,29 +229,23 @@ export const analyzeCommand = async (inputPath, options) => {
         }
     }
     if (!embeddingSkipped) {
-        lastPhaseLabel = 'Loading embedding model...';
-        phaseStart = Date.now();
-        bar.update(90, { phase: lastPhaseLabel });
+        updateBar(90, 'Loading embedding model...');
         const t0Emb = Date.now();
         await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (progress) => {
             const scaled = 90 + Math.round((progress.percent / 100) * 8);
             const label = progress.phase === 'loading-model' ? 'Loading embedding model...' : `Embedding ${progress.nodesProcessed || 0}/${progress.totalNodes || '?'}`;
-            if (label !== lastPhaseLabel) {
-                lastPhaseLabel = label;
-                phaseStart = Date.now();
-            }
-            bar.update(scaled, { phase: label });
+            updateBar(scaled, label);
         }, {}, cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined);
         embeddingTime = ((Date.now() - t0Emb) / 1000).toFixed(1);
     }
     // ── Phase 5: Finalize (98–100%) ───────────────────────────────────
-    bar.update(98, { phase: 'Saving metadata...' });
+    updateBar(98, 'Saving metadata...');
     const meta = {
         repoPath,
         lastCommit: currentCommit,
         indexedAt: new Date().toISOString(),
         stats: {
-            files: pipelineResult.fileContents.size,
+            files: pipelineResult.totalFileCount,
             nodes: stats.nodes,
             edges: stats.edges,
             communities: pipelineResult.communityResult?.stats.totalCommunities,
@@ -227,7 +267,7 @@ export const analyzeCommand = async (inputPath, options) => {
         aggregatedClusterCount = Array.from(groups.values()).filter(count => count >= 5).length;
     }
     const aiContext = await generateAIContextFiles(repoPath, storagePath, projectName, {
-        files: pipelineResult.fileContents.size,
+        files: pipelineResult.totalFileCount,
         nodes: stats.nodes,
         edges: stats.edges,
         communities: pipelineResult.communityResult?.stats.totalCommunities,
@@ -240,6 +280,7 @@ export const analyzeCommand = async (inputPath, options) => {
     // Since the process exits immediately after, Node.js reclaims everything.
     const totalTime = ((Date.now() - t0Global) / 1000).toFixed(1);
     clearInterval(elapsedTimer);
+    process.removeListener('SIGINT', sigintHandler);
     console.log = origLog;
     console.warn = origWarn;
     console.error = origError;

package/dist/cli/index.js

@@ -1,4 +1,24 @@
 #!/usr/bin/env node
+// Raise Node heap limit for large repos (e.g. Linux kernel).
+// Must run before any heavy allocation. If already set by the user, respect it.
+if (!process.env.NODE_OPTIONS?.includes('--max-old-space-size')) {
+    const execArgv = process.execArgv.join(' ');
+    if (!execArgv.includes('--max-old-space-size')) {
+        // Re-spawn with a larger heap (8 GB)
+        const { execFileSync } = await import('node:child_process');
+        try {
+            execFileSync(process.execPath, ['--max-old-space-size=8192', ...process.argv.slice(1)], {
+                stdio: 'inherit',
+                env: { ...process.env, NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --max-old-space-size=8192`.trim() },
+            });
+            process.exit(0);
+        }
+        catch (e) {
+            // If the child exited with an error code, propagate it
+            process.exit(e.status ?? 1);
+        }
+    }
+}
 import { Command } from 'commander';
 import { analyzeCommand } from './analyze.js';
 import { serveCommand } from './serve.js';

package/dist/cli/setup.js

@@ -13,9 +13,16 @@ import { getGlobalDir } from '../storage/repo-manager.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 /**
- * The MCP server entry for all editors
+ * The MCP server entry for all editors.
+ * On Windows, npx must be invoked via cmd /c since it's a .cmd script.
  */
 function getMcpEntry() {
+    if (process.platform === 'win32') {
+        return {
+            command: 'cmd',
+            args: ['/c', 'npx', '-y', 'gitnexus@latest', 'mcp'],
+        };
+    }
     return {
         command: 'npx',
         args: ['-y', 'gitnexus@latest', 'mcp'],

package/dist/cli/view.d.ts

@@ -0,0 +1,13 @@
+/**
+ * View Command
+ *
+ * Generates a self-contained graph.html from the KuzuDB index and
+ * opens it in the default browser.
+ *
+ * Usage: gitnexus view [path] [--no-open]
+ */
+export interface ViewCommandOptions {
+    noOpen?: boolean;
+    output?: string;
+}
+export declare const viewCommand: (inputPath?: string, options?: ViewCommandOptions) => Promise<void>;

package/dist/cli/view.js

@@ -0,0 +1,59 @@
+/**
+ * View Command
+ *
+ * Generates a self-contained graph.html from the KuzuDB index and
+ * opens it in the default browser.
+ *
+ * Usage: gitnexus view [path] [--no-open]
+ */
+import path from 'path';
+import fs from 'fs/promises';
+import { exec } from 'child_process';
+import { findRepo } from '../storage/repo-manager.js';
+import { initKuzu } from '../core/kuzu/kuzu-adapter.js';
+import { buildGraph } from '../server/api.js';
+import { generateHTMLGraphViewer } from '../core/graph/html-graph-viewer.js';
+import { getCurrentCommit } from '../storage/git.js';
+function openInBrowser(filePath) {
+    const url = `file://${filePath}`;
+    let cmd;
+    if (process.platform === 'darwin') {
+        cmd = `open "${url}"`;
+    }
+    else if (process.platform === 'win32') {
+        cmd = `start "" "${url}"`;
+    }
+    else {
+        cmd = `xdg-open "${url}"`;
+    }
+    exec(cmd, (err) => {
+        if (err)
+            console.error('Failed to open browser:', err.message);
+    });
+}
+export const viewCommand = async (inputPath, options) => {
+    console.log('⚠ Experimental: gitnexus view is under active development.\n');
+    const repoPath = inputPath ? path.resolve(inputPath) : process.cwd();
+    const repo = await findRepo(repoPath);
+    if (!repo) {
+        console.error('No index found. Run: gitnexus analyze');
+        process.exit(1);
+    }
+    const currentCommit = getCurrentCommit(repo.repoPath);
+    if (currentCommit !== repo.meta.lastCommit) {
+        console.warn('Index is stale — showing last indexed state. Run: gitnexus analyze\n');
+    }
+    await initKuzu(repo.kuzuPath);
+    const { nodes, relationships } = await buildGraph();
+    const projectName = path.basename(repo.repoPath);
+    const outputPath = options?.output
+        ? path.resolve(options.output)
+        : path.join(repo.storagePath, 'graph.html');
+    const html = generateHTMLGraphViewer(nodes, relationships, projectName);
+    await fs.writeFile(outputPath, html, 'utf-8');
+    console.log(`Graph written to: ${outputPath}`);
+    console.log(`Nodes: ${nodes.length}  Edges: ${relationships.length}`);
+    if (!options?.noOpen) {
+        openInBrowser(outputPath);
+    }
+};

package/dist/core/augmentation/engine.js

@@ -98,11 +98,11 @@ export async function augment(pattern, cwd) {
         for (const result of bm25Results.slice(0, 5)) {
             const escaped = result.filePath.replace(/'/g, "''");
             try {
-                const symbols = await executeQuery(repoId, `
-          MATCH (n) WHERE n.filePath = '${escaped}'
-          AND n.name CONTAINS '${pattern.replace(/'/g, "''").split(/\s+/)[0]}'
-          RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
-          LIMIT 3
+                const symbols = await executeQuery(repoId, `
+          MATCH (n) WHERE n.filePath = '${escaped}'
+          AND n.name CONTAINS '${pattern.replace(/'/g, "''").split(/\s+/)[0]}'
+          RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
+          LIMIT 3
         `);
                 for (const sym of symbols) {
                     symbolMatches.push({
@@ -130,10 +130,10 @@ export async function augment(pattern, cwd) {
             // Callers
             let callers = [];
             try {
-                const rows = await executeQuery(repoId, `
-          MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(n {id: '${escaped}'})
-          RETURN caller.name AS name
-          LIMIT 3
+                const rows = await executeQuery(repoId, `
+          MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(n {id: '${escaped}'})
+          RETURN caller.name AS name
+          LIMIT 3
         `);
                 callers = rows.map((r) => r.name || r[0]).filter(Boolean);
             }
@@ -141,10 +141,10 @@ export async function augment(pattern, cwd) {
             // Callees
             let callees = [];
             try {
-                const rows = await executeQuery(repoId, `
-          MATCH (n {id: '${escaped}'})-[:CodeRelation {type: 'CALLS'}]->(callee)
-          RETURN callee.name AS name
-          LIMIT 3
+                const rows = await executeQuery(repoId, `
+          MATCH (n {id: '${escaped}'})-[:CodeRelation {type: 'CALLS'}]->(callee)
+          RETURN callee.name AS name
+          LIMIT 3
         `);
                 callees = rows.map((r) => r.name || r[0]).filter(Boolean);
             }
@@ -152,9 +152,9 @@ export async function augment(pattern, cwd) {
             // Processes
             let processes = [];
             try {
-                const rows = await executeQuery(repoId, `
-          MATCH (n {id: '${escaped}'})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
-          RETURN p.heuristicLabel AS label, r.step AS step, p.stepCount AS stepCount
+                const rows = await executeQuery(repoId, `
+          MATCH (n {id: '${escaped}'})-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+          RETURN p.heuristicLabel AS label, r.step AS step, p.stepCount AS stepCount
         `);
                 processes = rows.map((r) => {
                     const label = r.label || r[0];
@@ -167,10 +167,10 @@ export async function augment(pattern, cwd) {
             // Cluster cohesion (internal ranking signal)
             let cohesion = 0;
             try {
-                const rows = await executeQuery(repoId, `
-          MATCH (n {id: '${escaped}'})-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
-          RETURN c.cohesion AS cohesion
-          LIMIT 1
+                const rows = await executeQuery(repoId, `
+          MATCH (n {id: '${escaped}'})-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+          RETURN c.cohesion AS cohesion
+          LIMIT 1
         `);
                 if (rows.length > 0) {
                     cohesion = (rows[0].cohesion ?? rows[0][0]) || 0;

package/dist/core/embeddings/embedding-pipeline.js

@@ -24,19 +24,19 @@ const queryEmbeddableNodes = async (executeQuery) => {
             let query;
             if (label === 'File') {
                 // File nodes don't have startLine/endLine
-                query = `
-          MATCH (n:File)
-          RETURN n.id AS id, n.name AS name, 'File' AS label, 
-                 n.filePath AS filePath, n.content AS content
+                query = `
+          MATCH (n:File)
+          RETURN n.id AS id, n.name AS name, 'File' AS label, 
+                 n.filePath AS filePath, n.content AS content
         `;
             }
             else {
                 // Code elements have startLine/endLine
-                query = `
-          MATCH (n:${label})
-          RETURN n.id AS id, n.name AS name, '${label}' AS label, 
-                 n.filePath AS filePath, n.content AS content,
-                 n.startLine AS startLine, n.endLine AS endLine
+                query = `
+          MATCH (n:${label})
+          RETURN n.id AS id, n.name AS name, '${label}' AS label, 
+                 n.filePath AS filePath, n.content AS content,
+                 n.startLine AS startLine, n.endLine AS endLine
         `;
             }
             const rows = await executeQuery(query);
@@ -77,8 +77,8 @@ const batchInsertEmbeddings = async (executeWithReusedStatement, updates) => {
  * Now indexes the separate CodeEmbedding table
  */
 const createVectorIndex = async (executeQuery) => {
-    const cypher = `
-    CALL CREATE_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', 'embedding', metric := 'cosine')
+    const cypher = `
+    CALL CREATE_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', 'embedding', metric := 'cosine')
   `;
     try {
         await executeQuery(cypher);
@@ -240,14 +240,14 @@ export const semanticSearch = async (executeQuery, query, k = 10, maxDistance =
     const queryVec = embeddingToArray(queryEmbedding);
     const queryVecStr = `[${queryVec.join(',')}]`;
     // Query the vector index on CodeEmbedding to get nodeIds and distances
-    const vectorQuery = `
-    CALL QUERY_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', 
-      CAST(${queryVecStr} AS FLOAT[384]), ${k})
-    YIELD node AS emb, distance
-    WITH emb, distance
-    WHERE distance < ${maxDistance}
-    RETURN emb.nodeId AS nodeId, distance
-    ORDER BY distance
+    const vectorQuery = `
+    CALL QUERY_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', 
+      CAST(${queryVecStr} AS FLOAT[384]), ${k})
+    YIELD node AS emb, distance
+    WITH emb, distance
+    WHERE distance < ${maxDistance}
+    RETURN emb.nodeId AS nodeId, distance
+    ORDER BY distance
   `;
     const embResults = await executeQuery(vectorQuery);
     if (embResults.length === 0) {
@@ -266,16 +266,16 @@ export const semanticSearch = async (executeQuery, query, k = 10, maxDistance =
         try {
             let nodeQuery;
             if (label === 'File') {
-                nodeQuery = `
-          MATCH (n:File {id: '${nodeId.replace(/'/g, "''")}'}) 
-          RETURN n.name AS name, n.filePath AS filePath
+                nodeQuery = `
+          MATCH (n:File {id: '${nodeId.replace(/'/g, "''")}'}) 
+          RETURN n.name AS name, n.filePath AS filePath
         `;
             }
             else {
-                nodeQuery = `
-          MATCH (n:${label} {id: '${nodeId.replace(/'/g, "''")}'}) 
-          RETURN n.name AS name, n.filePath AS filePath, 
-                 n.startLine AS startLine, n.endLine AS endLine
+                nodeQuery = `
+          MATCH (n:${label} {id: '${nodeId.replace(/'/g, "''")}'}) 
+          RETURN n.name AS name, n.filePath AS filePath, 
+                 n.startLine AS startLine, n.endLine AS endLine
         `;
             }
             const nodeRows = await executeQuery(nodeQuery);

package/dist/core/graph/graph.js

@@ -46,6 +46,11 @@ export const createKnowledgeGraph = () => {
         get relationships() {
             return Array.from(relationshipMap.values());
         },
+        iterNodes: () => nodeMap.values(),
+        iterRelationships: () => relationshipMap.values(),
+        forEachNode(fn) { nodeMap.forEach(fn); },
+        forEachRelationship(fn) { relationshipMap.forEach(fn); },
+        getNode: (id) => nodeMap.get(id),
         // O(1) count getters - avoid creating arrays just for length
         get nodeCount() {
             return nodeMap.size;

package/dist/core/graph/html-graph-viewer.d.ts

@@ -0,0 +1,15 @@
+/**
+ * HTML Graph Viewer Generator
+ *
+ * Produces a self-contained graph.html that renders the knowledge graph
+ * using Sigma.js v2 + graphology (both from CDN).
+ *
+ * Critical: node `content` fields are stripped before embedding to prevent
+ * </script> injection from source code breaking the HTML parser.
+ */
+import { GraphNode, GraphRelationship } from './types.js';
+/**
+ * Generate a self-contained HTML file that renders the knowledge graph.
+ * Strips large/unsafe fields from nodes before embedding.
+ */
+export declare function generateHTMLGraphViewer(nodes: GraphNode[], relationships: GraphRelationship[], projectName: string): string;