@optave/codegraph 3.1.3 → 3.1.4

package/src/graph/builders/temporal.js

@@ -0,0 +1,33 @@
+/**
+ * Build a co-change (temporal) graph weighted by Jaccard similarity.
+ */
+
+import { CodeGraph } from '../model.js';
+
+/**
+ * @param {object} db - Open better-sqlite3 database (readonly)
+ * @param {{ minJaccard?: number }} [opts]
+ * @returns {CodeGraph} Undirected graph weighted by Jaccard similarity
+ */
+export function buildTemporalGraph(db, opts = {}) {
+  const minJaccard = opts.minJaccard ?? 0.0;
+  const graph = new CodeGraph({ directed: false });
+
+  // Check if co_changes table exists
+  const tableCheck = db
+    .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='co_changes'")
+    .get();
+  if (!tableCheck) return graph;
+
+  const rows = db
+    .prepare('SELECT file_a, file_b, jaccard FROM co_changes WHERE jaccard >= ?')
+    .all(minJaccard);
+
+  for (const r of rows) {
+    if (!graph.hasNode(r.file_a)) graph.addNode(r.file_a, { label: r.file_a });
+    if (!graph.hasNode(r.file_b)) graph.addNode(r.file_b, { label: r.file_b });
+    graph.addEdge(r.file_a, r.file_b, { jaccard: r.jaccard });
+  }
+
+  return graph;
+}

package/src/graph/classifiers/index.js

@@ -0,0 +1,2 @@
+export { DEFAULT_WEIGHTS, minMaxNormalize, ROLE_WEIGHTS, scoreRisk } from './risk.js';
+export { classifyRoles, FRAMEWORK_ENTRY_PREFIXES } from './roles.js';

package/src/graph/classifiers/risk.js

@@ -0,0 +1,85 @@
+/**
+ * Risk scoring — pure logic, no DB.
+ */
+
+// Weights sum to 1.0. Complexity gets the highest weight because cognitive load
+// is the strongest predictor of defect density. Fan-in and churn are next as
+// they reflect coupling and volatility. Role adds architectural context, and MI
+// (maintainability index) is a weaker composite signal, so it gets the least.
+export const DEFAULT_WEIGHTS = {
+  fanIn: 0.25,
+  complexity: 0.3,
+  churn: 0.2,
+  role: 0.15,
+  mi: 0.1,
+};
+
+// Role weights reflect structural importance: core modules are central to the
+// dependency graph, utilities are widely imported, entry points are API
+// surfaces. Adapters bridge subsystems but are replaceable. Leaves and dead
+// code have minimal downstream impact.
+export const ROLE_WEIGHTS = {
+  core: 1.0,
+  utility: 0.9,
+  entry: 0.8,
+  adapter: 0.5,
+  leaf: 0.2,
+  dead: 0.1,
+};
+
+const DEFAULT_ROLE_WEIGHT = 0.5;
+
+/** Min-max normalize an array of numbers. All-equal → all zeros. */
+export function minMaxNormalize(values) {
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  if (max === min) return values.map(() => 0);
+  const range = max - min;
+  return values.map((v) => (v - min) / range);
+}
+
+function round4(n) {
+  return Math.round(n * 10000) / 10000;
+}
+
+/**
+ * Score risk for a list of items.
+ *
+ * @param {{ fan_in: number, cognitive: number, churn: number, mi: number, role: string|null }[]} items
+ * @param {object} [weights] - Override DEFAULT_WEIGHTS
+ * @returns {{ normFanIn: number, normComplexity: number, normChurn: number, normMI: number, roleWeight: number, riskScore: number }[]}
+ *   Parallel array with risk metrics for each input item.
+ */
+export function scoreRisk(items, weights = {}) {
+  const w = { ...DEFAULT_WEIGHTS, ...weights };
+
+  const fanIns = items.map((r) => r.fan_in);
+  const cognitives = items.map((r) => r.cognitive);
+  const churns = items.map((r) => r.churn);
+  const mis = items.map((r) => r.mi);
+
+  const normFanIns = minMaxNormalize(fanIns);
+  const normCognitives = minMaxNormalize(cognitives);
+  const normChurns = minMaxNormalize(churns);
+  const normMIsRaw = minMaxNormalize(mis);
+  const normMIs = normMIsRaw.map((v) => round4(1 - v));
+
+  return items.map((r, i) => {
+    const roleWeight = ROLE_WEIGHTS[r.role] ?? DEFAULT_ROLE_WEIGHT;
+    const riskScore =
+      w.fanIn * normFanIns[i] +
+      w.complexity * normCognitives[i] +
+      w.churn * normChurns[i] +
+      w.role * roleWeight +
+      w.mi * normMIs[i];
+
+    return {
+      normFanIn: round4(normFanIns[i]),
+      normComplexity: round4(normCognitives[i]),
+      normChurn: round4(normChurns[i]),
+      normMI: round4(normMIs[i]),
+      roleWeight,
+      riskScore: round4(riskScore),
+    };
+  });
+}

package/src/graph/classifiers/roles.js

@@ -0,0 +1,64 @@
+/**
+ * Node role classification — pure logic, no DB.
+ *
+ * Roles: entry, core, utility, adapter, leaf, dead
+ */
+
+export const FRAMEWORK_ENTRY_PREFIXES = ['route:', 'event:', 'command:'];
+
+function median(sorted) {
+  if (sorted.length === 0) return 0;
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+
+/**
+ * Classify nodes into architectural roles based on fan-in/fan-out metrics.
+ *
+ * @param {{ id: string, name: string, fanIn: number, fanOut: number, isExported: boolean }[]} nodes
+ * @returns {Map<string, string>} nodeId → role
+ */
+export function classifyRoles(nodes) {
+  if (nodes.length === 0) return new Map();
+
+  const nonZeroFanIn = nodes
+    .filter((n) => n.fanIn > 0)
+    .map((n) => n.fanIn)
+    .sort((a, b) => a - b);
+  const nonZeroFanOut = nodes
+    .filter((n) => n.fanOut > 0)
+    .map((n) => n.fanOut)
+    .sort((a, b) => a - b);
+
+  const medFanIn = median(nonZeroFanIn);
+  const medFanOut = median(nonZeroFanOut);
+
+  const result = new Map();
+
+  for (const node of nodes) {
+    const highIn = node.fanIn >= medFanIn && node.fanIn > 0;
+    const highOut = node.fanOut >= medFanOut && node.fanOut > 0;
+
+    let role;
+    const isFrameworkEntry = FRAMEWORK_ENTRY_PREFIXES.some((p) => node.name.startsWith(p));
+    if (isFrameworkEntry) {
+      role = 'entry';
+    } else if (node.fanIn === 0 && !node.isExported) {
+      role = 'dead';
+    } else if (node.fanIn === 0 && node.isExported) {
+      role = 'entry';
+    } else if (highIn && !highOut) {
+      role = 'core';
+    } else if (highIn && highOut) {
+      role = 'utility';
+    } else if (!highIn && highOut) {
+      role = 'adapter';
+    } else {
+      role = 'leaf';
+    }
+
+    result.set(node.id, role);
+  }
+
+  return result;
+}

package/src/graph/index.js

@@ -0,0 +1,13 @@
+// Graph subsystem barrel export
+
+export { bfs, fanInOut, louvainCommunities, shortestPath, tarjan } from './algorithms/index.js';
+export { buildDependencyGraph, buildStructureGraph, buildTemporalGraph } from './builders/index.js';
+export {
+  classifyRoles,
+  DEFAULT_WEIGHTS,
+  FRAMEWORK_ENTRY_PREFIXES,
+  minMaxNormalize,
+  ROLE_WEIGHTS,
+  scoreRisk,
+} from './classifiers/index.js';
+export { CodeGraph } from './model.js';

package/src/graph/model.js

@@ -0,0 +1,230 @@
+/**
+ * Unified in-memory graph model.
+ *
+ * Stores directed (default) or undirected graphs with node/edge attributes.
+ * Node IDs are always strings. DB integer IDs should be stringified before use.
+ */
+
+import Graph from 'graphology';
+
+export class CodeGraph {
+  /**
+   * @param {{ directed?: boolean }} [opts]
+   */
+  constructor(opts = {}) {
+    this._directed = opts.directed !== false;
+    /** @type {Map<string, object>} */
+    this._nodes = new Map();
+    /** @type {Map<string, Map<string, object>>} node → (target → edgeAttrs) */
+    this._successors = new Map();
+    /** @type {Map<string, Map<string, object>>} node → (source → edgeAttrs) */
+    this._predecessors = new Map();
+  }
+
+  get directed() {
+    return this._directed;
+  }
+
+  get nodeCount() {
+    return this._nodes.size;
+  }
+
+  get edgeCount() {
+    let count = 0;
+    for (const targets of this._successors.values()) count += targets.size;
+    // Undirected graphs store each edge twice (a→b and b→a)
+    return this._directed ? count : count / 2;
+  }
+
+  // ─── Node operations ────────────────────────────────────────────
+
+  addNode(id, attrs = {}) {
+    const key = String(id);
+    this._nodes.set(key, attrs);
+    if (!this._successors.has(key)) this._successors.set(key, new Map());
+    if (!this._predecessors.has(key)) this._predecessors.set(key, new Map());
+    return this;
+  }
+
+  hasNode(id) {
+    return this._nodes.has(String(id));
+  }
+
+  getNodeAttrs(id) {
+    return this._nodes.get(String(id));
+  }
+
+  /** @returns {IterableIterator<[string, object]>} */
+  nodes() {
+    return this._nodes.entries();
+  }
+
+  /** @returns {string[]} */
+  nodeIds() {
+    return [...this._nodes.keys()];
+  }
+
+  // ─── Edge operations ────────────────────────────────────────────
+
+  addEdge(source, target, attrs = {}) {
+    const src = String(source);
+    const tgt = String(target);
+    // Auto-add nodes if missing
+    if (!this._nodes.has(src)) this.addNode(src);
+    if (!this._nodes.has(tgt)) this.addNode(tgt);
+
+    this._successors.get(src).set(tgt, attrs);
+    this._predecessors.get(tgt).set(src, attrs);
+
+    if (!this._directed) {
+      this._successors.get(tgt).set(src, attrs);
+      this._predecessors.get(src).set(tgt, attrs);
+    }
+    return this;
+  }
+
+  hasEdge(source, target) {
+    const src = String(source);
+    const tgt = String(target);
+    return this._successors.has(src) && this._successors.get(src).has(tgt);
+  }
+
+  getEdgeAttrs(source, target) {
+    const src = String(source);
+    const tgt = String(target);
+    return this._successors.get(src)?.get(tgt);
+  }
+
+  /** @yields {[string, string, object]} source, target, attrs */
+  *edges() {
+    const seen = this._directed ? null : new Set();
+    for (const [src, targets] of this._successors) {
+      for (const [tgt, attrs] of targets) {
+        if (!this._directed) {
+          // \0 is safe as separator — node IDs are file paths/symbols, never contain null bytes
+          const key = src < tgt ? `${src}\0${tgt}` : `${tgt}\0${src}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+        }
+        yield [src, tgt, attrs];
+      }
+    }
+  }
+
+  // ─── Adjacency ──────────────────────────────────────────────────
+
+  /** Direct successors of a node (outgoing edges). */
+  successors(id) {
+    const key = String(id);
+    const map = this._successors.get(key);
+    return map ? [...map.keys()] : [];
+  }
+
+  /** Direct predecessors of a node (incoming edges). */
+  predecessors(id) {
+    const key = String(id);
+    const map = this._predecessors.get(key);
+    return map ? [...map.keys()] : [];
+  }
+
+  /** All neighbors (union of successors + predecessors). */
+  neighbors(id) {
+    const key = String(id);
+    const set = new Set();
+    const succ = this._successors.get(key);
+    if (succ) for (const k of succ.keys()) set.add(k);
+    const pred = this._predecessors.get(key);
+    if (pred) for (const k of pred.keys()) set.add(k);
+    return [...set];
+  }
+
+  outDegree(id) {
+    const map = this._successors.get(String(id));
+    return map ? map.size : 0;
+  }
+
+  inDegree(id) {
+    const map = this._predecessors.get(String(id));
+    return map ? map.size : 0;
+  }
+
+  // ─── Filtering ──────────────────────────────────────────────────
+
+  /** Return a new graph containing only nodes matching the predicate. */
+  subgraph(predicate) {
+    const g = new CodeGraph({ directed: this._directed });
+    for (const [id, attrs] of this._nodes) {
+      if (predicate(id, attrs)) g.addNode(id, { ...attrs });
+    }
+    for (const [src, tgt, attrs] of this.edges()) {
+      if (g.hasNode(src) && g.hasNode(tgt)) {
+        g.addEdge(src, tgt, { ...attrs });
+      }
+    }
+    return g;
+  }
+
+  /** Return a new graph containing only edges matching the predicate. */
+  filterEdges(predicate) {
+    const g = new CodeGraph({ directed: this._directed });
+    for (const [id, attrs] of this._nodes) {
+      g.addNode(id, { ...attrs });
+    }
+    for (const [src, tgt, attrs] of this.edges()) {
+      if (predicate(src, tgt, attrs)) {
+        g.addEdge(src, tgt, { ...attrs });
+      }
+    }
+    return g;
+  }
+
+  // ─── Conversion ─────────────────────────────────────────────────
+
+  /** Convert to flat edge array for native Rust interop. */
+  toEdgeArray() {
+    const result = [];
+    for (const [source, target] of this.edges()) {
+      result.push({ source, target });
+    }
+    return result;
+  }
+
+  /** Convert to graphology instance (for Louvain etc). */
+  toGraphology(opts = {}) {
+    const type = opts.type || (this._directed ? 'directed' : 'undirected');
+    const g = new Graph({ type });
+    for (const [id] of this._nodes) {
+      g.addNode(id);
+    }
+
+    for (const [src, tgt] of this.edges()) {
+      if (src === tgt) continue;
+      if (!g.hasEdge(src, tgt)) g.addEdge(src, tgt);
+    }
+    return g;
+  }
+
+  // ─── Utilities ──────────────────────────────────────────────────
+
+  clone() {
+    const g = new CodeGraph({ directed: this._directed });
+    for (const [id, attrs] of this._nodes) {
+      g.addNode(id, { ...attrs });
+    }
+    for (const [src, tgt, attrs] of this.edges()) {
+      g.addEdge(src, tgt, { ...attrs });
+    }
+    return g;
+  }
+
+  /** Merge another graph into this one. Nodes/edges from other override on conflict. */
+  merge(other) {
+    for (const [id, attrs] of other.nodes()) {
+      this.addNode(id, attrs);
+    }
+    for (const [src, tgt, attrs] of other.edges()) {
+      this.addEdge(src, tgt, attrs);
+    }
+    return this;
+  }
+}