@optave/codegraph 1.4.1 → 2.0.0

package/src/export.js

@@ -24,25 +24,60 @@ export function exportDOT(db, opts = {}) {
     `)
       .all();
 
+    // Try to use directory nodes from DB (built by structure analysis)
+    const hasDirectoryNodes =
+      db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'directory'").get().c > 0;
+
     const dirs = new Map();
     const allFiles = new Set();
     for (const { source, target } of edges) {
       allFiles.add(source);
       allFiles.add(target);
     }
-    for (const file of allFiles) {
-      const dir = path.dirname(file) || '.';
-      if (!dirs.has(dir)) dirs.set(dir, []);
-      dirs.get(dir).push(file);
+
+    if (hasDirectoryNodes) {
+      // Use DB directory structure with cohesion labels
+      const dbDirs = db
+        .prepare(`
+          SELECT n.id, n.name, nm.cohesion
+          FROM nodes n
+          LEFT JOIN node_metrics nm ON n.id = nm.node_id
+          WHERE n.kind = 'directory'
+        `)
+        .all();
+
+      for (const d of dbDirs) {
+        const containedFiles = db
+          .prepare(`
+            SELECT n.name FROM edges e
+            JOIN nodes n ON e.target_id = n.id
+            WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'file'
+          `)
+          .all(d.id)
+          .map((r) => r.name)
+          .filter((f) => allFiles.has(f));
+
+        if (containedFiles.length > 0) {
+          dirs.set(d.name, { files: containedFiles, cohesion: d.cohesion });
+        }
+      }
+    } else {
+      // Fallback: reconstruct from path.dirname()
+      for (const file of allFiles) {
+        const dir = path.dirname(file) || '.';
+        if (!dirs.has(dir)) dirs.set(dir, { files: [], cohesion: null });
+        dirs.get(dir).files.push(file);
+      }
     }
 
     let clusterIdx = 0;
-    for (const [dir, files] of [...dirs].sort()) {
+    for (const [dir, info] of [...dirs].sort((a, b) => a[0].localeCompare(b[0]))) {
       lines.push(`  subgraph cluster_${clusterIdx++} {`);
-      lines.push(`    label="${dir}";`);
+      const cohLabel = info.cohesion !== null ? ` (cohesion: ${info.cohesion.toFixed(2)})` : '';
+      lines.push(`    label="${dir}${cohLabel}";`);
       lines.push(`    style=dashed;`);
       lines.push(`    color="#999999";`);
-      for (const f of files) {
+      for (const f of info.files) {
         const label = path.basename(f);
         lines.push(`    "${f}" [label="${label}"];`);
       }
@@ -62,7 +97,7 @@ export function exportDOT(db, opts = {}) {
       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')
+      WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module') AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
       AND e.kind = 'calls'
     `)
       .all();
@@ -111,7 +146,7 @@ export function exportMermaid(db, opts = {}) {
       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')
+      WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module') AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
       AND e.kind = 'calls'
     `)
       .all();

package/src/index.js

@@ -46,5 +46,26 @@ export {
   moduleMapData,
   queryNameData,
 } from './queries.js';
+// Registry (multi-repo)
+export {
+  listRepos,
+  loadRegistry,
+  pruneRegistry,
+  REGISTRY_PATH,
+  registerRepo,
+  resolveRepoDbPath,
+  saveRegistry,
+  unregisterRepo,
+} from './registry.js';
+// Structure analysis
+export {
+  buildStructure,
+  formatHotspots,
+  formatModuleBoundaries,
+  formatStructure,
+  hotspotsData,
+  moduleBoundariesData,
+  structureData,
+} from './structure.js';
 // Watch mode
 export { watchProject } from './watcher.js';

package/src/mcp.js

@@ -9,7 +9,14 @@ import { createRequire } from 'node:module';
 import { findCycles } from './cycles.js';
 import { findDbPath } from './db.js';
 
-const TOOLS = [
+const REPO_PROP = {
+  repo: {
+    type: 'string',
+    description: 'Repository name from the registry (omit for local project)',
+  },
+};
+
+const BASE_TOOLS = [
   {
     name: 'query_function',
     description: 'Find callers and callees of a function by name',
@@ -143,7 +150,7 @@ const TOOLS = [
   {
     name: 'list_functions',
     description:
-      'List functions, methods, and classes in the codebase, optionally filtered by file or name pattern',
+      'List functions, methods, classes, structs, enums, traits, records, and modules in the codebase, optionally filtered by file or name pattern',
     inputSchema: {
       type: 'object',
       properties: {
@@ -153,15 +160,91 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'structure',
+    description:
+      'Show project structure with directory hierarchy, cohesion scores, and per-file metrics',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        directory: { type: 'string', description: 'Filter to a specific directory path' },
+        depth: { type: 'number', description: 'Max directory depth to show' },
+        sort: {
+          type: 'string',
+          enum: ['cohesion', 'fan-in', 'fan-out', 'density', 'files'],
+          description: 'Sort directories by metric',
+        },
+      },
+    },
+  },
+  {
+    name: 'hotspots',
+    description:
+      'Find structural hotspots: files or directories with extreme fan-in, fan-out, or symbol density',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        metric: {
+          type: 'string',
+          enum: ['fan-in', 'fan-out', 'density', 'coupling'],
+          description: 'Metric to rank by',
+        },
+        level: {
+          type: 'string',
+          enum: ['file', 'directory'],
+          description: 'Rank files or directories',
+        },
+        limit: { type: 'number', description: 'Number of results to return', default: 10 },
+      },
+    },
+  },
 ];
 
-export { TOOLS };
+const LIST_REPOS_TOOL = {
+  name: 'list_repos',
+  description: 'List all repositories registered in the codegraph registry',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+  },
+};
+
+/**
+ * Build the tool list based on multi-repo mode.
+ * @param {boolean} multiRepo - If true, inject `repo` prop into each tool and append `list_repos`
+ * @returns {object[]}
+ */
+function buildToolList(multiRepo) {
+  if (!multiRepo) return BASE_TOOLS;
+  return [
+    ...BASE_TOOLS.map((tool) => ({
+      ...tool,
+      inputSchema: {
+        ...tool.inputSchema,
+        properties: { ...tool.inputSchema.properties, ...REPO_PROP },
+      },
+    })),
+    LIST_REPOS_TOOL,
+  ];
+}
+
+// Backward-compatible export: full multi-repo tool list
+const TOOLS = buildToolList(true);
+
+export { TOOLS, buildToolList };
 
 /**
  * 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
  */
-export async function startMCPServer(customDbPath) {
+export async function startMCPServer(customDbPath, options = {}) {
+  const { allowedRepos } = options;
+  const multiRepo = options.multiRepo || !!allowedRepos;
   let Server, StdioServerTransport;
   try {
     const sdk = await import('@modelcontextprotocol/sdk/server/index.js');
@@ -196,13 +279,37 @@ export async function startMCPServer(customDbPath) {
     { capabilities: { tools: {} } },
   );
 
-  server.setRequestHandler('tools/list', async () => ({ tools: TOOLS }));
+  server.setRequestHandler('tools/list', async () => ({ tools: buildToolList(multiRepo) }));
 
   server.setRequestHandler('tools/call', async (request) => {
     const { name, arguments: args } = request.params;
-    const dbPath = customDbPath || undefined;
 
     try {
+      if (!multiRepo && args.repo) {
+        throw new Error(
+          'Multi-repo access is disabled. Restart with `codegraph mcp --multi-repo` to access other repositories.',
+        );
+      }
+      if (!multiRepo && name === 'list_repos') {
+        throw new Error(
+          'Multi-repo access is disabled. Restart with `codegraph mcp --multi-repo` to list repositories.',
+        );
+      }
+
+      let dbPath = customDbPath || undefined;
+      if (args.repo) {
+        if (allowedRepos && !allowedRepos.includes(args.repo)) {
+          throw new Error(`Repository "${args.repo}" is not in the allowed repos list.`);
+        }
+        const { resolveRepoDbPath } = await import('./registry.js');
+        const resolved = resolveRepoDbPath(args.repo);
+        if (!resolved)
+          throw new Error(
+            `Repository "${args.repo}" not found in registry or its database is missing.`,
+          );
+        dbPath = resolved;
+      }
+
       let result;
       switch (name) {
         case 'query_function':
@@ -296,6 +403,33 @@ export async function startMCPServer(customDbPath) {
             noTests: args.no_tests,
           });
           break;
+        case 'structure': {
+          const { structureData } = await import('./structure.js');
+          result = structureData(dbPath, {
+            directory: args.directory,
+            depth: args.depth,
+            sort: args.sort,
+          });
+          break;
+        }
+        case 'hotspots': {
+          const { hotspotsData } = await import('./structure.js');
+          result = hotspotsData(dbPath, {
+            metric: args.metric,
+            level: args.level,
+            limit: args.limit,
+          });
+          break;
+        }
+        case 'list_repos': {
+          const { listRepos } = await import('./registry.js');
+          let repos = listRepos();
+          if (allowedRepos) {
+            repos = repos.filter((r) => allowedRepos.includes(r.name));
+          }
+          result = { repos };
+          break;
+        }
         default:
           return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
       }

package/src/parser.js

@@ -2,7 +2,6 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Language, Parser } from 'web-tree-sitter';
-import { normalizePath } from './constants.js';
 import { warn } from './logger.js';
 import { loadNative } from './native.js';
 
@@ -731,7 +730,7 @@ export function extractGoSymbols(tree, _filePath) {
             if (typeNode.type === 'struct_type') {
               definitions.push({
                 name: nameNode.text,
-                kind: 'class',
+                kind: 'struct',
                 line: node.startPosition.row + 1,
                 endLine: nodeEndLine(node),
               });
@@ -876,7 +875,7 @@ export function extractRustSymbols(tree, _filePath) {
         if (nameNode) {
           definitions.push({
             name: nameNode.text,
-            kind: 'class',
+            kind: 'struct',
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
           });
@@ -889,7 +888,7 @@ export function extractRustSymbols(tree, _filePath) {
         if (nameNode) {
           definitions.push({
             name: nameNode.text,
-            kind: 'class',
+            kind: 'enum',
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
           });
@@ -902,7 +901,7 @@ export function extractRustSymbols(tree, _filePath) {
         if (nameNode) {
           definitions.push({
             name: nameNode.text,
-            kind: 'interface',
+            kind: 'trait',
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
           });
@@ -1186,7 +1185,7 @@ export function extractJavaSymbols(tree, _filePath) {
         if (nameNode) {
           definitions.push({
             name: nameNode.text,
-            kind: 'class',
+            kind: 'enum',
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
           });
@@ -1320,7 +1319,7 @@ export function extractCSharpSymbols(tree, _filePath) {
         if (nameNode) {
           definitions.push({
             name: nameNode.text,
-            kind: 'class',
+            kind: 'struct',
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
           });
@@ -1334,7 +1333,7 @@ export function extractCSharpSymbols(tree, _filePath) {
         if (nameNode) {
           definitions.push({
             name: nameNode.text,
-            kind: 'class',
+            kind: 'record',
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
           });
@@ -1378,7 +1377,7 @@ export function extractCSharpSymbols(tree, _filePath) {
         if (nameNode) {
           definitions.push({
             name: nameNode.text,
-            kind: 'class',
+            kind: 'enum',
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
           });
@@ -1588,7 +1587,7 @@ export function extractRubySymbols(tree, _filePath) {
         if (nameNode) {
           definitions.push({
             name: nameNode.text,
-            kind: 'class',
+            kind: 'module',
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
           });
@@ -1818,7 +1817,7 @@ export function extractPHPSymbols(tree, _filePath) {
         if (nameNode) {
           definitions.push({
             name: nameNode.text,
-            kind: 'interface',
+            kind: 'trait',
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
           });
@@ -1831,7 +1830,7 @@ export function extractPHPSymbols(tree, _filePath) {
         if (nameNode) {
           definitions.push({
             name: nameNode.text,
-            kind: 'class',
+            kind: 'enum',
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
           });
@@ -2145,7 +2144,7 @@ export async function parseFilesAuto(filePaths, rootDir, opts = {}) {
     const nativeResults = native.parseFiles(filePaths, rootDir);
     for (const r of nativeResults) {
       if (!r) continue;
-      const relPath = normalizePath(path.relative(rootDir, r.file));
+      const relPath = path.relative(rootDir, r.file).split(path.sep).join('/');
       result.set(relPath, normalizeNativeSymbols(r));
     }
     return result;
@@ -2163,7 +2162,7 @@ export async function parseFilesAuto(filePaths, rootDir, opts = {}) {
     }
     const symbols = wasmExtractSymbols(parsers, filePath, code);
     if (symbols) {
-      const relPath = normalizePath(path.relative(rootDir, filePath));
+      const relPath = path.relative(rootDir, filePath).split(path.sep).join('/');
       result.set(relPath, symbols);
     }
   }

package/src/registry.js

@@ -0,0 +1,145 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { debug, warn } from './logger.js';
+
+export const REGISTRY_PATH = path.join(os.homedir(), '.codegraph', 'registry.json');
+
+/**
+ * Load the registry from disk.
+ * Returns `{ repos: {} }` on missing or corrupt file.
+ */
+export function loadRegistry(registryPath = REGISTRY_PATH) {
+  try {
+    const raw = fs.readFileSync(registryPath, 'utf-8');
+    const data = JSON.parse(raw);
+    if (!data || typeof data.repos !== 'object') return { repos: {} };
+    return data;
+  } catch {
+    return { repos: {} };
+  }
+}
+
+/**
+ * Persist the registry to disk (atomic write via temp + rename).
+ * Creates the parent directory if needed.
+ */
+export function saveRegistry(registry, registryPath = REGISTRY_PATH) {
+  const dir = path.dirname(registryPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const tmp = `${registryPath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(registry, null, 2), 'utf-8');
+  fs.renameSync(tmp, registryPath);
+}
+
+/**
+ * Register a project directory. Idempotent.
+ * Name defaults to `path.basename(rootDir)`.
+ *
+ * When no explicit name is provided and the basename already exists
+ * pointing to a different path, auto-suffixes (`api` → `api-2`, `api-3`, …).
+ * Re-registering the same path updates in place. Explicit names always overwrite.
+ */
+export function registerRepo(rootDir, name, registryPath = REGISTRY_PATH) {
+  const absRoot = path.resolve(rootDir);
+  const baseName = name || path.basename(absRoot);
+  const registry = loadRegistry(registryPath);
+
+  let repoName = baseName;
+
+  // Auto-suffix only when no explicit name was provided
+  if (!name) {
+    const existing = registry.repos[baseName];
+    if (existing && path.resolve(existing.path) !== absRoot) {
+      // Basename collision with a different path — find next available suffix
+      let suffix = 2;
+      while (registry.repos[`${baseName}-${suffix}`]) {
+        const entry = registry.repos[`${baseName}-${suffix}`];
+        if (path.resolve(entry.path) === absRoot) {
+          // Already registered under this suffixed name — update in place
+          repoName = `${baseName}-${suffix}`;
+          break;
+        }
+        suffix++;
+      }
+      if (repoName === baseName) {
+        repoName = `${baseName}-${suffix}`;
+      }
+    }
+  }
+
+  registry.repos[repoName] = {
+    path: absRoot,
+    dbPath: path.join(absRoot, '.codegraph', 'graph.db'),
+    addedAt: new Date().toISOString(),
+  };
+
+  saveRegistry(registry, registryPath);
+  debug(`Registered repo "${repoName}" at ${absRoot}`);
+  return { name: repoName, entry: registry.repos[repoName] };
+}
+
+/**
+ * Remove a repo from the registry. Returns false if not found.
+ */
+export function unregisterRepo(name, registryPath = REGISTRY_PATH) {
+  const registry = loadRegistry(registryPath);
+  if (!registry.repos[name]) return false;
+  delete registry.repos[name];
+  saveRegistry(registry, registryPath);
+  return true;
+}
+
+/**
+ * List all registered repos, sorted by name.
+ */
+export function listRepos(registryPath = REGISTRY_PATH) {
+  const registry = loadRegistry(registryPath);
+  return Object.entries(registry.repos)
+    .map(([name, entry]) => ({
+      name,
+      path: entry.path,
+      dbPath: entry.dbPath,
+      addedAt: entry.addedAt,
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Resolve a repo name to its database path.
+ * Returns undefined if the repo is not found or its DB file is missing.
+ */
+export function resolveRepoDbPath(name, registryPath = REGISTRY_PATH) {
+  const registry = loadRegistry(registryPath);
+  const entry = registry.repos[name];
+  if (!entry) return undefined;
+  if (!fs.existsSync(entry.dbPath)) {
+    warn(`Registry: database missing for "${name}" at ${entry.dbPath}`);
+    return undefined;
+  }
+  return entry.dbPath;
+}
+
+/**
+ * Remove registry entries whose repo directory no longer exists on disk.
+ * Only checks the repo directory (not the DB file — a missing DB is normal pre-build state).
+ * Returns an array of `{ name, path }` for each pruned entry.
+ */
+export function pruneRegistry(registryPath = REGISTRY_PATH) {
+  const registry = loadRegistry(registryPath);
+  const pruned = [];
+
+  for (const [name, entry] of Object.entries(registry.repos)) {
+    if (!fs.existsSync(entry.path)) {
+      pruned.push({ name, path: entry.path });
+      delete registry.repos[name];
+    }
+  }
+
+  if (pruned.length > 0) {
+    saveRegistry(registry, registryPath);
+  }
+
+  return pruned;
+}