@optave/codegraph 3.3.0 → 3.4.0

package/src/features/{triage.js → triage.ts}

@@ -1,13 +1,33 @@
-import { openRepo } from '../db/index.js';
+import { openRepo, type Repository } from '../db/index.js';
+import type { RiskResult, RiskWeights } from '../graph/classifiers/risk.js';
 import { DEFAULT_WEIGHTS, scoreRisk } from '../graph/classifiers/risk.js';
 import { loadConfig } from '../infrastructure/config.js';
 import { warn } from '../infrastructure/logger.js';
 import { isTestFile } from '../infrastructure/test-filter.js';
 import { paginateResult } from '../shared/paginate.js';
+import type { CodegraphConfig, Role, TriageNodeRow } from '../types.js';
 
 // ─── Scoring ─────────────────────────────────────────────────────────
 
-const SORT_FNS = {
+interface TriageItem {
+  name: string;
+  kind: string;
+  file: string;
+  line: number;
+  role: string | null;
+  fanIn: number;
+  cognitive: number;
+  churn: number;
+  maintainabilityIndex: number;
+  normFanIn: number;
+  normComplexity: number;
+  normChurn: number;
+  normMI: number;
+  roleWeight: number;
+  riskScore: number;
+}
+
+const SORT_FNS: Record<string, (a: TriageItem, b: TriageItem) => number> = {
   risk: (a, b) => b.riskScore - a.riskScore,
   complexity: (a, b) => b.cognitive - a.cognitive,
   churn: (a, b) => b.churn - a.churn,
@@ -15,13 +35,7 @@ const SORT_FNS = {
   mi: (a, b) => a.maintainabilityIndex - b.maintainabilityIndex,
 };
 
-/**
- * Build scored triage items from raw rows and risk metrics.
- * @param {object[]} rows - Raw DB rows
- * @param {object[]} riskMetrics - Per-row risk metric objects from scoreRisk
- * @returns {object[]}
- */
-function buildTriageItems(rows, riskMetrics) {
+function buildTriageItems(rows: TriageNodeRow[], riskMetrics: RiskResult[]): TriageItem[] {
   return rows.map((r, i) => ({
     name: r.name,
     kind: r.kind,
@@ -32,23 +46,29 @@ function buildTriageItems(rows, riskMetrics) {
     cognitive: r.cognitive,
     churn: r.churn,
     maintainabilityIndex: r.mi,
-    normFanIn: riskMetrics[i].normFanIn,
-    normComplexity: riskMetrics[i].normComplexity,
-    normChurn: riskMetrics[i].normChurn,
-    normMI: riskMetrics[i].normMI,
-    roleWeight: riskMetrics[i].roleWeight,
-    riskScore: riskMetrics[i].riskScore,
+    normFanIn: riskMetrics[i]!.normFanIn,
+    normComplexity: riskMetrics[i]!.normComplexity,
+    normChurn: riskMetrics[i]!.normChurn,
+    normMI: riskMetrics[i]!.normMI,
+    roleWeight: riskMetrics[i]!.roleWeight,
+    riskScore: riskMetrics[i]!.riskScore,
   }));
 }
 
-/**
- * Compute signal coverage and summary statistics.
- * @param {object[]} filtered - All filtered rows
- * @param {object[]} scored - Scored and filtered items
- * @param {object} weights - Active weights
- * @returns {object}
- */
-function computeTriageSummary(filtered, scored, weights) {
+interface TriageSummary {
+  total: number;
+  analyzed: number;
+  avgScore: number;
+  maxScore: number;
+  weights: RiskWeights;
+  signalCoverage: Record<string, number>;
+}
+
+function computeTriageSummary(
+  filtered: TriageNodeRow[],
+  scored: TriageItem[],
+  weights: RiskWeights,
+): TriageSummary {
   const signalCoverage = {
     complexity: round4(filtered.filter((r) => r.cognitive > 0).length / filtered.length),
     churn: round4(filtered.filter((r) => r.churn > 0).length / filtered.length),
@@ -73,7 +93,7 @@ function computeTriageSummary(filtered, scored, weights) {
 
 // ─── Data Function ────────────────────────────────────────────────────
 
-const EMPTY_SUMMARY = (weights) => ({
+const EMPTY_SUMMARY = (weights: RiskWeights): TriageSummary => ({
   total: 0,
   analyzed: 0,
   avgScore: 0,
@@ -82,37 +102,55 @@ const EMPTY_SUMMARY = (weights) => ({
   signalCoverage: {},
 });
 
-/**
- * Compute composite risk scores for all symbols.
- *
- * @param {string} [customDbPath] - Path to graph.db
- * @param {object} [opts]
- * @returns {{ items: object[], summary: object, _pagination?: object }}
- */
-export function triageData(customDbPath, opts = {}) {
+interface TriageDataOpts {
+  noTests?: boolean;
+  minScore?: number | string | null;
+  sort?: string;
+  config?: CodegraphConfig;
+  weights?: Partial<RiskWeights>;
+  file?: string;
+  kind?: string;
+  role?: Role;
+  limit?: number;
+  offset?: number;
+  repo?: Repository;
+}
+
+export function triageData(
+  customDbPath?: string,
+  opts: TriageDataOpts = {},
+): { items: TriageItem[]; summary: TriageSummary } {
   const { repo, close } = openRepo(customDbPath, opts);
   try {
     const noTests = opts.noTests || false;
     const minScore = opts.minScore != null ? Number(opts.minScore) : null;
     const sort = opts.sort || 'risk';
     const config = opts.config || loadConfig();
-    const riskConfig = config.risk || {};
-    const weights = { ...DEFAULT_WEIGHTS, ...(riskConfig.weights || {}), ...(opts.weights || {}) };
+    const riskConfig = ((config as unknown as Record<string, unknown>)['risk'] || {}) as {
+      weights?: Partial<RiskWeights>;
+      roleWeights?: Record<string, number>;
+      defaultRoleWeight?: number;
+    };
+    const weights: RiskWeights = {
+      ...DEFAULT_WEIGHTS,
+      ...(riskConfig.weights || {}),
+      ...(opts.weights || {}),
+    };
     const riskOpts = {
       roleWeights: riskConfig.roleWeights,
       defaultRoleWeight: riskConfig.defaultRoleWeight,
     };
 
-    let rows;
+    let rows: TriageNodeRow[];
     try {
       rows = repo.findNodesForTriage({
         noTests,
-        file: opts.file || null,
-        kind: opts.kind || null,
-        role: opts.role || null,
+        file: opts.file || undefined,
+        kind: opts.kind || undefined,
+        role: opts.role || undefined,
       });
-    } catch (err) {
-      warn(`triage query failed: ${err.message}`);
+    } catch (err: unknown) {
+      warn(`triage query failed: ${(err as Error).message}`);
       return { items: [], summary: EMPTY_SUMMARY(weights) };
     }
 
@@ -125,7 +163,7 @@ export function triageData(customDbPath, opts = {}) {
     const items = buildTriageItems(filtered, riskMetrics);
 
     const scored = minScore != null ? items.filter((it) => it.riskScore >= minScore) : items;
-    scored.sort(SORT_FNS[sort] || SORT_FNS.risk);
+    scored.sort(SORT_FNS[sort] || SORT_FNS['risk']!);
 
     const result = {
       items: scored,
@@ -143,6 +181,6 @@ export function triageData(customDbPath, opts = {}) {
 
 // ─── Utilities ────────────────────────────────────────────────────────
 
-function round4(n) {
+function round4(n: number): number {
   return Math.round(n * 10000) / 10000;
 }

package/src/graph/algorithms/{bfs.js → bfs.ts}

@@ -1,18 +1,26 @@
+import type { CodeGraph } from '../model.js';
+
+export interface BfsOpts {
+  maxDepth?: number;
+  direction?: 'forward' | 'backward' | 'both';
+}
+
 /**
  * Breadth-first traversal on a CodeGraph.
  *
- * @param {import('../model.js').CodeGraph} graph
- * @param {string|string[]} startIds - One or more starting node IDs
- * @param {{ maxDepth?: number, direction?: 'forward'|'backward'|'both' }} [opts]
- * @returns {Map<string, number>} nodeId → depth from nearest start node
+ * @returns nodeId → depth from nearest start node
  */
-export function bfs(graph, startIds, opts = {}) {
+export function bfs(
+  graph: CodeGraph,
+  startIds: string | string[],
+  opts: BfsOpts = {},
+): Map<string, number> {
   const maxDepth = opts.maxDepth ?? Infinity;
   const direction = opts.direction ?? 'forward';
   const starts = Array.isArray(startIds) ? startIds : [startIds];
 
-  const depths = new Map();
-  const queue = [];
+  const depths = new Map<string, number>();
+  const queue: string[] = [];
 
   for (const id of starts) {
     const key = String(id);
@@ -24,11 +32,11 @@ export function bfs(graph, startIds, opts = {}) {
 
   let head = 0;
   while (head < queue.length) {
-    const current = queue[head++];
-    const depth = depths.get(current);
+    const current = queue[head++]!;
+    const depth = depths.get(current)!;
     if (depth >= maxDepth) continue;
 
-    let neighbors;
+    let neighbors: string[];
     if (direction === 'forward') {
       neighbors = graph.successors(current);
     } else if (direction === 'backward') {

package/src/graph/algorithms/{centrality.js → centrality.ts}

@@ -1,11 +1,15 @@
+import type { CodeGraph } from '../model.js';
+
+export interface FanInOut {
+  fanIn: number;
+  fanOut: number;
+}
+
 /**
  * Fan-in / fan-out centrality for all nodes in a CodeGraph.
- *
- * @param {import('../model.js').CodeGraph} graph
- * @returns {Map<string, { fanIn: number, fanOut: number }>}
  */
-export function fanInOut(graph) {
-  const result = new Map();
+export function fanInOut(graph: CodeGraph): Map<string, FanInOut> {
+  const result = new Map<string, FanInOut>();
   for (const id of graph.nodeIds()) {
     result.set(id, {
       fanIn: graph.inDegree(id),

package/src/graph/algorithms/{index.js → index.ts}

@@ -1,5 +1,6 @@
 export { bfs } from './bfs.js';
 export { fanInOut } from './centrality.js';
+export { detectClusters } from './leiden/index.js';
 export { louvainCommunities } from './louvain.js';
 export { shortestPath } from './shortest-path.js';
 export { tarjan } from './tarjan.js';

package/src/graph/algorithms/leiden/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Vendored from ngraph.leiden by Andrei Kashcha (anvaka)
+https://github.com/anvaka/ngraph.leiden
+
+Copyright (c) 2025 Andrei Kashcha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,204 @@
+/**
+ * Graph adapter that converts a CodeGraph into the dense array format
+ * expected by the Leiden optimiser.
+ *
+ * Vendored from ngraph.leiden (MIT) — adapted for CodeGraph.
+ */
+
+import type { CodeGraph, EdgeAttrs, NodeAttrs } from '../../model.js';
+
+export interface EdgeEntry {
+  to: number;
+  w: number;
+}
+
+export interface InEdgeEntry {
+  from: number;
+  w: number;
+}
+
+export interface GraphAdapterOptions {
+  directed?: boolean;
+  linkWeight?: (attrs: EdgeAttrs) => number;
+  nodeSize?: (attrs: NodeAttrs) => number;
+  baseNodeIds?: string[];
+}
+
+export interface GraphAdapter {
+  n: number;
+  nodeIds: string[];
+  idToIndex: Map<string, number>;
+  size: Float64Array;
+  selfLoop: Float64Array;
+  strengthOut: Float64Array;
+  strengthIn: Float64Array;
+  outEdges: EdgeEntry[][];
+  inEdges: InEdgeEntry[][];
+  directed: boolean;
+  totalWeight: number;
+  forEachNeighbor: (i: number, cb: (to: number, w: number) => void) => void;
+}
+
+// Typed arrays always return a number for in-bounds access, but noUncheckedIndexedAccess
+// widens the return to `number | undefined`. These helpers wrap compound assignment
+// patterns (+=, -=) that appear frequently in this performance-critical code.
+function taGet(a: Float64Array, i: number): number {
+  return a[i] as number;
+}
+
+function taAdd(a: Float64Array, i: number, v: number): void {
+  a[i] = taGet(a, i) + v;
+}
+
+function taSub(a: Float64Array, i: number, v: number): void {
+  a[i] = taGet(a, i) - v;
+}
+
+export function makeGraphAdapter(graph: CodeGraph, opts: GraphAdapterOptions = {}): GraphAdapter {
+  const linkWeight: (attrs: EdgeAttrs) => number =
+    opts.linkWeight ||
+    // biome-ignore lint/complexity/useLiteralKeys: index signature requires bracket access
+    ((attrs) => (attrs && typeof attrs['weight'] === 'number' ? attrs['weight'] : 1));
+  const nodeSize: (attrs: NodeAttrs) => number =
+    // biome-ignore lint/complexity/useLiteralKeys: index signature requires bracket access
+    opts.nodeSize || ((attrs) => (attrs && typeof attrs['size'] === 'number' ? attrs['size'] : 1));
+  const directed: boolean = !!opts.directed;
+  const baseNodeIds: string[] | undefined = opts.baseNodeIds;
+
+  // Build dense node index mapping
+  const nodeIds: string[] = [];
+  const idToIndex = new Map<string, number>();
+  if (Array.isArray(baseNodeIds) && baseNodeIds.length > 0) {
+    for (let i = 0; i < baseNodeIds.length; i++) {
+      const id = baseNodeIds[i] as string;
+      if (!graph.hasNode(id)) throw new Error(`Missing node: ${id}`);
+      idToIndex.set(id, i);
+      nodeIds.push(id);
+    }
+  } else {
+    for (const [id] of graph.nodes()) {
+      idToIndex.set(id, nodeIds.length);
+      nodeIds.push(id);
+    }
+  }
+  const n: number = nodeIds.length;
+
+  // Storage
+  const size = new Float64Array(n);
+  const selfLoop = new Float64Array(n);
+  const strengthOut = new Float64Array(n);
+  const strengthIn = new Float64Array(n);
+
+  // Edge list by source for fast iteration
+  const outEdges: EdgeEntry[][] = new Array(n);
+  const inEdges: InEdgeEntry[][] = new Array(n);
+  for (let i = 0; i < n; i++) {
+    outEdges[i] = [];
+    inEdges[i] = [];
+  }
+
+  // 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);
+    }
+  } 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);
+      }
+    }
+  }
+
+  // Node sizes
+  for (const [id, attrs] of graph.nodes()) {
+    const i = idToIndex.get(id);
+    if (i != null) size[i] = +nodeSize(attrs) || 0;
+  }
+
+  // Totals
+  const totalWeight: number = strengthOut.reduce((a, b) => a + b, 0);
+
+  function forEachNeighbor(i: number, cb: (to: number, w: number) => void): void {
+    const list = outEdges[i] as EdgeEntry[];
+    for (let k = 0; k < list.length; k++) cb((list[k] as EdgeEntry).to, (list[k] as EdgeEntry).w);
+  }
+
+  return {
+    n,
+    nodeIds,
+    idToIndex,
+    size,
+    selfLoop,
+    strengthOut,
+    strengthIn,
+    outEdges,
+    inEdges,
+    directed,
+    totalWeight,
+    forEachNeighbor,
+  };
+}

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

@@ -0,0 +1,77 @@
+/**
+ * CPM (Constant Potts Model) quality functions.
+ * Vendored from ngraph.leiden (MIT) — no external dependencies.
+ */
+
+/**
+ * Minimal view of a partition needed by CPM quality functions.
+ */
+export interface PartitionView {
+  readonly communityCount: number;
+  nodeCommunity: Int32Array;
+  readonly communityInternalEdgeWeight: Float64Array;
+  readonly communityTotalSize: Float64Array;
+  getOutEdgeWeightToCommunity(c: number): number;
+  getInEdgeWeightFromCommunity(c: number): number;
+  getNeighborEdgeWeightToCommunity(c: number): number;
+}
+
+/**
+ * Minimal view of a graph needed by CPM quality functions.
+ */
+export interface GraphView {
+  n: number;
+  directed: boolean;
+  selfLoop: Float64Array;
+  size: Float64Array;
+}
+
+// Typed array safe-access helper (see adapter.ts for rationale)
+function fget(a: Float64Array, i: number): number {
+  return a[i] as number;
+}
+function iget(a: Int32Array, i: number): number {
+  return a[i] as number;
+}
+
+export function diffCPM(
+  part: PartitionView,
+  g: GraphView,
+  v: number,
+  c: number,
+  gamma: number = 1.0,
+): number {
+  const oldC: number = iget(part.nodeCommunity, v);
+  if (c === oldC) return 0;
+  let w_old: number;
+  let w_new: number;
+  let selfCorrection: number = 0;
+  if (g.directed) {
+    w_old =
+      (part.getOutEdgeWeightToCommunity(oldC) || 0) +
+      (part.getInEdgeWeightFromCommunity(oldC) || 0);
+    w_new =
+      c < g.n
+        ? (part.getOutEdgeWeightToCommunity(c) || 0) + (part.getInEdgeWeightFromCommunity(c) || 0)
+        : 0;
+    // Self-loop weight appears in both out and in arrays for oldC,
+    // making w_old include 2x selfLoop. Correct to match moveNodeToCommunity.
+    selfCorrection = 2 * (fget(g.selfLoop, v) || 0);
+  } else {
+    w_old = part.getNeighborEdgeWeightToCommunity(oldC) || 0;
+    w_new = c < g.n ? part.getNeighborEdgeWeightToCommunity(c) || 0 : 0;
+  }
+  const s_v: number = fget(g.size, v) || 1;
+  const S_old: number = fget(part.communityTotalSize, oldC) || 0;
+  const S_new: number = c < part.communityTotalSize.length ? fget(part.communityTotalSize, c) : 0;
+  return w_new - w_old + selfCorrection - gamma * s_v * (S_new - S_old + s_v);
+}
+
+export function qualityCPM(part: PartitionView, _g: GraphView, gamma: number = 1.0): number {
+  let sum: number = 0;
+  for (let c = 0; c < part.communityCount; c++) {
+    const S: number = fget(part.communityTotalSize, c) || 0;
+    sum += fget(part.communityInternalEdgeWeight, c) - (gamma * (S * (S - 1))) / 2;
+  }
+  return sum;
+}