@optave/codegraph 1.1.0

package/src/cli.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { buildGraph } from './builder.js';
+import { queryName, impactAnalysis, moduleMap, fileDeps, fnDeps, fnImpact, diffImpact } from './queries.js';
+import { buildEmbeddings, search, MODELS } from './embedder.js';
+import { watchProject } from './watcher.js';
+import { exportDOT, exportMermaid, exportJSON } from './export.js';
+import { findCycles, formatCycles } from './cycles.js';
+import { findDbPath } from './db.js';
+import { setVerbose } from './logger.js';
+import path from 'path';
+import Database from 'better-sqlite3';
+import fs from 'fs';
+
+const program = new Command();
+program
+  .name('codegraph')
+  .description('Local code dependency graph tool')
+  .version('1.1.0')
+  .option('-v, --verbose', 'Enable verbose/debug output')
+  .hook('preAction', (thisCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.verbose) setVerbose(true);
+  });
+
+program
+  .command('build [dir]')
+  .description('Parse repo and build graph in .codegraph/graph.db')
+  .option('--no-incremental', 'Force full rebuild (ignore file hashes)')
+  .action(async (dir, opts) => {
+    const root = path.resolve(dir || '.');
+    await buildGraph(root, { incremental: opts.incremental });
+  });
+
+program
+  .command('query <name>')
+  .description('Find a function/class, show callers and callees')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-j, --json', 'Output as JSON')
+  .action((name, opts) => {
+    queryName(name, opts.db, { json: opts.json });
+  });
+
+program
+  .command('impact <file>')
+  .description('Show what depends on this file (transitive)')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-j, --json', 'Output as JSON')
+  .action((file, opts) => {
+    impactAnalysis(file, opts.db, { json: opts.json });
+  });
+
+program
+  .command('map')
+  .description('High-level module overview with most-connected nodes')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-n, --limit <number>', 'Number of top nodes', '20')
+  .option('-j, --json', 'Output as JSON')
+  .action((opts) => {
+    moduleMap(opts.db, parseInt(opts.limit), { json: opts.json });
+  });
+
+program
+  .command('deps <file>')
+  .description('Show what this file imports and what imports it')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-j, --json', 'Output as JSON')
+  .action((file, opts) => {
+    fileDeps(file, opts.db, { json: opts.json });
+  });
+
+program
+  .command('fn <name>')
+  .description('Function-level dependencies: callers, callees, and transitive call chain')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--depth <n>', 'Transitive caller depth', '3')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('-j, --json', 'Output as JSON')
+  .action((name, opts) => {
+    fnDeps(name, opts.db, { depth: parseInt(opts.depth), noTests: !opts.tests, json: opts.json });
+  });
+
+program
+  .command('fn-impact <name>')
+  .description('Function-level impact: what functions break if this one changes')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--depth <n>', 'Max transitive depth', '5')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('-j, --json', 'Output as JSON')
+  .action((name, opts) => {
+    fnImpact(name, opts.db, { depth: parseInt(opts.depth), noTests: !opts.tests, json: opts.json });
+  });
+
+program
+  .command('diff-impact [ref]')
+  .description('Show impact of git changes (unstaged, staged, or vs a ref)')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--staged', 'Analyze staged changes instead of unstaged')
+  .option('--depth <n>', 'Max transitive caller depth', '3')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('-j, --json', 'Output as JSON')
+  .action((ref, opts) => {
+    diffImpact(opts.db, { ref, staged: opts.staged, depth: parseInt(opts.depth), noTests: !opts.tests, json: opts.json });
+  });
+
+// ─── New commands ────────────────────────────────────────────────────────
+
+program
+  .command('export')
+  .description('Export dependency graph as DOT (Graphviz), Mermaid, or JSON')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-f, --format <format>', 'Output format: dot, mermaid, json', 'dot')
+  .option('--functions', 'Function-level graph instead of file-level')
+  .option('-o, --output <file>', 'Write to file instead of stdout')
+  .action((opts) => {
+    const db = new Database(findDbPath(opts.db), { readonly: true });
+    const exportOpts = { fileLevel: !opts.functions };
+
+    let output;
+    switch (opts.format) {
+      case 'mermaid':
+        output = exportMermaid(db, exportOpts);
+        break;
+      case 'json':
+        output = JSON.stringify(exportJSON(db), null, 2);
+        break;
+      case 'dot':
+      default:
+        output = exportDOT(db, exportOpts);
+        break;
+    }
+
+    db.close();
+
+    if (opts.output) {
+      fs.writeFileSync(opts.output, output, 'utf-8');
+      console.log(`Exported ${opts.format} to ${opts.output}`);
+    } else {
+      console.log(output);
+    }
+  });
+
+program
+  .command('cycles')
+  .description('Detect circular dependencies in the codebase')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--functions', 'Function-level cycle detection')
+  .option('-j, --json', 'Output as JSON')
+  .action((opts) => {
+    const db = new Database(findDbPath(opts.db), { readonly: true });
+    const cycles = findCycles(db, { fileLevel: !opts.functions });
+    db.close();
+
+    if (opts.json) {
+      console.log(JSON.stringify({ cycles, count: cycles.length }, null, 2));
+    } else {
+      console.log(formatCycles(cycles));
+    }
+  });
+
+program
+  .command('mcp')
+  .description('Start MCP (Model Context Protocol) server for AI assistant integration')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .action(async (opts) => {
+    const { startMCPServer } = await import('./mcp.js');
+    await startMCPServer(opts.db);
+  });
+
+// ─── Embedding commands ─────────────────────────────────────────────────
+
+program
+  .command('models')
+  .description('List available embedding models')
+  .action(() => {
+    console.log('\nAvailable embedding models:\n');
+    for (const [key, config] of Object.entries(MODELS)) {
+      const def = key === 'minilm' ? ' (default)' : '';
+      console.log(`  ${key.padEnd(12)} ${String(config.dim).padStart(4)}d  ${config.desc}${def}`);
+    }
+    console.log('\nUsage: codegraph embed --model <name>');
+    console.log('       codegraph search "query" --model <name>\n');
+  });
+
+program
+  .command('embed [dir]')
+  .description('Build semantic embeddings for all functions/methods/classes (requires prior `build`)')
+  .option('-m, --model <name>', 'Embedding model: minilm (default), jina-small, jina-base, nomic. Run `codegraph models` for details', 'minilm')
+  .action(async (dir, opts) => {
+    const root = path.resolve(dir || '.');
+    await buildEmbeddings(root, opts.model);
+  });
+
+program
+  .command('search <query>')
+  .description('Semantic search: find functions by natural language description')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-m, --model <name>', 'Override embedding model (auto-detects from DB)')
+  .option('-n, --limit <number>', 'Max results', '15')
+  .option('-T, --no-tests', 'Exclude test/spec files')
+  .option('--min-score <score>', 'Minimum similarity threshold', '0.2')
+  .option('-k, --kind <kind>', 'Filter by kind: function, method, class')
+  .option('--file <pattern>', 'Filter by file path pattern')
+  .action(async (query, opts) => {
+    await search(query, opts.db, {
+      limit: parseInt(opts.limit),
+      noTests: !opts.tests,
+      minScore: parseFloat(opts.minScore),
+      model: opts.model,
+      kind: opts.kind,
+      filePattern: opts.file
+    });
+  });
+
+program
+  .command('watch [dir]')
+  .description('Watch project for file changes and incrementally update the graph')
+  .action(async (dir) => {
+    const root = path.resolve(dir || '.');
+    await watchProject(root);
+  });
+
+program.parse();

package/src/config.js

@@ -0,0 +1,55 @@
+import fs from 'fs';
+import path from 'path';
+import { debug } from './logger.js';
+
+export const CONFIG_FILES = ['.codegraphrc.json', '.codegraphrc', 'codegraph.config.json'];
+
+export const DEFAULTS = {
+  include: [],
+  exclude: [],
+  ignoreDirs: [],
+  extensions: [],
+  aliases: {},
+  build: {
+    incremental: true,
+    dbPath: '.codegraph/graph.db'
+  },
+  query: {
+    defaultDepth: 3,
+    defaultLimit: 20
+  }
+};
+
+/**
+ * Load project configuration from a .codegraphrc.json or similar file.
+ * Returns merged config with defaults.
+ */
+export function loadConfig(cwd) {
+  cwd = cwd || process.cwd();
+  for (const name of CONFIG_FILES) {
+    const filePath = path.join(cwd, name);
+    if (fs.existsSync(filePath)) {
+      try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const config = JSON.parse(raw);
+        debug(`Loaded config from ${filePath}`);
+        return mergeConfig(DEFAULTS, config);
+      } catch (err) {
+        debug(`Failed to parse config ${filePath}: ${err.message}`);
+      }
+    }
+  }
+  return { ...DEFAULTS };
+}
+
+function mergeConfig(defaults, overrides) {
+  const result = { ...defaults };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value && typeof value === 'object' && !Array.isArray(value) && defaults[key] && typeof defaults[key] === 'object') {
+      result[key] = { ...defaults[key], ...value };
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}

package/src/constants.js

@@ -0,0 +1,28 @@
+import path from 'path';
+
+export const IGNORE_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', '.nuxt', '.svelte-kit',
+  'coverage', '.codegraph', '__pycache__', '.tox', 'vendor', '.venv', 'venv',
+  'env', '.env'
+]);
+
+export const EXTENSIONS = new Set([
+  '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
+  '.tf', '.hcl', '.py'
+]);
+
+export function shouldIgnore(dirName) {
+  return IGNORE_DIRS.has(dirName) || dirName.startsWith('.');
+}
+
+export function isSupportedFile(filePath) {
+  return EXTENSIONS.has(path.extname(filePath));
+}
+
+/**
+ * Normalize a file path to always use forward slashes.
+ * Ensures cross-platform consistency in the SQLite database.
+ */
+export function normalizePath(filePath) {
+  return filePath.split(path.sep).join('/');
+}

package/src/cycles.js

@@ -0,0 +1,104 @@
+/**
+ * Detect circular dependencies in the codebase using Tarjan's SCC algorithm.
+ * @param {object} db - Open SQLite database
+ * @param {object} opts - { fileLevel: true }
+ * @returns {string[][]} Array of cycles, each cycle is an array of file paths
+ */
+export function findCycles(db, opts = {}) {
+  const fileLevel = opts.fileLevel !== false;
+
+  // Build adjacency list
+  let edges;
+  if (fileLevel) {
+    edges = db.prepare(`
+      SELECT DISTINCT n1.file AS source, n2.file AS target
+      FROM edges e
+      JOIN nodes n1 ON e.source_id = n1.id
+      JOIN nodes n2 ON e.target_id = n2.id
+      WHERE n1.file != n2.file AND e.kind IN ('imports', 'imports-type')
+    `).all();
+  } else {
+    edges = db.prepare(`
+      SELECT DISTINCT
+        (n1.name || '|' || n1.file) AS source,
+        (n2.name || '|' || n2.file) AS target
+      FROM edges e
+      JOIN nodes n1 ON e.source_id = n1.id
+      JOIN nodes n2 ON e.target_id = n2.id
+      WHERE n1.kind IN ('function', 'method', 'class')
+        AND n2.kind IN ('function', 'method', 'class')
+        AND e.kind = 'calls'
+        AND n1.id != n2.id
+    `).all();
+  }
+
+  const graph = new Map();
+  for (const { source, target } of edges) {
+    if (!graph.has(source)) graph.set(source, []);
+    graph.get(source).push(target);
+    if (!graph.has(target)) graph.set(target, []);
+  }
+
+  // Tarjan's strongly connected components algorithm
+  let index = 0;
+  const stack = [];
+  const onStack = new Set();
+  const indices = new Map();
+  const lowlinks = new Map();
+  const sccs = [];
+
+  function strongconnect(v) {
+    indices.set(v, index);
+    lowlinks.set(v, index);
+    index++;
+    stack.push(v);
+    onStack.add(v);
+
+    for (const w of (graph.get(v) || [])) {
+      if (!indices.has(w)) {
+        strongconnect(w);
+        lowlinks.set(v, Math.min(lowlinks.get(v), lowlinks.get(w)));
+      } else if (onStack.has(w)) {
+        lowlinks.set(v, Math.min(lowlinks.get(v), indices.get(w)));
+      }
+    }
+
+    if (lowlinks.get(v) === indices.get(v)) {
+      const scc = [];
+      let w;
+      do {
+        w = stack.pop();
+        onStack.delete(w);
+        scc.push(w);
+      } while (w !== v);
+      if (scc.length > 1) sccs.push(scc);
+    }
+  }
+
+  for (const node of graph.keys()) {
+    if (!indices.has(node)) strongconnect(node);
+  }
+
+  return sccs;
+}
+
+/**
+ * Format cycles for human-readable output.
+ */
+export function formatCycles(cycles) {
+  if (cycles.length === 0) {
+    return 'No circular dependencies detected.';
+  }
+
+  const lines = [`Found ${cycles.length} circular dependency cycle(s):\n`];
+  for (let i = 0; i < cycles.length; i++) {
+    const cycle = cycles[i];
+    lines.push(`  Cycle ${i + 1} (${cycle.length} files):`);
+    for (const file of cycle) {
+      lines.push(`    -> ${file}`);
+    }
+    lines.push(`    -> ${cycle[0]} (back to start)`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}

package/src/db.js

@@ -0,0 +1,117 @@
+import Database from 'better-sqlite3';
+import path from 'path';
+import fs from 'fs';
+import { warn, debug, info } from './logger.js';
+
+// ─── Schema Migrations ─────────────────────────────────────────────────
+export const MIGRATIONS = [
+  {
+    version: 1,
+    up: `
+      CREATE TABLE IF NOT EXISTS nodes (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        file TEXT NOT NULL,
+        line INTEGER,
+        end_line INTEGER,
+        UNIQUE(name, kind, file, line)
+      );
+      CREATE TABLE IF NOT EXISTS edges (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        source_id INTEGER NOT NULL,
+        target_id INTEGER NOT NULL,
+        kind TEXT NOT NULL,
+        confidence REAL DEFAULT 1.0,
+        dynamic INTEGER DEFAULT 0,
+        FOREIGN KEY(source_id) REFERENCES nodes(id),
+        FOREIGN KEY(target_id) REFERENCES nodes(id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
+      CREATE INDEX IF NOT EXISTS idx_nodes_file ON nodes(file);
+      CREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(kind);
+      CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id);
+      CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id);
+      CREATE INDEX IF NOT EXISTS idx_edges_kind ON edges(kind);
+    `
+  },
+  {
+    version: 2,
+    up: `
+      CREATE INDEX IF NOT EXISTS idx_nodes_name_kind_file ON nodes(name, kind, file);
+      CREATE INDEX IF NOT EXISTS idx_nodes_file_kind ON nodes(file, kind);
+      CREATE INDEX IF NOT EXISTS idx_edges_source_kind ON edges(source_id, kind);
+      CREATE INDEX IF NOT EXISTS idx_edges_target_kind ON edges(target_id, kind);
+    `
+  },
+  {
+    version: 3,
+    up: `
+      CREATE TABLE IF NOT EXISTS file_hashes (
+        file TEXT PRIMARY KEY,
+        hash TEXT NOT NULL,
+        mtime INTEGER NOT NULL
+      );
+    `
+  }
+];
+
+export function openDb(dbPath) {
+  const dir = path.dirname(dbPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  return db;
+}
+
+export function initSchema(db) {
+  db.exec(`CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL DEFAULT 0)`);
+
+  const row = db.prepare('SELECT version FROM schema_version').get();
+  let currentVersion = row ? row.version : 0;
+
+  if (!row) {
+    db.prepare('INSERT INTO schema_version (version) VALUES (0)').run();
+  }
+
+  for (const migration of MIGRATIONS) {
+    if (migration.version > currentVersion) {
+      debug(`Running migration v${migration.version}`);
+      db.exec(migration.up);
+      db.prepare('UPDATE schema_version SET version = ?').run(migration.version);
+      currentVersion = migration.version;
+    }
+  }
+
+  try { db.exec('ALTER TABLE nodes ADD COLUMN end_line INTEGER'); } catch { /* already exists */ }
+  try { db.exec('ALTER TABLE edges ADD COLUMN confidence REAL DEFAULT 1.0'); } catch { /* already exists */ }
+  try { db.exec('ALTER TABLE edges ADD COLUMN dynamic INTEGER DEFAULT 0'); } catch { /* already exists */ }
+}
+
+export function findDbPath(customPath) {
+  if (customPath) return path.resolve(customPath);
+  let dir = process.cwd();
+  while (true) {
+    const candidate = path.join(dir, '.codegraph', 'graph.db');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.join(process.cwd(), '.codegraph', 'graph.db');
+}
+
+/**
+ * Open a database in readonly mode, with a user-friendly error if the DB doesn't exist.
+ */
+export function openReadonlyOrFail(customPath) {
+  const dbPath = findDbPath(customPath);
+  if (!fs.existsSync(dbPath)) {
+    console.error(
+      `No codegraph database found at ${dbPath}.\n` +
+      `Run "codegraph build" first to analyze your codebase.`
+    );
+    process.exit(1);
+  }
+  return new Database(dbPath, { readonly: true });
+}