@ophan/core 0.0.1 → 0.0.3

package/dist/edge-resolvers/import.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImportEdgeResolver = void 0;
+const module_resolvers_1 = require("../module-resolvers");
+/**
+ * Resolves import edges from import statements.
+ * Three resolution paths:
+ * 1. Direct: imported name found in the resolved target file
+ * 2. Barrel fallback: imported name found via package-scoped search (re-exports)
+ * 3. Namespace fallback: intersect fn.calls with target file's functions
+ *
+ * Owns importAdded Set for deduplication (import edges are undirected).
+ */
+class ImportEdgeResolver {
+    constructor() {
+        this.edgeTypes = ["import"];
+    }
+    resolve(ctx) {
+        const edges = [];
+        const importAdded = new Set();
+        for (const fn of ctx.functions) {
+            if (ctx.affectedHashes && !ctx.affectedHashes.has(fn.contentHash))
+                continue;
+            if (!fn.imports)
+                continue;
+            for (const imp of fn.imports) {
+                const langResolver = (0, module_resolvers_1.getModuleResolverForFile)(fn.filePath);
+                const targetFile = langResolver?.resolveModuleToFile(imp.module, fn.filePath, ctx.fileToHashes, ctx.resolver);
+                // Determine package scope for fallback through barrel file re-exports
+                let pkgScope;
+                if (ctx.resolver) {
+                    for (const [pkgName] of ctx.resolver.workspacePackages) {
+                        if (imp.module === pkgName ||
+                            imp.module.startsWith(pkgName + "/")) {
+                            pkgScope = ctx.pkgNameToHashes.get(pkgName);
+                            break;
+                        }
+                    }
+                }
+                if (!targetFile && !pkgScope)
+                    continue;
+                // Create edges to the specific functions named in the import
+                let matched = false;
+                for (const importedName of imp.names) {
+                    // Direct lookup: function defined in the resolved target file
+                    const directHash = targetFile
+                        ? ctx.fileNameToHash.get(`${targetFile}::${importedName}`)
+                        : undefined;
+                    if (directHash && directHash !== fn.contentHash) {
+                        matched = true;
+                        const a = fn.contentHash < directHash ? fn.contentHash : directHash;
+                        const b = fn.contentHash < directHash ? directHash : fn.contentHash;
+                        const importKey = `${a}|${b}`;
+                        if (!importAdded.has(importKey)) {
+                            importAdded.add(importKey);
+                            edges.push({
+                                sourceHash: a,
+                                targetHash: b,
+                                edgeType: "import",
+                                weight: ctx.config.edgeWeights.import,
+                            });
+                        }
+                    }
+                    else if (pkgScope) {
+                        // Fallback: imported name is a re-export through a barrel file
+                        const targetHashes = pkgScope.get(importedName);
+                        if (targetHashes) {
+                            for (const targetHash of targetHashes) {
+                                if (targetHash === fn.contentHash)
+                                    continue;
+                                matched = true;
+                                const a = fn.contentHash < targetHash ? fn.contentHash : targetHash;
+                                const b = fn.contentHash < targetHash ? targetHash : fn.contentHash;
+                                const importKey = `${a}|${b}`;
+                                if (!importAdded.has(importKey)) {
+                                    importAdded.add(importKey);
+                                    edges.push({
+                                        sourceHash: a,
+                                        targetHash: b,
+                                        edgeType: "import",
+                                        weight: ctx.config.edgeWeights.import,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+                // Fallback for namespace imports: intersect fn.calls with target file's functions
+                if (!matched && fn.calls && targetFile) {
+                    const targetFnsInFile = ctx.fileToHashes.get(targetFile);
+                    if (targetFnsInFile) {
+                        for (const calledName of fn.calls) {
+                            const targetHash = ctx.fileNameToHash.get(`${targetFile}::${calledName}`);
+                            if (targetHash &&
+                                targetHash !== fn.contentHash &&
+                                targetFnsInFile.has(targetHash)) {
+                                const a = fn.contentHash < targetHash ? fn.contentHash : targetHash;
+                                const b = fn.contentHash < targetHash ? targetHash : fn.contentHash;
+                                const importKey = `${a}|${b}`;
+                                if (!importAdded.has(importKey)) {
+                                    importAdded.add(importKey);
+                                    edges.push({
+                                        sourceHash: a,
+                                        targetHash: b,
+                                        edgeType: "import",
+                                        weight: ctx.config.edgeWeights.import,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        return edges;
+    }
+}
+exports.ImportEdgeResolver = ImportEdgeResolver;

package/dist/edge-resolvers/index.d.ts

@@ -0,0 +1,9 @@
+export type { EdgeResolver, EdgeResolverContext } from "./types";
+export { CallEdgeResolver } from "./call";
+export { JsxRefEdgeResolver } from "./jsx-ref";
+export { CoLocationEdgeResolver } from "./co-location";
+export { ImportEdgeResolver } from "./import";
+import type { EdgeResolver } from "./types";
+export declare function registerEdgeResolver(resolver: EdgeResolver): void;
+export declare function getEdgeResolvers(): readonly EdgeResolver[];
+//# sourceMappingURL=index.d.ts.map

package/dist/edge-resolvers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/edge-resolvers/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAQ5C,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAEjE;AAED,wBAAgB,gBAAgB,IAAI,SAAS,YAAY,EAAE,CAE1D"}

package/dist/edge-resolvers/index.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImportEdgeResolver = exports.CoLocationEdgeResolver = exports.JsxRefEdgeResolver = exports.CallEdgeResolver = void 0;
+exports.registerEdgeResolver = registerEdgeResolver;
+exports.getEdgeResolvers = getEdgeResolvers;
+var call_1 = require("./call");
+Object.defineProperty(exports, "CallEdgeResolver", { enumerable: true, get: function () { return call_1.CallEdgeResolver; } });
+var jsx_ref_1 = require("./jsx-ref");
+Object.defineProperty(exports, "JsxRefEdgeResolver", { enumerable: true, get: function () { return jsx_ref_1.JsxRefEdgeResolver; } });
+var co_location_1 = require("./co-location");
+Object.defineProperty(exports, "CoLocationEdgeResolver", { enumerable: true, get: function () { return co_location_1.CoLocationEdgeResolver; } });
+var import_1 = require("./import");
+Object.defineProperty(exports, "ImportEdgeResolver", { enumerable: true, get: function () { return import_1.ImportEdgeResolver; } });
+const call_2 = require("./call");
+const jsx_ref_2 = require("./jsx-ref");
+const co_location_2 = require("./co-location");
+const import_2 = require("./import");
+const registry = [];
+function registerEdgeResolver(resolver) {
+    registry.push(resolver);
+}
+function getEdgeResolvers() {
+    return registry;
+}
+// Register built-in resolvers
+registerEdgeResolver(new call_2.CallEdgeResolver());
+registerEdgeResolver(new jsx_ref_2.JsxRefEdgeResolver());
+registerEdgeResolver(new co_location_2.CoLocationEdgeResolver());
+registerEdgeResolver(new import_2.ImportEdgeResolver());

package/dist/edge-resolvers/jsx-ref.d.ts

@@ -0,0 +1,13 @@
+import type { EdgeResolver, EdgeResolverContext } from "./types";
+import type { FunctionEdge } from "../graph";
+/**
+ * Resolves JSX component reference edges.
+ * When a function renders <Component />, creates a weak edge to that component.
+ * Separated from call edges because UI composition is a weaker domain signal
+ * than direct function calls.
+ */
+export declare class JsxRefEdgeResolver implements EdgeResolver {
+    readonly edgeTypes: readonly ["jsx_ref"];
+    resolve(ctx: EdgeResolverContext): FunctionEdge[];
+}
+//# sourceMappingURL=jsx-ref.d.ts.map

package/dist/edge-resolvers/jsx-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-ref.d.ts","sourceRoot":"","sources":["../../src/edge-resolvers/jsx-ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;;GAKG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD,QAAQ,CAAC,SAAS,uBAAwB;IAE1C,OAAO,CAAC,GAAG,EAAE,mBAAmB,GAAG,YAAY,EAAE;CAqBlD"}

package/dist/edge-resolvers/jsx-ref.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsxRefEdgeResolver = void 0;
+/**
+ * Resolves JSX component reference edges.
+ * When a function renders <Component />, creates a weak edge to that component.
+ * Separated from call edges because UI composition is a weaker domain signal
+ * than direct function calls.
+ */
+class JsxRefEdgeResolver {
+    constructor() {
+        this.edgeTypes = ["jsx_ref"];
+    }
+    resolve(ctx) {
+        const edges = [];
+        for (const fn of ctx.functions) {
+            if (ctx.affectedHashes && !ctx.affectedHashes.has(fn.contentHash))
+                continue;
+            if (!fn.jsxRefs)
+                continue;
+            for (const refName of fn.jsxRefs) {
+                const targetHashes = ctx.nameToHashes.get(refName);
+                if (!targetHashes)
+                    continue;
+                for (const targetHash of targetHashes) {
+                    if (targetHash === fn.contentHash)
+                        continue;
+                    edges.push({
+                        sourceHash: fn.contentHash,
+                        targetHash,
+                        edgeType: "jsx_ref",
+                        weight: ctx.config.edgeWeights.jsx_ref,
+                    });
+                }
+            }
+        }
+        return edges;
+    }
+}
+exports.JsxRefEdgeResolver = JsxRefEdgeResolver;

package/dist/edge-resolvers/types.d.ts

@@ -0,0 +1,40 @@
+import type { FunctionInfo } from "../shared";
+import type { GraphConfig, FunctionEdge, ModuleResolver } from "../graph";
+/**
+ * Shared context built once per resolveEdges() invocation.
+ * Contains pre-built lookup maps that edge resolvers need.
+ * The orchestrator builds this — resolvers consume it.
+ */
+export interface EdgeResolverContext {
+    /** function_name → Set<content_hash> (handles name collisions across files) */
+    nameToHashes: Map<string, Set<string>>;
+    /** file_path → Set<content_hash> */
+    fileToHashes: Map<string, Set<string>>;
+    /** "file_path::function_name" → content_hash (targeted import lookup) */
+    fileNameToHash: Map<string, string>;
+    /** package_name → Map<function_name, Set<content_hash>> (barrel file fallback) */
+    pkgNameToHashes: Map<string, Map<string, Set<string>>>;
+    /** file_path → FunctionInfo[] sorted by startLine */
+    fileToSortedFns: Map<string, FunctionInfo[]>;
+    /** All extracted functions for this scan */
+    functions: FunctionInfo[];
+    /** Graph configuration (edge weights, etc.) */
+    config: GraphConfig;
+    /** Optional: limit resolution to these hashes (incremental mode) */
+    affectedHashes?: Set<string>;
+    /** Optional: workspace module resolver for import resolution */
+    resolver?: ModuleResolver;
+}
+/**
+ * Strategy interface for edge resolution.
+ * Each implementation handles one category of edges (calls, imports, co-location, etc.).
+ *
+ * Resolvers own their own deduplication — the orchestrator concatenates results.
+ */
+export interface EdgeResolver {
+    /** Edge type identifier(s) this resolver produces */
+    readonly edgeTypes: readonly string[];
+    /** Resolve edges from the shared context */
+    resolve(ctx: EdgeResolverContext): FunctionEdge[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/edge-resolvers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/edge-resolvers/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE1E;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACvC,oCAAoC;IACpC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACvC,yEAAyE;IACzE,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,kFAAkF;IAClF,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACvD,qDAAqD;IACrD,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;IAC7C,4CAA4C;IAC5C,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,+CAA+C;IAC/C,MAAM,EAAE,WAAW,CAAC;IACpB,oEAAoE;IACpE,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,4CAA4C;IAC5C,OAAO,CAAC,GAAG,EAAE,mBAAmB,GAAG,YAAY,EAAE,CAAC;CACnD"}

package/dist/edge-resolvers/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/graph.d.ts

@@ -0,0 +1,293 @@
+import type Database from "better-sqlite3";
+import Graph from "graphology";
+import type { EdgeResolverContext } from "./edge-resolvers";
+import type { FunctionInfo } from "./shared";
+export interface GraphConfig {
+    /** Which community detection algorithm to use (extensible via registerDetector()) */
+    algorithm: string;
+    /** Relative edge weights by type (higher = stronger signal for community detection) */
+    edgeWeights: {
+        call: number;
+        type_ref: number;
+        import: number;
+        co_location: number;
+        jsx_ref: number;
+        transitive_call: number;
+        co_caller: number;
+    };
+    /** Louvain/Leiden resolution parameter. Higher = more, smaller communities */
+    resolution: number;
+    /** Minimum functions in a community (smaller clusters are dissolved) */
+    minCommunitySize: number;
+    /** Maximum functions in a community (larger clusters may indicate poor resolution) */
+    maxCommunitySize: number;
+    /** When true, resolution scales up automatically with codebase size */
+    autoResolution?: boolean;
+    /** Exponential decay factor for directory distance between files.
+     *  Applied as exp(-directoryDecay * distance) to cross-directory edges.
+     *  0 = no penalty, higher = stronger penalty for distant files.
+     *  Default: 0.1 */
+    directoryDecay?: number;
+}
+/**
+ * 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.
+ */
+export declare const DEFAULT_EDGE_WEIGHTS: GraphConfig["edgeWeights"];
+export declare const DEFAULT_GRAPH_CONFIG: GraphConfig;
+/**
+ * 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
+ */
+export declare function computeDirectoryDistance(filePathA: string, filePathB: string, rootPath: string): number;
+/**
+ * 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.
+ */
+export declare function computePackage(filePath: string, rootPath: string, resolver?: ModuleResolver): string;
+export interface ModuleResolver {
+    /** Map workspace package names (e.g. "@ophan/core") to their directory + exports */
+    workspacePackages: Map<string, {
+        dir: string;
+        exports: Record<string, string>;
+    }>;
+    /** Map package directory to its tsconfig path aliases */
+    pathAliases: Map<string, {
+        baseUrl: string;
+        paths: Record<string, string[]>;
+    }>;
+}
+/**
+ * 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.
+ */
+export declare function buildModuleResolver(rootPath: string, functions?: FunctionInfo[]): ModuleResolver;
+export interface FunctionEdge {
+    sourceHash: string;
+    targetHash: string;
+    edgeType: "call" | "type_ref" | "import" | "co_location" | "jsx_ref" | "transitive_call" | "co_caller";
+    weight: number;
+}
+export interface CommunityEdge {
+    sourceCommunity: string;
+    targetCommunity: string;
+    algorithm: string;
+    weight: number;
+    edgeCount: number;
+}
+export interface CommunityAssignment {
+    contentHash: string;
+    level: number;
+    communityId: string;
+    algorithm: string;
+}
+export declare function loadGraphConfig(db: Database.Database): GraphConfig;
+export declare function saveGraphConfig(db: Database.Database, config: GraphConfig): void;
+/**
+ * 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.
+ */
+export declare function buildEdgeResolverContext(db: Database.Database, functions: FunctionInfo[], config: GraphConfig, affectedHashes?: Set<string>, resolver?: ModuleResolver): EdgeResolverContext;
+export declare function resolveEdges(db: Database.Database, functions: FunctionInfo[], config: GraphConfig, affectedHashes?: Set<string>, resolver?: ModuleResolver): FunctionEdge[];
+/**
+ * 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.
+ */
+export declare function addTransitiveEdges(edges: FunctionEdge[], config: GraphConfig): FunctionEdge[];
+/**
+ * Store resolved edges in the function_edges table.
+ * Clears existing edges first (they're rebuilt from source each scan).
+ */
+export declare function storeEdges(db: Database.Database, edges: FunctionEdge[]): void;
+/**
+ * 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.
+ */
+export declare function storeEdgesIncremental(db: Database.Database, affectedHashes: Set<string>, newEdges: FunctionEdge[]): void;
+/**
+ * Load all edges from the database.
+ */
+export declare function loadEdges(db: Database.Database): FunctionEdge[];
+/**
+ * Store community assignments in the communities table.
+ */
+export declare function storeCommunities(db: Database.Database, assignments: CommunityAssignment[]): void;
+/**
+ * Load community assignments from the database.
+ */
+export declare function loadCommunities(db: Database.Database, algorithm: string, level: number): CommunityAssignment[];
+/**
+ * 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.
+ */
+export declare function computeCommunityEdges(db: Database.Database, algorithm: string, edges?: FunctionEdge[]): CommunityEdge[];
+/**
+ * Store community edges (full replace per algorithm).
+ */
+export declare function storeCommunityEdges(db: Database.Database, edges: CommunityEdge[]): void;
+/**
+ * Load community edges from the database.
+ */
+export declare function loadCommunityEdges(db: Database.Database, algorithm: string): CommunityEdge[];
+export interface DetectionResult {
+    assignments: CommunityAssignment[];
+    communityCount: number;
+    modularity: number | null;
+    nodesInGraph: number;
+    edgesInGraph: number;
+    dissolvedCount: number;
+    effectiveResolution?: number;
+}
+/**
+ * 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.
+ */
+export declare function buildGraph(edges: FunctionEdge[], hashToFilePath?: Map<string, string>, rootPath?: string, directoryDecay?: number, allHashes?: Set<string>): Graph;
+export interface CentralityResult {
+    /** Map of content_hash → betweenness centrality score (0–1, normalized) */
+    scores: Map<string, number>;
+    /** Functions ranked by centrality descending — top bridge functions first */
+    ranked: {
+        contentHash: string;
+        score: number;
+    }[];
+}
+/**
+ * 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.
+ */
+export declare function computeCentrality(graph: Graph): CentralityResult;
+/**
+ * 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).
+ */
+export declare function rescueDissolvedNodes(assignments: CommunityAssignment[], edges: FunctionEdge[], dissolvedMarker: string): number;
+/**
+ * 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.
+ */
+export declare function detectCommunities(edges: FunctionEdge[], config: GraphConfig, hashToFilePath?: Map<string, string>, rootPath?: string, allHashes?: Set<string>): DetectionResult;
+/**
+ * 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.
+ */
+export declare function matchCommunities(oldAssignments: CommunityAssignment[], newAssignments: CommunityAssignment[], threshold?: number): CommunityAssignment[];
+/**
+ * Label Propagation Algorithm (LPA) for community detection.
+ * Delegates to LabelPropDetector — kept as a standalone export for backward compatibility.
+ */
+export declare function labelPropagation(graph: Graph, maxIterations?: number): Record<string, number>;
+/**
+ * Compute the set of content hashes that changed between old and new function sets.
+ * Returns the symmetric difference: hashes that appeared or disappeared.
+ */
+export declare function computeChangedHashes(oldHashes: Set<string>, newHashes: Set<string>): Set<string>;
+/**
+ * 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.
+ */
+export declare function analyzeGraph(db: Database.Database, functions: FunctionInfo[], config?: GraphConfig, oldHashes?: Set<string>, rootPath?: string): DetectionResult;
+export interface HierarchicalDetectionResult {
+    l0: DetectionResult;
+    communityEdges: CommunityEdge[];
+    l1Assignments: CommunityAssignment[];
+    l1GroupCount: number;
+}
+/**
+ * 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.
+ */
+export declare function detectHierarchicalCommunities(db: Database.Database, functions: FunctionInfo[], config?: GraphConfig, oldHashes?: Set<string>, rootPath?: string): HierarchicalDetectionResult;
+export interface ComparisonMetrics {
+    label: string;
+    algorithm: string;
+    resolution: number | null;
+    communityCount: number;
+    dissolvedCount: number;
+    dissolvedPct: number;
+    coverage: number;
+    minSize: number;
+    medianSize: number;
+    maxSize: number;
+    modularity: number | null;
+    nodesInGraph: number;
+    edgesInGraph: number;
+}
+export interface ComparisonConfig {
+    label: string;
+    algorithm: string;
+    resolution: number;
+}
+export declare const DEFAULT_COMPARISONS: ComparisonConfig[];
+/**
+ * Compute comparison metrics from a DetectionResult.
+ * Pure function — no DB or side effects.
+ */
+export declare function computeComparisonMetrics(result: DetectionResult, label: string, algorithm: string, resolution: number | null): ComparisonMetrics;
+/**
+ * Run community detection at multiple configurations on the same edges.
+ * Does NOT write to DB — pure computation for comparison.
+ */
+export declare function runComparison(edges: FunctionEdge[], baseConfig: GraphConfig, configurations: ComparisonConfig[], hashToFilePath?: Map<string, string>, rootPath?: string, allHashes?: Set<string>): ComparisonMetrics[];
+//# sourceMappingURL=graph.d.ts.map

package/dist/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAG3C,OAAO,KAAK,MAAM,YAAY,CAAC;AAG/B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAI7C,MAAM,WAAW,WAAW;IAC1B,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAElB,uFAAuF;IACvF,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,eAAe,EAAE,MAAM,CAAC;QACxB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IAEF,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IAEnB,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,CAAC;IAEzB,sFAAsF;IACtF,gBAAgB,EAAE,MAAM,CAAC;IAEzB,uEAAuE;IACvE,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;uBAGmB;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,aAAa,CAiE3D,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,WAQlC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,CAoBR;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,cAAc,GACxB,MAAM,CAkBR;AAID,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,iBAAiB,EAAE,GAAG,CACpB,MAAM,EACN;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CACjD,CAAC;IACF,yDAAyD;IACzD,WAAW,EAAE,GAAG,CACd,MAAM,EACN;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;KAAE,CACrD,CAAC;CACH;AA6DD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,YAAY,EAAE,GACzB,cAAc,CAuDhB;AAID,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EACJ,MAAM,GACN,UAAU,GACV,QAAQ,GACR,aAAa,GACb,SAAS,GACT,iBAAiB,GACjB,WAAW,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,WAAW,CAoBlE;AAED,wBAAgB,eAAe,CAC7B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,MAAM,EAAE,WAAW,GAClB,IAAI,CAIN;AAID;;;;;GAKG;AACH;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,SAAS,EAAE,YAAY,EAAE,EACzB,MAAM,EAAE,WAAW,EACnB,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,QAAQ,CAAC,EAAE,cAAc,GACxB,mBAAmB,CAgFrB;AAED,wBAAgB,YAAY,CAC1B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,SAAS,EAAE,YAAY,EAAE,EACzB,MAAM,EAAE,WAAW,EACnB,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,QAAQ,CAAC,EAAE,cAAc,GACxB,YAAY,EAAE,CAOhB;AAQD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,YAAY,EAAE,EACrB,MAAM,EAAE,WAAW,GAClB,YAAY,EAAE,CAmEhB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,IAAI,CAc7E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,EAC3B,QAAQ,EAAE,YAAY,EAAE,GACvB,IAAI,CA0BN;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,YAAY,EAAE,CAkB/D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,WAAW,EAAE,mBAAmB,EAAE,GACjC,IAAI,CAsBN;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,mBAAmB,EAAE,CAkBvB;AAID;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,YAAY,EAAE,GACrB,aAAa,EAAE,CA6DjB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,aAAa,EAAE,GACrB,IAAI,CA0BN;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,SAAS,EAAE,MAAM,GAChB,aAAa,EAAE,CAoBjB;AAID,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,mBAAmB,EAAE,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,YAAY,EAAE,EACrB,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,QAAQ,CAAC,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,EACvB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACtB,KAAK,CAsEP;AAID,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,6EAA6E;IAC7E,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,gBAAgB,CAmBhE;AAID;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,mBAAmB,EAAE,EAClC,KAAK,EAAE,YAAY,EAAE,EACrB,eAAe,EAAE,MAAM,GACtB,MAAM,CAyDR;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,YAAY,EAAE,EACrB,MAAM,EAAE,WAAW,EACnB,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACtB,eAAe,CAwJjB;AAID;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,mBAAmB,EAAE,EACrC,cAAc,EAAE,mBAAmB,EAAE,EACrC,SAAS,SAAM,GACd,mBAAmB,EAAE,CAkEvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,KAAK,EACZ,aAAa,SAAM,GAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,GAAG,CAAC,MAAM,CAAC,CASb;AA0BD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,SAAS,EAAE,YAAY,EAAE,EACzB,MAAM,CAAC,EAAE,WAAW,EACpB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EACvB,QAAQ,CAAC,EAAE,MAAM,GAChB,eAAe,CAuFjB;AAID,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,eAAe,CAAC;IACpB,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,SAAS,EAAE,YAAY,EAAE,EACzB,MAAM,CAAC,EAAE,WAAW,EACpB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EACvB,QAAQ,CAAC,EAAE,MAAM,GAChB,2BAA2B,CAiF7B;AAID,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,mBAAmB,EAAE,gBAAgB,EAQjD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,iBAAiB,CA8CnB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,YAAY,EAAE,EACrB,UAAU,EAAE,WAAW,EACvB,cAAc,EAAE,gBAAgB,EAAE,EAClC,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACtB,iBAAiB,EAAE,CAsBrB"}