@monoes/monograph 1.2.0 → 1.2.2

package/src/graph/regex-search.ts

@@ -21,14 +21,15 @@ export function regexSearchNodes(
   db: MonographDb,
   pattern: RegExp | string,
   fields: Array<'name' | 'filePath' | 'language' | 'label'> = ['name', 'filePath'],
+  limit = 200,
 ): RegexNodeMatch[] {
   const re = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
 
   const rows = db.prepare(
     `SELECT id, label, name, norm_label, file_path, start_line, end_line,
             community_id, is_exported, language, properties
-     FROM nodes`,
-  ).all() as {
+     FROM nodes LIMIT ?`,
+  ).all(limit) as {
     id: string;
     label: string;
     name: string;
@@ -96,13 +97,14 @@ export function regexSearchEdges(
   db: MonographDb,
   pattern: RegExp | string,
   fields: Array<'relation' | 'confidence' | 'reason'> = ['relation', 'reason'],
+  limit = 200,
 ): RegexEdgeMatch[] {
   const re = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
 
   const rows = db.prepare(
     `SELECT id, source_id, target_id, relation, confidence, confidence_score, reason
-     FROM edges`,
-  ).all() as {
+     FROM edges LIMIT ?`,
+  ).all(limit) as {
     id: string;
     source_id: string;
     target_id: string;
@@ -193,3 +195,35 @@ export function regexSearchEdgesInMemory(
 
   return results;
 }
+
+// ── LLM formatters ─────────────────────────────────────────────────────────────
+
+/**
+ * Format node regex match results as structured text for LLM consumption.
+ */
+export function formatRegexNodeMatches(matches: RegexNodeMatch[], pattern: string): string {
+  if (matches.length === 0) return `No nodes matching /${pattern}/.`;
+  const lines: string[] = [`${matches.length} node(s) matching /${pattern}/:`];
+  for (const m of matches) {
+    const loc = m.node.filePath
+      ? ` ${m.node.filePath}${m.node.startLine != null ? `:${m.node.startLine}` : ''}`
+      : '';
+    lines.push(`  [${m.field}] ${m.node.label} ${m.node.name}${loc}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Format edge regex match results as structured text for LLM consumption.
+ */
+export function formatRegexEdgeMatches(matches: RegexEdgeMatch[], pattern: string): string {
+  if (matches.length === 0) return `No edges matching /${pattern}/.`;
+  const lines: string[] = [`${matches.length} edge(s) matching /${pattern}/:`];
+  for (const m of matches) {
+    lines.push(
+      `  [${m.field}] ${m.edge.sourceId} -[${m.edge.relation}]-> ${m.edge.targetId}` +
+      (m.edge.reason ? `  // ${m.edge.reason}` : ''),
+    );
+  }
+  return lines.join('\n');
+}

package/src/graph/regression.ts

@@ -86,6 +86,18 @@ const FINDING_TYPE_TO_METRIC: Record<string, string> = {
   ambiguous_edge: 'ambiguousEdgeCount',
 };
 
+/** Canonical metric names — defined once to avoid duplicating the same literal Set/Object. */
+const METRIC_NAMES = Object.values(FINDING_TYPE_TO_METRIC);
+const METRIC_NAME_SET = new Set(METRIC_NAMES);
+
+/** Module-level cache for parsed Tolerance objects — avoids re-parsing identical specs. */
+const toleranceCache = new Map<string, Tolerance>();
+function parseTolerance(spec: string): Tolerance {
+  let t = toleranceCache.get(spec);
+  if (!t) { t = Tolerance.parse(spec); toleranceCache.set(spec, t); }
+  return t;
+}
+
 // ── checkRegression ───────────────────────────────────────────────────────────
 
 /**
@@ -104,51 +116,39 @@ export function checkRegression(
 ): RegressionOutcome {
   const baseline: BaselineData | null = loadBaseline(baselinePath);
 
-  // Compute current counts from DB
+  // Compute current counts from DB using shared METRIC_NAMES init
   const currentFindings = extractFindingsFromDb(db, '');
-  const currentCounts: Record<string, number> = {
-    godNodeCount: 0,
-    surpriseCount: 0,
-    bridgeNodeCount: 0,
-    unreachableExportCount: 0,
-    ambiguousEdgeCount: 0,
-  };
+  const currentCounts: Record<string, number> = Object.fromEntries(METRIC_NAMES.map(m => [m, 0]));
   for (const f of currentFindings) {
     const metricName = FINDING_TYPE_TO_METRIC[f.type];
-    if (metricName && metricName in currentCounts) {
+    if (metricName && METRIC_NAME_SET.has(metricName)) {
       currentCounts[metricName]++;
     }
   }
 
-  // Compute baseline counts
-  const baselineCounts: Record<string, number> = {
-    godNodeCount: 0,
-    surpriseCount: 0,
-    bridgeNodeCount: 0,
-    unreachableExportCount: 0,
-    ambiguousEdgeCount: 0,
-  };
+  // Compute baseline counts using shared METRIC_NAMES init
+  const baselineCounts: Record<string, number> = Object.fromEntries(METRIC_NAMES.map(m => [m, 0]));
   if (baseline) {
     for (const f of baseline.findings) {
       const metricName = FINDING_TYPE_TO_METRIC[f.type];
-      if (metricName && metricName in baselineCounts) {
+      if (metricName && METRIC_NAME_SET.has(metricName)) {
         baselineCounts[metricName]++;
       }
     }
   }
 
-  // Default tolerance
-  const defaultTolerance = Tolerance.parse(toleranceSpec);
+  // Default tolerance — use cached parse to avoid rebuilding on repeated calls with same spec
+  const defaultTolerance = parseTolerance(toleranceSpec);
 
-  // Check each metric
+  // Check each metric — per-metric tolerances also cached
   const checkedMetrics: RegressionMetric[] = [];
-  for (const metric of Object.keys(currentCounts)) {
+  for (const metric of METRIC_NAMES) {
     const baselineVal = baselineCounts[metric] ?? 0;
     const currentVal = currentCounts[metric] ?? 0;
     const delta = currentVal - baselineVal;
 
     const metricSpec = metricTolerances?.[metric];
-    const tol = metricSpec ? Tolerance.parse(metricSpec) : defaultTolerance;
+    const tol = metricSpec ? parseTolerance(metricSpec) : defaultTolerance;
     const tolStr = tol.toString();
     const violated = tol.exceeded(baselineVal, currentVal);
 
@@ -172,3 +172,28 @@ export function checkRegression(
 
   return { passed, violations, checkedMetrics, summary };
 }
+
+/**
+ * Format a RegressionOutcome as structured text for LLM consumption.
+ * Shows pass/fail status, per-metric results, and actionable violation details.
+ */
+export function formatRegressionOutcome(outcome: RegressionOutcome): string {
+  const lines: string[] = [outcome.summary];
+
+  lines.push('\nMetrics:');
+  for (const m of outcome.checkedMetrics) {
+    const sign = m.delta > 0 ? `+${m.delta}` : String(m.delta);
+    const status = m.violated ? 'VIOLATED' : 'ok';
+    lines.push(`  ${m.metric}: baseline=${m.baseline} current=${m.current} delta=${sign} tolerance=${m.tolerance} [${status}]`);
+  }
+
+  if (outcome.violations.length > 0) {
+    lines.push('\nViolations requiring attention:');
+    for (const v of outcome.violations) {
+      const sign = v.delta > 0 ? `+${v.delta}` : String(v.delta);
+      lines.push(`  ${v.metric} exceeded tolerance ${v.tolerance} (delta ${sign}): investigate new ${v.metric.replace(/Count$/, '')} introductions`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/graph/ripple-impact.ts

@@ -22,26 +22,38 @@ export interface RippleResult {
 }
 
 /**
- * Compute the ripple impact of changing `startNodeId`.
+ * 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 edges        Directed edges in the graph.
+ * @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 rippleImpact(
+export function rippleImpactFromMap(
   startNodeId: string,
-  edges: RippleEdge[],
+  outgoing: Map<string, string[]>,
   maxDepth = 3,
   decayFactor = 0.5,
 ): RippleResult {
-  // Build directed adjacency (source → targets)
-  const outgoing = new Map<string, string[]>();
-  for (const { sourceId, targetId } of edges) {
-    if (!outgoing.has(sourceId)) outgoing.set(sourceId, []);
-    outgoing.get(sourceId)!.push(targetId);
-  }
-
   if (!outgoing.has(startNodeId)) {
     return { byDepth: {}, totalScore: 0 };
   }
@@ -69,3 +81,51 @@ export function rippleImpact(
 
   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

@@ -50,75 +50,78 @@ function percentile(sorted: number[], p: number): number {
 }
 
 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, properties
+    SELECT
+      start_line,
+      end_line,
+      CAST(json_extract(properties, '$.paramCount') AS INTEGER) AS param_count
     FROM nodes
     WHERE label IN ('Function', 'Method')
-  `).all() as FunctionNode[];
-
-  const locs: number[] = [];
-  const params: number[] = [];
+      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) {
-    if (row.start_line === null || row.end_line === null) continue;
     const loc = row.end_line - row.start_line + 1;
     if (loc < 1) continue;
-    locs.push(loc);
-
-    let paramCount = 0;
-    if (row.properties) {
-      try {
-        const props = JSON.parse(row.properties) as Record<string, unknown>;
-        if (typeof props['paramCount'] === 'number') {
-          paramCount = props['paramCount'];
-        }
-      } catch {
-        // ignore malformed JSON
+
+    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;
       }
     }
-    params.push(paramCount);
-  }
 
-  const total = locs.length;
-
-  // ── LOC distribution ───────────────────────────────────────────────────────
-  const functionSizeDistribution: SizeBin[] = LOC_BINS.map(bin => {
-    const count = locs.filter(l => l >= bin.min && l <= bin.max).length;
-    return {
-      label: bin.label,
-      min: bin.min,
-      max: bin.max === Infinity ? 999999 : bin.max,
-      count,
-      percentage: total > 0 ? Math.round((count / total) * 1000) / 10 : 0,
-    };
-  });
-
-  // ── Param distribution ─────────────────────────────────────────────────────
-  const paramCountDistribution: SizeBin[] = PARAM_BINS.map(bin => {
-    const count = params.filter(p => p >= bin.min && p <= bin.max).length;
-    return {
-      label: bin.label,
-      min: bin.min,
-      max: bin.max === Infinity ? 999999 : bin.max,
-      count,
-      percentage: total > 0 ? Math.round((count / total) * 1000) / 10 : 0,
-    };
-  });
-
-  // ── Risk summary ───────────────────────────────────────────────────────────
-  let largeFunction = 0;
-  let longParamList = 0;
-  let highRisk = 0;
-  for (let i = 0; i < locs.length; i++) {
-    const large = locs[i] > 100;
-    const longParam = (params[i] ?? 0) > 5;
+    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 ────────────────────────────────────────────────────────────
-  const sortedLocs = [...locs].sort((a, b) => a - b);
+  sortedLocs.sort((a, b) => a - b);
   const p50loc = percentile(sortedLocs, 0.50);
   const p90loc = percentile(sortedLocs, 0.90);
   const p95loc = percentile(sortedLocs, 0.95);
@@ -132,3 +135,45 @@ export function computeRiskProfile(db: MonographDb): RiskProfileReport {
     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

@@ -29,26 +29,29 @@ function hashString(s: string): number {
   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
+ * 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): Uint32Array {
-  const PRIME = 4294967311; // first prime > 2^32
+function minHashSignature(
+  shingles: string[],
+  numHashes: number,
+  seedsA: BigInt64Array,
+  seedsB: BigInt64Array,
+): Uint32Array {
   const sig = new Uint32Array(numHashes).fill(0xffffffff);
 
-  // Deterministic seeds derived from hash index
   for (const shingle of shingles) {
-    const x = hashString(shingle);
+    const x = BigInt(hashString(shingle));
     for (let i = 0; i < numHashes; i++) {
-      // Deterministic a, b per hash function — use index-based seeds
-      const a = ((i * 2654435761 + 0x9e3779b9) >>> 0);
-      const b = ((i * 2246822519 + 0x85ebca6b) >>> 0);
-      // Linear hash modulo prime (BigInt for correctness)
-      const hashVal = Number((BigInt(a) * BigInt(x) + BigInt(b)) % BigInt(PRIME)) >>> 0;
-      if (hashVal < sig[i]) {
-        sig[i] = hashVal;
-      }
+      // 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;
@@ -65,11 +68,20 @@ export function createShingleFilter(k = 5, numHashes = 128): ShingleFilter {
   const numBands = Math.round(Math.sqrt(numHashes));
   const numRows = Math.floor(numHashes / numBands);
 
-  function getBandKey(id: string, band: number, sig: Uint32Array): string {
+  // 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]);
+      if (idx < numHashes) parts.push(sig[idx]!);
     }
     return `b${band}:${parts.join(',')}`;
   }
@@ -80,12 +92,12 @@ export function createShingleFilter(k = 5, numHashes = 128): ShingleFilter {
   return {
     add(id: string, tokens: string[]): void {
       const shingles = kShingles(tokens, k);
-      const sig = minHashSignature(shingles, numHashes);
+      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(id, band, sig);
+        const key = getBandKey(band, sig);
         const bucket = bandBuckets.get(key);
         if (bucket) {
           bucket.push(id);
@@ -97,20 +109,14 @@ export function createShingleFilter(k = 5, numHashes = 128): ShingleFilter {
 
     candidates(tokens: string[], topK = 10): string[] {
       const shingles = kShingles(tokens, k);
-      const querySig = minHashSignature(shingles, numHashes);
+      const querySig = minHashSignature(shingles, numHashes, seedsA, seedsB);
 
-      // Collect candidate IDs via LSH band matching
+      // 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 key = getBandKey('__query__', band, querySig);
-        // Manually compute the key for the query signature
-        const parts: number[] = [];
-        for (let r = 0; r < numRows; r++) {
-          const idx = band * numRows + r;
-          if (idx < numHashes) parts.push(querySig[idx]);
-        }
-        const queryKey = `b${band}:${parts.join(',')}`;
+        const queryKey = getBandKey(band, querySig);
         const bucket = bandBuckets.get(queryKey);
         if (bucket) {
           for (const id of bucket) {