@ophan/core 0.0.1 → 0.0.3

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;

package/dist/edge-resolvers/co-location.d.ts

@@ -0,0 +1,16 @@
+import type { EdgeResolver, EdgeResolverContext } from "./types";
+import type { FunctionEdge } from "../graph";
+/**
+ * Resolves co-location edges — proximity-based connections between functions
+ * in the same file or same directory.
+ *
+ * Same-file: all-pairs with weight decaying by positional distance (1/offset).
+ * Directory (cross-file): half the same-file weight, also decaying by offset.
+ *
+ * Owns a shared dedup Set to prevent duplicate edges across both phases.
+ */
+export declare class CoLocationEdgeResolver implements EdgeResolver {
+    readonly edgeTypes: readonly ["co_location"];
+    resolve(ctx: EdgeResolverContext): FunctionEdge[];
+}
+//# sourceMappingURL=co-location.d.ts.map

package/dist/edge-resolvers/co-location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"co-location.d.ts","sourceRoot":"","sources":["../../src/edge-resolvers/co-location.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,YAAW,YAAY;IACzD,QAAQ,CAAC,SAAS,2BAA4B;IAE9C,OAAO,CAAC,GAAG,EAAE,mBAAmB,GAAG,YAAY,EAAE;CAsFlD"}

package/dist/edge-resolvers/co-location.js

@@ -0,0 +1,129 @@
+"use strict";
+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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CoLocationEdgeResolver = void 0;
+const path = __importStar(require("path"));
+/**
+ * Resolves co-location edges — proximity-based connections between functions
+ * in the same file or same directory.
+ *
+ * Same-file: all-pairs with weight decaying by positional distance (1/offset).
+ * Directory (cross-file): half the same-file weight, also decaying by offset.
+ *
+ * Owns a shared dedup Set to prevent duplicate edges across both phases.
+ */
+class CoLocationEdgeResolver {
+    constructor() {
+        this.edgeTypes = ["co_location"];
+    }
+    resolve(ctx) {
+        const edges = [];
+        const colocAdded = new Set();
+        // Phase 1: Same-file co-location
+        for (const fn of ctx.functions) {
+            if (ctx.affectedHashes && !ctx.affectedHashes.has(fn.contentHash))
+                continue;
+            const sortedSiblings = ctx.fileToSortedFns.get(fn.filePath);
+            if (!sortedSiblings || sortedSiblings.length <= 1)
+                continue;
+            const idx = sortedSiblings.indexOf(fn);
+            if (idx < 0)
+                continue;
+            for (let offset = 1; offset < sortedSiblings.length - idx; offset++) {
+                const neighbor = sortedSiblings[idx + offset];
+                if (!neighbor)
+                    break;
+                const a = fn.contentHash < neighbor.contentHash
+                    ? fn.contentHash
+                    : neighbor.contentHash;
+                const b = fn.contentHash < neighbor.contentHash
+                    ? neighbor.contentHash
+                    : fn.contentHash;
+                const key = `${a}|${b}`;
+                if (!colocAdded.has(key)) {
+                    colocAdded.add(key);
+                    edges.push({
+                        sourceHash: a,
+                        targetHash: b,
+                        edgeType: "co_location",
+                        weight: ctx.config.edgeWeights.co_location / offset,
+                    });
+                }
+            }
+        }
+        // Phase 2: Directory co-location (cross-file, same directory)
+        const dirToFns = new Map();
+        for (const fn of ctx.functions) {
+            const dir = path.dirname(fn.filePath);
+            const list = dirToFns.get(dir) || [];
+            list.push(fn);
+            dirToFns.set(dir, list);
+        }
+        const dirWeight = ctx.config.edgeWeights.co_location * 0.5;
+        for (const fns of dirToFns.values()) {
+            const files = new Set(fns.map((f) => f.filePath));
+            if (files.size < 2)
+                continue;
+            fns.sort((a, b) => a.filePath.localeCompare(b.filePath) || a.startLine - b.startLine);
+            for (let i = 0; i < fns.length; i++) {
+                if (ctx.affectedHashes && !ctx.affectedHashes.has(fns[i].contentHash))
+                    continue;
+                for (let j = i + 1; j < fns.length; j++) {
+                    if (fns[i].filePath === fns[j].filePath)
+                        continue;
+                    const a = fns[i].contentHash < fns[j].contentHash
+                        ? fns[i].contentHash
+                        : fns[j].contentHash;
+                    const b = fns[i].contentHash < fns[j].contentHash
+                        ? fns[j].contentHash
+                        : fns[i].contentHash;
+                    const key = `${a}|${b}`;
+                    if (!colocAdded.has(key)) {
+                        colocAdded.add(key);
+                        const offset = j - i;
+                        edges.push({
+                            sourceHash: a,
+                            targetHash: b,
+                            edgeType: "co_location",
+                            weight: dirWeight / offset,
+                        });
+                    }
+                }
+            }
+        }
+        return edges;
+    }
+}
+exports.CoLocationEdgeResolver = CoLocationEdgeResolver;

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

@@ -0,0 +1,16 @@
+import type { EdgeResolver, EdgeResolverContext } from "./types";
+import type { FunctionEdge } from "../graph";
+/**
+ * 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).
+ */
+export declare class ImportEdgeResolver implements EdgeResolver {
+    readonly edgeTypes: readonly ["import"];
+    resolve(ctx: EdgeResolverContext): FunctionEdge[];
+}
+//# sourceMappingURL=import.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../src/edge-resolvers/import.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAG7C;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD,QAAQ,CAAC,SAAS,sBAAuB;IAEzC,OAAO,CAAC,GAAG,EAAE,mBAAmB,GAAG,YAAY,EAAE;CAqHlD"}