gitnexus 1.0.0

package/dist/server/api.js

@@ -0,0 +1,156 @@
+/**
+ * HTTP API Server
+ *
+ * REST API for browser-based clients to query the local .gitnexus/ index.
+ */
+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 { 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 () => {
+    const nodes = [];
+    for (const table of NODE_TABLES) {
+        try {
+            let query = '';
+            if (table === 'File') {
+                query = `MATCH (n:File) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.content AS content`;
+            }
+            else if (table === 'Folder') {
+                query = `MATCH (n:Folder) RETURN n.id AS id, n.name AS name, n.filePath AS filePath`;
+            }
+            else if (table === 'Community') {
+                query = `MATCH (n:Community) RETURN n.id AS id, n.label AS label, n.heuristicLabel AS heuristicLabel, n.cohesion AS cohesion, n.symbolCount AS symbolCount`;
+            }
+            else if (table === 'Process') {
+                query = `MATCH (n:Process) RETURN n.id AS id, n.label AS label, n.heuristicLabel AS heuristicLabel, n.processType AS processType, n.stepCount AS stepCount, n.communities AS communities, n.entryPointId AS entryPointId, n.terminalId AS terminalId`;
+            }
+            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);
+            for (const row of rows) {
+                nodes.push({
+                    id: row.id ?? row[0],
+                    label: table,
+                    properties: {
+                        name: row.name ?? row.label ?? row[1],
+                        filePath: row.filePath ?? row[2],
+                        startLine: row.startLine,
+                        endLine: row.endLine,
+                        content: row.content,
+                        heuristicLabel: row.heuristicLabel,
+                        cohesion: row.cohesion,
+                        symbolCount: row.symbolCount,
+                        processType: row.processType,
+                        stepCount: row.stepCount,
+                        communities: row.communities,
+                        entryPointId: row.entryPointId,
+                        terminalId: row.terminalId,
+                    },
+                });
+            }
+        }
+        catch {
+            // ignore empty tables
+        }
+    }
+    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,
+        });
+    }
+    return { nodes, relationships };
+};
+export const createServer = async (port) => {
+    const app = express();
+    app.use(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 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);
+    });
+    // Execute Cypher query
+    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 });
+    });
+    // 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);
+            res.json({ results });
+            return;
+        }
+        // FTS-only fallback when embeddings aren't loaded
+        const results = await searchFTSFromKuzu(query, limit);
+        res.json({ results });
+    });
+    // Read file
+    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 });
+    });
+    app.listen(port, () => {
+        console.log(`GitNexus server running on http://localhost:${port}`);
+    });
+};

package/dist/storage/git.d.ts

@@ -0,0 +1,7 @@
+export declare const isGitRepo: (repoPath: string) => boolean;
+export declare const getCurrentCommit: (repoPath: string) => string;
+export declare const getStatusPorcelain: (repoPath: string) => string;
+/**
+ * Find the git repository root from any path inside the repo
+ */
+export declare const getGitRoot: (fromPath: string) => string | null;

package/dist/storage/git.js

@@ -0,0 +1,39 @@
+import { execSync } from 'child_process';
+export const isGitRepo = (repoPath) => {
+    try {
+        execSync('git rev-parse --is-inside-work-tree', { cwd: repoPath, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const getCurrentCommit = (repoPath) => {
+    try {
+        return execSync('git rev-parse HEAD', { cwd: repoPath }).toString().trim();
+    }
+    catch {
+        return '';
+    }
+};
+export const getStatusPorcelain = (repoPath) => {
+    try {
+        return execSync('git status --porcelain', { cwd: repoPath }).toString();
+    }
+    catch {
+        return '';
+    }
+};
+/**
+ * Find the git repository root from any path inside the repo
+ */
+export const getGitRoot = (fromPath) => {
+    try {
+        return execSync('git rev-parse --show-toplevel', { cwd: fromPath })
+            .toString()
+            .trim();
+    }
+    catch {
+        return null;
+    }
+};

package/dist/storage/repo-manager.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Repository Manager
+ *
+ * Manages GitNexus index storage in .gitnexus/ at repo root.
+ */
+export interface RepoMeta {
+    repoPath: string;
+    lastCommit: string;
+    indexedAt: string;
+    stats?: {
+        files?: number;
+        nodes?: number;
+        edges?: number;
+        communities?: number;
+        processes?: number;
+        embeddings?: number;
+    };
+}
+export interface IndexedRepo {
+    repoPath: string;
+    storagePath: string;
+    kuzuPath: string;
+    metaPath: string;
+    meta: RepoMeta;
+}
+/**
+ * Get the .gitnexus storage path for a repository
+ */
+export declare const getStoragePath: (repoPath: string) => string;
+/**
+ * Get paths to key storage files
+ */
+export declare const getStoragePaths: (repoPath: string) => {
+    storagePath: string;
+    kuzuPath: string;
+    metaPath: string;
+};
+/**
+ * Load metadata from an indexed repo
+ */
+export declare const loadMeta: (storagePath: string) => Promise<RepoMeta | null>;
+/**
+ * Save metadata to storage
+ */
+export declare const saveMeta: (storagePath: string, meta: RepoMeta) => Promise<void>;
+/**
+ * Check if a path has a GitNexus index
+ */
+export declare const hasIndex: (repoPath: string) => Promise<boolean>;
+/**
+ * Load an indexed repo from a path
+ */
+export declare const loadRepo: (repoPath: string) => Promise<IndexedRepo | null>;
+/**
+ * Find .gitnexus by walking up from a starting path
+ */
+export declare const findRepo: (startPath: string) => Promise<IndexedRepo | null>;
+/**
+ * Add .gitnexus to .gitignore if not already present
+ */
+export declare const addToGitignore: (repoPath: string) => Promise<void>;

package/dist/storage/repo-manager.js

@@ -0,0 +1,106 @@
+/**
+ * Repository Manager
+ *
+ * Manages GitNexus index storage in .gitnexus/ at repo root.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+const GITNEXUS_DIR = '.gitnexus';
+/**
+ * Get the .gitnexus storage path for a repository
+ */
+export const getStoragePath = (repoPath) => {
+    return path.join(path.resolve(repoPath), GITNEXUS_DIR);
+};
+/**
+ * Get paths to key storage files
+ */
+export const getStoragePaths = (repoPath) => {
+    const storagePath = getStoragePath(repoPath);
+    return {
+        storagePath,
+        kuzuPath: path.join(storagePath, 'kuzu'),
+        metaPath: path.join(storagePath, 'meta.json'),
+    };
+};
+/**
+ * Load metadata from an indexed repo
+ */
+export const loadMeta = async (storagePath) => {
+    try {
+        const metaPath = path.join(storagePath, 'meta.json');
+        const raw = await fs.readFile(metaPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Save metadata to storage
+ */
+export const saveMeta = async (storagePath, meta) => {
+    await fs.mkdir(storagePath, { recursive: true });
+    const metaPath = path.join(storagePath, 'meta.json');
+    await fs.writeFile(metaPath, JSON.stringify(meta, null, 2), 'utf-8');
+};
+/**
+ * Check if a path has a GitNexus index
+ */
+export const hasIndex = async (repoPath) => {
+    const { metaPath } = getStoragePaths(repoPath);
+    try {
+        await fs.access(metaPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Load an indexed repo from a path
+ */
+export const loadRepo = async (repoPath) => {
+    const paths = getStoragePaths(repoPath);
+    const meta = await loadMeta(paths.storagePath);
+    if (!meta)
+        return null;
+    return {
+        repoPath: path.resolve(repoPath),
+        ...paths,
+        meta,
+    };
+};
+/**
+ * Find .gitnexus by walking up from a starting path
+ */
+export const findRepo = async (startPath) => {
+    let current = path.resolve(startPath);
+    const root = path.parse(current).root;
+    while (current !== root) {
+        const repo = await loadRepo(current);
+        if (repo)
+            return repo;
+        current = path.dirname(current);
+    }
+    return null;
+};
+/**
+ * Add .gitnexus to .gitignore if not already present
+ */
+export const addToGitignore = async (repoPath) => {
+    const gitignorePath = path.join(repoPath, '.gitignore');
+    try {
+        const content = await fs.readFile(gitignorePath, 'utf-8');
+        if (content.includes(GITNEXUS_DIR))
+            return;
+        const newContent = content.endsWith('\n')
+            ? `${content}${GITNEXUS_DIR}\n`
+            : `${content}\n${GITNEXUS_DIR}\n`;
+        await fs.writeFile(gitignorePath, newContent, 'utf-8');
+    }
+    catch {
+        // .gitignore doesn't exist, create it
+        await fs.writeFile(gitignorePath, `${GITNEXUS_DIR}\n`, 'utf-8');
+    }
+};

package/dist/types/pipeline.d.ts

@@ -0,0 +1,28 @@
+import { GraphNode, GraphRelationship, KnowledgeGraph } from '../core/graph/types.js';
+import { CommunityDetectionResult } from '../core/ingestion/community-processor.js';
+import { ProcessDetectionResult } from '../core/ingestion/process-processor.js';
+export type PipelinePhase = 'idle' | 'extracting' | 'structure' | 'parsing' | 'imports' | 'calls' | 'heritage' | 'communities' | 'processes' | 'enriching' | 'complete' | 'error';
+export interface PipelineProgress {
+    phase: PipelinePhase;
+    percent: number;
+    message: string;
+    detail?: string;
+    stats?: {
+        filesProcessed: number;
+        totalFiles: number;
+        nodesCreated: number;
+    };
+}
+export interface PipelineResult {
+    graph: KnowledgeGraph;
+    fileContents: Map<string, string>;
+    communityResult?: CommunityDetectionResult;
+    processResult?: ProcessDetectionResult;
+}
+export interface SerializablePipelineResult {
+    nodes: GraphNode[];
+    relationships: GraphRelationship[];
+    fileContents: Record<string, string>;
+}
+export declare const serializePipelineResult: (result: PipelineResult) => SerializablePipelineResult;
+export declare const deserializePipelineResult: (serialized: SerializablePipelineResult, createGraph: () => KnowledgeGraph) => PipelineResult;

package/dist/types/pipeline.js

@@ -0,0 +1,16 @@
+// Helper to convert PipelineResult to serializable format
+export const serializePipelineResult = (result) => ({
+    nodes: result.graph.nodes,
+    relationships: result.graph.relationships,
+    fileContents: Object.fromEntries(result.fileContents),
+});
+// Helper to reconstruct from serializable format (used in main thread)
+export const deserializePipelineResult = (serialized, createGraph) => {
+    const graph = createGraph();
+    serialized.nodes.forEach(node => graph.addNode(node));
+    serialized.relationships.forEach(rel => graph.addRelationship(rel));
+    return {
+        graph,
+        fileContents: new Map(Object.entries(serialized.fileContents)),
+    };
+};

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "gitnexus",
+  "version": "1.0.0",
+  "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",
+  "homepage": "https://github.com/abhigyanpatwari/GitNexus#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abhigyanpatwari/GitNexus.git",
+    "directory": "gitnexus"
+  },
+  "bugs": {
+    "url": "https://github.com/abhigyanpatwari/GitNexus/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "code-intelligence",
+    "knowledge-graph",
+    "cursor",
+    "claude",
+    "ai-agent",
+    "gitnexus",
+    "static-analysis",
+    "codebase-indexing"
+  ],
+  "type": "module",
+  "bin": {
+    "gitnexus": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "vendor"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/cli/index.ts",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.0.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "commander": "^12.0.0",
+    "cors": "^2.8.5",
+    "express": "^4.19.2",
+    "glob": "^11.0.0",
+    "graphology": "^0.25.4",
+    "graphology-indices": "^0.17.0",
+    "graphology-utils": "^2.3.0",
+    "kuzu": "^0.11.3",
+    "lru-cache": "^11.0.0",
+    "mnemonist": "^0.39.0",
+    "ora": "^8.0.0",
+    "pandemonium": "^2.4.0",
+    "tree-sitter": "^0.21.0",
+    "tree-sitter-c": "^0.21.0",
+    "tree-sitter-c-sharp": "^0.21.0",
+    "tree-sitter-cpp": "^0.22.0",
+    "tree-sitter-go": "^0.21.0",
+    "tree-sitter-java": "^0.21.0",
+    "tree-sitter-javascript": "^0.21.0",
+    "tree-sitter-python": "^0.21.0",
+    "tree-sitter-rust": "^0.21.0",
+    "tree-sitter-typescript": "^0.21.0",
+    "typescript": "^5.4.5",
+    "uuid": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.0.0",
+    "@types/uuid": "^10.0.0",
+    "tsx": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/skills/debugging.md

@@ -0,0 +1,104 @@
+---
+name: gitnexus-debugging
+description: Trace bugs through call chains using knowledge graph
+---
+
+# Debugging with GitNexus
+
+## Quick Start
+```
+0. If "Index is stale" → gitnexus_analyze({})
+1. gitnexus_search({query})                → Find code related to error
+2. gitnexus_explore({name, type: "symbol"}) → Get callers and callees
+3. READ gitnexus://process/{name}           → Trace execution flow
+```
+
+## When to Use
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "Who calls this method?"
+- "Debug the payment issue"
+
+## Workflow Checklist
+```
+Bug Investigation:
+- [ ] Understand the symptom (error message, behavior)
+- [ ] gitnexus_search to find related code
+- [ ] Identify the suspect function
+- [ ] gitnexus_explore to see callers/callees
+- [ ] READ gitnexus://process/{name} if suspect is in a process
+- [ ] READ gitnexus://schema for Cypher query help
+- [ ] gitnexus_cypher for custom traces
+```
+
+## Resource Reference
+
+### gitnexus://schema
+Graph schema for writing Cypher queries:
+```yaml
+nodes: [Function, Class, Method, File, Community, Process]
+relationships: [CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS]
+example_queries:
+  find_callers: |
+    MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "X"})
+    RETURN caller.name
+```
+
+### gitnexus://process/{name}
+Trace execution flow to find where bug might occur:
+```yaml
+name: CheckoutFlow
+trace:
+  1: handleCheckout
+  2: validateCart
+  3: processPayment  ← bug here?
+  4: sendConfirmation
+```
+
+## Tool Reference
+
+### gitnexus_search
+Find code related to error or symptom:
+```
+gitnexus_search({query: "payment validation error", depth: "full"})
+```
+
+### gitnexus_explore
+Get symbol context:
+```
+gitnexus_explore({name: "validatePayment", type: "symbol"})
+→ Callers: processCheckout, webhookHandler
+→ Callees: verifyCard, fetchRates
+```
+
+### gitnexus_cypher
+Custom graph queries for tracing:
+```cypher
+// Trace call chain (2 hops)
+MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
+RETURN [n IN nodes(path) | n.name] AS chain
+```
+
+## Example: "Payment endpoint returns 500 intermittently"
+
+```
+1. gitnexus_search({query: "payment error handling"})
+   → validatePayment, handlePaymentError, PaymentException
+
+2. gitnexus_explore({name: "validatePayment", type: "symbol"})
+   → Callees: verifyCard, fetchRates (external API!)
+
+3. READ gitnexus://process/CheckoutFlow
+   → Step 3: validatePayment → calls external API
+
+4. Root cause: fetchRates calls external API without proper timeout
+```
+
+## Debugging Patterns
+
+| Symptom | Approach |
+|---------|----------|
+| Error message | Search for error text, trace throw sites |
+| Wrong return value | Trace data flow through callees |
+| Intermittent failure | Look for external calls, timeouts |
+| Performance issue | Find hot paths via callers count |