feat: louvain community detection for module boundary analysis (#133)

Add `codegraph communities` command that runs Louvain clustering on the
dependency graph, compares discovered communities against directory
structure, and surfaces architectural drift (split/merge candidates,
drift score). Supports file-level (default) and function-level modes,
configurable resolution, and drift-only output. Integrated into stats,
MCP, and programmatic API.

Impact: 9 functions changed, 8 affected

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: carlos-alm

package-lock.json

@@ -57,6 +57,8 @@
   "dependencies": {
     "better-sqlite3": "^12.6.2",
     "commander": "^14.0.3",
+    "graphology": "^0.25.4",
+    "graphology-communities-louvain": "^2.0.2",
     "web-tree-sitter": "^0.26.5"
   },
   "peerDependencies": {

package.json

@@ -137,8 +137,8 @@ program
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
-  .action((opts) => {
-    stats(opts.db, { noTests: resolveNoTests(opts), json: opts.json });
+  .action(async (opts) => {
+    await stats(opts.db, { noTests: resolveNoTests(opts), json: opts.json });
   });
 
 program
@@ -742,6 +742,27 @@ program
     });
   });
 
+program
+  .command('communities')
+  .description('Detect natural module boundaries using Louvain community detection')
+  .option('--functions', 'Function-level instead of file-level')
+  .option('--resolution <n>', 'Louvain resolution parameter (default 1.0)', '1.0')
+  .option('--drift', 'Show only drift analysis')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-j, --json', 'Output as JSON')
+  .action(async (opts) => {
+    const { communities } = await import('./communities.js');
+    communities(opts.db, {
+      functions: opts.functions,
+      resolution: parseFloat(opts.resolution),
+      drift: opts.drift,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+    });
+  });
+
 program
   .command('branch-compare <base> <target>')
   .description('Compare code structure between two branches/refs')