@ophan/core 0.0.2 → 0.0.4

package/dist/community-detectors/index.d.ts

@@ -0,0 +1,20 @@
+export type { CommunityDetector, RawDetectionResult, DetectorOptions } from "./types";
+export { LouvainDetector } from "./louvain";
+export { LabelPropDetector } from "./label-prop";
+export { LeidenDetector } from "./leiden";
+import type { CommunityDetector } from "./types";
+/**
+ * Register a community detection algorithm.
+ * Call before detectCommunities() to make the algorithm available via GraphConfig.algorithm.
+ */
+export declare function registerDetector(detector: CommunityDetector): void;
+/**
+ * Get a registered detector by name.
+ * Throws if the algorithm is not registered.
+ */
+export declare function getDetector(name: string): CommunityDetector;
+/**
+ * List all registered detector names.
+ */
+export declare function listDetectors(): string[];
+//# sourceMappingURL=index.d.ts.map

package/dist/community-detectors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/community-detectors/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAOjD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAElE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAO3D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAExC"}

package/dist/community-detectors/index.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LeidenDetector = exports.LabelPropDetector = exports.LouvainDetector = void 0;
+exports.registerDetector = registerDetector;
+exports.getDetector = getDetector;
+exports.listDetectors = listDetectors;
+var louvain_1 = require("./louvain");
+Object.defineProperty(exports, "LouvainDetector", { enumerable: true, get: function () { return louvain_1.LouvainDetector; } });
+var label_prop_1 = require("./label-prop");
+Object.defineProperty(exports, "LabelPropDetector", { enumerable: true, get: function () { return label_prop_1.LabelPropDetector; } });
+var leiden_1 = require("./leiden");
+Object.defineProperty(exports, "LeidenDetector", { enumerable: true, get: function () { return leiden_1.LeidenDetector; } });
+const louvain_2 = require("./louvain");
+const label_prop_2 = require("./label-prop");
+const leiden_2 = require("./leiden");
+const registry = new Map();
+/**
+ * Register a community detection algorithm.
+ * Call before detectCommunities() to make the algorithm available via GraphConfig.algorithm.
+ */
+function registerDetector(detector) {
+    registry.set(detector.name, detector);
+}
+/**
+ * Get a registered detector by name.
+ * Throws if the algorithm is not registered.
+ */
+function getDetector(name) {
+    const detector = registry.get(name);
+    if (!detector) {
+        const available = [...registry.keys()].join(", ");
+        throw new Error(`Unknown community detection algorithm: "${name}". Available: ${available}`);
+    }
+    return detector;
+}
+/**
+ * List all registered detector names.
+ */
+function listDetectors() {
+    return [...registry.keys()];
+}
+// Register built-in detectors
+registerDetector(new louvain_2.LouvainDetector());
+registerDetector(new label_prop_2.LabelPropDetector());
+registerDetector(new leiden_2.LeidenDetector());

package/dist/community-detectors/label-prop.d.ts

@@ -0,0 +1,20 @@
+import type Graph from "graphology";
+import type { CommunityDetector, DetectorOptions, RawDetectionResult } from "./types";
+/**
+ * Label Propagation Algorithm (LPA) for community detection.
+ *
+ * Each node starts with a unique label. On each iteration, every node adopts
+ * the label with the highest total edge weight among its neighbors. Ties are
+ * broken randomly. Converges when no node changes its label.
+ *
+ * Pros: fast, no resolution parameter needed, finds natural cluster boundaries
+ * Cons: non-deterministic, may produce different results on each run
+ */
+export declare class LabelPropDetector implements CommunityDetector {
+    readonly name = "label-propagation";
+    readonly supportsResolution = false;
+    private maxIterations;
+    constructor(maxIterations?: number);
+    detect(graph: Graph, options: DetectorOptions): RawDetectionResult;
+}
+//# sourceMappingURL=label-prop.d.ts.map

package/dist/community-detectors/label-prop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-prop.d.ts","sourceRoot":"","sources":["../../src/community-detectors/label-prop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAEtF;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,YAAW,iBAAiB;IACzD,QAAQ,CAAC,IAAI,uBAAuB;IACpC,QAAQ,CAAC,kBAAkB,SAAS;IAEpC,OAAO,CAAC,aAAa,CAAS;gBAElB,aAAa,SAAM;IAI/B,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,GAAG,kBAAkB;CA8DnE"}

package/dist/community-detectors/label-prop.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LabelPropDetector = void 0;
+/**
+ * Label Propagation Algorithm (LPA) for community detection.
+ *
+ * Each node starts with a unique label. On each iteration, every node adopts
+ * the label with the highest total edge weight among its neighbors. Ties are
+ * broken randomly. Converges when no node changes its label.
+ *
+ * Pros: fast, no resolution parameter needed, finds natural cluster boundaries
+ * Cons: non-deterministic, may produce different results on each run
+ */
+class LabelPropDetector {
+    constructor(maxIterations = 100) {
+        this.name = "label-propagation";
+        this.supportsResolution = false;
+        this.maxIterations = maxIterations;
+    }
+    detect(graph, options) {
+        // Initialize: each node gets a unique label
+        const labels = new Map();
+        let nextLabel = 0;
+        graph.forEachNode((node) => {
+            labels.set(node, nextLabel++);
+        });
+        const nodes = graph.nodes();
+        for (let iter = 0; iter < this.maxIterations; iter++) {
+            let changed = false;
+            // Shuffle nodes for random processing order (reduces bias)
+            for (let i = nodes.length - 1; i > 0; i--) {
+                const j = Math.floor(Math.random() * (i + 1));
+                [nodes[i], nodes[j]] = [nodes[j], nodes[i]];
+            }
+            for (const node of nodes) {
+                // Sum weights per neighboring label
+                const labelWeights = new Map();
+                graph.forEachEdge(node, (_edge, attrs, source, target) => {
+                    const neighbor = source === node ? target : source;
+                    const neighborLabel = labels.get(neighbor);
+                    const weight = attrs[options.weightAttribute] || 1.0;
+                    labelWeights.set(neighborLabel, (labelWeights.get(neighborLabel) || 0) + weight);
+                });
+                if (labelWeights.size === 0)
+                    continue;
+                // Find label(s) with maximum weight
+                let maxWeight = -Infinity;
+                const candidates = [];
+                for (const [label, weight] of labelWeights) {
+                    if (weight > maxWeight) {
+                        maxWeight = weight;
+                        candidates.length = 0;
+                        candidates.push(label);
+                    }
+                    else if (weight === maxWeight) {
+                        candidates.push(label);
+                    }
+                }
+                // Break ties randomly
+                const chosen = candidates[Math.floor(Math.random() * candidates.length)];
+                if (chosen !== labels.get(node)) {
+                    labels.set(node, chosen);
+                    changed = true;
+                }
+            }
+            if (!changed)
+                break;
+        }
+        // Convert to Record<string, number>
+        const communities = {};
+        for (const [node, label] of labels) {
+            communities[node] = label;
+        }
+        return { communities, modularity: null };
+    }
+}
+exports.LabelPropDetector = LabelPropDetector;

package/dist/community-detectors/leiden.d.ts

@@ -0,0 +1,22 @@
+import type Graph from "graphology";
+import type { CommunityDetector, DetectorOptions, RawDetectionResult } from "./types";
+/**
+ * Leiden community detection algorithm (Traag, van Eck & Waltman, 2019).
+ *
+ * Improvement over Louvain with three phases per iteration:
+ *   1. Local moving: nodes move to neighboring community maximizing modularity gain
+ *   2. Refinement: ensures each community is internally connected by re-examining
+ *      sub-structure within communities (the key Leiden innovation)
+ *   3. Aggregation: create super-graph where communities become nodes
+ *
+ * Guarantees communities are well-connected (no disconnected subgroups within a community).
+ * Uses modularity quality function: Q = Σ_c [e_c/m - γ(n_c/2m)²]
+ *
+ * Reference: https://arxiv.org/abs/1810.08473
+ */
+export declare class LeidenDetector implements CommunityDetector {
+    readonly name = "leiden";
+    readonly supportsResolution = true;
+    detect(graph: Graph, options: DetectorOptions): RawDetectionResult;
+}
+//# sourceMappingURL=leiden.d.ts.map

package/dist/community-detectors/leiden.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leiden.d.ts","sourceRoot":"","sources":["../../src/community-detectors/leiden.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAe,YAAW,iBAAiB;IACtD,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,kBAAkB,QAAQ;IAEnC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,GAAG,kBAAkB;CAqEnE"}

package/dist/community-detectors/leiden.js

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LeidenDetector = void 0;
+/**
+ * Leiden community detection algorithm (Traag, van Eck & Waltman, 2019).
+ *
+ * Improvement over Louvain with three phases per iteration:
+ *   1. Local moving: nodes move to neighboring community maximizing modularity gain
+ *   2. Refinement: ensures each community is internally connected by re-examining
+ *      sub-structure within communities (the key Leiden innovation)
+ *   3. Aggregation: create super-graph where communities become nodes
+ *
+ * Guarantees communities are well-connected (no disconnected subgroups within a community).
+ * Uses modularity quality function: Q = Σ_c [e_c/m - γ(n_c/2m)²]
+ *
+ * Reference: https://arxiv.org/abs/1810.08473
+ */
+class LeidenDetector {
+    constructor() {
+        this.name = "leiden";
+        this.supportsResolution = true;
+    }
+    detect(graph, options) {
+        if (graph.order === 0) {
+            return { communities: {}, modularity: null };
+        }
+        const nodes = graph.nodes();
+        const weightAttr = options.weightAttribute;
+        const resolution = options.resolution;
+        // Total edge weight in graph (sum of all edge weights)
+        let totalWeight = 0;
+        graph.forEachEdge((_edge, attrs) => {
+            totalWeight += attrs[weightAttr] || 1.0;
+        });
+        if (totalWeight === 0) {
+            // No edges — each node is its own community
+            const communities = {};
+            nodes.forEach((n, i) => { communities[n] = i; });
+            return { communities, modularity: 0 };
+        }
+        // Initialize: each node in its own community
+        const nodeToComm = new Map();
+        nodes.forEach((n, i) => nodeToComm.set(n, i));
+        let nextCommId = nodes.length;
+        // Precompute node strengths (weighted degree)
+        const nodeStrength = new Map();
+        for (const node of nodes) {
+            let strength = 0;
+            graph.forEachEdge(node, (_edge, attrs) => {
+                strength += attrs[weightAttr] || 1.0;
+            });
+            nodeStrength.set(node, strength);
+        }
+        // Run Leiden iterations
+        const maxIterations = 10;
+        for (let iter = 0; iter < maxIterations; iter++) {
+            const moved = localMovingPhase(graph, nodeToComm, nodeStrength, totalWeight, resolution, weightAttr);
+            refinementPhase(graph, nodeToComm, nodeStrength, totalWeight, resolution, weightAttr, nextCommId);
+            // Update nextCommId to be above any community ID used
+            let maxComm = 0;
+            for (const c of nodeToComm.values()) {
+                if (c > maxComm)
+                    maxComm = c;
+            }
+            nextCommId = maxComm + 1;
+            if (!moved)
+                break;
+        }
+        // Renumber communities to contiguous integers
+        const communities = {};
+        const commRemap = new Map();
+        let nextId = 0;
+        for (const node of nodes) {
+            const comm = nodeToComm.get(node);
+            if (!commRemap.has(comm)) {
+                commRemap.set(comm, nextId++);
+            }
+            communities[node] = commRemap.get(comm);
+        }
+        // Compute modularity
+        const modularity = computeModularity(graph, communities, totalWeight, resolution, weightAttr);
+        return { communities, modularity };
+    }
+}
+exports.LeidenDetector = LeidenDetector;
+/**
+ * Phase 1: Local moving — nodes greedily move to neighboring community maximizing modularity gain.
+ * Returns true if any node moved.
+ */
+function localMovingPhase(graph, nodeToComm, nodeStrength, totalWeight, resolution, weightAttr) {
+    const nodes = graph.nodes();
+    let moved = false;
+    // Shuffle nodes for random processing order
+    for (let i = nodes.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [nodes[i], nodes[j]] = [nodes[j], nodes[i]];
+    }
+    // Precompute community aggregate strengths
+    const commStrength = new Map();
+    for (const [node, comm] of nodeToComm) {
+        commStrength.set(comm, (commStrength.get(comm) || 0) + (nodeStrength.get(node) || 0));
+    }
+    for (const node of nodes) {
+        const currentComm = nodeToComm.get(node);
+        const ki = nodeStrength.get(node) || 0;
+        // Sum edge weights to each neighboring community
+        const neighborCommWeights = new Map();
+        graph.forEachEdge(node, (_edge, attrs, source, target) => {
+            const neighbor = source === node ? target : source;
+            const neighborComm = nodeToComm.get(neighbor);
+            const weight = attrs[weightAttr] || 1.0;
+            neighborCommWeights.set(neighborComm, (neighborCommWeights.get(neighborComm) || 0) + weight);
+        });
+        // Temporarily remove node from its community for evaluation
+        const currentCommStrengthWithout = (commStrength.get(currentComm) || 0) - ki;
+        const edgesToCurrent = neighborCommWeights.get(currentComm) || 0;
+        // Modularity loss from removing node from current community
+        const removeLoss = edgesToCurrent / totalWeight - resolution * ki * currentCommStrengthWithout / (2 * totalWeight * totalWeight);
+        // Find best community to move to
+        let bestComm = currentComm;
+        let bestGain = 0;
+        for (const [comm, edgesToComm] of neighborCommWeights) {
+            if (comm === currentComm)
+                continue;
+            const commStr = commStrength.get(comm) || 0;
+            // Modularity gain from adding node to this community
+            const addGain = edgesToComm / totalWeight - resolution * ki * commStr / (2 * totalWeight * totalWeight);
+            const netGain = addGain - removeLoss;
+            if (netGain > bestGain) {
+                bestGain = netGain;
+                bestComm = comm;
+            }
+        }
+        if (bestComm !== currentComm) {
+            // Move node
+            commStrength.set(currentComm, (commStrength.get(currentComm) || 0) - ki);
+            commStrength.set(bestComm, (commStrength.get(bestComm) || 0) + ki);
+            nodeToComm.set(node, bestComm);
+            moved = true;
+        }
+    }
+    return moved;
+}
+/**
+ * Phase 2: Refinement — ensures communities are internally connected.
+ * For each community, check if it can be split into better-connected sub-communities.
+ * Nodes that are weakly connected within their community are moved to improve quality.
+ */
+function refinementPhase(graph, nodeToComm, nodeStrength, totalWeight, resolution, weightAttr, nextCommId) {
+    // Group nodes by community
+    const commMembers = new Map();
+    for (const [node, comm] of nodeToComm) {
+        const members = commMembers.get(comm) || [];
+        members.push(node);
+        commMembers.set(comm, members);
+    }
+    for (const [commId, members] of commMembers) {
+        if (members.length <= 2)
+            continue;
+        // Check connectivity within this community using BFS
+        // If community is already a single connected component, skip refinement
+        const memberSet = new Set(members);
+        const components = findConnectedComponents(graph, memberSet, weightAttr);
+        if (components.length <= 1) {
+            // Community is connected — try sub-community refinement
+            // Each node starts in its own sub-community within this community
+            const subComm = new Map();
+            let subId = nextCommId;
+            for (const member of members) {
+                subComm.set(member, subId++);
+            }
+            // Precompute sub-community strengths
+            const subCommStrength = new Map();
+            for (const member of members) {
+                const sc = subComm.get(member);
+                subCommStrength.set(sc, nodeStrength.get(member) || 0);
+            }
+            // Local moving within this community only — iterate until convergence
+            for (let refIter = 0; refIter < 10; refIter++) {
+                let refMoved = false;
+                // Shuffle members
+                const shuffled = [...members];
+                for (let i = shuffled.length - 1; i > 0; i--) {
+                    const j = Math.floor(Math.random() * (i + 1));
+                    [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+                }
+                for (const node of shuffled) {
+                    const currentSub = subComm.get(node);
+                    const ki = nodeStrength.get(node) || 0;
+                    const neighborSubWeights = new Map();
+                    graph.forEachEdge(node, (_edge, attrs, source, target) => {
+                        const neighbor = source === node ? target : source;
+                        if (!memberSet.has(neighbor))
+                            return; // Only within this community
+                        const nSub = subComm.get(neighbor);
+                        const weight = attrs[weightAttr] || 1.0;
+                        neighborSubWeights.set(nSub, (neighborSubWeights.get(nSub) || 0) + weight);
+                    });
+                    const edgesToCurrent = neighborSubWeights.get(currentSub) || 0;
+                    const currentSubStr = (subCommStrength.get(currentSub) || 0) - ki;
+                    const removeLoss = edgesToCurrent / totalWeight - resolution * ki * currentSubStr / (2 * totalWeight * totalWeight);
+                    let bestSub = currentSub;
+                    let bestGain = 0;
+                    for (const [sc, edgesToSub] of neighborSubWeights) {
+                        if (sc === currentSub)
+                            continue;
+                        const scStr = subCommStrength.get(sc) || 0;
+                        const addGain = edgesToSub / totalWeight - resolution * ki * scStr / (2 * totalWeight * totalWeight);
+                        const netGain = addGain - removeLoss;
+                        if (netGain > bestGain) {
+                            bestGain = netGain;
+                            bestSub = sc;
+                        }
+                    }
+                    if (bestSub !== currentSub) {
+                        subCommStrength.set(currentSub, (subCommStrength.get(currentSub) || 0) - ki);
+                        subCommStrength.set(bestSub, (subCommStrength.get(bestSub) || 0) + ki);
+                        subComm.set(node, bestSub);
+                        refMoved = true;
+                    }
+                }
+                if (!refMoved)
+                    break;
+            }
+            // Check if refinement produced multiple sub-communities
+            const subGroups = new Map();
+            for (const member of members) {
+                const sc = subComm.get(member);
+                const group = subGroups.get(sc) || [];
+                group.push(member);
+                subGroups.set(sc, group);
+            }
+            if (subGroups.size > 1) {
+                // Apply the refined partition — each sub-community gets its own ID
+                for (const [subCommId, subMembers] of subGroups) {
+                    for (const member of subMembers) {
+                        nodeToComm.set(member, subCommId);
+                    }
+                }
+            }
+        }
+        else {
+            // Community is disconnected — split into connected components
+            for (let i = 1; i < components.length; i++) {
+                const newId = nextCommId++;
+                for (const node of components[i]) {
+                    nodeToComm.set(node, newId);
+                }
+            }
+        }
+    }
+}
+/**
+ * Find connected components within a subset of nodes on the graph.
+ * Only traverses edges where both endpoints are in the subset.
+ */
+function findConnectedComponents(graph, memberSet, weightAttr) {
+    const visited = new Set();
+    const components = [];
+    for (const node of memberSet) {
+        if (visited.has(node))
+            continue;
+        const component = [];
+        const queue = [node];
+        visited.add(node);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            component.push(current);
+            graph.forEachEdge(current, (_edge, attrs, source, target) => {
+                const neighbor = source === current ? target : source;
+                if (memberSet.has(neighbor) && !visited.has(neighbor)) {
+                    const weight = attrs[weightAttr] || 1.0;
+                    if (weight > 0) {
+                        visited.add(neighbor);
+                        queue.push(neighbor);
+                    }
+                }
+            });
+        }
+        components.push(component);
+    }
+    return components;
+}
+/**
+ * Compute modularity of a partition.
+ * Q = (1/2m) Σ_ij [A_ij - γ * ki*kj / 2m] * δ(ci, cj)
+ */
+function computeModularity(graph, communities, totalWeight, resolution, weightAttr) {
+    if (totalWeight === 0)
+        return 0;
+    // Sum of edge weights within communities
+    let internalWeight = 0;
+    graph.forEachEdge((_edge, attrs, source, target) => {
+        if (communities[source] === communities[target]) {
+            internalWeight += attrs[weightAttr] || 1.0;
+        }
+    });
+    // Sum of strengths per community
+    const commStrength = new Map();
+    for (const [node, comm] of Object.entries(communities)) {
+        let strength = 0;
+        graph.forEachEdge(node, (_edge, attrs) => {
+            strength += attrs[weightAttr] || 1.0;
+        });
+        commStrength.set(comm, (commStrength.get(comm) || 0) + strength);
+    }
+    let expectedWeight = 0;
+    for (const strength of commStrength.values()) {
+        expectedWeight += strength * strength;
+    }
+    return internalWeight / (2 * totalWeight) - resolution * expectedWeight / (4 * totalWeight * totalWeight);
+}

package/dist/community-detectors/louvain.d.ts

@@ -0,0 +1,13 @@
+import type Graph from "graphology";
+import type { CommunityDetector, DetectorOptions, RawDetectionResult } from "./types";
+/**
+ * Louvain community detection via graphology-communities-louvain.
+ * Deterministic, fast, returns modularity score. Resolution parameter
+ * controls granularity (higher = more, smaller communities).
+ */
+export declare class LouvainDetector implements CommunityDetector {
+    readonly name = "louvain";
+    readonly supportsResolution = true;
+    detect(graph: Graph, options: DetectorOptions): RawDetectionResult;
+}
+//# sourceMappingURL=louvain.d.ts.map

package/dist/community-detectors/louvain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"louvain.d.ts","sourceRoot":"","sources":["../../src/community-detectors/louvain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AAEpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAEtF;;;;GAIG;AACH,qBAAa,eAAgB,YAAW,iBAAiB;IACvD,QAAQ,CAAC,IAAI,aAAa;IAC1B,QAAQ,CAAC,kBAAkB,QAAQ;IAEnC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,GAAG,kBAAkB;CAUnE"}

package/dist/community-detectors/louvain.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LouvainDetector = void 0;
+const graphology_communities_louvain_1 = __importDefault(require("graphology-communities-louvain"));
+/**
+ * Louvain community detection via graphology-communities-louvain.
+ * Deterministic, fast, returns modularity score. Resolution parameter
+ * controls granularity (higher = more, smaller communities).
+ */
+class LouvainDetector {
+    constructor() {
+        this.name = "louvain";
+        this.supportsResolution = true;
+    }
+    detect(graph, options) {
+        const result = graphology_communities_louvain_1.default.detailed(graph, {
+            resolution: options.resolution,
+            getEdgeWeight: options.weightAttribute,
+        });
+        return {
+            communities: result.communities,
+            modularity: result.modularity,
+        };
+    }
+}
+exports.LouvainDetector = LouvainDetector;

package/dist/community-detectors/types.d.ts

@@ -0,0 +1,36 @@
+import type Graph from "graphology";
+/**
+ * Raw output from a community detection algorithm.
+ * Maps node IDs to integer community labels. Post-processing (dissolution,
+ * splitting, rescue, stable matching) is handled by detectCommunities().
+ */
+export interface RawDetectionResult {
+    /** Node ID → community label */
+    communities: Record<string, number>;
+    /** Modularity score (null if the algorithm doesn't compute it) */
+    modularity: number | null;
+}
+/**
+ * Options passed to a detector's detect() method.
+ */
+export interface DetectorOptions {
+    /** Louvain resolution parameter (ignored by algorithms that don't support it) */
+    resolution: number;
+    /** Edge weight attribute name on the graphology graph */
+    weightAttribute: string;
+}
+/**
+ * Strategy interface for community detection algorithms.
+ * Implementations wrap a specific algorithm (Louvain, label propagation, etc.)
+ * and produce raw community assignments. All post-processing is algorithm-agnostic
+ * and stays in detectCommunities().
+ */
+export interface CommunityDetector {
+    /** Algorithm identifier (e.g., "louvain", "label-propagation") */
+    readonly name: string;
+    /** Whether this algorithm uses the resolution parameter */
+    readonly supportsResolution: boolean;
+    /** Run community detection on the given graph */
+    detect(graph: Graph, options: DetectorOptions): RawDetectionResult;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/community-detectors/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/community-detectors/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AAEpC;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,kEAAkE;IAClE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC,iDAAiD;IACjD,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,GAAG,kBAAkB,CAAC;CACpE"}

package/dist/{parsers/__fixtures__/no-functions.js → community-detectors/types.js}

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

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

@@ -0,0 +1,13 @@
+import type { EdgeResolver, EdgeResolverContext } from "./types";
+import type { FunctionEdge } from "../graph";
+/**
+ * Resolves direct function call edges.
+ * For each function's calls[] array, looks up callee names in the name→hash index.
+ * Creates edges from caller to all matching callees (handles name collisions).
+ * Self-calls are skipped.
+ */
+export declare class CallEdgeResolver implements EdgeResolver {
+    readonly edgeTypes: readonly ["call"];
+    resolve(ctx: EdgeResolverContext): FunctionEdge[];
+}
+//# sourceMappingURL=call.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"call.d.ts","sourceRoot":"","sources":["../../src/edge-resolvers/call.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,gBAAiB,YAAW,YAAY;IACnD,QAAQ,CAAC,SAAS,oBAAqB;IAEvC,OAAO,CAAC,GAAG,EAAE,mBAAmB,GAAG,YAAY,EAAE;CAqBlD"}

package/dist/edge-resolvers/call.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallEdgeResolver = void 0;
+/**
+ * Resolves direct function call edges.
+ * For each function's calls[] array, looks up callee names in the name→hash index.
+ * Creates edges from caller to all matching callees (handles name collisions).
+ * Self-calls are skipped.
+ */
+class CallEdgeResolver {
+    constructor() {
+        this.edgeTypes = ["call"];
+    }
+    resolve(ctx) {
+        const edges = [];
+        for (const fn of ctx.functions) {
+            if (ctx.affectedHashes && !ctx.affectedHashes.has(fn.contentHash))
+                continue;
+            if (!fn.calls)
+                continue;
+            for (const calledName of fn.calls) {
+                const targetHashes = ctx.nameToHashes.get(calledName);
+                if (!targetHashes)
+                    continue;
+                for (const targetHash of targetHashes) {
+                    if (targetHash === fn.contentHash)
+                        continue;
+                    edges.push({
+                        sourceHash: fn.contentHash,
+                        targetHash,
+                        edgeType: "call",
+                        weight: ctx.config.edgeWeights.call,
+                    });
+                }
+            }
+        }
+        return edges;
+    }
+}
+exports.CallEdgeResolver = CallEdgeResolver;