feat: harden multi-repo registry and add structural analysis

Registry hardening (3 of 4 audit concerns):
- Add pruneRegistry() to remove stale entries where repo dir no longer exists
- Add --repos allowlist on MCP server for repo-level access control
- Auto-suffix name collisions in registerRepo (api → api-2) when no explicit name

Structural analysis (new):
- Add src/structure.js with directory nodes, containment edges, and metrics
  (symbol density, avg fan-out, cohesion scores)
- Add structure/hotspots CLI commands
- Extend DOT/Mermaid export with directory clusters
- Add 'directory' and 'contains' kinds to DB schema

CLI additions:
- codegraph registry prune
- codegraph mcp --repos <names>
- codegraph structure [dir]
- codegraph hotspots

Author: github-actions[bot]

src/builder.js

@@ -10,18 +10,20 @@ import { computeConfidence, resolveImportPath, resolveImportsBatch } from './res
 
 export { resolveImportPath } from './resolve.js';
 
-export function collectFiles(dir, files = [], config = {}) {
+export function collectFiles(dir, files = [], config = {}, directories = null) {
+  const trackDirs = directories !== null;
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     warn(`Cannot read directory ${dir}: ${err.message}`);
-    return files;
+    return trackDirs ? { files, directories } : files;
   }
 
   // Merge config ignoreDirs with defaults
   const extraIgnore = config.ignoreDirs ? new Set(config.ignoreDirs) : null;
 
+  let hasFiles = false;
   for (const entry of entries) {
     if (entry.name.startsWith('.') && entry.name !== '.') {
       if (IGNORE_DIRS.has(entry.name)) continue;
@@ -32,12 +34,16 @@ export function collectFiles(dir, files = [], config = {}) {
 
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      collectFiles(full, files, config);
+      collectFiles(full, files, config, directories);
     } else if (EXTENSIONS.has(path.extname(entry.name))) {
       files.push(full);
+      hasFiles = true;
     }
   }
-  return files;
+  if (trackDirs && hasFiles) {
+    directories.add(dir);
+  }
+  return trackDirs ? { files, directories } : files;
 }
 
 export function loadPathAliases(rootDir) {
@@ -163,7 +169,9 @@ export async function buildGraph(rootDir, opts = {}) {
     );
   }
 
-  const files = collectFiles(rootDir, [], config);
+  const collected = collectFiles(rootDir, [], config, new Set());
+  const files = collected.files;
+  const discoveredDirs = collected.directories;
   console.log(`Found ${files.length} files to parse`);
 
   // Check for incremental build
@@ -179,23 +187,28 @@ export async function buildGraph(rootDir, opts = {}) {
 
   if (isFullBuild) {
     db.exec(
-      'PRAGMA foreign_keys = OFF; DELETE FROM edges; DELETE FROM nodes; PRAGMA foreign_keys = ON;',
+      'PRAGMA foreign_keys = OFF; DELETE FROM node_metrics; DELETE FROM edges; DELETE FROM nodes; PRAGMA foreign_keys = ON;',
     );
   } else {
     console.log(`Incremental: ${changed.length} changed, ${removed.length} removed`);
-    // Remove nodes/edges for changed and removed files
+    // Remove metrics/edges/nodes for changed and removed files
     const deleteNodesForFile = db.prepare('DELETE FROM nodes WHERE file = ?');
     const deleteEdgesForFile = db.prepare(`
       DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = @f)
       OR target_id IN (SELECT id FROM nodes WHERE file = @f)
     `);
+    const deleteMetricsForFile = db.prepare(
+      'DELETE FROM node_metrics WHERE node_id IN (SELECT id FROM nodes WHERE file = ?)',
+    );
     for (const relPath of removed) {
       deleteEdgesForFile.run({ f: relPath });
+      deleteMetricsForFile.run(relPath);
       deleteNodesForFile.run(relPath);
     }
     for (const item of changed) {
       const relPath = item.relPath || normalizePath(path.relative(rootDir, item.file));
       deleteEdgesForFile.run({ f: relPath });
+      deleteMetricsForFile.run(relPath);
       deleteNodesForFile.run(relPath);
     }
   }
@@ -539,6 +552,30 @@ export async function buildGraph(rootDir, opts = {}) {
   });
   buildEdges();
 
+  // Build line count map for structure metrics
+  const lineCountMap = new Map();
+  for (const [relPath] of fileSymbols) {
+    const absPath = path.join(rootDir, relPath);
+    try {
+      const content = fs.readFileSync(absPath, 'utf-8');
+      lineCountMap.set(relPath, content.split('\n').length);
+    } catch {
+      lineCountMap.set(relPath, 0);
+    }
+  }
+
+  // Build directory structure, containment edges, and metrics
+  const relDirs = new Set();
+  for (const absDir of discoveredDirs) {
+    relDirs.add(normalizePath(path.relative(rootDir, absDir)));
+  }
+  try {
+    const { buildStructure } = await import('./structure.js');
+    buildStructure(db, fileSymbols, rootDir, lineCountMap, relDirs);
+  } catch (err) {
+    debug(`Structure analysis failed: ${err.message}`);
+  }
+
   const nodeCount = db.prepare('SELECT COUNT(*) as c FROM nodes').get().c;
   console.log(`Graph built: ${nodeCount} nodes, ${edgeCount} edges`);
   console.log(`Stored in ${dbPath}`);

src/cli.js

@@ -19,7 +19,13 @@ import {
   moduleMap,
   queryName,
 } from './queries.js';
-import { listRepos, REGISTRY_PATH, registerRepo, unregisterRepo } from './registry.js';
+import {
+  listRepos,
+  pruneRegistry,
+  REGISTRY_PATH,
+  registerRepo,
+  unregisterRepo,
+} from './registry.js';
 import { watchProject } from './watcher.js';
 
 const program = new Command();
@@ -187,9 +193,14 @@ program
   .command('mcp')
   .description('Start MCP (Model Context Protocol) server for AI assistant integration')
   .option('-d, --db <path>', 'Path to graph.db')
+  .option('--repos <names>', 'Comma-separated list of allowed repo names (restricts access)')
   .action(async (opts) => {
     const { startMCPServer } = await import('./mcp.js');
-    await startMCPServer(opts.db);
+    const mcpOpts = {};
+    if (opts.repos) {
+      mcpOpts.allowedRepos = opts.repos.split(',').map((s) => s.trim());
+    }
+    await startMCPServer(opts.db, mcpOpts);
   });
 
 // ─── Registry commands ──────────────────────────────────────────────────
@@ -242,6 +253,21 @@ registry
     }
   });
 
+registry
+  .command('prune')
+  .description('Remove registry entries whose directories no longer exist')
+  .action(() => {
+    const pruned = pruneRegistry();
+    if (pruned.length === 0) {
+      console.log('No stale entries found.');
+    } else {
+      for (const entry of pruned) {
+        console.log(`Pruned "${entry.name}" (${entry.path})`);
+      }
+      console.log(`\nRemoved ${pruned.length} stale ${pruned.length === 1 ? 'entry' : 'entries'}.`);
+    }
+  });
+
 // ─── Embedding commands ─────────────────────────────────────────────────
 
 program
@@ -295,6 +321,53 @@ program
     });
   });
 
+program
+  .command('structure [dir]')
+  .description(
+    'Show project directory structure with hierarchy, cohesion scores, and per-file metrics',
+  )
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--depth <n>', 'Max directory depth')
+  .option('--sort <metric>', 'Sort by: cohesion | fan-in | fan-out | density | files', 'files')
+  .option('-j, --json', 'Output as JSON')
+  .action(async (dir, opts) => {
+    const { structureData, formatStructure } = await import('./structure.js');
+    const data = structureData(opts.db, {
+      directory: dir,
+      depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
+      sort: opts.sort,
+    });
+    if (opts.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      console.log(formatStructure(data));
+    }
+  });
+
+program
+  .command('hotspots')
+  .description(
+    'Find structural hotspots: files or directories with extreme fan-in, fan-out, or symbol density',
+  )
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-n, --limit <number>', 'Number of results', '10')
+  .option('--metric <metric>', 'fan-in | fan-out | density | coupling', 'fan-in')
+  .option('--level <level>', 'file | directory', 'file')
+  .option('-j, --json', 'Output as JSON')
+  .action(async (opts) => {
+    const { hotspotsData, formatHotspots } = await import('./structure.js');
+    const data = hotspotsData(opts.db, {
+      metric: opts.metric,
+      level: opts.level,
+      limit: parseInt(opts.limit, 10),
+    });
+    if (opts.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      console.log(formatHotspots(data));
+    }
+  });
+
 program
   .command('watch [dir]')
   .description('Watch project for file changes and incrementally update the graph')

src/db.js

@@ -33,6 +33,19 @@ export const MIGRATIONS = [
       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);
+      CREATE TABLE IF NOT EXISTS node_metrics (
+        node_id INTEGER PRIMARY KEY,
+        line_count INTEGER,
+        symbol_count INTEGER,
+        import_count INTEGER,
+        export_count INTEGER,
+        fan_in INTEGER,
+        fan_out INTEGER,
+        cohesion REAL,
+        file_count INTEGER,
+        FOREIGN KEY(node_id) REFERENCES nodes(id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_node_metrics_node ON node_metrics(node_id);
     `,
   },
   {

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}"];`);
       }

src/index.js

@@ -50,11 +50,22 @@ export {
 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';