@ophan/cli 0.0.1 → 0.0.3

package/README.md

@@ -1,82 +1,72 @@
 # @ophan/cli
 
-Command-line interface for analyzing codebases and managing Ophan databases.
+AI-powered security analysis and documentation for your codebase. Detects vulnerabilities, maps data flows, and auto-documents every function — from the command line.
 
-## Usage
+Part of [Ophan](https://ophan.dev). Works standalone or alongside the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ophan.ophan).
 
-### Repository Analysis
-```bash
-# Analyze a repo (creates .ophan/index.db)
-npx ophan analyze --path /path/to/repo
+## Quick Start
 
-# Or as dev dependency
-npm install --save-dev ophan
-npx ophan analyze
+```bash
+npx @ophan/cli analyze
 ```
 
-### Commands
-- `ophan analyze` — Scan repo, extract functions, analyze with Claude, store by content hash
-- `ophan sync` — Push/pull analysis to/from Supabase (requires auth)
-- `ophan gc` — Garbage collect orphaned analysis entries (manual only, never automatic, 30-day grace period)
+That's it. Ophan scans your repo, extracts every function, and sends them to Claude for security analysis and documentation. Results are stored locally in `.ophan/index.db`.
 
-## How Analysis Works
+You'll need an [Anthropic API key](https://console.anthropic.com/) set as `ANTHROPIC_API_KEY` in your environment or a `.env` file.
 
-### Initial Run
-1. Discovers all TypeScript/JavaScript source files
-2. Extracts functions, computes SHA256 content hash for each
-3. Checks local DB — skips functions with existing analysis for that hash
-4. Sends new functions to Claude for analysis
-5. Stores results in `function_analysis` (keyed by content_hash)
-6. Updates `file_functions` with file path, function name, content_hash, mtime
+## What You Get
 
-### Incremental Updates
-1. Checks `file_mtime` in `file_functions` — skips entirely unchanged files (no parsing needed)
-2. Re-parses changed files, re-hashes functions
-3. Only analyzes functions with new/unknown hashes
-4. Updates `file_functions` mappings
+For every function in your codebase:
 
-### Garbage Collection
-`ophan gc` is manual only — never runs automatically. This protects against branch switching scenarios (e.g. function deleted on feature branch but still exists on main).
+- **Security analysis** — SQL injection, XSS, hardcoded secrets, path traversal, unsanitized input
+- **Data flow tags** — which functions touch user input, PII, credentials, databases, external APIs
+- **Documentation** — plain-English descriptions, parameter docs, return type docs
 
-How it works:
-1. Scans codebase, computes all current hashes
-2. Compares to stored `function_analysis` entries
-3. Only deletes entries not seen in grace period (default 30 days, configurable)
-4. Updates `last_referenced_at` in Supabase for synced entries
-5. If synced, GC'd entries can be re-downloaded on next sync instead of re-analyzed
+## Commands
 
-`file_functions` is ephemeral — rebuilt on every scan. `function_analysis` is persistent until explicit GC.
+```bash
+npx @ophan/cli analyze          # Analyze current directory
+npx @ophan/cli analyze --path . # Analyze a specific path
+npx @ophan/cli sync             # Sync results to ophan.dev (optional)
+npx @ophan/cli gc               # Clean up old analysis entries
+```
 
-### Sync
-`ophan sync` pushes/pulls `function_analysis` rows to/from Supabase:
-- Insert-only (content-addressed = immutable, no conflicts)
-- Free users: scoped to `user_id`
-- Team users: scoped to `team_id` (new members pull existing analysis)
+### As a dev dependency
 
-## Design Principles
+```bash
+npm install --save-dev @ophan/cli
+npx @ophan/cli analyze
+```
 
-### Local-First
-All analysis stored in per-repo `.ophan/index.db` (gitignored). No cloud required for core functionality. Supabase sync is optional.
+Add to your team's repo so everyone gets the CLI on `npm install`. Analysis is cached by content hash — unchanged functions are never re-analyzed.
 
-### Dev Dependency Model
-Add to `devDependencies` — one engineer installs, whole team gets CLI on `npm install`. Bottom-up adoption path.
+## How It Works
 
-### Non-Invasive
-Database in hidden `.ophan/` directory, gitignored. Does not modify source code or project configuration.
+1. Parses your source files using language-native ASTs (TypeScript compiler API, Python's `ast` module)
+2. Extracts every function and computes a SHA256 content hash
+3. Skips functions that haven't changed since last analysis
+4. Sends new/changed functions to Claude for security and documentation analysis
+5. Stores results locally in `.ophan/index.db` (gitignored)
 
-### Content-Addressed
-Analysis keyed by function content hash, not file path. Branch-agnostic, merge-friendly, deduplication built in.
+Supports **TypeScript**, **JavaScript**, and **Python**.
+
+## Cloud Sync
+
+Optionally sync your analysis to [ophan.dev](https://ophan.dev) for a web dashboard, team sharing, and cross-machine access.
+
+```bash
+npx @ophan/cli login             # Authenticate with ophan.dev
+npx @ophan/cli analyze           # Auto-pulls from cloud, then analyzes remaining
+npx @ophan/cli sync              # Push new results to cloud
+```
 
-## Output
+## Resources
 
-Creates `.ophan/index.db` containing:
-- `function_analysis` — content_hash, analysis JSON, model version, timestamp
-- `file_functions` — file path, function name, content_hash, file mtime
+- [Documentation](https://docs.ophan.dev)
+- [CLI Reference](https://docs.ophan.dev/cli/commands)
+- [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=ophan.ophan)
+- [GitHub](https://github.com/nicholasgriffintn/ophan)
 
-## CI/CD Integration
+## License
 
-### GitHub Action (Planned)
-Run `ophan analyze` on PRs:
-- Comment with new function documentation
-- Fail if new security warnings introduced
-- Show data flow changes in PR review
+MIT

package/dist/auth.js

@@ -113,7 +113,7 @@ async function login(webappUrl, timeoutMs = 120000) {
     return new Promise((resolve, reject) => {
         const timeout = setTimeout(() => {
             server.close();
-            reject(new Error("Login timed out. Please try again with `ophan login`."));
+            reject(new Error("Login timed out. Please try again with `npx @ophan/cli login`."));
         }, timeoutMs);
         const server = http.createServer(async (req, res) => {
             const url = new URL(req.url || "/", `http://localhost:${port}`);
@@ -196,7 +196,7 @@ async function login(webappUrl, timeoutMs = 120000) {
 async function getAuthenticatedClient() {
     const creds = readCredentials();
     if (!creds) {
-        throw new Error("Not logged in. Run `ophan login` first.");
+        throw new Error("Not logged in. Run `npx @ophan/cli login` first.");
     }
     const supabase = (0, supabase_js_1.createClient)(creds.api_url, creds.api_key, {
         auth: {
@@ -224,7 +224,7 @@ async function getAuthenticatedClient() {
         refresh_token: creds.refresh_token,
     });
     if (error || !data.session) {
-        throw new Error(`Session expired or invalid. Run \`ophan login\` again.\n  ${error?.message || "No session returned"}`);
+        throw new Error(`Session expired or invalid. Run \`npx @ophan/cli login\` again.\n  ${error?.message || "No session returned"}`);
     }
     // Persist the new tokens so next invocation can use the fresh access_token
     // without consuming the refresh token again

package/dist/index.js

@@ -46,11 +46,16 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 require("dotenv/config");
 const commander_1 = require("commander");
 const core_1 = require("@ophan/core");
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
 const auth_1 = require("./auth");
 const sync_1 = require("./sync");
 const watch_1 = require("./watch");
@@ -64,7 +69,7 @@ program
  * Returns undefined if user isn't logged in or repo doesn't exist in Supabase.
  * Silent — never fails the analyze command.
  */
-async function createPullFn(rootPath) {
+async function createPullFn(rootPath, onProgress) {
     const creds = (0, auth_1.readCredentials)();
     if (!creds)
         return undefined;
@@ -79,8 +84,14 @@ async function createPullFn(rootPath) {
             .single();
         if (!repo)
             return undefined;
+        const log = onProgress ?? ((step) => console.log(`  ${step}`));
         return async (hashes) => {
-            await (0, sync_1.pullFromSupabase)(rootPath, supabase, userId, repo.id, hashes, (step) => console.log(`  ${step}`));
+            try {
+                await (0, sync_1.pullFromSupabase)(rootPath, supabase, userId, repo.id, hashes, log);
+            }
+            catch {
+                // Pull is a non-critical optimization — silently degrade
+            }
         };
     }
     catch {
@@ -96,7 +107,13 @@ async function runAnalyze(rootPath) {
             process.stdout.cursorTo(0);
         }
         process.stdout.write(`  [${current}/${total}] ${file}\n`);
-    }, pullFn);
+    }, pullFn, (analyzed, total) => {
+        if (process.stdout.isTTY) {
+            process.stdout.clearLine(0);
+            process.stdout.cursorTo(0);
+        }
+        process.stdout.write(`  Analyzing: ${analyzed}/${total} functions`);
+    });
     console.log(`\n✅ Done! ${result.analyzed} analyzed, ${result.skipped} cached` +
         (result.pulled ? ` (${result.pulled} from cloud)` : "") +
         ` across ${result.files} files` +
@@ -115,10 +132,29 @@ program
     .description("Remove orphaned analysis entries (manual, safe for branch switching)")
     .option("-p, --path <path>", "Path to repository", process.cwd())
     .option("-d, --days <days>", "Grace period in days", "30")
+    .option("-f, --force", "Run GC even when not on default branch")
     .action(async (options) => {
     const rootPath = path.resolve(options.path);
     const maxAgeDays = parseInt(options.days, 10);
     const dbPath = path.join(rootPath, ".ophan", "index.db");
+    // Branch safety check — GC on a feature branch can orphan
+    // hashes that only exist on the default branch
+    const currentBranch = (0, sync_1.getGitBranch)(rootPath);
+    if (currentBranch !== null) {
+        const defaultBranch = (0, sync_1.getDefaultBranch)(rootPath);
+        if (currentBranch !== defaultBranch && !options.force) {
+            console.error(`⚠️  You're on branch '${currentBranch}', not '${defaultBranch}'.\n` +
+                `   Running GC on a feature branch can delete analysis for functions\n` +
+                `   that only exist on '${defaultBranch}'. If synced, these deletions\n` +
+                `   propagate to the cloud.\n\n` +
+                `   Switch to '${defaultBranch}' first, or use --force to proceed.`);
+            process.exit(1);
+        }
+        if (currentBranch !== defaultBranch && options.force) {
+            console.warn(`⚠️  Running GC on branch '${currentBranch}' (default: '${defaultBranch}').\n` +
+                `   Proceeding with --force.\n`);
+        }
+    }
     console.log("🧹 Refreshing file index...\n");
     await (0, core_1.refreshFileIndex)(rootPath, (current, total, file) => {
         if (process.stdout.isTTY) {
@@ -144,7 +180,7 @@ program
         try {
             await (0, auth_1.getAuthenticatedClient)();
             console.log(`  Already logged in as ${existing.email}`);
-            console.log(`  Run \`ophan logout\` first to switch accounts.`);
+            console.log(`  Run \`npx @ophan/cli logout\` first to switch accounts.`);
             return;
         }
         catch {
@@ -172,21 +208,51 @@ program
 // ========== SYNC ==========
 program
     .command("sync")
-    .description("Sync analysis to ophan.dev")
+    .description("Sync analysis with ophan.dev (pull + push)")
     .option("-p, --path <path>", "Path to repository", process.cwd())
     .action(async (options) => {
     const rootPath = path.resolve(options.path);
+    const dbPath = path.join(rootPath, ".ophan", "index.db");
     try {
         const { supabase, userId } = await (0, auth_1.getAuthenticatedClient)();
-        console.log("☁️  Syncing to ophan.dev...\n");
-        const result = await (0, sync_1.syncToSupabase)(rootPath, supabase, userId, (step) => {
-            console.log(`  ${step}`);
-        });
-        console.log(`\n✅ Sync complete: ${result.pushed} analysis entries pushed, ` +
-            `${result.locations} file locations synced` +
-            (result.gcProcessed > 0
-                ? `, ${result.gcProcessed} GC deletions applied`
-                : ""));
+        console.log("☁️  Syncing with ophan.dev...\n");
+        // Pull first: fetch missing analysis from cloud
+        let pulled = 0;
+        const repoName = path.basename(rootPath);
+        const { data: repo } = await supabase
+            .from("repos")
+            .select("id")
+            .eq("user_id", userId)
+            .eq("name", repoName)
+            .single();
+        if (repo) {
+            const missingHashes = (0, core_1.findMissingHashes)(dbPath);
+            if (missingHashes.length > 0) {
+                const pullResult = await (0, sync_1.pullFromSupabase)(rootPath, supabase, userId, repo.id, missingHashes, (step) => console.log(`  ${step}`));
+                pulled = pullResult.pulled;
+            }
+            else {
+                console.log("  No missing analyses to pull.");
+            }
+        }
+        // Then push local analysis to cloud
+        const result = await (0, sync_1.syncToSupabase)(rootPath, supabase, userId, (step) => console.log(`  ${step}`));
+        const parts = [
+            `${pulled} pulled`,
+            `${result.pushed} pushed`,
+            `${result.locations} file locations synced`,
+        ];
+        if (result.practices > 0)
+            parts.push(`${result.practices} practices synced`);
+        if (result.communities > 0)
+            parts.push(`${result.communities} community memberships`);
+        if (result.communityEdges > 0)
+            parts.push(`${result.communityEdges} community edges`);
+        if (result.summaries > 0)
+            parts.push(`${result.summaries} summaries`);
+        if (result.gcProcessed > 0)
+            parts.push(`${result.gcProcessed} GC deletions applied`);
+        console.log(`\n✅ Sync complete: ${parts.join(", ")}`);
     }
     catch (err) {
         console.error(`\n❌ Sync failed: ${err.message}`);
@@ -202,7 +268,21 @@ program
     .option("--sync", "Auto-sync to cloud after each analysis batch")
     .action(async (options) => {
     const rootPath = path.resolve(options.path);
-    const pullFn = await createPullFn(rootPath);
+    // Watch is long-running (used by extension host) — never crash on stray rejections.
+    // Common cause: Supabase server unreachable during pull/sync operations.
+    process.on("unhandledRejection", (reason) => {
+        const msg = reason?.message ?? String(reason);
+        if (options.json) {
+            process.stdout.write(JSON.stringify({ event: "error", message: `Unhandled rejection: ${msg}` }) + "\n");
+        }
+        else {
+            console.error(`  ❌ Unexpected error: ${msg}`);
+        }
+    });
+    const pullProgress = options.json
+        ? (step) => process.stdout.write(JSON.stringify({ event: "pull_progress", message: step }) + "\n")
+        : undefined;
+    const pullFn = await createPullFn(rootPath, pullProgress);
     let syncFn;
     if (options.sync) {
         const creds = (0, auth_1.readCredentials)();
@@ -213,18 +293,18 @@ program
             }
             catch {
                 if (options.json) {
-                    process.stdout.write(JSON.stringify({ event: "sync_warning", message: "Session expired — sync disabled. Run ophan login." }) + "\n");
+                    process.stdout.write(JSON.stringify({ event: "sync_warning", message: "Session expired — sync disabled. Run npx @ophan/cli login." }) + "\n");
                 }
                 else {
-                    console.warn("  ⚠️  Session expired — sync disabled. Run `ophan login` to re-authenticate.");
+                    console.warn("  ⚠️  Session expired — sync disabled. Run `npx @ophan/cli login` to re-authenticate.");
                 }
             }
         }
         else if (options.json) {
-            process.stdout.write(JSON.stringify({ event: "sync_warning", message: "Not logged in — sync disabled. Run ophan login." }) + "\n");
+            process.stdout.write(JSON.stringify({ event: "sync_warning", message: "Not logged in — sync disabled. Run npx @ophan/cli login." }) + "\n");
         }
         else {
-            console.warn("  ⚠️  Not logged in — sync disabled. Run `ophan login` to enable cloud sync.");
+            console.warn("  ⚠️  Not logged in — sync disabled. Run `npx @ophan/cli login` to enable cloud sync.");
         }
     }
     await (0, watch_1.startWatch)({
@@ -234,12 +314,291 @@ program
         json: options.json,
     });
 });
-// Keep "init" as alias for "analyze" for backwards compat
+// ========== INIT ==========
 program
     .command("init")
-    .description("Alias for analyze")
+    .description("Initialize Ophan for this repository (fast, no network calls)")
     .option("-p, --path <path>", "Path to repository", process.cwd())
     .action(async (options) => {
-    await runAnalyze(path.resolve(options.path));
+    const rootPath = path.resolve(options.path);
+    const dbPath = path.join(rootPath, ".ophan", "index.db");
+    console.log("Initializing Ophan...\n");
+    // Create .ophan dir + DB tables + gitignore
+    fs.mkdirSync(path.join(rootPath, ".ophan"), { recursive: true });
+    (0, core_1.ensureGitignore)(rootPath);
+    (0, core_1.initDb)(dbPath).close();
+    // Scan files and index all functions
+    let fileCount = 0;
+    await (0, core_1.refreshFileIndex)(rootPath, (current, total, file) => {
+        fileCount = total;
+        if (process.stdout.isTTY) {
+            process.stdout.clearLine(0);
+            process.stdout.cursorTo(0);
+        }
+        process.stdout.write(`  [${current}/${total}] ${file}\n`);
+    });
+    // Count indexed functions
+    const db = new better_sqlite3_1.default(dbPath, { readonly: true });
+    const row = db.prepare("SELECT COUNT(*) as count FROM file_functions").get();
+    db.close();
+    console.log(`\n✅ Initialized! Found ${row.count} functions across ${fileCount} files.`);
+    console.log(`   Database: .ophan/index.db\n`);
+    console.log(`   Next: run \`npx @ophan/cli watch\` to start analysis.`);
+});
+// ========== GRAPH ==========
+program
+    .command("graph")
+    .description("Build function relationship graph and detect communities")
+    .option("-p, --path <path>", "Path to repository", process.cwd())
+    .option("-a, --algorithm <algorithm>", "Community detection algorithm (louvain, leiden, label-propagation)", core_1.DEFAULT_GRAPH_CONFIG.algorithm)
+    .option("-r, --resolution <number>", "Louvain resolution parameter (higher = more communities)", String(core_1.DEFAULT_GRAPH_CONFIG.resolution))
+    .option("--min-size <number>", "Minimum community size (smaller clusters are dissolved)", String(core_1.DEFAULT_GRAPH_CONFIG.minCommunitySize))
+    .option("--max-size <number>", "Maximum community size (informational)", String(core_1.DEFAULT_GRAPH_CONFIG.maxCommunitySize))
+    .option("--json", "Output results as JSON")
+    .option("--summarize", "Generate documentation for detected communities using Claude")
+    .option("--raw-source", "Use raw function source code for documentation (requires --summarize)")
+    .option("--directory-decay <number>", "Directory distance decay factor (0=off, higher=stronger)", String(core_1.DEFAULT_GRAPH_CONFIG.directoryDecay))
+    .option("--compare", "Compare multiple algorithm configurations side by side")
+    .action(async (options) => {
+    const rootPath = path.resolve(options.path);
+    const dbPath = path.join(rootPath, ".ophan", "index.db");
+    if (!fs.existsSync(dbPath)) {
+        console.error("No .ophan/index.db found. Run `npx @ophan/cli init` first.");
+        process.exit(1);
+    }
+    if (options.rawSource && !options.summarize) {
+        console.error("--raw-source requires --summarize");
+        process.exit(1);
+    }
+    const config = {
+        algorithm: options.algorithm,
+        edgeWeights: core_1.DEFAULT_GRAPH_CONFIG.edgeWeights,
+        resolution: parseFloat(options.resolution),
+        minCommunitySize: parseInt(options.minSize, 10),
+        maxCommunitySize: parseInt(options.maxSize, 10),
+        directoryDecay: parseFloat(options.directoryDecay),
+    };
+    if (!options.json) {
+        console.log(`\nBuilding function graph (${config.algorithm}, resolution=${config.resolution})...\n`);
+    }
+    // Extract functions with relationship data
+    const functions = await (0, core_1.extractAllFunctions)(rootPath, !options.json ? (current, total, file) => {
+        if (process.stdout.isTTY) {
+            process.stdout.clearLine(0);
+            process.stdout.cursorTo(0);
+        }
+        process.stdout.write(`  [${current}/${total}] ${file}`);
+    } : undefined);
+    if (!options.json) {
+        console.log(`\n\n  ${functions.length} functions extracted, resolving edges...\n`);
+    }
+    // Populate file_functions index from extracted functions (needed for edge resolution)
+    const db = (0, core_1.initDb)(dbPath);
+    // Snapshot old hashes before populateFileIndex overwrites file_functions
+    // This enables incremental edge resolution (only recompute changed + neighbor edges)
+    const oldHashes = new Set(db.prepare("SELECT DISTINCT content_hash FROM file_functions").all()
+        .map((r) => r.content_hash));
+    (0, core_1.populateFileIndex)(db, functions);
+    if (!options.json) {
+        console.log(`  Indexed ${functions.length} functions, detecting communities...\n`);
+    }
+    // --compare mode: resolve edges once, run multiple algorithm configs, print table
+    if (options.compare) {
+        const resolver = rootPath ? (0, core_1.buildModuleResolver)(rootPath, functions) : undefined;
+        const edges = (0, core_1.resolveEdges)(db, functions, config, undefined, resolver);
+        (0, core_1.storeEdges)(db, edges);
+        const edgesWithTransitive = (0, core_1.addTransitiveEdges)(edges, config);
+        // Build hash→filePath map for directory distance decay
+        let hashToFilePath;
+        if (rootPath && (config.directoryDecay ?? 0) > 0) {
+            hashToFilePath = new Map();
+            for (const fn of functions)
+                hashToFilePath.set(fn.contentHash, fn.filePath);
+        }
+        const allHashes = new Set(functions.map((f) => f.contentHash));
+        const metrics = (0, core_1.runComparison)(edgesWithTransitive, config, core_1.DEFAULT_COMPARISONS, hashToFilePath, rootPath, allHashes);
+        if (options.json) {
+            console.log(JSON.stringify({ nodes: allHashes.size, edges: edgesWithTransitive.length, comparisons: metrics }));
+        }
+        else {
+            console.log(`  Algorithm Comparison (${allHashes.size} nodes, ${edgesWithTransitive.length} edges)\n`);
+            // Table header
+            const header = [
+                "Configuration".padEnd(25),
+                "Communities".padStart(12),
+                "Dissolved".padStart(14),
+                "Coverage".padStart(9),
+                "Min".padStart(5),
+                "Med".padStart(5),
+                "Max".padStart(5),
+                "Modularity".padStart(11),
+            ].join("");
+            console.log(`  ${header}`);
+            console.log(`  ${"─".repeat(header.length)}`);
+            for (const m of metrics) {
+                const dissolved = `${m.dissolvedCount} (${m.dissolvedPct.toFixed(0)}%)`;
+                const modularity = m.modularity !== null ? m.modularity.toFixed(4) : "---";
+                const row = [
+                    m.label.padEnd(25),
+                    String(m.communityCount).padStart(12),
+                    dissolved.padStart(14),
+                    `${m.coverage.toFixed(0)}%`.padStart(9),
+                    String(m.minSize).padStart(5),
+                    String(m.medianSize).padStart(5),
+                    String(m.maxSize).padStart(5),
+                    modularity.padStart(11),
+                ].join("");
+                console.log(`  ${row}`);
+            }
+            console.log();
+        }
+        db.close();
+        return;
+    }
+    // Run full graph pipeline with hierarchical detection
+    const hierResult = (0, core_1.detectHierarchicalCommunities)(db, functions, config, oldHashes, rootPath);
+    const result = hierResult.l0;
+    // Build source map for raw-source summarization mode
+    let sourceMap;
+    if (options.rawSource) {
+        sourceMap = new Map();
+        for (const fn of functions)
+            sourceMap.set(fn.contentHash, fn.sourceCode);
+    }
+    if (options.json) {
+        const output = {
+            algorithm: config.algorithm,
+            resolution: config.resolution,
+            nodes: result.nodesInGraph,
+            edges: result.edgesInGraph,
+            communities: result.communityCount,
+            dissolved: result.dissolvedCount,
+            modularity: result.modularity,
+            assignments: result.assignments,
+            communityEdges: hierResult.communityEdges,
+            l1Groups: hierResult.l1GroupCount,
+            l1Assignments: hierResult.l1Assignments,
+        };
+        // Summarize if requested
+        if (options.summarize) {
+            const sumResult = await (0, core_1.summarizeCommunities)(db, {
+                config: { algorithm: config.algorithm },
+                sourceMap,
+                rootPath,
+            });
+            const l1 = (0, core_1.loadAllSummaries)(db, config.algorithm, 1);
+            const l2 = (0, core_1.loadAllSummaries)(db, config.algorithm, 2);
+            const l3 = (0, core_1.loadAllSummaries)(db, config.algorithm, 3);
+            const cc = (0, core_1.loadAllSummaries)(db, config.algorithm, 10);
+            output.summaries = {
+                l1: l1.map((s) => ({ communityId: s.communityId, ...s.summary })),
+                l2: l2.map((s) => ({ communityId: s.communityId, ...s.summary })),
+                l3: l3.map((s) => ({ communityId: s.communityId, ...s.summary })),
+                crossCutting: cc.map((s) => ({ communityId: s.communityId, ...s.summary })),
+                stats: sumResult,
+            };
+        }
+        console.log(JSON.stringify(output));
+    }
+    else {
+        console.log(`  Nodes:       ${result.nodesInGraph}`);
+        console.log(`  Edges:       ${result.edgesInGraph}`);
+        console.log(`  Communities: ${result.communityCount}`);
+        if (result.dissolvedCount > 0) {
+            console.log(`  Dissolved:   ${result.dissolvedCount} (below min size ${config.minCommunitySize})`);
+        }
+        if (result.modularity !== null) {
+            console.log(`  Modularity:  ${result.modularity.toFixed(4)}`);
+        }
+        if (result.effectiveResolution && result.effectiveResolution !== config.resolution) {
+            console.log(`  Resolution:  ${result.effectiveResolution} (auto-scaled from ${config.resolution})`);
+        }
+        if (hierResult.l1GroupCount > 0) {
+            console.log(`  Groups:      ${hierResult.l1GroupCount} (hierarchical)`);
+        }
+        if (hierResult.communityEdges.length > 0) {
+            console.log(`  Cross-edges: ${hierResult.communityEdges.length} (between communities)`);
+        }
+        // Show community breakdown
+        if (result.communityCount > 0) {
+            const communityMap = new Map();
+            for (const a of result.assignments) {
+                if (a.communityId === "__dissolved")
+                    continue;
+                const members = communityMap.get(a.communityId) || [];
+                members.push(a.contentHash);
+                communityMap.set(a.communityId, members);
+            }
+            console.log(`\n  Community breakdown:`);
+            // Look up function names from DB for display
+            const readDb = new better_sqlite3_1.default(dbPath, { readonly: true });
+            const lookupName = readDb.prepare("SELECT function_name, file_path FROM file_functions WHERE content_hash = ? LIMIT 1");
+            const sorted = [...communityMap.entries()].sort((a, b) => b[1].length - a[1].length);
+            for (const [communityId, hashes] of sorted) {
+                const overMax = hashes.length > config.maxCommunitySize;
+                const flag = overMax ? " (large)" : "";
+                console.log(`\n    Community ${communityId}${flag} (${hashes.length} functions):`);
+                for (const hash of hashes.slice(0, 15)) {
+                    const row = lookupName.get(hash);
+                    if (row) {
+                        const relPath = path.relative(rootPath, row.file_path);
+                        console.log(`      ${row.function_name}  (${relPath})`);
+                    }
+                    else {
+                        console.log(`      ${hash.slice(0, 12)}...`);
+                    }
+                }
+                if (hashes.length > 15) {
+                    console.log(`      ... and ${hashes.length - 15} more`);
+                }
+            }
+            readDb.close();
+        }
+        // Summarize if requested
+        if (options.summarize) {
+            // Check if any function analysis exists (for a useful warning in non-raw mode)
+            const analysisCount = db.prepare("SELECT COUNT(*) as count FROM function_analysis").get().count;
+            if (!options.rawSource && analysisCount === 0) {
+                console.log("  ⚠️  No function analysis found. Run `ophan analyze` first for best results.\n");
+            }
+            else if (result.communityCount > 0) {
+                console.log(options.rawSource
+                    ? "\n📝 Generating documentation from source code...\n"
+                    : "\n📝 Generating documentation...\n");
+                const sumResult = await (0, core_1.summarizeCommunities)(db, {
+                    config: { algorithm: config.algorithm },
+                    onProgress: (step) => console.log(`  ${step}`),
+                    sourceMap,
+                    rootPath,
+                });
+                const generated = sumResult.l1Summarized + sumResult.l2Summarized + sumResult.l3Summarized;
+                const cached = sumResult.l1Cached + sumResult.l2Cached + sumResult.l3Cached;
+                const driftSkipped = sumResult.l1DriftSkipped;
+                const failed = sumResult.l1Failed ?? 0;
+                const parts = [`${generated} generated`, `${cached} cached`];
+                if (driftSkipped > 0)
+                    parts.push(`${driftSkipped} drift-skipped`);
+                if (failed > 0)
+                    parts.push(`${failed} failed`);
+                console.log(`\n✅ Documentation: ${parts.join(", ")}`);
+                if (sumResult.ccDetected > 0) {
+                    console.log(`  Cross-cutting: ${sumResult.ccDetected} detected, ${sumResult.ccSummarized} documented, ${sumResult.ccCached} cached`);
+                    const ccSummaries = (0, core_1.loadAllSummaries)(db, config.algorithm, 10);
+                    if (ccSummaries.length > 0) {
+                        console.log(`\n  Cross-Cutting Concerns:`);
+                        for (const s of ccSummaries) {
+                            const sum = s.summary;
+                            const badge = sum.concernType === "security" ? "SEC" : "DATA";
+                            const communities = (sum.affectedCommunities || [])
+                                .map((c) => c.communityTitle).join(", ");
+                            console.log(`    [${badge}] ${sum.title} (${communities})`);
+                        }
+                    }
+                }
+            }
+        }
+        console.log();
+    }
+    db.close();
 });
 program.parse();