@optave/codegraph 3.3.0 → 3.4.0

package/src/features/batch.js

@@ -1,156 +0,0 @@
-/**
- * Batch query orchestration — run the same query command against multiple targets
- * and return all results in a single JSON payload.
- *
- * Designed for multi-agent swarms that need to dispatch 20+ queries in one call.
- */
-
-import {
-  contextData,
-  explainData,
-  exportsData,
-  fileDepsData,
-  fnDepsData,
-  fnImpactData,
-  impactAnalysisData,
-  whereData,
-} from '../domain/queries.js';
-import { ConfigError } from '../shared/errors.js';
-import { complexityData } from './complexity.js';
-import { dataflowData } from './dataflow.js';
-import { flowData } from './flow.js';
-
-/**
- * Map of supported batch commands → their data function + first-arg semantics.
- * `sig` describes how the target string is passed to the data function:
- *   - 'name'   → dataFn(target, dbPath, opts)
- *   - 'target' → dataFn(target, dbPath, opts)
- *   - 'file'   → dataFn(target, dbPath, opts)
- *   - 'dbOnly' → dataFn(dbPath, { ...opts, target })  (target goes into opts)
- */
-export const BATCH_COMMANDS = {
-  'fn-impact': { fn: fnImpactData, sig: 'name' },
-  context: { fn: contextData, sig: 'name' },
-  explain: { fn: explainData, sig: 'target' },
-  where: { fn: whereData, sig: 'target' },
-  query: { fn: fnDepsData, sig: 'name' },
-  impact: { fn: impactAnalysisData, sig: 'file' },
-  deps: { fn: fileDepsData, sig: 'file' },
-  exports: { fn: exportsData, sig: 'file' },
-  flow: { fn: flowData, sig: 'name' },
-  dataflow: { fn: dataflowData, sig: 'name' },
-  complexity: { fn: complexityData, sig: 'dbOnly' },
-};
-
-/**
- * Run a query command against multiple targets, returning all results.
- *
- * @param {string} command - One of the keys in BATCH_COMMANDS
- * @param {string[]} targets - List of target names/paths
- * @param {string} [customDbPath] - Path to graph.db
- * @param {object} [opts] - Shared options passed to every invocation
- * @returns {{ command: string, total: number, succeeded: number, failed: number, results: object[] }}
- */
-export function batchData(command, targets, customDbPath, opts = {}) {
-  const entry = BATCH_COMMANDS[command];
-  if (!entry) {
-    throw new ConfigError(
-      `Unknown batch command "${command}". Valid commands: ${Object.keys(BATCH_COMMANDS).join(', ')}`,
-    );
-  }
-
-  const results = [];
-  let succeeded = 0;
-  let failed = 0;
-
-  for (const target of targets) {
-    try {
-      let data;
-      if (entry.sig === 'dbOnly') {
-        // complexityData(dbPath, { ...opts, target })
-        data = entry.fn(customDbPath, { ...opts, target });
-      } else {
-        // All other: dataFn(target, dbPath, opts)
-        data = entry.fn(target, customDbPath, opts);
-      }
-      results.push({ target, ok: true, data });
-      succeeded++;
-    } catch (err) {
-      results.push({ target, ok: false, error: err.message });
-      failed++;
-    }
-  }
-
-  return { command, total: targets.length, succeeded, failed, results };
-}
-
-/**
- * Expand comma-separated positional args into individual entries.
- * `['a,b', 'c']` → `['a', 'b', 'c']`.
- * Trims whitespace, filters empties. Passes through object items unchanged.
- *
- * @param {Array<string|object>} targets
- * @returns {Array<string|object>}
- */
-export function splitTargets(targets) {
-  const out = [];
-  for (const item of targets) {
-    if (typeof item !== 'string') {
-      out.push(item);
-      continue;
-    }
-    for (const part of item.split(',')) {
-      const trimmed = part.trim();
-      if (trimmed) out.push(trimmed);
-    }
-  }
-  return out;
-}
-
-/**
- * Multi-command batch orchestration — run different commands per target.
- *
- * @param {Array<{command: string, target: string, opts?: object}>} items
- * @param {string} [customDbPath]
- * @param {object} [sharedOpts] - Default opts merged under per-item opts
- * @returns {{ mode: 'multi', total: number, succeeded: number, failed: number, results: object[] }}
- */
-export function multiBatchData(items, customDbPath, sharedOpts = {}) {
-  const results = [];
-  let succeeded = 0;
-  let failed = 0;
-
-  for (const item of items) {
-    const { command, target, opts: itemOpts } = item;
-    const entry = BATCH_COMMANDS[command];
-
-    if (!entry) {
-      results.push({
-        command,
-        target,
-        ok: false,
-        error: `Unknown batch command "${command}". Valid commands: ${Object.keys(BATCH_COMMANDS).join(', ')}`,
-      });
-      failed++;
-      continue;
-    }
-
-    const merged = { ...sharedOpts, ...itemOpts };
-
-    try {
-      let data;
-      if (entry.sig === 'dbOnly') {
-        data = entry.fn(customDbPath, { ...merged, target });
-      } else {
-        data = entry.fn(target, customDbPath, merged);
-      }
-      results.push({ command, target, ok: true, data });
-      succeeded++;
-    } catch (err) {
-      results.push({ command, target, ok: false, error: err.message });
-      failed++;
-    }
-  }
-
-  return { mode: 'multi', total: items.length, succeeded, failed, results };
-}

package/src/graph/algorithms/louvain.js

@@ -1,26 +0,0 @@
-/**
- * Louvain community detection via graphology.
- *
- * @param {import('../model.js').CodeGraph} graph
- * @param {{ resolution?: number }} [opts]
- * @returns {{ assignments: Map<string, number>, modularity: number }}
- */
-import graphologyLouvain from 'graphology-communities-louvain';
-
-export function louvainCommunities(graph, opts = {}) {
-  const gy = graph.toGraphology({ type: 'undirected' });
-
-  if (gy.order === 0 || gy.size === 0) {
-    return { assignments: new Map(), modularity: 0 };
-  }
-
-  const resolution = opts.resolution ?? 1.0;
-  const details = graphologyLouvain.detailed(gy, { resolution });
-
-  const assignments = new Map();
-  for (const [nodeId, communityId] of Object.entries(details.communities)) {
-    assignments.set(nodeId, communityId);
-  }
-
-  return { assignments, modularity: details.modularity };
-}

package/src/graph/builders/structure.js

@@ -1,40 +0,0 @@
-/**
- * Build a containment graph (directory → file) from the SQLite database.
- */
-
-import { CodeGraph } from '../model.js';
-
-/**
- * @param {object} db - Open better-sqlite3 database (readonly)
- * @returns {CodeGraph} Directed graph with directory→file containment edges
- */
-export function buildStructureGraph(db) {
-  const graph = new CodeGraph();
-
-  const dirs = db.prepare("SELECT id, name FROM nodes WHERE kind = 'directory'").all();
-
-  for (const d of dirs) {
-    graph.addNode(String(d.id), { label: d.name, kind: 'directory' });
-  }
-
-  const files = db.prepare("SELECT id, name, file FROM nodes WHERE kind = 'file'").all();
-
-  for (const f of files) {
-    graph.addNode(String(f.id), { label: f.name, kind: 'file', file: f.file });
-  }
-
-  const containsEdges = db
-    .prepare(`
-      SELECT e.source_id, e.target_id
-      FROM edges e
-      JOIN nodes n ON e.source_id = n.id
-      WHERE e.kind = 'contains' AND n.kind = 'directory'
-    `)
-    .all();
-
-  for (const e of containsEdges) {
-    graph.addEdge(String(e.source_id), String(e.target_id), { kind: 'contains' });
-  }
-
-  return graph;
-}

package/src/graph/builders/temporal.js

@@ -1,33 +0,0 @@
-/**
- * Build a co-change (temporal) graph weighted by Jaccard similarity.
- */
-
-import { CodeGraph } from '../model.js';
-
-/**
- * @param {object} db - Open better-sqlite3 database (readonly)
- * @param {{ minJaccard?: number }} [opts]
- * @returns {CodeGraph} Undirected graph weighted by Jaccard similarity
- */
-export function buildTemporalGraph(db, opts = {}) {
-  const minJaccard = opts.minJaccard ?? 0.0;
-  const graph = new CodeGraph({ directed: false });
-
-  // Check if co_changes table exists
-  const tableCheck = db
-    .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='co_changes'")
-    .get();
-  if (!tableCheck) return graph;
-
-  const rows = db
-    .prepare('SELECT file_a, file_b, jaccard FROM co_changes WHERE jaccard >= ?')
-    .all(minJaccard);
-
-  for (const r of rows) {
-    if (!graph.hasNode(r.file_a)) graph.addNode(r.file_a, { label: r.file_a });
-    if (!graph.hasNode(r.file_b)) graph.addNode(r.file_b, { label: r.file_b });
-    graph.addEdge(r.file_a, r.file_b, { jaccard: r.jaccard });
-  }
-
-  return graph;
-}

package/src/mcp/server.js

@@ -1,143 +0,0 @@
-/**
- * MCP (Model Context Protocol) server for codegraph.
- * Exposes codegraph queries as tools that AI coding assistants can call.
- *
- * Requires: npm install @modelcontextprotocol/sdk
- */
-
-import { createRequire } from 'node:module';
-import { findDbPath } from '../db/index.js';
-import { loadConfig } from '../infrastructure/config.js';
-import { CodegraphError, ConfigError } from '../shared/errors.js';
-import { MCP_MAX_LIMIT } from '../shared/paginate.js';
-import { initMcpDefaults } from './middleware.js';
-import { buildToolList } from './tool-registry.js';
-import { TOOL_HANDLERS } from './tools/index.js';
-
-/**
- * Start the MCP server.
- * This function requires @modelcontextprotocol/sdk to be installed.
- *
- * @param {string} [customDbPath] - Path to a specific graph.db
- * @param {object} [options]
- * @param {boolean} [options.multiRepo] - Enable multi-repo access (default: false)
- * @param {string[]} [options.allowedRepos] - Restrict access to these repo names only
- */
-async function loadMCPSdk() {
-  try {
-    const sdk = await import('@modelcontextprotocol/sdk/server/index.js');
-    const transport = await import('@modelcontextprotocol/sdk/server/stdio.js');
-    const types = await import('@modelcontextprotocol/sdk/types.js');
-    return {
-      Server: sdk.Server,
-      StdioServerTransport: transport.StdioServerTransport,
-      ListToolsRequestSchema: types.ListToolsRequestSchema,
-      CallToolRequestSchema: types.CallToolRequestSchema,
-    };
-  } catch {
-    throw new ConfigError(
-      'MCP server requires @modelcontextprotocol/sdk.\nInstall it with: npm install @modelcontextprotocol/sdk',
-    );
-  }
-}
-
-function createLazyLoaders() {
-  let _queries;
-  let _Database;
-  return {
-    async getQueries() {
-      if (!_queries) _queries = await import('../domain/queries.js');
-      return _queries;
-    },
-    getDatabase() {
-      if (!_Database) {
-        const require = createRequire(import.meta.url);
-        _Database = require('better-sqlite3');
-      }
-      return _Database;
-    },
-  };
-}
-
-async function resolveDbPath(customDbPath, args, allowedRepos) {
-  let dbPath = customDbPath || undefined;
-  if (args.repo) {
-    if (allowedRepos && !allowedRepos.includes(args.repo)) {
-      throw new ConfigError(`Repository "${args.repo}" is not in the allowed repos list.`);
-    }
-    const { resolveRepoDbPath } = await import('../infrastructure/registry.js');
-    const resolved = resolveRepoDbPath(args.repo);
-    if (!resolved)
-      throw new ConfigError(
-        `Repository "${args.repo}" not found in registry or its database is missing.`,
-      );
-    dbPath = resolved;
-  }
-  return dbPath;
-}
-
-function validateMultiRepoAccess(multiRepo, name, args) {
-  if (!multiRepo && args.repo) {
-    throw new ConfigError(
-      'Multi-repo access is disabled. Restart with `codegraph mcp --multi-repo` to access other repositories.',
-    );
-  }
-  if (!multiRepo && name === 'list_repos') {
-    throw new ConfigError(
-      'Multi-repo access is disabled. Restart with `codegraph mcp --multi-repo` to list repositories.',
-    );
-  }
-}
-
-export async function startMCPServer(customDbPath, options = {}) {
-  const { allowedRepos } = options;
-  const multiRepo = options.multiRepo || !!allowedRepos;
-
-  // Apply config-based MCP page-size overrides
-  const config = options.config || loadConfig();
-  initMcpDefaults(config.mcp?.defaults);
-
-  const { Server, StdioServerTransport, ListToolsRequestSchema, CallToolRequestSchema } =
-    await loadMCPSdk();
-
-  // Connect transport FIRST so the server can receive the client's
-  // `initialize` request while heavy modules (queries, better-sqlite3)
-  // are still loading.  These are lazy-loaded on the first tool call
-  // and cached for subsequent calls.
-  const { getQueries, getDatabase } = createLazyLoaders();
-
-  const server = new Server(
-    { name: 'codegraph', version: '1.0.0' },
-    { capabilities: { tools: {} } },
-  );
-
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: buildToolList(multiRepo),
-  }));
-
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-    try {
-      validateMultiRepoAccess(multiRepo, name, args);
-      const dbPath = await resolveDbPath(customDbPath, args, allowedRepos);
-
-      const toolEntry = TOOL_HANDLERS.get(name);
-      if (!toolEntry) {
-        return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
-      }
-
-      const ctx = { dbPath, getQueries, getDatabase, findDbPath, allowedRepos, MCP_MAX_LIMIT };
-      const result = await toolEntry.handler(args, ctx);
-      if (result?.content) return result;
-      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
-    } catch (err) {
-      const code = err instanceof CodegraphError ? err.code : 'UNKNOWN_ERROR';
-      const text =
-        err instanceof CodegraphError ? `[${code}] ${err.message}` : `Error: ${err.message}`;
-      return { content: [{ type: 'text', text }], isError: true };
-    }
-  });
-
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-}

package/src/mcp/tools/batch-query.js

@@ -1,11 +0,0 @@
-export const name = 'batch_query';
-
-export async function handler(args, ctx) {
-  const { batchData } = await import('../../features/batch.js');
-  return batchData(args.command, args.targets, ctx.dbPath, {
-    depth: args.depth,
-    file: args.file,
-    kind: args.kind,
-    noTests: args.no_tests,
-  });
-}

package/src/mcp/tools/brief.js

@@ -1,8 +0,0 @@
-export const name = 'brief';
-
-export async function handler(args, ctx) {
-  const { briefData } = await ctx.getQueries();
-  return briefData(args.file, ctx.dbPath, {
-    noTests: args.no_tests,
-  });
-}

package/src/mcp/tools/code-owners.js

@@ -1,12 +0,0 @@
-export const name = 'code_owners';
-
-export async function handler(args, ctx) {
-  const { ownersData } = await import('../../features/owners.js');
-  return ownersData(ctx.dbPath, {
-    file: args.file,
-    owner: args.owner,
-    boundary: args.boundary,
-    kind: args.kind,
-    noTests: args.no_tests,
-  });
-}

package/src/mcp/tools/impact-analysis.js

@@ -1,12 +0,0 @@
-import { effectiveLimit, effectiveOffset } from '../middleware.js';
-
-export const name = 'impact_analysis';
-
-export async function handler(args, ctx) {
-  const { impactAnalysisData } = await ctx.getQueries();
-  return impactAnalysisData(args.file, ctx.dbPath, {
-    noTests: args.no_tests,
-    limit: effectiveLimit(args, name),
-    offset: effectiveOffset(args),
-  });
-}

package/src/mcp/tools/list-repos.js

@@ -1,11 +0,0 @@
-export const name = 'list_repos';
-
-export async function handler(_args, ctx) {
-  const { listRepos, pruneRegistry } = await import('../../infrastructure/registry.js');
-  pruneRegistry();
-  let repos = listRepos();
-  if (ctx.allowedRepos) {
-    repos = repos.filter((r) => ctx.allowedRepos.includes(r.name));
-  }
-  return { repos };
-}

package/src/mcp/tools/module-map.js

@@ -1,6 +0,0 @@
-export const name = 'module_map';
-
-export async function handler(args, ctx) {
-  const { moduleMapData } = await ctx.getQueries();
-  return moduleMapData(ctx.dbPath, args.limit || 20, { noTests: args.no_tests });
-}

package/src/mcp/tools/path.js

@@ -1,12 +0,0 @@
-export const name = 'path';
-
-export async function handler(args, ctx) {
-  const { pathData } = await ctx.getQueries();
-  return pathData(args.from, args.to, ctx.dbPath, {
-    maxDepth: args.depth ?? 10,
-    edgeKinds: args.edge_kinds,
-    fromFile: args.from_file,
-    toFile: args.to_file,
-    noTests: args.no_tests,
-  });
-}

package/src/mcp/tools/symbol-children.js

@@ -1,14 +0,0 @@
-import { effectiveOffset, MCP_DEFAULTS } from '../middleware.js';
-
-export const name = 'symbol_children';
-
-export async function handler(args, ctx) {
-  const { childrenData } = await ctx.getQueries();
-  return childrenData(args.name, ctx.dbPath, {
-    file: args.file,
-    kind: args.kind,
-    noTests: args.no_tests,
-    limit: Math.min(args.limit ?? MCP_DEFAULTS.context, ctx.MCP_MAX_LIMIT),
-    offset: effectiveOffset(args),
-  });
-}

package/src/presentation/batch.js

@@ -1,26 +0,0 @@
-import { batchData, multiBatchData } from '../features/batch.js';
-
-/**
- * CLI wrapper — calls batchData and prints JSON to stdout.
- */
-export function batch(command, targets, customDbPath, opts = {}) {
-  const data = batchData(command, targets, customDbPath, opts);
-  console.log(JSON.stringify(data, null, 2));
-}
-
-/**
- * CLI wrapper for batch-query — detects multi-command mode (objects with .command)
- * or falls back to single-command batchData (default: 'where').
- */
-export function batchQuery(targets, customDbPath, opts = {}) {
-  const { command: defaultCommand = 'where', ...rest } = opts;
-  const isMulti = targets.length > 0 && typeof targets[0] === 'object' && targets[0].command;
-
-  let data;
-  if (isMulti) {
-    data = multiBatchData(targets, customDbPath, rest);
-  } else {
-    data = batchData(defaultCommand, targets, customDbPath, rest);
-  }
-  console.log(JSON.stringify(data, null, 2));
-}

package/src/presentation/dataflow.js

@@ -1,110 +0,0 @@
-import { dataflowData, dataflowImpactData } from '../features/dataflow.js';
-import { outputResult } from '../infrastructure/result-formatter.js';
-
-/**
- * CLI display for dataflow command.
- */
-export function dataflow(name, customDbPath, opts = {}) {
-  if (opts.impact) {
-    return dataflowImpact(name, customDbPath, opts);
-  }
-
-  const data = dataflowData(name, customDbPath, opts);
-
-  if (outputResult(data, 'results', opts)) return;
-
-  if (data.warning) {
-    console.log(`⚠  ${data.warning}`);
-    return;
-  }
-  if (data.results.length === 0) {
-    console.log(`No symbols matching "${name}".`);
-    return;
-  }
-
-  for (const r of data.results) {
-    console.log(`\n${r.kind} ${r.name}  (${r.file}:${r.line})`);
-    console.log('─'.repeat(60));
-
-    if (r.flowsTo.length > 0) {
-      console.log('\n  Data flows TO:');
-      for (const f of r.flowsTo) {
-        const conf = f.confidence < 1.0 ? ` [${(f.confidence * 100).toFixed(0)}%]` : '';
-        console.log(`    → ${f.target} (${f.file}:${f.line}) arg[${f.paramIndex}]${conf}`);
-      }
-    }
-
-    if (r.flowsFrom.length > 0) {
-      console.log('\n  Data flows FROM:');
-      for (const f of r.flowsFrom) {
-        const conf = f.confidence < 1.0 ? ` [${(f.confidence * 100).toFixed(0)}%]` : '';
-        console.log(`    ← ${f.source} (${f.file}:${f.line}) arg[${f.paramIndex}]${conf}`);
-      }
-    }
-
-    if (r.returns.length > 0) {
-      console.log('\n  Return value consumed by:');
-      for (const c of r.returns) {
-        console.log(`    → ${c.consumer} (${c.file}:${c.line})  ${c.expression}`);
-      }
-    }
-
-    if (r.returnedBy.length > 0) {
-      console.log('\n  Uses return value of:');
-      for (const p of r.returnedBy) {
-        console.log(`    ← ${p.producer} (${p.file}:${p.line})  ${p.expression}`);
-      }
-    }
-
-    if (r.mutates.length > 0) {
-      console.log('\n  Mutates:');
-      for (const m of r.mutates) {
-        console.log(`    ✎ ${m.expression}  (line ${m.line})`);
-      }
-    }
-
-    if (r.mutatedBy.length > 0) {
-      console.log('\n  Mutated by:');
-      for (const m of r.mutatedBy) {
-        console.log(`    ✎ ${m.source} — ${m.expression}  (line ${m.line})`);
-      }
-    }
-  }
-}
-
-/**
- * CLI display for dataflow --impact.
- */
-function dataflowImpact(name, customDbPath, opts = {}) {
-  const data = dataflowImpactData(name, customDbPath, {
-    noTests: opts.noTests,
-    depth: opts.depth ? Number(opts.depth) : 5,
-    file: opts.file,
-    kind: opts.kind,
-    limit: opts.limit,
-    offset: opts.offset,
-  });
-
-  if (outputResult(data, 'results', opts)) return;
-
-  if (data.warning) {
-    console.log(`⚠  ${data.warning}`);
-    return;
-  }
-  if (data.results.length === 0) {
-    console.log(`No symbols matching "${name}".`);
-    return;
-  }
-
-  for (const r of data.results) {
-    console.log(
-      `\n${r.kind} ${r.name}  (${r.file}:${r.line})  — ${r.totalAffected} data-dependent consumer${r.totalAffected !== 1 ? 's' : ''}`,
-    );
-    for (const [level, items] of Object.entries(r.levels)) {
-      console.log(`  Level ${level}:`);
-      for (const item of items) {
-        console.log(`    ${item.name} (${item.file}:${item.line})`);
-      }
-    }
-  }
-}

package/src/presentation/sequence-renderer.js

@@ -1,43 +0,0 @@
-/**
- * Mermaid sequence diagram renderer — pure data → string transform.
- *
- * Converts sequenceData() output into Mermaid sequenceDiagram syntax.
- * No DB access, no I/O — just data in, formatted string out.
- */
-
-/**
- * Escape special Mermaid characters in labels.
- */
-function escapeMermaid(str) {
-  return str
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/:/g, '#colon;')
-    .replace(/"/g, '#quot;');
-}
-
-/**
- * Convert sequenceData result to Mermaid sequenceDiagram syntax.
- * @param {{ participants, messages, truncated, depth }} seqResult
- * @returns {string}
- */
-export function sequenceToMermaid(seqResult) {
-  const lines = ['sequenceDiagram'];
-
-  for (const p of seqResult.participants) {
-    lines.push(`    participant ${p.id} as ${escapeMermaid(p.label)}`);
-  }
-
-  for (const msg of seqResult.messages) {
-    const arrow = msg.type === 'return' ? '-->>' : '->>';
-    lines.push(`    ${msg.from}${arrow}${msg.to}: ${escapeMermaid(msg.label)}`);
-  }
-
-  if (seqResult.truncated && seqResult.participants.length > 0) {
-    lines.push(
-      `    note right of ${seqResult.participants[0].id}: Truncated at depth ${seqResult.depth}`,
-    );
-  }
-
-  return lines.join('\n');
-}