@ophan/core 0.0.2 → 0.0.4

package/dist/graph.js

@@ -0,0 +1,1295 @@
+"use strict";
+// Graph analysis module — builds a function relationship graph, runs community detection,
+// and produces hierarchical documentation structure.
+//
+// Architecture:
+//   1. Parsers extract call sites, imports, exports → FunctionInfo with relationship fields
+//   2. This module resolves names to content hashes → function_edges table
+//   3. graphology builds in-memory graph from edges
+//   4. Community detection (configurable algorithm) → communities table
+//   5. (Phase 2) Hierarchical summarization → community_summaries table
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_COMPARISONS = exports.DEFAULT_GRAPH_CONFIG = exports.DEFAULT_EDGE_WEIGHTS = void 0;
+exports.computeDirectoryDistance = computeDirectoryDistance;
+exports.computePackage = computePackage;
+exports.buildModuleResolver = buildModuleResolver;
+exports.loadGraphConfig = loadGraphConfig;
+exports.saveGraphConfig = saveGraphConfig;
+exports.buildEdgeResolverContext = buildEdgeResolverContext;
+exports.resolveEdges = resolveEdges;
+exports.addTransitiveEdges = addTransitiveEdges;
+exports.storeEdges = storeEdges;
+exports.storeEdgesIncremental = storeEdgesIncremental;
+exports.loadEdges = loadEdges;
+exports.storeCommunities = storeCommunities;
+exports.loadCommunities = loadCommunities;
+exports.computeCommunityEdges = computeCommunityEdges;
+exports.storeCommunityEdges = storeCommunityEdges;
+exports.loadCommunityEdges = loadCommunityEdges;
+exports.buildGraph = buildGraph;
+exports.computeCentrality = computeCentrality;
+exports.rescueDissolvedNodes = rescueDissolvedNodes;
+exports.detectCommunities = detectCommunities;
+exports.matchCommunities = matchCommunities;
+exports.labelPropagation = labelPropagation;
+exports.computeChangedHashes = computeChangedHashes;
+exports.analyzeGraph = analyzeGraph;
+exports.detectHierarchicalCommunities = detectHierarchicalCommunities;
+exports.computeComparisonMetrics = computeComparisonMetrics;
+exports.runComparison = runComparison;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const graphology_1 = __importDefault(require("graphology"));
+const betweenness_1 = __importDefault(require("graphology-metrics/centrality/betweenness"));
+const community_detectors_1 = require("./community-detectors");
+const edge_resolvers_1 = require("./edge-resolvers");
+/**
+ * Default edge weights for graph construction.
+ *
+ * These control how strongly each relationship type pulls functions into the
+ * same community. All weights are relative — what matters is the ratio between
+ * them, not the absolute values. Weights from different edge types between the
+ * same function pair are summed in the merged graph.
+ *
+ * Edit these to tune community detection. After changing, re-run:
+ *   pnpm dev graph --compare --path .
+ * to see the effect across all algorithms.
+ */
+exports.DEFAULT_EDGE_WEIGHTS = {
+    /**
+     * Direct function calls: `fnA()` calls `fnB()`.
+     * Strongest signal — actual runtime dependency.
+     * ↑ increase: call relationships dominate clustering
+     * ↓ decrease: proximity and imports become relatively more important
+     */
+    call: 0.5,
+    /**
+     * Type references: function A uses a type defined near function B.
+     * NOT YET EXTRACTED by parsers — no type_ref edges are currently produced.
+     * Reserved for future use.
+     */
+    type_ref: 0.5,
+    /**
+     * Import statements: `import { validate } from "./auth"` creates an edge.
+     * Includes barrel file fallback (workspace package re-exports).
+     * ↑ increase: module boundaries become stronger clustering signal
+     * ↓ decrease: imports matter less relative to calls and proximity
+     */
+    import: 0.2,
+    /**
+     * File/directory proximity. Two sub-types:
+     *   Same-file: all pairs connected, weight decays as 1/offset (adjacent=full, distance N=1/N)
+     *   Same-directory (cross-file): half the same-file weight (hardcoded 0.5x multiplier)
+     *
+     * This is the main knob for "respect file boundaries". Higher values keep
+     * same-file functions together even when they have cross-file call edges.
+     *
+     * ↑ increase: files/directories cluster together more strongly
+     * ↓ decrease: only call/import relationships drive clustering
+     * 0: disable proximity entirely (pure topology)
+     */
+    co_location: 0.7,
+    /**
+     * JSX component references: `<Button />`, `<Card />`.
+     * Separated from calls because UI composition is a weaker domain signal
+     * than functional dependency. Without this separation, functions using
+     * shared UI components get pulled into the UI component's community.
+     *
+     * ↑ increase: components rendering the same UI primitives cluster together
+     * ↓ decrease: JSX composition becomes noise
+     */
+    jsx_ref: 0.2,
+    /**
+     * 2-hop call chains: A→B→C creates A↔C edge.
+     * Derived in-memory (not stored in DB). Stacks with direct edges.
+     * ↑ increase: transitive relationships pull functions together more
+     * ↓ decrease: only direct connections drive clustering
+     */
+    transitive_call: 0.4,
+    /**
+     * Shared caller: if A calls both B and C, creates B↔C edge.
+     * Derived in-memory (not stored in DB). Callers with >15 callees are skipped.
+     * Weakest signal — correlation (same caller) is suggestive but indirect.
+     * ↑ increase: functions used by the same caller cluster together more
+     * ↓ decrease: only direct relationships matter
+     */
+    co_caller: 0.4,
+};
+exports.DEFAULT_GRAPH_CONFIG = {
+    algorithm: "leiden",
+    edgeWeights: { ...exports.DEFAULT_EDGE_WEIGHTS },
+    resolution: 3.0,
+    minCommunitySize: 3,
+    maxCommunitySize: 18,
+    autoResolution: true,
+    directoryDecay: 0.7,
+};
+/**
+ * Compute directory-level distance between two files relative to rootPath.
+ * Distance = number of unique directory segments when traversing from one file's
+ * directory to the other via their common ancestor.
+ *
+ * Examples (relative to root):
+ *   src/components/Button.tsx vs src/components/Input.tsx → 0 (same dir)
+ *   src/components/Button.tsx vs src/utils/format.ts → 2 (sibling dirs)
+ *   packages/core/src/graph.ts vs packages/webapp/src/App.tsx → 4
+ */
+function computeDirectoryDistance(filePathA, filePathB, rootPath) {
+    const segsA = path
+        .relative(rootPath, path.dirname(filePathA))
+        .split(path.sep)
+        .filter(Boolean);
+    const segsB = path
+        .relative(rootPath, path.dirname(filePathB))
+        .split(path.sep)
+        .filter(Boolean);
+    let common = 0;
+    while (common < segsA.length &&
+        common < segsB.length &&
+        segsA[common] === segsB[common]) {
+        common++;
+    }
+    return segsA.length - common + (segsB.length - common);
+}
+/**
+ * Extract a human-readable package label for a file.
+ * Uses the ModuleResolver to find the containing workspace package if available.
+ * Falls back to the first directory segment relative to root.
+ */
+function computePackage(filePath, rootPath, resolver) {
+    if (resolver) {
+        let bestMatch = "";
+        let bestName = "root";
+        for (const [name, pkg] of resolver.workspacePackages) {
+            if (filePath.startsWith(pkg.dir + path.sep) &&
+                pkg.dir.length > bestMatch.length) {
+                bestMatch = pkg.dir;
+                bestName = name;
+            }
+        }
+        if (bestMatch)
+            return bestName;
+    }
+    const rel = path.relative(rootPath, filePath).replace(/\\/g, "/");
+    const parts = rel.split("/");
+    return parts.length > 1 ? parts[0] : "root";
+}
+/** Marker files that indicate a package/project root directory */
+const PACKAGE_MARKERS = [
+    "package.json",
+    "pyproject.toml",
+    "go.mod",
+    "Cargo.toml",
+    "setup.py",
+    "pom.xml",
+];
+/**
+ * Discover package directories by walking UP from analyzed file directories
+ * and looking for marker files (package.json, pyproject.toml, go.mod, etc.).
+ *
+ * Technology-agnostic: works on any codebase regardless of directory naming.
+ * The checked set ensures each directory is only inspected once.
+ */
+function discoverPackageDirs(rootPath, functions) {
+    const fileDirs = new Set(functions.map((f) => path.dirname(f.filePath)));
+    const packageDirs = new Set();
+    const checked = new Set();
+    for (const dir of fileDirs) {
+        let current = dir;
+        while (current.startsWith(rootPath) && current !== path.dirname(current)) {
+            if (checked.has(current))
+                break;
+            checked.add(current);
+            for (const marker of PACKAGE_MARKERS) {
+                try {
+                    fs.statSync(path.join(current, marker));
+                    packageDirs.add(current);
+                    break;
+                }
+                catch {
+                    /* no marker here */
+                }
+            }
+            current = path.dirname(current);
+        }
+    }
+    // Always include root if it has a marker file
+    if (!checked.has(rootPath)) {
+        for (const marker of PACKAGE_MARKERS) {
+            try {
+                fs.statSync(path.join(rootPath, marker));
+                packageDirs.add(rootPath);
+                break;
+            }
+            catch {
+                /* no marker */
+            }
+        }
+    }
+    return [...packageDirs];
+}
+/**
+ * Build a ModuleResolver by discovering packages via marker files.
+ * Walks up from analyzed file directories to find package.json, pyproject.toml, etc.
+ * Reads package.json (for name + exports) and tsconfig.json (for path aliases).
+ * Runs once per graph command invocation — not per-edge.
+ */
+function buildModuleResolver(rootPath, functions) {
+    const workspacePackages = new Map();
+    const pathAliases = new Map();
+    const packageDirs = functions
+        ? discoverPackageDirs(rootPath, functions)
+        : [rootPath]; // fallback: just root
+    for (const dir of packageDirs) {
+        // Read package.json for name + exports
+        try {
+            const pkgJson = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8"));
+            const name = pkgJson.name;
+            if (name) {
+                const exports = {};
+                if (pkgJson.exports && typeof pkgJson.exports === "object") {
+                    for (const [key, value] of Object.entries(pkgJson.exports)) {
+                        if (typeof value === "string")
+                            exports[key] = value;
+                    }
+                }
+                if (!exports["."] && pkgJson.main) {
+                    exports["."] = pkgJson.main;
+                }
+                workspacePackages.set(name, { dir, exports });
+            }
+        }
+        catch {
+            /* skip dirs without valid package.json */
+        }
+        // Read tsconfig.json for paths
+        try {
+            const tsconfig = JSON.parse(fs.readFileSync(path.join(dir, "tsconfig.json"), "utf-8"));
+            const compilerOptions = tsconfig.compilerOptions;
+            if (compilerOptions?.paths) {
+                const baseUrl = compilerOptions.baseUrl
+                    ? path.resolve(dir, compilerOptions.baseUrl)
+                    : dir;
+                pathAliases.set(dir, { baseUrl, paths: compilerOptions.paths });
+            }
+        }
+        catch {
+            /* skip dirs without tsconfig or paths */
+        }
+    }
+    return { workspacePackages, pathAliases };
+}
+// ============ CONFIG PERSISTENCE ============
+function loadGraphConfig(db) {
+    const row = db
+        .prepare("SELECT value FROM graph_config WHERE key = 'config'")
+        .get();
+    if (!row)
+        return { ...exports.DEFAULT_GRAPH_CONFIG };
+    try {
+        const stored = JSON.parse(row.value);
+        return {
+            ...exports.DEFAULT_GRAPH_CONFIG,
+            ...stored,
+            edgeWeights: {
+                ...exports.DEFAULT_GRAPH_CONFIG.edgeWeights,
+                ...(stored.edgeWeights || {}),
+            },
+        };
+    }
+    catch {
+        return { ...exports.DEFAULT_GRAPH_CONFIG };
+    }
+}
+function saveGraphConfig(db, config) {
+    db.prepare("INSERT OR REPLACE INTO graph_config (key, value) VALUES ('config', ?)").run(JSON.stringify(config));
+}
+// ============ EDGE RESOLUTION ============
+/**
+ * Given extracted functions with call-site data, resolve name-based calls to
+ * content hash edges. Uses the file_functions index for name→hash lookup.
+ *
+ * Returns edges ready to insert into function_edges table.
+ */
+/**
+ * Build shared lookup context for edge resolvers.
+ * Queries file_functions once and constructs all lookup maps that resolvers need.
+ * Called once per resolveEdges() invocation.
+ */
+function buildEdgeResolverContext(db, functions, config, affectedHashes, resolver) {
+    // Query all file_functions rows once
+    const allDbRows = db
+        .prepare("SELECT file_path, function_name, content_hash FROM file_functions")
+        .all();
+    // Build name→hash lookup
+    const nameToHashes = new Map();
+    for (const row of allDbRows) {
+        const existing = nameToHashes.get(row.function_name) || new Set();
+        existing.add(row.content_hash);
+        nameToHashes.set(row.function_name, existing);
+    }
+    // Build file→hashes for import target resolution
+    const fileToHashes = new Map();
+    for (const row of allDbRows) {
+        const existing = fileToHashes.get(row.file_path) || new Set();
+        existing.add(row.content_hash);
+        fileToHashes.set(row.file_path, existing);
+    }
+    // Build (file::name) → hash for targeted import edges
+    const fileNameToHash = new Map();
+    for (const row of allDbRows) {
+        fileNameToHash.set(`${row.file_path}::${row.function_name}`, row.content_hash);
+    }
+    // Build package-scoped name→hashes for fallback import resolution.
+    // When imports resolve through barrel files (index.ts with re-exports),
+    // the imported name isn't defined in the barrel — it's in another file.
+    // This map lets us find the function by name within the package scope.
+    const pkgNameToHashes = new Map();
+    if (resolver) {
+        for (const [pkgName, pkg] of resolver.workspacePackages) {
+            const nameMap = new Map();
+            for (const row of allDbRows) {
+                if (row.file_path.startsWith(pkg.dir + path.sep)) {
+                    const existing = nameMap.get(row.function_name) || new Set();
+                    existing.add(row.content_hash);
+                    nameMap.set(row.function_name, existing);
+                }
+            }
+            if (nameMap.size > 0) {
+                pkgNameToHashes.set(pkgName, nameMap);
+            }
+        }
+    }
+    // Build file → sorted functions map for proximity-based co-location edges
+    const fileToSortedFns = new Map();
+    for (const fn of functions) {
+        const list = fileToSortedFns.get(fn.filePath) || [];
+        list.push(fn);
+        fileToSortedFns.set(fn.filePath, list);
+    }
+    for (const fns of fileToSortedFns.values()) {
+        fns.sort((a, b) => a.startLine - b.startLine);
+    }
+    return {
+        nameToHashes,
+        fileToHashes,
+        fileNameToHash,
+        pkgNameToHashes,
+        fileToSortedFns,
+        functions,
+        config,
+        affectedHashes,
+        resolver,
+    };
+}
+function resolveEdges(db, functions, config, affectedHashes, resolver) {
+    const ctx = buildEdgeResolverContext(db, functions, config, affectedHashes, resolver);
+    const edges = [];
+    for (const edgeResolver of (0, edge_resolvers_1.getEdgeResolvers)()) {
+        edges.push(...edgeResolver.resolve(ctx));
+    }
+    return edges;
+}
+// ============ TRANSITIVE EDGES ============
+/** Maximum callees per caller for co-caller edge generation.
+ *  Hub functions with many callees would create O(n^2) edges — cap to prevent explosion. */
+const CO_CALLER_CAP = 15;
+/**
+ * Derive transitive edges from the call graph to increase connectivity.
+ * Pure function — no DB access.
+ *
+ * Two derived edge types:
+ * 1. **transitive_call** (A→B→C creates A↔C): 2-hop call chain connectivity.
+ * 2. **co_caller** (A→B, A→C creates B↔C): Functions called by the same caller.
+ *
+ * Edges are NOT deduped against direct edges — being related in multiple ways
+ * (e.g., direct call + transitive chain) intentionally increases connection strength.
+ * buildGraph() merges parallel edges by summing weights.
+ */
+function addTransitiveEdges(edges, config) {
+    // Build directed call adjacency: caller → Set<callee>
+    // Only 'call' edges preserve direction (sourceHash=caller, targetHash=callee)
+    const callsTo = new Map();
+    for (const edge of edges) {
+        if (edge.edgeType === "call") {
+            let targets = callsTo.get(edge.sourceHash);
+            if (!targets) {
+                targets = new Set();
+                callsTo.set(edge.sourceHash, targets);
+            }
+            targets.add(edge.targetHash);
+        }
+    }
+    if (callsTo.size === 0)
+        return edges;
+    const newEdges = [];
+    // 1. Transitive call: A→B→C creates A↔C
+    const transitiveAdded = new Set();
+    for (const [caller, callees] of callsTo) {
+        for (const callee of callees) {
+            const indirectCallees = callsTo.get(callee);
+            if (!indirectCallees)
+                continue;
+            for (const indirect of indirectCallees) {
+                if (indirect === caller)
+                    continue; // skip self-loops
+                const a = caller < indirect ? caller : indirect;
+                const b = caller < indirect ? indirect : caller;
+                const key = `${a}|${b}`;
+                if (!transitiveAdded.has(key)) {
+                    transitiveAdded.add(key);
+                    newEdges.push({
+                        sourceHash: a,
+                        targetHash: b,
+                        edgeType: "transitive_call",
+                        weight: config.edgeWeights.transitive_call,
+                    });
+                }
+            }
+        }
+    }
+    // 2. Co-caller: A→B, A→C creates B↔C (capped to prevent hub explosion)
+    const coCallerAdded = new Set();
+    for (const [, callees] of callsTo) {
+        if (callees.size < 2 || callees.size > CO_CALLER_CAP)
+            continue;
+        const calleeList = [...callees];
+        for (let i = 0; i < calleeList.length; i++) {
+            for (let j = i + 1; j < calleeList.length; j++) {
+                const a = calleeList[i] < calleeList[j] ? calleeList[i] : calleeList[j];
+                const b = calleeList[i] < calleeList[j] ? calleeList[j] : calleeList[i];
+                const key = `${a}|${b}`;
+                if (!coCallerAdded.has(key)) {
+                    coCallerAdded.add(key);
+                    newEdges.push({
+                        sourceHash: a,
+                        targetHash: b,
+                        edgeType: "co_caller",
+                        weight: config.edgeWeights.co_caller,
+                    });
+                }
+            }
+        }
+    }
+    return [...edges, ...newEdges];
+}
+/**
+ * Store resolved edges in the function_edges table.
+ * Clears existing edges first (they're rebuilt from source each scan).
+ */
+function storeEdges(db, edges) {
+    db.exec("DELETE FROM function_edges");
+    const insert = db.prepare("INSERT OR REPLACE INTO function_edges (source_hash, target_hash, edge_type, weight) VALUES (?, ?, ?, ?)");
+    const tx = db.transaction(() => {
+        for (const edge of edges) {
+            insert.run(edge.sourceHash, edge.targetHash, edge.edgeType, edge.weight);
+        }
+    });
+    tx();
+}
+/**
+ * Incremental edge storage: delete edges for affected hashes, then insert new edges.
+ * Used when only a subset of functions changed — keeps unaffected edges in place.
+ */
+function storeEdgesIncremental(db, affectedHashes, newEdges) {
+    const hashes = [...affectedHashes];
+    // Delete in chunks to stay within SQLite variable limits
+    const deleteStmt = db.prepare("DELETE FROM function_edges WHERE source_hash = ? OR target_hash = ?");
+    const insertStmt = db.prepare("INSERT OR REPLACE INTO function_edges (source_hash, target_hash, edge_type, weight) VALUES (?, ?, ?, ?)");
+    const tx = db.transaction(() => {
+        for (const hash of hashes) {
+            deleteStmt.run(hash, hash);
+        }
+        for (const edge of newEdges) {
+            insertStmt.run(edge.sourceHash, edge.targetHash, edge.edgeType, edge.weight);
+        }
+    });
+    tx();
+}
+/**
+ * Load all edges from the database.
+ */
+function loadEdges(db) {
+    const rows = db
+        .prepare("SELECT source_hash, target_hash, edge_type, weight FROM function_edges")
+        .all();
+    return rows.map((r) => ({
+        sourceHash: r.source_hash,
+        targetHash: r.target_hash,
+        edgeType: r.edge_type,
+        weight: r.weight,
+    }));
+}
+/**
+ * Store community assignments in the communities table.
+ */
+function storeCommunities(db, assignments) {
+    // Clear existing assignments for this algorithm + level
+    if (assignments.length === 0)
+        return;
+    const algorithm = assignments[0].algorithm;
+    const level = assignments[0].level;
+    db.prepare("DELETE FROM communities WHERE algorithm = ? AND level = ?").run(algorithm, level);
+    const insert = db.prepare("INSERT INTO communities (content_hash, level, community_id, algorithm) VALUES (?, ?, ?, ?)");
+    const tx = db.transaction(() => {
+        for (const a of assignments) {
+            insert.run(a.contentHash, a.level, a.communityId, a.algorithm);
+        }
+    });
+    tx();
+}
+/**
+ * Load community assignments from the database.
+ */
+function loadCommunities(db, algorithm, level) {
+    const rows = db
+        .prepare("SELECT content_hash, level, community_id, algorithm FROM communities WHERE algorithm = ? AND level = ?")
+        .all(algorithm, level);
+    return rows.map((r) => ({
+        contentHash: r.content_hash,
+        level: r.level,
+        communityId: r.community_id,
+        algorithm: r.algorithm,
+    }));
+}
+// ============ COMMUNITY EDGES ============
+/**
+ * Aggregate function-level edges into community-level edges.
+ * For each pair of distinct L0 communities, sums the weights of all
+ * function edges that cross between them.
+ */
+function computeCommunityEdges(db, algorithm, edges) {
+    // Load L0 community assignments (excluding dissolved)
+    const assignments = db
+        .prepare("SELECT content_hash, community_id FROM communities WHERE level = 0 AND algorithm = ? AND community_id != '__dissolved'")
+        .all(algorithm);
+    const hashToCommunity = new Map();
+    for (const a of assignments) {
+        hashToCommunity.set(a.content_hash, a.community_id);
+    }
+    // Use provided edges (includes transitive) or load from DB
+    const fnEdges = edges
+        ? edges.map((e) => ({
+            source_hash: e.sourceHash,
+            target_hash: e.targetHash,
+            weight: e.weight,
+        }))
+        : db
+            .prepare("SELECT source_hash, target_hash, weight FROM function_edges")
+            .all();
+    // Accumulate cross-community edges
+    const edgeMap = new Map();
+    for (const e of fnEdges) {
+        const srcComm = hashToCommunity.get(e.source_hash);
+        const tgtComm = hashToCommunity.get(e.target_hash);
+        if (!srcComm || !tgtComm || srcComm === tgtComm)
+            continue;
+        // Canonical ordering
+        const a = srcComm < tgtComm ? srcComm : tgtComm;
+        const b = srcComm < tgtComm ? tgtComm : srcComm;
+        const key = `${a}|${b}`;
+        const existing = edgeMap.get(key) || { weight: 0, count: 0 };
+        existing.weight += e.weight;
+        existing.count += 1;
+        edgeMap.set(key, existing);
+    }
+    const result = [];
+    for (const [key, data] of edgeMap) {
+        const [a, b] = key.split("|");
+        result.push({
+            sourceCommunity: a,
+            targetCommunity: b,
+            algorithm,
+            weight: data.weight,
+            edgeCount: data.count,
+        });
+    }
+    return result;
+}
+/**
+ * Store community edges (full replace per algorithm).
+ */
+function storeCommunityEdges(db, edges) {
+    if (edges.length === 0) {
+        db.exec("DELETE FROM community_edges");
+        return;
+    }
+    const algorithm = edges[0].algorithm;
+    db.prepare("DELETE FROM community_edges WHERE algorithm = ?").run(algorithm);
+    const insert = db.prepare("INSERT INTO community_edges (source_community, target_community, algorithm, weight, edge_count) VALUES (?, ?, ?, ?, ?)");
+    const tx = db.transaction(() => {
+        for (const edge of edges) {
+            insert.run(edge.sourceCommunity, edge.targetCommunity, edge.algorithm, edge.weight, edge.edgeCount);
+        }
+    });
+    tx();
+}
+/**
+ * Load community edges from the database.
+ */
+function loadCommunityEdges(db, algorithm) {
+    const rows = db
+        .prepare("SELECT source_community, target_community, algorithm, weight, edge_count FROM community_edges WHERE algorithm = ?")
+        .all(algorithm);
+    return rows.map((r) => ({
+        sourceCommunity: r.source_community,
+        targetCommunity: r.target_community,
+        algorithm: r.algorithm,
+        weight: r.weight,
+        edgeCount: r.edge_count,
+    }));
+}
+/**
+ * Build a graphology graph from function edges.
+ * Creates an undirected weighted graph — multiple edges between the same
+ * pair (different edge types) are merged by summing weights.
+ */
+function buildGraph(edges, hashToFilePath, rootPath, directoryDecay, allHashes) {
+    const graph = new graphology_1.default({ type: "undirected" });
+    // Add ALL function hashes as nodes (every extracted function is a node)
+    if (allHashes) {
+        for (const hash of allHashes) {
+            graph.addNode(hash);
+        }
+    }
+    // Also add any nodes from edges not already present
+    for (const edge of edges) {
+        if (!graph.hasNode(edge.sourceHash))
+            graph.addNode(edge.sourceHash);
+        if (!graph.hasNode(edge.targetHash))
+            graph.addNode(edge.targetHash);
+    }
+    // Pre-compute directory segments for each node (avoids repeated path operations per-edge)
+    const dirSegCache = new Map();
+    const applyDecay = hashToFilePath &&
+        rootPath &&
+        directoryDecay !== undefined &&
+        directoryDecay > 0;
+    if (applyDecay) {
+        for (const [hash, fp] of hashToFilePath) {
+            dirSegCache.set(hash, path
+                .relative(rootPath, path.dirname(fp))
+                .split(path.sep)
+                .filter(Boolean));
+        }
+    }
+    // Merge parallel edges (same pair, different types) by summing weights
+    const mergedWeights = new Map();
+    for (const edge of edges) {
+        const a = edge.sourceHash < edge.targetHash ? edge.sourceHash : edge.targetHash;
+        const b = edge.sourceHash < edge.targetHash ? edge.targetHash : edge.sourceHash;
+        const key = `${a}|${b}`;
+        let weight = edge.weight;
+        if (applyDecay) {
+            const segsA = dirSegCache.get(a);
+            const segsB = dirSegCache.get(b);
+            if (segsA && segsB) {
+                let common = 0;
+                while (common < segsA.length &&
+                    common < segsB.length &&
+                    segsA[common] === segsB[common]) {
+                    common++;
+                }
+                const dist = segsA.length - common + (segsB.length - common);
+                if (dist > 0) {
+                    weight *= Math.exp(-directoryDecay * dist);
+                }
+            }
+        }
+        mergedWeights.set(key, (mergedWeights.get(key) || 0) + weight);
+    }
+    for (const [key, weight] of mergedWeights) {
+        const [a, b] = key.split("|");
+        graph.addEdge(a, b, { weight });
+    }
+    return graph;
+}
+/**
+ * Compute betweenness centrality for all nodes in the graph.
+ * High-centrality nodes are "bridge" functions that many shortest paths
+ * pass through — coupling points between communities.
+ */
+function computeCentrality(graph) {
+    if (graph.order === 0) {
+        return { scores: new Map(), ranked: [] };
+    }
+    const raw = (0, betweenness_1.default)(graph, {
+        getEdgeWeight: "weight",
+        normalized: true,
+    });
+    const scores = new Map();
+    const ranked = [];
+    for (const [node, score] of Object.entries(raw)) {
+        scores.set(node, score);
+        ranked.push({ contentHash: node, score });
+    }
+    ranked.sort((a, b) => b.score - a.score);
+    return { scores, ranked };
+}
+// ============ COMMUNITY DETECTION ============
+/**
+ * Rescue dissolved nodes by assigning each to the community with the strongest
+ * total edge weight. Mutates assignments in-place. Returns the number rescued.
+ *
+ * Nodes with zero connections to any non-dissolved community stay dissolved.
+ * Rescued nodes update the membership map so subsequent rescues see them as
+ * placed (enabling chained rescue where node B is rescued into a community
+ * that node A was just rescued into).
+ */
+function rescueDissolvedNodes(assignments, edges, dissolvedMarker) {
+    const dissolvedHashes = [];
+    for (const a of assignments) {
+        if (a.communityId === dissolvedMarker) {
+            dissolvedHashes.push(a.contentHash);
+        }
+    }
+    if (dissolvedHashes.length === 0)
+        return 0;
+    // Build membership map (hash → community) for non-dissolved nodes
+    const hashToComm = new Map();
+    for (const a of assignments) {
+        if (a.communityId !== dissolvedMarker) {
+            hashToComm.set(a.contentHash, a.communityId);
+        }
+    }
+    if (hashToComm.size === 0)
+        return 0;
+    let rescued = 0;
+    for (const hash of dissolvedHashes) {
+        // Sum edge weights to each community
+        const commWeights = new Map();
+        for (const edge of edges) {
+            const neighbor = edge.sourceHash === hash
+                ? edge.targetHash
+                : edge.targetHash === hash
+                    ? edge.sourceHash
+                    : null;
+            if (!neighbor)
+                continue;
+            const comm = hashToComm.get(neighbor);
+            if (comm) {
+                commWeights.set(comm, (commWeights.get(comm) || 0) + edge.weight);
+            }
+        }
+        // Find the community with strongest total connection
+        let bestComm = "";
+        let bestWeight = 0;
+        for (const [comm, weight] of commWeights) {
+            if (weight > bestWeight) {
+                bestWeight = weight;
+                bestComm = comm;
+            }
+        }
+        if (bestComm) {
+            const assignment = assignments.find((a) => a.contentHash === hash);
+            if (assignment) {
+                assignment.communityId = bestComm;
+                hashToComm.set(hash, bestComm); // chained rescue
+                rescued++;
+            }
+        }
+    }
+    return rescued;
+}
+/**
+ * Run community detection on the given edges using the configured algorithm.
+ * Returns assignments ready for storage, plus stats about the detection run.
+ *
+ * Small communities (< minCommunitySize) are dissolved — their members are
+ * assigned to a special "__dissolved" community. Dissolved nodes are then
+ * rescued: each is assigned to the community it's most connected to by total
+ * edge weight. Truly isolated nodes (zero connections) stay dissolved.
+ */
+function detectCommunities(edges, config, hashToFilePath, rootPath, allHashes) {
+    const graph = buildGraph(edges, hashToFilePath, rootPath, config.directoryDecay, allHashes);
+    if (graph.order === 0) {
+        return {
+            assignments: [],
+            communityCount: 0,
+            modularity: null,
+            nodesInGraph: 0,
+            edgesInGraph: 0,
+            dissolvedCount: 0,
+        };
+    }
+    // Auto-resolution: scale resolution with codebase size for better granularity
+    let resolution = config.resolution;
+    if (config.autoResolution !== false) {
+        const nodeCount = graph.order;
+        if (nodeCount < 50)
+            resolution = Math.max(resolution, 1.0);
+        else if (nodeCount < 200)
+            resolution = Math.max(resolution, 1.5);
+        else
+            resolution = Math.max(resolution, 2.0);
+    }
+    const detector = (0, community_detectors_1.getDetector)(config.algorithm);
+    const raw = detector.detect(graph, { resolution, weightAttribute: "weight" });
+    const communities = raw.communities;
+    const modularity = raw.modularity;
+    // Group nodes by community
+    const communityMembers = new Map();
+    for (const [node, communityId] of Object.entries(communities)) {
+        const members = communityMembers.get(communityId) || [];
+        members.push(node);
+        communityMembers.set(communityId, members);
+    }
+    // Active splitting: re-run Louvain at higher resolution on oversized communities
+    const splitMembers = new Map();
+    for (const [communityId, members] of communityMembers) {
+        if (members.length > config.maxCommunitySize &&
+            detector.supportsResolution) {
+            const memberSet = new Set(members);
+            const subEdges = edges.filter((e) => memberSet.has(e.sourceHash) && memberSet.has(e.targetHash));
+            if (subEdges.length > 0) {
+                const subResult = detectCommunities(subEdges, {
+                    ...config,
+                    resolution: resolution * 2,
+                    autoResolution: false, // prevent recursive auto-scaling
+                });
+                // Only accept the split if it produced multiple communities without destroying too many
+                if (subResult.communityCount > 1 &&
+                    subResult.dissolvedCount <= members.length * 0.5) {
+                    for (const a of subResult.assignments) {
+                        a.communityId = `${communityId}_${a.communityId}`;
+                    }
+                    // Rescue dissolved split fragments into nearest sub-community
+                    const dissolvedMarker = `${communityId}___dissolved`;
+                    rescueDissolvedNodes(subResult.assignments, subEdges, dissolvedMarker);
+                    splitMembers.set(String(communityId), []);
+                    for (const a of subResult.assignments) {
+                        const list = splitMembers.get(a.communityId) || [];
+                        list.push(a.contentHash);
+                        splitMembers.set(a.communityId, list);
+                    }
+                }
+            }
+        }
+    }
+    // Build final assignments
+    const assignments = [];
+    let dissolvedCount = 0;
+    for (const [communityId, members] of communityMembers) {
+        // If this community was split, use the split assignments instead
+        if (splitMembers.has(String(communityId)))
+            continue;
+        const isTooSmall = members.length < config.minCommunitySize;
+        const assignedId = isTooSmall ? "__dissolved" : String(communityId);
+        if (isTooSmall)
+            dissolvedCount += members.length;
+        for (const contentHash of members) {
+            assignments.push({
+                contentHash,
+                level: 0,
+                communityId: assignedId,
+                algorithm: config.algorithm,
+            });
+        }
+    }
+    // Add split community assignments
+    for (const [subCommunityId, members] of splitMembers) {
+        // Detect dissolved groups from recursive splits (prefixed: "66___dissolved")
+        const isDissolvedGroup = subCommunityId.endsWith("___dissolved");
+        if (isDissolvedGroup) {
+            dissolvedCount += members.length;
+        }
+        const isTooSmall = members.length < config.minCommunitySize;
+        const assignedId = isDissolvedGroup || isTooSmall ? "__dissolved" : subCommunityId;
+        if (isTooSmall && !isDissolvedGroup)
+            dissolvedCount += members.length;
+        for (const contentHash of members) {
+            assignments.push({
+                contentHash,
+                level: 0,
+                communityId: assignedId,
+                algorithm: config.algorithm,
+            });
+        }
+    }
+    // Rescue top-level dissolved nodes into nearest community
+    const topRescued = rescueDissolvedNodes(assignments, edges, "__dissolved");
+    dissolvedCount -= topRescued;
+    // Count actual (non-dissolved) communities
+    const realCommunities = new Set(assignments
+        .filter((a) => a.communityId !== "__dissolved")
+        .map((a) => a.communityId));
+    return {
+        assignments,
+        communityCount: realCommunities.size,
+        modularity,
+        nodesInGraph: graph.order,
+        edgesInGraph: graph.size,
+        dissolvedCount,
+        effectiveResolution: resolution,
+    };
+}
+// ============ STABLE COMMUNITY MATCHING (Gate 1) ============
+/**
+ * Match new community assignments to old ones by Jaccard similarity.
+ * Remaps new community IDs to reuse old IDs where membership overlaps significantly.
+ * This prevents summary cache misses caused by Louvain's arbitrary ID renumbering.
+ *
+ * Algorithm: greedy 1:1 matching — sort all (new, old, Jaccard) triples by score
+ * descending, accept matches where J ≥ threshold, each ID used at most once.
+ */
+function matchCommunities(oldAssignments, newAssignments, threshold = 0.5) {
+    if (oldAssignments.length === 0 || newAssignments.length === 0) {
+        return newAssignments;
+    }
+    // Group by communityId → set of content hashes (skip __dissolved)
+    const groupByComm = (assignments) => {
+        const map = new Map();
+        for (const a of assignments) {
+            if (a.communityId === "__dissolved")
+                continue;
+            const set = map.get(a.communityId) || new Set();
+            set.add(a.contentHash);
+            map.set(a.communityId, set);
+        }
+        return map;
+    };
+    const oldGroups = groupByComm(oldAssignments);
+    const newGroups = groupByComm(newAssignments);
+    if (oldGroups.size === 0 || newGroups.size === 0) {
+        return newAssignments;
+    }
+    // Compute all Jaccard similarities
+    const candidates = [];
+    for (const [newId, newMembers] of newGroups) {
+        for (const [oldId, oldMembers] of oldGroups) {
+            let intersection = 0;
+            for (const h of newMembers) {
+                if (oldMembers.has(h))
+                    intersection++;
+            }
+            const union = newMembers.size + oldMembers.size - intersection;
+            if (union === 0)
+                continue;
+            const jaccard = intersection / union;
+            if (jaccard >= threshold) {
+                candidates.push({ newId, oldId, jaccard });
+            }
+        }
+    }
+    // Greedy 1:1 matching: best scores first
+    candidates.sort((a, b) => b.jaccard - a.jaccard);
+    const usedOld = new Set();
+    const usedNew = new Set();
+    const remap = new Map(); // newId → oldId
+    for (const { newId, oldId } of candidates) {
+        if (usedNew.has(newId) || usedOld.has(oldId))
+            continue;
+        remap.set(newId, oldId);
+        usedNew.add(newId);
+        usedOld.add(oldId);
+    }
+    if (remap.size === 0) {
+        return newAssignments;
+    }
+    // Apply remapping
+    return newAssignments.map((a) => {
+        const remappedId = remap.get(a.communityId);
+        if (remappedId) {
+            return { ...a, communityId: remappedId };
+        }
+        return a;
+    });
+}
+/**
+ * Label Propagation Algorithm (LPA) for community detection.
+ * Delegates to LabelPropDetector — kept as a standalone export for backward compatibility.
+ */
+function labelPropagation(graph, maxIterations = 100) {
+    const detector = new community_detectors_1.LabelPropDetector(maxIterations);
+    const result = detector.detect(graph, {
+        resolution: 0,
+        weightAttribute: "weight",
+    });
+    return result.communities;
+}
+// ============ ORCHESTRATION ============
+/**
+ * Compute the set of content hashes that changed between old and new function sets.
+ * Returns the symmetric difference: hashes that appeared or disappeared.
+ */
+function computeChangedHashes(oldHashes, newHashes) {
+    const changed = new Set();
+    for (const h of newHashes) {
+        if (!oldHashes.has(h))
+            changed.add(h);
+    }
+    for (const h of oldHashes) {
+        if (!newHashes.has(h))
+            changed.add(h);
+    }
+    return changed;
+}
+/**
+ * Find edge neighbors of a set of hashes — any hash connected to them via function_edges.
+ */
+function findEdgeNeighbors(db, hashes) {
+    const neighbors = new Set();
+    const stmt = db.prepare("SELECT source_hash, target_hash FROM function_edges WHERE source_hash = ? OR target_hash = ?");
+    for (const hash of hashes) {
+        const rows = stmt.all(hash, hash);
+        for (const row of rows) {
+            neighbors.add(row.source_hash);
+            neighbors.add(row.target_hash);
+        }
+    }
+    return neighbors;
+}
+/**
+ * Full graph analysis pipeline: resolve edges → build graph → detect communities → store.
+ * Call after file scanning to update the relationship graph.
+ *
+ * When `oldHashes` is provided, uses incremental edge resolution: only recomputes edges
+ * for changed functions + their neighbors, keeping the rest of the graph stable.
+ */
+function analyzeGraph(db, functions, config, oldHashes, rootPath) {
+    const graphConfig = config || loadGraphConfig(db);
+    const newHashes = new Set(functions.map((f) => f.contentHash));
+    // Build module resolver using marker file discovery for workspace + alias import resolution
+    const resolver = rootPath
+        ? buildModuleResolver(rootPath, functions)
+        : undefined;
+    // Determine incremental vs full rebuild
+    const changedHashes = oldHashes
+        ? computeChangedHashes(oldHashes, newHashes)
+        : null;
+    const useIncremental = changedHashes !== null &&
+        changedHashes.size > 0 &&
+        changedHashes.size / Math.max(newHashes.size, 1) <= 0.5;
+    let edges;
+    if (changedHashes !== null && changedHashes.size === 0) {
+        // No-change fast path: skip edge resolution, load existing edges
+        edges = loadEdges(db);
+    }
+    else if (useIncremental) {
+        // Incremental mode: only resolve edges for changed functions + their neighbors
+        const neighbors = findEdgeNeighbors(db, changedHashes);
+        const affectedHashes = new Set([...changedHashes, ...neighbors]);
+        // Filter to only hashes that still exist (exclude removed hashes)
+        for (const h of affectedHashes) {
+            if (!newHashes.has(h))
+                affectedHashes.delete(h);
+        }
+        const newEdges = resolveEdges(db, functions, graphConfig, affectedHashes, resolver);
+        storeEdgesIncremental(db, affectedHashes, newEdges);
+        edges = loadEdges(db);
+    }
+    else {
+        // Full rebuild (first run or >50% changed)
+        edges = resolveEdges(db, functions, graphConfig, undefined, resolver);
+        storeEdges(db, edges);
+    }
+    // Add transitive edges (derived from call graph, not stored in DB)
+    const edgesWithTransitive = addTransitiveEdges(edges, graphConfig);
+    // Build hash→filePath map for directory distance decay
+    let hashToFilePath;
+    if (rootPath && (graphConfig.directoryDecay ?? 0.1) > 0) {
+        hashToFilePath = new Map();
+        for (const fn of functions) {
+            hashToFilePath.set(fn.contentHash, fn.filePath);
+        }
+    }
+    // Detect communities from all edges including transitive
+    const result = detectCommunities(edgesWithTransitive, graphConfig, hashToFilePath, rootPath, newHashes);
+    // Stable community matching — remap new IDs to old IDs by Jaccard similarity
+    const oldAssignments = loadCommunities(db, graphConfig.algorithm, 0);
+    const remapped = matchCommunities(oldAssignments, result.assignments);
+    result.assignments = remapped;
+    // Store community assignments
+    storeCommunities(db, result.assignments);
+    // Compute and store community edges (using full edge set including transitive)
+    const communityEdges = computeCommunityEdges(db, graphConfig.algorithm, edgesWithTransitive);
+    storeCommunityEdges(db, communityEdges);
+    // Save config used (for reproducibility)
+    saveGraphConfig(db, graphConfig);
+    return result;
+}
+/**
+ * Detect hierarchical communities: first L0 (function-level), then L1 (community-level).
+ *
+ * After L0 detection + community edge computation, builds a meta-graph where:
+ *   - Nodes = L0 community IDs (excluding __dissolved)
+ *   - Edges = community_edges (weighted by aggregate function edge weight)
+ *
+ * Runs Louvain on meta-graph to produce L1 group assignments.
+ * Stores L1 assignments in the communities table with level=1,
+ * where content_hash = L0 community_id.
+ *
+ * When `oldHashes` is provided, enables incremental edge resolution in the L0 step.
+ */
+function detectHierarchicalCommunities(db, functions, config, oldHashes, rootPath) {
+    const graphConfig = config || loadGraphConfig(db);
+    // Step 1: Run L0 detection (also computes + stores community edges)
+    const l0 = analyzeGraph(db, functions, graphConfig, oldHashes, rootPath);
+    // Step 2: Load community edges
+    const communityEdges = loadCommunityEdges(db, graphConfig.algorithm);
+    // Step 3: Need at least 3 real communities for meaningful grouping
+    const realCommunities = new Set(l0.assignments
+        .filter((a) => a.communityId !== "__dissolved")
+        .map((a) => a.communityId));
+    if (realCommunities.size < 3 || communityEdges.length < 2) {
+        return { l0, communityEdges, l1Assignments: [], l1GroupCount: 0 };
+    }
+    // Step 4: Build meta-graph from community edges
+    const metaEdges = communityEdges.map((ce) => ({
+        sourceHash: ce.sourceCommunity,
+        targetHash: ce.targetCommunity,
+        edgeType: "call",
+        weight: ce.weight,
+    }));
+    const metaGraph = buildGraph(metaEdges);
+    if (metaGraph.order < 3) {
+        return { l0, communityEdges, l1Assignments: [], l1GroupCount: 0 };
+    }
+    // Step 5: Run community detection on meta-graph
+    const metaDetector = (0, community_detectors_1.getDetector)(graphConfig.algorithm);
+    const metaRaw = metaDetector.detect(metaGraph, {
+        resolution: graphConfig.resolution,
+        weightAttribute: "weight",
+    });
+    const metaCommunities = metaRaw.communities;
+    // Step 6: Build L1 assignments
+    const l1Members = new Map();
+    for (const [communityId, groupId] of Object.entries(metaCommunities)) {
+        const members = l1Members.get(groupId) || [];
+        members.push(communityId);
+        l1Members.set(groupId, members);
+    }
+    // Dissolve groups with only 1 community (no useful grouping)
+    const l1Assignments = [];
+    let realGroupCount = 0;
+    for (const [groupId, members] of l1Members) {
+        const isTooSmall = members.length < 2;
+        if (!isTooSmall)
+            realGroupCount++;
+        for (const communityId of members) {
+            l1Assignments.push({
+                contentHash: communityId,
+                level: 1,
+                communityId: isTooSmall ? "__dissolved" : String(groupId),
+                algorithm: graphConfig.algorithm,
+            });
+        }
+    }
+    // Step 6.5: Stable matching for L1 assignments
+    const oldL1Assignments = loadCommunities(db, graphConfig.algorithm, 1);
+    const remappedL1 = matchCommunities(oldL1Assignments, l1Assignments);
+    // Step 7: Store L1 assignments
+    if (remappedL1.length > 0) {
+        storeCommunities(db, remappedL1);
+    }
+    return {
+        l0,
+        communityEdges,
+        l1Assignments: remappedL1,
+        l1GroupCount: realGroupCount,
+    };
+}
+exports.DEFAULT_COMPARISONS = [
+    { label: "louvain@1.0", algorithm: "louvain", resolution: 1.0 },
+    { label: "louvain@1.5", algorithm: "louvain", resolution: 1.5 },
+    { label: "louvain@2.0", algorithm: "louvain", resolution: 2.0 },
+    { label: "louvain@3.0", algorithm: "louvain", resolution: 3.0 },
+    { label: "leiden@1.5", algorithm: "leiden", resolution: 1.5 },
+    { label: "leiden@2.0", algorithm: "leiden", resolution: 2.0 },
+    { label: "label-propagation", algorithm: "label-propagation", resolution: 0 },
+];
+/**
+ * Compute comparison metrics from a DetectionResult.
+ * Pure function — no DB or side effects.
+ */
+function computeComparisonMetrics(result, label, algorithm, resolution) {
+    const totalNodes = result.nodesInGraph;
+    // Collect community sizes (excluding dissolved)
+    const commSizes = new Map();
+    for (const a of result.assignments) {
+        if (a.communityId === "__dissolved")
+            continue;
+        commSizes.set(a.communityId, (commSizes.get(a.communityId) || 0) + 1);
+    }
+    const sizes = [...commSizes.values()].sort((a, b) => a - b);
+    const minSize = sizes.length > 0 ? sizes[0] : 0;
+    const maxSize = sizes.length > 0 ? sizes[sizes.length - 1] : 0;
+    const medianSize = sizes.length > 0
+        ? sizes.length % 2 === 1
+            ? sizes[Math.floor(sizes.length / 2)]
+            : Math.round((sizes[Math.floor(sizes.length / 2) - 1] +
+                sizes[Math.floor(sizes.length / 2)]) /
+                2)
+        : 0;
+    const dissolvedPct = totalNodes > 0 ? Math.round((result.dissolvedCount / totalNodes) * 100) : 0;
+    const coverage = totalNodes > 0
+        ? Math.round(((totalNodes - result.dissolvedCount) / totalNodes) * 100)
+        : 0;
+    return {
+        label,
+        algorithm,
+        resolution,
+        communityCount: result.communityCount,
+        dissolvedCount: result.dissolvedCount,
+        dissolvedPct,
+        coverage,
+        minSize,
+        medianSize,
+        maxSize,
+        modularity: result.modularity,
+        nodesInGraph: result.nodesInGraph,
+        edgesInGraph: result.edgesInGraph,
+    };
+}
+/**
+ * Run community detection at multiple configurations on the same edges.
+ * Does NOT write to DB — pure computation for comparison.
+ */
+function runComparison(edges, baseConfig, configurations, hashToFilePath, rootPath, allHashes) {
+    return configurations.map((cfg) => {
+        const config = {
+            ...baseConfig,
+            algorithm: cfg.algorithm,
+            resolution: cfg.resolution,
+            autoResolution: false, // explicit resolution for fair comparison
+        };
+        const result = detectCommunities(edges, config, hashToFilePath, rootPath, allHashes);
+        return computeComparisonMetrics(result, cfg.label, cfg.algorithm, cfg.resolution || null);
+    });
+}