@optave/codegraph 3.5.0 → 3.7.0

package/src/graph/algorithms/leiden/adapter.ts

@@ -50,6 +50,111 @@ function taAdd(a: Float64Array, i: number, v: number): void {
   a[i] = taGet(a, i) + v;
 }
 
+/**
+ * Populate edge arrays for a directed graph. Each edge is stored once in
+ * outEdges[from] and inEdges[to]. Self-loops are tracked in both the selfLoop
+ * array and the adjacency lists (partition.ts accounts for this).
+ */
+function populateDirectedEdges(
+  graph: CodeGraph,
+  idToIndex: Map<string, number>,
+  linkWeight: (attrs: EdgeAttrs) => number,
+  selfLoop: Float64Array,
+  outEdges: EdgeEntry[][],
+  inEdges: InEdgeEntry[][],
+  strengthOut: Float64Array,
+  strengthIn: Float64Array,
+): void {
+  for (const [src, tgt, attrs] of graph.edges()) {
+    const from = idToIndex.get(src);
+    const to = idToIndex.get(tgt);
+    if (from == null || to == null) continue;
+    const w: number = +linkWeight(attrs) || 0;
+    if (from === to) {
+      taAdd(selfLoop, from, w);
+      // Self-loop is intentionally kept in outEdges/inEdges as well.
+      // partition.ts's moveNodeToCommunity (directed path) accounts for this
+      // by subtracting selfLoopWeight once from outToOld+inFromOld to avoid
+      // triple-counting (see partition.ts moveNodeToCommunity directed block).
+    }
+    (outEdges[from] as EdgeEntry[]).push({ to, w });
+    (inEdges[to] as InEdgeEntry[]).push({ from, w });
+    taAdd(strengthOut, from, w);
+    taAdd(strengthIn, to, w);
+  }
+}
+
+/**
+ * Populate edge arrays for an undirected graph. Reciprocal pairs are
+ * symmetrized and averaged to produce a single weight per undirected edge.
+ * Self-loops use single-w convention (matching modularity.ts formulas).
+ */
+function populateUndirectedEdges(
+  graph: CodeGraph,
+  idToIndex: Map<string, number>,
+  linkWeight: (attrs: EdgeAttrs) => number,
+  n: number,
+  selfLoop: Float64Array,
+  outEdges: EdgeEntry[][],
+  inEdges: InEdgeEntry[][],
+  strengthOut: Float64Array,
+  strengthIn: Float64Array,
+): void {
+  const pairAgg = new Map<string, { sum: number; seenAB: number; seenBA: number }>();
+
+  for (const [src, tgt, attrs] of graph.edges()) {
+    const a = idToIndex.get(src);
+    const b = idToIndex.get(tgt);
+    if (a == null || b == null) continue;
+    const w: number = +linkWeight(attrs) || 0;
+    if (a === b) {
+      taAdd(selfLoop, a, w);
+      continue;
+    }
+    const i = a < b ? a : b;
+    const j = a < b ? b : a;
+    const key = `${i}:${j}`;
+    let rec = pairAgg.get(key);
+    if (!rec) {
+      rec = { sum: 0, seenAB: 0, seenBA: 0 };
+      pairAgg.set(key, rec);
+    }
+    rec.sum += w;
+    if (a === i) rec.seenAB = 1;
+    else rec.seenBA = 1;
+  }
+
+  for (const [key, rec] of pairAgg.entries()) {
+    const parts = key.split(':');
+    const i = +(parts[0] as string);
+    const j = +(parts[1] as string);
+    const dirCount: number = (rec.seenAB ? 1 : 0) + (rec.seenBA ? 1 : 0);
+    const w: number = dirCount > 0 ? rec.sum / dirCount : 0;
+    if (w === 0) continue;
+    (outEdges[i] as EdgeEntry[]).push({ to: j, w });
+    (outEdges[j] as EdgeEntry[]).push({ to: i, w });
+    (inEdges[i] as InEdgeEntry[]).push({ from: j, w });
+    (inEdges[j] as InEdgeEntry[]).push({ from: i, w });
+    taAdd(strengthOut, i, w);
+    taAdd(strengthOut, j, w);
+    taAdd(strengthIn, i, w);
+    taAdd(strengthIn, j, w);
+  }
+
+  // Add self-loops into adjacency and strengths.
+  // Note: uses single-w convention (not standard 2w) — the modularity formulas in
+  // modularity.ts are written to match this convention, keeping the system self-consistent.
+  for (let v = 0; v < n; v++) {
+    const w: number = taGet(selfLoop, v);
+    if (w !== 0) {
+      (outEdges[v] as EdgeEntry[]).push({ to: v, w });
+      (inEdges[v] as InEdgeEntry[]).push({ from: v, w });
+      taAdd(strengthOut, v, w);
+      taAdd(strengthIn, v, w);
+    }
+  }
+}
+
 export function makeGraphAdapter(graph: CodeGraph, opts: GraphAdapterOptions = {}): GraphAdapter {
   const linkWeight: (attrs: EdgeAttrs) => number =
     opts.linkWeight || ((attrs) => (attrs && typeof attrs.weight === 'number' ? attrs.weight : 1));
@@ -92,78 +197,28 @@ export function makeGraphAdapter(graph: CodeGraph, opts: GraphAdapterOptions = {
 
   // Populate from graph
   if (directed) {
-    for (const [src, tgt, attrs] of graph.edges()) {
-      const from = idToIndex.get(src);
-      const to = idToIndex.get(tgt);
-      if (from == null || to == null) continue;
-      const w: number = +linkWeight(attrs) || 0;
-      if (from === to) {
-        taAdd(selfLoop, from, w);
-        // Self-loop is intentionally kept in outEdges/inEdges as well.
-        // partition.ts's moveNodeToCommunity (directed path) accounts for this
-        // by subtracting selfLoopWeight once from outToOld+inFromOld to avoid
-        // triple-counting (see partition.ts moveNodeToCommunity directed block).
-      }
-      (outEdges[from] as EdgeEntry[]).push({ to, w });
-      (inEdges[to] as InEdgeEntry[]).push({ from, w });
-      taAdd(strengthOut, from, w);
-      taAdd(strengthIn, to, w);
-    }
+    populateDirectedEdges(
+      graph,
+      idToIndex,
+      linkWeight,
+      selfLoop,
+      outEdges,
+      inEdges,
+      strengthOut,
+      strengthIn,
+    );
   } else {
-    // Undirected: symmetrize and average reciprocal pairs
-    const pairAgg = new Map<string, { sum: number; seenAB: number; seenBA: number }>();
-
-    for (const [src, tgt, attrs] of graph.edges()) {
-      const a = idToIndex.get(src);
-      const b = idToIndex.get(tgt);
-      if (a == null || b == null) continue;
-      const w: number = +linkWeight(attrs) || 0;
-      if (a === b) {
-        taAdd(selfLoop, a, w);
-        continue;
-      }
-      const i = a < b ? a : b;
-      const j = a < b ? b : a;
-      const key = `${i}:${j}`;
-      let rec = pairAgg.get(key);
-      if (!rec) {
-        rec = { sum: 0, seenAB: 0, seenBA: 0 };
-        pairAgg.set(key, rec);
-      }
-      rec.sum += w;
-      if (a === i) rec.seenAB = 1;
-      else rec.seenBA = 1;
-    }
-
-    for (const [key, rec] of pairAgg.entries()) {
-      const parts = key.split(':');
-      const i = +(parts[0] as string);
-      const j = +(parts[1] as string);
-      const dirCount: number = (rec.seenAB ? 1 : 0) + (rec.seenBA ? 1 : 0);
-      const w: number = dirCount > 0 ? rec.sum / dirCount : 0;
-      if (w === 0) continue;
-      (outEdges[i] as EdgeEntry[]).push({ to: j, w });
-      (outEdges[j] as EdgeEntry[]).push({ to: i, w });
-      (inEdges[i] as InEdgeEntry[]).push({ from: j, w });
-      (inEdges[j] as InEdgeEntry[]).push({ from: i, w });
-      taAdd(strengthOut, i, w);
-      taAdd(strengthOut, j, w);
-      taAdd(strengthIn, i, w);
-      taAdd(strengthIn, j, w);
-    }
-
-    // Add self-loops into adjacency and strengths.
-    // Note: uses single-w convention (not standard 2w) — the modularity formulas in
-    // modularity.ts are written to match this convention, keeping the system self-consistent.
-    for (let v = 0; v < n; v++) {
-      const w: number = taGet(selfLoop, v);
-      if (w !== 0) {
-        (outEdges[v] as EdgeEntry[]).push({ to: v, w });
-        (inEdges[v] as InEdgeEntry[]).push({ from: v, w });
-        taAdd(strengthOut, v, w);
-        taAdd(strengthIn, v, w);
-      }
-    }
+    populateUndirectedEdges(
+      graph,
+      idToIndex,
+      linkWeight,
+      n,
+      selfLoop,
+      outEdges,
+      inEdges,
+      strengthOut,
+      strengthIn,
+    );
   }
 
   // Node sizes

package/src/graph/algorithms/leiden/index.ts

@@ -119,34 +119,17 @@ interface OriginalPartition {
   getInEdgeWeightFromCommunity(c: number): number;
 }
 
-function buildOriginalPartition(g: GraphAdapter, communityMap: Int32Array): OriginalPartition {
-  const n: number = g.n;
-  let maxC: number = 0;
-  for (let i = 0; i < n; i++) {
-    const ci = iget(communityMap, i);
-    if (ci > maxC) maxC = ci;
-  }
-  const cc: number = maxC + 1;
-
-  const nodeCommunity = communityMap;
-  const internalWeight = new Float64Array(cc);
-  const totalStr = new Float64Array(cc);
-  const totalOutStr = new Float64Array(cc);
-  const totalInStr = new Float64Array(cc);
-  const totalSize = new Float64Array(cc);
-
-  for (let i = 0; i < n; i++) {
-    const c: number = iget(communityMap, i);
-    totalSize[c] = fget(totalSize, c) + fget(g.size, i);
-    if (g.directed) {
-      totalOutStr[c] = fget(totalOutStr, c) + fget(g.strengthOut, i);
-      totalInStr[c] = fget(totalInStr, c) + fget(g.strengthIn, i);
-    } else {
-      totalStr[c] = fget(totalStr, c) + fget(g.strengthOut, i);
-    }
-    if (fget(g.selfLoop, i)) internalWeight[c] = fget(internalWeight, c) + fget(g.selfLoop, i);
-  }
-
+/**
+ * Accumulate intra-community edge weights for quality evaluation.
+ * For directed graphs, counts all intra-community non-self edges.
+ * For undirected, counts each edge once (j > i) to avoid double-counting.
+ */
+function accumulateInternalEdgeWeights(
+  g: GraphAdapter,
+  communityMap: Int32Array,
+  n: number,
+  internalWeight: Float64Array,
+): void {
   if (g.directed) {
     for (let i = 0; i < n; i++) {
       const ci: number = iget(communityMap, i);
@@ -168,6 +151,62 @@ function buildOriginalPartition(g: GraphAdapter, communityMap: Int32Array): Orig
       }
     }
   }
+}
+
+/**
+ * Accumulate per-community node-level aggregates (size, strength) from
+ * the graph adapter and community mapping.
+ */
+function accumulateNodeAggregates(
+  g: GraphAdapter,
+  communityMap: Int32Array,
+  n: number,
+  totalSize: Float64Array,
+  totalStr: Float64Array,
+  totalOutStr: Float64Array,
+  totalInStr: Float64Array,
+  internalWeight: Float64Array,
+): void {
+  for (let i = 0; i < n; i++) {
+    const c: number = iget(communityMap, i);
+    totalSize[c] = fget(totalSize, c) + fget(g.size, i);
+    if (g.directed) {
+      totalOutStr[c] = fget(totalOutStr, c) + fget(g.strengthOut, i);
+      totalInStr[c] = fget(totalInStr, c) + fget(g.strengthIn, i);
+    } else {
+      totalStr[c] = fget(totalStr, c) + fget(g.strengthOut, i);
+    }
+    if (fget(g.selfLoop, i)) internalWeight[c] = fget(internalWeight, c) + fget(g.selfLoop, i);
+  }
+}
+
+function buildOriginalPartition(g: GraphAdapter, communityMap: Int32Array): OriginalPartition {
+  const n: number = g.n;
+  let maxC: number = 0;
+  for (let i = 0; i < n; i++) {
+    const ci = iget(communityMap, i);
+    if (ci > maxC) maxC = ci;
+  }
+  const cc: number = maxC + 1;
+
+  const nodeCommunity = communityMap;
+  const internalWeight = new Float64Array(cc);
+  const totalStr = new Float64Array(cc);
+  const totalOutStr = new Float64Array(cc);
+  const totalInStr = new Float64Array(cc);
+  const totalSize = new Float64Array(cc);
+
+  accumulateNodeAggregates(
+    g,
+    communityMap,
+    n,
+    totalSize,
+    totalStr,
+    totalOutStr,
+    totalInStr,
+    internalWeight,
+  );
+  accumulateInternalEdgeWeights(g, communityMap, n, internalWeight);
 
   return {
     communityCount: cc,

package/src/graph/algorithms/leiden/optimiser.ts

@@ -129,83 +129,15 @@ export function runLouvainUndirectedModularity(
         const nodeIndex: number = order[idx]!;
         if (level === 0 && fixedNodeMask && fixedNodeMask[nodeIndex]) continue;
         const candidateCount: number = partition.accumulateNeighborCommunityEdgeWeights(nodeIndex);
-        let bestCommunityId: number = partition.nodeCommunity[nodeIndex]!;
-        let bestGain: number = 0;
-        const maxCommunitySize: number = options.maxCommunitySize;
-        if (strategyCode === CandidateStrategy.All) {
-          for (let communityId = 0; communityId < partition.communityCount; communityId++) {
-            if (communityId === partition.nodeCommunity[nodeIndex]!) continue;
-            if (
-              maxCommunitySize < Infinity &&
-              partition.getCommunityTotalSize(communityId) + graphAdapter.size[nodeIndex]! >
-                maxCommunitySize
-            )
-              continue;
-            const gain: number = computeQualityGain(partition, nodeIndex, communityId, options);
-            if (gain > bestGain) {
-              bestGain = gain;
-              bestCommunityId = communityId;
-            }
-          }
-        } else if (strategyCode === CandidateStrategy.RandomAny) {
-          const tries: number = Math.min(10, Math.max(1, partition.communityCount));
-          for (let trialIndex = 0; trialIndex < tries; trialIndex++) {
-            const communityId: number = (random() * partition.communityCount) | 0;
-            if (communityId === partition.nodeCommunity[nodeIndex]!) continue;
-            if (
-              maxCommunitySize < Infinity &&
-              partition.getCommunityTotalSize(communityId) + graphAdapter.size[nodeIndex]! >
-                maxCommunitySize
-            )
-              continue;
-            const gain: number = computeQualityGain(partition, nodeIndex, communityId, options);
-            if (gain > bestGain) {
-              bestGain = gain;
-              bestCommunityId = communityId;
-            }
-          }
-        } else if (strategyCode === CandidateStrategy.RandomNeighbor) {
-          const tries: number = Math.min(10, Math.max(1, candidateCount));
-          for (let trialIndex = 0; trialIndex < tries; trialIndex++) {
-            const communityId: number = partition.getCandidateCommunityAt(
-              (random() * candidateCount) | 0,
-            );
-            if (communityId === partition.nodeCommunity[nodeIndex]!) continue;
-            if (
-              maxCommunitySize < Infinity &&
-              partition.getCommunityTotalSize(communityId) + graphAdapter.size[nodeIndex]! >
-                maxCommunitySize
-            )
-              continue;
-            const gain: number = computeQualityGain(partition, nodeIndex, communityId, options);
-            if (gain > bestGain) {
-              bestGain = gain;
-              bestCommunityId = communityId;
-            }
-          }
-        } else {
-          for (let trialIndex = 0; trialIndex < candidateCount; trialIndex++) {
-            const communityId: number = partition.getCandidateCommunityAt(trialIndex);
-            if (maxCommunitySize < Infinity) {
-              const nextSize: number =
-                partition.getCommunityTotalSize(communityId) + graphAdapter.size[nodeIndex]!;
-              if (nextSize > maxCommunitySize) continue;
-            }
-            const gain: number = computeQualityGain(partition, nodeIndex, communityId, options);
-            if (gain > bestGain) {
-              bestGain = gain;
-              bestCommunityId = communityId;
-            }
-          }
-        }
-        if (options.allowNewCommunity) {
-          const newCommunityId: number = partition.communityCount;
-          const gain: number = computeQualityGain(partition, nodeIndex, newCommunityId, options);
-          if (gain > bestGain) {
-            bestGain = gain;
-            bestCommunityId = newCommunityId;
-          }
-        }
+        const { bestCommunityId, bestGain } = findBestCommunityMove(
+          partition,
+          graphAdapter,
+          nodeIndex,
+          candidateCount,
+          strategyCode,
+          options,
+          random,
+        );
         if (bestCommunityId !== partition.nodeCommunity[nodeIndex]! && bestGain > GAIN_EPSILON) {
           partition.moveNodeToCommunity(nodeIndex, bestCommunityId);
           improved = true;
@@ -267,6 +199,109 @@ export function runLouvainUndirectedModularity(
   };
 }
 
+/**
+ * Evaluate all candidate communities for a node and return the best move.
+ * Encapsulates the four candidate-selection strategies (All, RandomAny,
+ * RandomNeighbor, Neighbors) and the optional new-community probe.
+ */
+function findBestCommunityMove(
+  partition: Partition,
+  graphAdapter: GraphAdapter,
+  nodeIndex: number,
+  candidateCount: number,
+  strategyCode: CandidateStrategyCode,
+  options: NormalizedOptions,
+  random: () => number,
+): { bestCommunityId: number; bestGain: number } {
+  let bestCommunityId: number = partition.nodeCommunity[nodeIndex]!;
+  let bestGain: number = 0;
+  const maxCommunitySize: number = options.maxCommunitySize;
+
+  const evaluateCandidate = (communityId: number): void => {
+    if (communityId === partition.nodeCommunity[nodeIndex]!) return;
+    if (
+      maxCommunitySize < Infinity &&
+      partition.getCommunityTotalSize(communityId) + graphAdapter.size[nodeIndex]! >
+        maxCommunitySize
+    )
+      return;
+    const gain: number = computeQualityGain(partition, nodeIndex, communityId, options);
+    if (gain > bestGain) {
+      bestGain = gain;
+      bestCommunityId = communityId;
+    }
+  };
+
+  if (strategyCode === CandidateStrategy.All) {
+    for (let communityId = 0; communityId < partition.communityCount; communityId++) {
+      evaluateCandidate(communityId);
+    }
+  } else if (strategyCode === CandidateStrategy.RandomAny) {
+    const tries: number = Math.min(10, Math.max(1, partition.communityCount));
+    for (let trialIndex = 0; trialIndex < tries; trialIndex++) {
+      evaluateCandidate((random() * partition.communityCount) | 0);
+    }
+  } else if (strategyCode === CandidateStrategy.RandomNeighbor) {
+    const tries: number = Math.min(10, Math.max(1, candidateCount));
+    for (let trialIndex = 0; trialIndex < tries; trialIndex++) {
+      evaluateCandidate(partition.getCandidateCommunityAt((random() * candidateCount) | 0));
+    }
+  } else {
+    for (let trialIndex = 0; trialIndex < candidateCount; trialIndex++) {
+      evaluateCandidate(partition.getCandidateCommunityAt(trialIndex));
+    }
+  }
+
+  if (options.allowNewCommunity) {
+    const newCommunityId: number = partition.communityCount;
+    const gain: number = computeQualityGain(partition, nodeIndex, newCommunityId, options);
+    if (gain > bestGain) {
+      bestGain = gain;
+      bestCommunityId = newCommunityId;
+    }
+  }
+
+  return { bestCommunityId, bestGain };
+}
+
+/**
+ * Run a BFS on the subgraph induced by `inCommunity` starting from `start`.
+ * Returns the list of visited nodes. Works on both directed (weak connectivity
+ * via both outEdges and inEdges) and undirected graphs.
+ */
+function bfsComponent(
+  g: GraphAdapter,
+  start: number,
+  inCommunity: Uint8Array,
+  visited: Uint8Array,
+): number[] {
+  const queue: number[] = [start];
+  visited[start] = 1;
+  let head: number = 0;
+  while (head < queue.length) {
+    const v: number = queue[head++]!;
+    const out: EdgeEntry[] = g.outEdges[v]!;
+    for (let k = 0; k < out.length; k++) {
+      const w: number = out[k]!.to;
+      if (inCommunity[w] && !visited[w]) {
+        visited[w] = 1;
+        queue.push(w);
+      }
+    }
+    if (g.directed) {
+      const inc: InEdgeEntry[] = g.inEdges[v]!;
+      for (let k = 0; k < inc.length; k++) {
+        const w: number = inc[k]!.from;
+        if (inCommunity[w] && !visited[w]) {
+          visited[w] = 1;
+          queue.push(w);
+        }
+      }
+    }
+  }
+  return queue;
+}
+
 // Build a coarse graph where each community becomes a single node.
 // Self-loops (g.selfLoop[]) don't need separate handling here because they
 // are already present in g.outEdges (directed path keeps them in both arrays).
@@ -450,38 +485,12 @@ function splitDisconnectedCommunities(g: GraphAdapter, partition: Partition): vo
       if (visited[start]) continue;
       componentCount++;
 
-      // BFS within the community subgraph.
-      // For directed graphs, traverse both outEdges and inEdges to check
-      // weak connectivity (reachability ignoring edge direction).
-      const queue: number[] = [start];
-      visited[start] = 1;
-      let head: number = 0;
-      while (head < queue.length) {
-        const v: number = queue[head++]!;
-        const out: EdgeEntry[] = g.outEdges[v]!;
-        for (let k = 0; k < out.length; k++) {
-          const w: number = out[k]!.to;
-          if (inCommunity[w] && !visited[w]) {
-            visited[w] = 1;
-            queue.push(w);
-          }
-        }
-        if (g.directed) {
-          const inc: InEdgeEntry[] = g.inEdges[v]!;
-          for (let k = 0; k < inc.length; k++) {
-            const w: number = inc[k]!.from;
-            if (inCommunity[w] && !visited[w]) {
-              visited[w] = 1;
-              queue.push(w);
-            }
-          }
-        }
-      }
+      const component: number[] = bfsComponent(g, start, inCommunity, visited);
 
       if (componentCount > 1) {
         // Secondary component — assign new community ID directly.
         const newC: number = nextC++;
-        for (let q = 0; q < queue.length; q++) nc[queue[q]!] = newC;
+        for (let q = 0; q < component.length; q++) nc[component[q]!] = newC;
         didSplit = true;
       }
     }