@monoes/monograph 1.1.0 → 1.2.1

package/src/graph/ripple-impact.ts

@@ -0,0 +1,131 @@
+/**
+ * Ripple / cascade impact analysis.
+ *
+ * Given a starting node, perform a multi-hop BFS through *directed* edges and
+ * compute how far a change can propagate.  Each depth level is assigned a
+ * decaying weight so that direct dependents (depth 1) contribute more to the
+ * totalScore than transitive dependents.
+ *
+ * Default decay factor: 0.5 per hop (configurable).
+ */
+
+export interface RippleEdge {
+  sourceId: string;
+  targetId: string;
+}
+
+export interface RippleResult {
+  /** Nodes reachable at each depth, starting at depth 1 (direct neighbors). */
+  byDepth: Record<number, string[]>;
+  /** Weighted sum: Σ(count_at_depth * decay^depth). */
+  totalScore: number;
+}
+
+/**
+ * Build a directed outgoing adjacency map from an edge list.
+ *
+ * Callers that run rippleImpact for multiple starting nodes on the same edge set
+ * should build once and pass the map directly to `rippleImpactFromMap`.
+ */
+export function buildOutgoingMap(edges: RippleEdge[]): Map<string, string[]> {
+  const outgoing = new Map<string, string[]>();
+  for (const { sourceId, targetId } of edges) {
+    if (!outgoing.has(sourceId)) outgoing.set(sourceId, []);
+    outgoing.get(sourceId)!.push(targetId);
+  }
+  return outgoing;
+}
+
+/**
+ * Compute the ripple impact of changing `startNodeId` using a pre-built
+ * outgoing adjacency map.
+ *
+ * Use this variant when querying multiple start nodes on the same edge set —
+ * build the map once with `buildOutgoingMap` and reuse it across calls.
+ *
+ * @param startNodeId  The node whose change we are propagating.
+ * @param outgoing     Pre-built directed adjacency map (source → targets).
+ * @param maxDepth     Maximum BFS depth (default 3).
+ * @param decayFactor  Weight multiplier per depth level (default 0.5).
+ */
+export function rippleImpactFromMap(
+  startNodeId: string,
+  outgoing: Map<string, string[]>,
+  maxDepth = 3,
+  decayFactor = 0.5,
+): RippleResult {
+  if (!outgoing.has(startNodeId)) {
+    return { byDepth: {}, totalScore: 0 };
+  }
+
+  const visited = new Set<string>([startNodeId]);
+  const byDepth: Record<number, string[]> = {};
+  let frontier = [startNodeId];
+  let totalScore = 0;
+
+  for (let depth = 1; depth <= maxDepth; depth++) {
+    const nextFrontier: string[] = [];
+    for (const node of frontier) {
+      for (const neighbor of outgoing.get(node) ?? []) {
+        if (!visited.has(neighbor)) {
+          visited.add(neighbor);
+          nextFrontier.push(neighbor);
+        }
+      }
+    }
+    if (nextFrontier.length === 0) break;
+    byDepth[depth] = nextFrontier;
+    totalScore += nextFrontier.length * Math.pow(decayFactor, depth);
+    frontier = nextFrontier;
+  }
+
+  return { byDepth, totalScore };
+}
+
+/**
+ * Compute the ripple impact of changing `startNodeId`.
+ *
+ * Builds the adjacency map from `edges` on each call. For repeated queries
+ * over the same edge set, prefer `buildOutgoingMap` + `rippleImpactFromMap`.
+ *
+ * @param startNodeId  The node whose change we are propagating.
+ * @param edges        Directed edges in the graph.
+ * @param maxDepth     Maximum BFS depth (default 3).
+ * @param decayFactor  Weight multiplier per depth level (default 0.5).
+ */
+export function rippleImpact(
+  startNodeId: string,
+  edges: RippleEdge[],
+  maxDepth = 3,
+  decayFactor = 0.5,
+): RippleResult {
+  return rippleImpactFromMap(startNodeId, buildOutgoingMap(edges), maxDepth, decayFactor);
+}
+
+/**
+ * Format ripple impact results as structured text for LLM consumption.
+ */
+export function formatRippleImpact(
+  startNodeId: string,
+  result: RippleResult,
+  nodeLabels?: Map<string, string>,
+): string {
+  const depths = Object.keys(result.byDepth).map(Number).sort((a, b) => a - b);
+  if (depths.length === 0) {
+    return `No ripple impact found for: ${startNodeId} (isolated or leaf node)`;
+  }
+
+  const lines: string[] = [
+    `Ripple impact of changing: ${startNodeId}`,
+    `  Total score: ${result.totalScore.toFixed(3)} (weighted cascade depth)`,
+  ];
+  for (const depth of depths) {
+    const nodes = result.byDepth[depth]!;
+    lines.push(`  Depth ${depth} (${nodes.length} node${nodes.length === 1 ? '' : 's'}):`);
+    for (const id of nodes) {
+      const label = nodeLabels?.get(id);
+      lines.push(`    - ${id}${label ? ` [${label}]` : ''}`);
+    }
+  }
+  return lines.join('\n');
+}

package/src/graph/risk-profile.ts

@@ -0,0 +1,179 @@
+import type { MonographDb } from '../storage/db.js';
+
+export interface SizeBin {
+  label: string;    // e.g. '1-10 lines'
+  min: number;
+  max: number;
+  count: number;
+  percentage: number;
+}
+
+export interface RiskProfileReport {
+  functionSizeDistribution: SizeBin[];
+  paramCountDistribution: SizeBin[];
+  riskSummary: {
+    largeFunction: number;    // LOC > 100
+    longParamList: number;    // params > 5
+    highRisk: number;         // BOTH large AND long param list
+  };
+  p50loc: number;
+  p90loc: number;
+  p95loc: number;
+}
+
+interface FunctionNode {
+  start_line: number | null;
+  end_line: number | null;
+  properties: string | null;
+}
+
+const LOC_BINS: Array<{ label: string; min: number; max: number }> = [
+  { label: '1-10 lines',   min: 1,   max: 10  },
+  { label: '11-25 lines',  min: 11,  max: 25  },
+  { label: '26-50 lines',  min: 26,  max: 50  },
+  { label: '51-100 lines', min: 51,  max: 100 },
+  { label: '101-250 lines',min: 101, max: 250 },
+  { label: '250+ lines',   min: 251, max: Infinity },
+];
+
+const PARAM_BINS: Array<{ label: string; min: number; max: number }> = [
+  { label: '0-2 params', min: 0, max: 2 },
+  { label: '3-5 params', min: 3, max: 5 },
+  { label: '6-8 params', min: 6, max: 8 },
+  { label: '9+ params',  min: 9, max: Infinity },
+];
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.floor(sorted.length * p);
+  return sorted[Math.min(idx, sorted.length - 1)];
+}
+
+export function computeRiskProfile(db: MonographDb): RiskProfileReport {
+  // Push paramCount extraction to SQL with json_extract to avoid per-row JSON.parse
+  const rows = db.prepare(`
+    SELECT
+      start_line,
+      end_line,
+      CAST(json_extract(properties, '$.paramCount') AS INTEGER) AS param_count
+    FROM nodes
+    WHERE label IN ('Function', 'Method')
+      AND start_line IS NOT NULL
+      AND end_line IS NOT NULL
+  `).all() as { start_line: number; end_line: number; param_count: number | null }[];
+
+  // ── Single-pass: compute LOC, assign to bins, accumulate risk summary ─────
+  const locBinCounts = new Array<number>(LOC_BINS.length).fill(0);
+  const paramBinCounts = new Array<number>(PARAM_BINS.length).fill(0);
+  const sortedLocs: number[] = [];
+  let largeFunction = 0;
+  let longParamList = 0;
+  let highRisk = 0;
+
+  for (const row of rows) {
+    const loc = row.end_line - row.start_line + 1;
+    if (loc < 1) continue;
+
+    sortedLocs.push(loc);
+
+    // Assign to LOC bin in O(bins) rather than O(N×bins) via filter
+    for (let i = 0; i < LOC_BINS.length; i++) {
+      const bin = LOC_BINS[i];
+      if (loc >= bin.min && loc <= bin.max) {
+        locBinCounts[i]++;
+        break;
+      }
+    }
+
+    const pc = row.param_count ?? 0;
+    for (let i = 0; i < PARAM_BINS.length; i++) {
+      const bin = PARAM_BINS[i];
+      if (pc >= bin.min && pc <= bin.max) {
+        paramBinCounts[i]++;
+        break;
+      }
+    }
+
+    const large = loc > 100;
+    const longParam = pc > 5;
+    if (large) largeFunction++;
+    if (longParam) longParamList++;
+    if (large && longParam) highRisk++;
+  }
+
+  const total = sortedLocs.length;
+
+  // ── Build bin result arrays ───────────────────────────────────────────────
+  const functionSizeDistribution: SizeBin[] = LOC_BINS.map((bin, i) => ({
+    label: bin.label,
+    min: bin.min,
+    max: bin.max === Infinity ? 999999 : bin.max,
+    count: locBinCounts[i],
+    percentage: total > 0 ? Math.round((locBinCounts[i] / total) * 1000) / 10 : 0,
+  }));
+
+  const paramCountDistribution: SizeBin[] = PARAM_BINS.map((bin, i) => ({
+    label: bin.label,
+    min: bin.min,
+    max: bin.max === Infinity ? 999999 : bin.max,
+    count: paramBinCounts[i],
+    percentage: total > 0 ? Math.round((paramBinCounts[i] / total) * 1000) / 10 : 0,
+  }));
+
+  // ── Percentiles ────────────────────────────────────────────────────────────
+  sortedLocs.sort((a, b) => a - b);
+  const p50loc = percentile(sortedLocs, 0.50);
+  const p90loc = percentile(sortedLocs, 0.90);
+  const p95loc = percentile(sortedLocs, 0.95);
+
+  return {
+    functionSizeDistribution,
+    paramCountDistribution,
+    riskSummary: { largeFunction, longParamList, highRisk },
+    p50loc,
+    p90loc,
+    p95loc,
+  };
+}
+
+/**
+ * Format a RiskProfileReport as structured text with distribution tables for LLM navigation.
+ *
+ * @param report - RiskProfileReport from computeRiskProfile()
+ * @returns structured text suitable for LLM consumption
+ */
+export function formatRiskProfile(report: RiskProfileReport): string {
+  const { functionSizeDistribution, paramCountDistribution, riskSummary, p50loc, p90loc, p95loc } = report;
+
+  const total = functionSizeDistribution.reduce((s, b) => s + b.count, 0);
+  if (total === 0) {
+    return 'risk_profile: no Function/Method nodes with line info found\n';
+  }
+
+  const lines: string[] = [
+    `risk_profile: ${total} functions analysed`,
+    `  p50_loc: ${p50loc}  p90_loc: ${p90loc}  p95_loc: ${p95loc}`,
+    `  large_functions(loc>100): ${riskSummary.largeFunction}  long_param_list(params>5): ${riskSummary.longParamList}  high_risk(both): ${riskSummary.highRisk}`,
+    '',
+    'function_size_distribution:',
+  ];
+
+  for (const bin of functionSizeDistribution) {
+    const bar = '#'.repeat(Math.round(bin.percentage / 5)); // 1 char per 5%
+    lines.push(`  ${bin.label.padEnd(15)}  ${String(bin.count).padStart(5)}  (${String(bin.percentage).padStart(5)}%)  ${bar}`);
+  }
+
+  lines.push('');
+  lines.push('param_count_distribution:');
+  for (const bin of paramCountDistribution) {
+    const bar = '#'.repeat(Math.round(bin.percentage / 5));
+    lines.push(`  ${bin.label.padEnd(15)}  ${String(bin.count).padStart(5)}  (${String(bin.percentage).padStart(5)}%)  ${bar}`);
+  }
+
+  if (riskSummary.highRisk > 0) {
+    lines.push('');
+    lines.push(`high_risk_note: ${riskSummary.highRisk} function(s) have both loc>100 AND params>5 — prime refactor candidates`);
+  }
+
+  return lines.join('\n');
+}

package/src/graph/shingle-filter.ts

@@ -0,0 +1,149 @@
+export interface ShingleFilter {
+  add(id: string, tokens: string[]): void;
+  candidates(tokens: string[], topK?: number): string[];   // fast pre-filter
+}
+
+/**
+ * Generate k-shingles (k-grams) from a token array.
+ * Each shingle is the concatenation of k consecutive tokens joined by a space.
+ */
+function kShingles(tokens: string[], k: number): string[] {
+  if (tokens.length < k) return [tokens.join(' ')];
+  const shingles: string[] = [];
+  for (let i = 0; i <= tokens.length - k; i++) {
+    shingles.push(tokens.slice(i, i + k).join(' '));
+  }
+  return shingles;
+}
+
+/**
+ * Simple string hash that produces a non-negative 32-bit integer.
+ * Uses a djb2-style hash.
+ */
+function hashString(s: string): number {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) {
+    h = ((h << 5) + h) ^ s.charCodeAt(i);
+    h = h >>> 0; // keep unsigned 32-bit
+  }
+  return h;
+}
+
+const MINHASH_PRIME = BigInt(4294967311); // first prime > 2^32
+
+/**
+ * Compute a MinHash signature for a set of shingles using
+ * numHashes linear hash functions: h_i(x) = (a_i * x + b_i) % prime.
+ *
+ * @param seedsA  Precomputed BigInt a-coefficients (length numHashes)
+ * @param seedsB  Precomputed BigInt b-constants   (length numHashes)
+ */
+function minHashSignature(
+  shingles: string[],
+  numHashes: number,
+  seedsA: BigInt64Array,
+  seedsB: BigInt64Array,
+): Uint32Array {
+  const sig = new Uint32Array(numHashes).fill(0xffffffff);
+
+  for (const shingle of shingles) {
+    const x = BigInt(hashString(shingle));
+    for (let i = 0; i < numHashes; i++) {
+      // Precomputed seeds avoid recomputing the same (a, b) per shingle per call.
+      const hashVal = Number((seedsA[i]! * x + seedsB[i]!) % MINHASH_PRIME) >>> 0;
+      if (hashVal < sig[i]!) sig[i] = hashVal;
+    }
+  }
+  return sig;
+}
+
+export function createShingleFilter(k = 5, numHashes = 128): ShingleFilter {
+  // Each entry: { sig: Uint32Array }
+  const index = new Map<string, Uint32Array>();
+
+  // LSH: split numHashes into bands of rows
+  // Standard LSH: numBands * numRows = numHashes, threshold ≈ (1/numBands)^(1/numRows)
+  // We target threshold ~0.5: solve (1/b)^(1/r) = 0.5 with b*r = numHashes
+  // A reasonable split is sqrt(numHashes) bands of sqrt(numHashes) rows each.
+  const numBands = Math.round(Math.sqrt(numHashes));
+  const numRows = Math.floor(numHashes / numBands);
+
+  // Precompute MinHash seeds once per filter instance to avoid recomputing
+  // (a, b) inside the hot inner loop of minHashSignature().
+  const seedsA = new BigInt64Array(numHashes);
+  const seedsB = new BigInt64Array(numHashes);
+  for (let i = 0; i < numHashes; i++) {
+    seedsA[i] = BigInt(((i * 2654435761 + 0x9e3779b9) >>> 0));
+    seedsB[i] = BigInt(((i * 2246822519 + 0x85ebca6b) >>> 0));
+  }
+
+  function getBandKey(band: number, sig: Uint32Array): string {
+    const parts: number[] = [];
+    for (let r = 0; r < numRows; r++) {
+      const idx = band * numRows + r;
+      if (idx < numHashes) parts.push(sig[idx]!);
+    }
+    return `b${band}:${parts.join(',')}`;
+  }
+
+  // Band bucket → list of candidate IDs
+  const bandBuckets = new Map<string, string[]>();
+
+  return {
+    add(id: string, tokens: string[]): void {
+      const shingles = kShingles(tokens, k);
+      const sig = minHashSignature(shingles, numHashes, seedsA, seedsB);
+      index.set(id, sig);
+
+      // Insert into LSH band buckets
+      for (let band = 0; band < numBands; band++) {
+        const key = getBandKey(band, sig);
+        const bucket = bandBuckets.get(key);
+        if (bucket) {
+          bucket.push(id);
+        } else {
+          bandBuckets.set(key, [id]);
+        }
+      }
+    },
+
+    candidates(tokens: string[], topK = 10): string[] {
+      const shingles = kShingles(tokens, k);
+      const querySig = minHashSignature(shingles, numHashes, seedsA, seedsB);
+
+      // Collect candidate IDs via LSH band matching.
+      // Use getBandKey() consistently — eliminates the duplicate inline computation.
+      const candidateScores = new Map<string, number>();
+
+      for (let band = 0; band < numBands; band++) {
+        const queryKey = getBandKey(band, querySig);
+        const bucket = bandBuckets.get(queryKey);
+        if (bucket) {
+          for (const id of bucket) {
+            candidateScores.set(id, (candidateScores.get(id) ?? 0) + 1);
+          }
+        }
+      }
+
+      if (candidateScores.size === 0) return [];
+
+      // Compute Jaccard estimate from signature agreement for ranked results
+      const ranked = [...candidateScores.keys()].map(id => {
+        const sig = index.get(id)!;
+        let matches = 0;
+        for (let i = 0; i < numHashes; i++) {
+          if (sig[i] === querySig[i]) matches++;
+        }
+        const jaccardEst = matches / numHashes;
+        return { id, jaccardEst };
+      });
+
+      // Filter by estimated Jaccard > 0.5 and return topK
+      return ranked
+        .filter(r => r.jaccardEst > 0.5)
+        .sort((a, b) => b.jaccardEst - a.jaccardEst)
+        .slice(0, topK)
+        .map(r => r.id);
+    },
+  };
+}

package/src/graph/statistics.ts

@@ -0,0 +1,161 @@
+import { bfsFromNode } from 'graphology-traversal/bfs.js';
+import type Graph from 'graphology';
+import { loadGraphFromDb } from './loader.js';
+import type { MonographDb } from '../storage/db.js';
+
+// ---------------------------------------------------------------------------
+// Module-level graph cache — avoids reloading the full graph on every call
+// when multiple statistics functions are invoked in the same request cycle.
+// TTL: 5 seconds; keyed by DB file path (better-sqlite3 exposes .name).
+// ---------------------------------------------------------------------------
+const GRAPH_CACHE_TTL_MS = 5_000;
+
+interface GraphCacheEntry {
+  graph: Graph;
+  expiresAt: number;
+}
+
+const _graphCache = new Map<string, GraphCacheEntry>();
+
+function getGraph(db: MonographDb): Graph {
+  const key = (db as unknown as { name: string }).name ?? '__default__';
+  const now = Date.now();
+  const cached = _graphCache.get(key);
+  if (cached && now < cached.expiresAt) return cached.graph;
+  const graph = loadGraphFromDb(db);
+  _graphCache.set(key, { graph, expiresAt: now + GRAPH_CACHE_TTL_MS });
+  return graph;
+}
+
+/**
+ * Evict the cached graph for a given DB instance (call after writes).
+ */
+export function invalidateGraphCache(db: MonographDb): void {
+  const key = (db as unknown as { name: string }).name ?? '__default__';
+  _graphCache.delete(key);
+}
+
+/**
+ * Graph density: ratio of actual edges to maximum possible directed edges.
+ * For a directed graph with n nodes: max = n * (n - 1).
+ * Ignores self-loops.
+ */
+export function graphDensity(db: MonographDb): number {
+  const graph = getGraph(db);
+  const n = graph.order;
+  if (n < 2) return 0;
+  const maxEdges = n * (n - 1);
+  // Use simple directed edge count (deduplicate multi-edges for density)
+  const seen = new Set<string>();
+  graph.forEachEdge((_, _attr, src, tgt) => {
+    if (src !== tgt) seen.add(`${src}→${tgt}`);
+  });
+  return seen.size / maxEdges;
+}
+
+/**
+ * Average local clustering coefficient across all nodes.
+ * For a directed graph, the local clustering coefficient of node v is:
+ *   (triangles through v) / (directed_pairs through v)
+ * where directed_pairs = k_in * k_out - mutual_pairs
+ * We use the undirected approximation: treat edges as undirected, count triangles.
+ */
+export function clusteringCoefficient(db: MonographDb): number {
+  const graph = getGraph(db);
+  if (graph.order === 0) return 0;
+
+  // Build undirected adjacency sets
+  const neighbors = new Map<string, Set<string>>();
+  graph.forEachNode(node => neighbors.set(node, new Set()));
+  graph.forEachEdge((_, _attr, src, tgt) => {
+    if (src !== tgt) {
+      neighbors.get(src)!.add(tgt);
+      neighbors.get(tgt)!.add(src);
+    }
+  });
+
+  let totalCoeff = 0;
+  let countWithNeighbors = 0;
+
+  for (const [node, nbrs] of neighbors) {
+    const k = nbrs.size;
+    if (k < 2) continue;
+
+    let triangles = 0;
+    const nbList = [...nbrs];
+    for (let i = 0; i < nbList.length; i++) {
+      for (let j = i + 1; j < nbList.length; j++) {
+        if (neighbors.get(nbList[i])?.has(nbList[j])) {
+          triangles++;
+        }
+      }
+    }
+
+    const possible = (k * (k - 1)) / 2;
+    totalCoeff += triangles / possible;
+    countWithNeighbors++;
+  }
+
+  if (countWithNeighbors === 0) return 0;
+  return totalCoeff / countWithNeighbors;
+}
+
+// ---------------------------------------------------------------------------
+// Shared BFS result for path-length metrics
+// ---------------------------------------------------------------------------
+
+export interface PathStats {
+  /** Average shortest path length across all reachable pairs (i ≠ j). */
+  averagePathLength: number;
+  /** Maximum shortest path length (diameter) across all reachable pairs. */
+  diameter: number;
+}
+
+/**
+ * Compute both average path length and graph diameter in a single BFS pass.
+ * Unreachable pairs are excluded from averagePathLength.
+ */
+export function pathStats(db: MonographDb): PathStats {
+  const graph = getGraph(db);
+  const nodes = graph.nodes();
+  if (nodes.length < 2) return { averagePathLength: 0, diameter: 0 };
+
+  let totalLength = 0;
+  let reachablePairs = 0;
+  let maxDist = 0;
+
+  for (const source of nodes) {
+    bfsFromNode(graph, source, (node, _attr, depth) => {
+      if (node !== source && depth > 0) {
+        totalLength += depth;
+        reachablePairs++;
+        if (depth > maxDist) maxDist = depth;
+      }
+    });
+  }
+
+  return {
+    averagePathLength: reachablePairs === 0 ? 0 : totalLength / reachablePairs,
+    diameter: maxDist,
+  };
+}
+
+/**
+ * Average shortest path length across all reachable node pairs (i, j) where i ≠ j.
+ * Computed using BFS from each node. Unreachable pairs are excluded from the average.
+ *
+ * @deprecated Prefer `pathStats(db).averagePathLength` to share BFS with `graphDiameter`.
+ */
+export function averagePathLength(db: MonographDb): number {
+  return pathStats(db).averagePathLength;
+}
+
+/**
+ * Graph diameter: the maximum shortest path length across all reachable node pairs.
+ * Returns 0 for empty or single-node graphs.
+ *
+ * @deprecated Prefer `pathStats(db).diameter` to share BFS with `averagePathLength`.
+ */
+export function graphDiameter(db: MonographDb): number {
+  return pathStats(db).diameter;
+}