@monoes/monograph 1.1.0 → 1.2.1

package/src/analysis/cluster-quality.ts

@@ -0,0 +1,143 @@
+/**
+ * Cluster quality metrics: silhouette score and modularity score.
+ *
+ * References:
+ *  - Silhouette: Rousseeuw (1987) — (b-a)/max(a,b) averaged over all nodes
+ *  - Modularity: Newman & Girvan (2004) — Q = Σ[e_ii - a_i²]
+ */
+
+export type Edge = { sourceId: string; targetId: string };
+
+/**
+ * Build an adjacency map from an edge list (undirected).
+ */
+function buildAdjacency(edges: Edge[]): Map<string, Set<string>> {
+  const adj = new Map<string, Set<string>>();
+  for (const { sourceId, targetId } of edges) {
+    if (!adj.has(sourceId)) adj.set(sourceId, new Set());
+    if (!adj.has(targetId)) adj.set(targetId, new Set());
+    adj.get(sourceId)!.add(targetId);
+    adj.get(targetId)!.add(sourceId);
+  }
+  return adj;
+}
+
+/**
+ * Average hop-distance proxy: fraction of community members NOT adjacent to node.
+ * For graph-based silhouette we use the complement of the adjacency fraction
+ * as a distance (0 = neighbor, 1 = no edge).
+ *
+ * a(i) = mean distance to other nodes in same community
+ * b(i) = min mean distance to any other community
+ * silhouette(i) = (b(i) - a(i)) / max(a(i), b(i))
+ *
+ * @param communityMembers - precomputed communityId → nodeId[] map (excludes self)
+ */
+function nodeSilhouette(
+  nodeId: string,
+  community: number,
+  communityMembers: Map<number, string[]>,
+  adj: Map<string, Set<string>>,
+): number {
+  const neighbors = adj.get(nodeId) ?? new Set<string>();
+
+  const sameMembers = (communityMembers.get(community) ?? []).filter(n => n !== nodeId);
+  if (sameMembers.length === 0) return 0; // singleton community
+
+  // a(i): mean distance to same community (1 = not neighbor, 0 = neighbor)
+  const a =
+    sameMembers.reduce((sum, nid) => sum + (neighbors.has(nid) ? 0 : 1), 0) /
+    sameMembers.length;
+
+  // b(i): minimum mean distance to any other community
+  let b = Infinity;
+  for (const [cid, members] of communityMembers) {
+    if (cid === community || members.length === 0) continue;
+    const meanDist =
+      members.reduce((sum, nid) => sum + (neighbors.has(nid) ? 0 : 1), 0) /
+      members.length;
+    if (meanDist < b) b = meanDist;
+  }
+
+  if (!isFinite(b)) return 0; // only one community exists
+  const denom = Math.max(a, b);
+  if (denom === 0) return 0;
+  return (b - a) / denom;
+}
+
+/**
+ * Compute the average silhouette score for the partitioning.
+ * Returns a value in [-1, 1] where higher is better.
+ *
+ * Precomputes the communityMembers map once (O(N)) before the per-node loop,
+ * reducing overall complexity from O(N²) to O(N + K*N) where K = community count.
+ */
+export function silhouetteScore(
+  memberships: Map<string, number>,
+  edges: Edge[],
+): number {
+  if (memberships.size === 0) return 0;
+  const adj = buildAdjacency(edges);
+
+  // Precompute communityId → nodeId[] once to avoid O(N) re-scan per node
+  const communityMembers = new Map<number, string[]>();
+  for (const [nid, cid] of memberships) {
+    let members = communityMembers.get(cid);
+    if (!members) {
+      members = [];
+      communityMembers.set(cid, members);
+    }
+    members.push(nid);
+  }
+
+  let total = 0;
+  for (const [nodeId, community] of memberships) {
+    total += nodeSilhouette(nodeId, community, communityMembers, adj);
+  }
+  return total / memberships.size;
+}
+
+/**
+ * Compute Newman–Girvan modularity Q.
+ *
+ * Q = (1/2m) * Σ_{ij} [A_ij - k_i*k_j/(2m)] * δ(c_i, c_j)
+ *
+ * where m = total edge count, k_i = degree of node i, A_ij = adjacency.
+ * Returns a value in (-0.5, 1].
+ */
+export function modularityScore(
+  memberships: Map<string, number>,
+  edges: Edge[],
+): number {
+  const adj = buildAdjacency(edges);
+
+  // Degree map (undirected) — use adj to count undirected edges correctly
+  const degree = new Map<string, number>();
+  for (const [nodeId, neighbors] of adj) {
+    degree.set(nodeId, neighbors.size);
+  }
+
+  // m_undirected: each undirected edge is counted once in adj (both directions added)
+  // so sum of degrees = 2 * m_undirected
+  const totalDegree = [...degree.values()].reduce((s, d) => s + d, 0);
+  const m = totalDegree / 2;
+  if (m === 0) return 0;
+
+  const twoM = 2 * m;
+  let Q = 0;
+
+  const nodes = [...memberships.keys()];
+  for (let i = 0; i < nodes.length; i++) {
+    const u = nodes[i]!;
+    for (let j = i + 1; j < nodes.length; j++) {
+      const v = nodes[j]!;
+      if (memberships.get(u) !== memberships.get(v)) continue;
+      const aij = adj.get(u)?.has(v) ? 1 : 0;
+      const ki = degree.get(u) ?? 0;
+      const kj = degree.get(v) ?? 0;
+      Q += aij - (ki * kj) / twoM;
+    }
+  }
+
+  return Q / m; // normalise by m (equivalent to 1/(2m) summed both directions)
+}

package/src/analysis/combined.ts

@@ -0,0 +1,39 @@
+import type { MonographDb } from '../storage/db.js';
+
+export type AnalysisKind = 'dead-code' | 'duplication' | 'health';
+
+export interface CombinedOptions {
+  only?: AnalysisKind[];
+  skip?: AnalysisKind[];
+}
+
+export interface CombinedResult {
+  analyses: Set<AnalysisKind>;
+  ranAt: string; // ISO timestamp
+}
+
+export function resolveAnalyses(opts: CombinedOptions): Set<AnalysisKind> {
+  let result = new Set<AnalysisKind>(['dead-code', 'duplication', 'health']);
+
+  if (opts.skip) {
+    for (const kind of opts.skip) {
+      result.delete(kind);
+    }
+  }
+
+  if (opts.only && opts.only.length > 0) {
+    const onlySet = new Set(opts.only);
+    result = new Set([...result].filter((k) => onlySet.has(k)));
+  }
+
+  return result;
+}
+
+export async function runCombined(
+  db: MonographDb,
+  opts: CombinedOptions
+): Promise<CombinedResult> {
+  const analyses = resolveAnalyses(opts);
+  const ranAt = new Date().toISOString();
+  return { analyses, ranAt };
+}

package/src/analysis/corpus-health.ts

@@ -0,0 +1,41 @@
+export const CORPUS_WARN_MIN_WORDS = 50_000;
+export const CORPUS_WARN_MAX_WORDS = 500_000;
+export const CORPUS_WARN_MAX_FILES = 200;
+
+export interface CorpusStats {
+  wordCount: number;
+  fileCount: number;
+}
+
+export interface CorpusHealthResult {
+  healthy: boolean;
+  warnings: string[];
+  stats: CorpusStats;
+}
+
+export function checkCorpusHealth(stats: CorpusStats): CorpusHealthResult {
+  const warnings: string[] = [];
+
+  if (stats.wordCount < CORPUS_WARN_MIN_WORDS) {
+    warnings.push(
+      `Corpus too small: ${stats.wordCount.toLocaleString()} words (min ${CORPUS_WARN_MIN_WORDS.toLocaleString()}). ` +
+      `Results may be low-quality on toy projects.`
+    );
+  }
+
+  if (stats.wordCount > CORPUS_WARN_MAX_WORDS) {
+    warnings.push(
+      `Corpus too large: ${stats.wordCount.toLocaleString()} words (max ${CORPUS_WARN_MAX_WORDS.toLocaleString()}). ` +
+      `Consider using --code-only or filtering to a subset.`
+    );
+  }
+
+  if (stats.fileCount > CORPUS_WARN_MAX_FILES) {
+    warnings.push(
+      `Too many files: ${stats.fileCount} (max ${CORPUS_WARN_MAX_FILES}). ` +
+      `Consider using --ignore patterns to exclude generated or vendor files.`
+    );
+  }
+
+  return { healthy: warnings.length === 0, warnings, stats };
+}

package/src/analysis/coverage-gaps.ts

@@ -0,0 +1,246 @@
+import type { MonographDb } from '../storage/db.js';
+
+export interface UntestedFile {
+  nodeId: string;
+  filePath: string;
+  reachabilityRole: string;   // 'runtime'
+  inDegree: number;           // from runtime files
+  reason: string;             // e.g. 'No test imports this file'
+}
+
+export interface UntestedExport {
+  nodeId: string;
+  name: string;
+  filePath: string | null;
+  startLine: number | null;
+  exportType: string;   // label
+}
+
+export interface CoverageGapsResult {
+  untestedFiles: UntestedFile[];
+  untestedExports: UntestedExport[];
+  fileCoveragePct: number;     // (runtime files reachable by tests) / (total runtime files) * 100
+  exportCoveragePct: number;
+  summary: string;
+}
+
+interface FileRow {
+  id: string;
+  file_path: string;
+}
+
+interface ImportEdgeRow {
+  source_id: string;
+  target_id: string;
+}
+
+interface ExportRow {
+  id: string;
+  name: string;
+  file_path: string | null;
+  start_line: number | null;
+  label: string;
+}
+
+interface InDegreeRow {
+  target_id: string;
+  cnt: number;
+}
+
+export function computeCoverageGaps(db: MonographDb): CoverageGapsResult {
+  // Runtime-reachable files
+  const runtimeFiles = db.prepare(
+    `SELECT id, file_path FROM nodes
+     WHERE label = 'File'
+       AND json_extract(properties, '$.reachabilityRole') = 'runtime'`
+  ).all() as FileRow[];
+
+  // Test entry points
+  const testFiles = db.prepare(
+    `SELECT id, file_path FROM nodes
+     WHERE label = 'File'
+       AND json_extract(properties, '$.reachabilityRole') = 'test'`
+  ).all() as FileRow[];
+
+  // All IMPORTS edges between files for BFS
+  const allImportEdges = db.prepare(
+    `SELECT e.source_id, e.target_id
+     FROM edges e
+     WHERE e.relation IN ('IMPORTS', 'RE_EXPORTS')
+       AND e.source_id IN (SELECT id FROM nodes WHERE label = 'File')
+       AND e.target_id IN (SELECT id FROM nodes WHERE label = 'File')`
+  ).all() as ImportEdgeRow[];
+
+  // Build forward adjacency for BFS
+  const forwardAdj = new Map<string, string[]>();
+  for (const edge of allImportEdges) {
+    let list = forwardAdj.get(edge.source_id);
+    if (!list) {
+      list = [];
+      forwardAdj.set(edge.source_id, list);
+    }
+    list.push(edge.target_id);
+  }
+
+  // BFS from test entry points
+  const testReachable = new Set<string>();
+  const queue: string[] = [];
+  for (const tf of testFiles) {
+    if (!testReachable.has(tf.id)) {
+      testReachable.add(tf.id);
+      queue.push(tf.id);
+    }
+  }
+
+  let head = 0;
+  while (head < queue.length) {
+    const current = queue[head++];
+    const neighbors = forwardAdj.get(current) ?? [];
+    for (const neighbor of neighbors) {
+      if (!testReachable.has(neighbor)) {
+        testReachable.add(neighbor);
+        queue.push(neighbor);
+      }
+    }
+  }
+
+  // Compute in-degree from runtime files only (not test files) so fan-in reflects
+  // real dependency weight, not test coverage depth.
+  const runtimeFileIdSet = new Set(runtimeFiles.map(rf => rf.id));
+  const inDegreeMap = new Map<string, number>();
+  for (const edge of allImportEdges) {
+    if (!runtimeFileIdSet.has(edge.source_id)) continue;
+    const current = inDegreeMap.get(edge.target_id) ?? 0;
+    inDegreeMap.set(edge.target_id, current + 1);
+  }
+
+  // Untested files = runtime files NOT in the test-reachable set
+  const untestedFiles: UntestedFile[] = [];
+  for (const rf of runtimeFiles) {
+    if (!testReachable.has(rf.id)) {
+      untestedFiles.push({
+        nodeId: rf.id,
+        filePath: rf.file_path,
+        reachabilityRole: 'runtime',
+        inDegree: inDegreeMap.get(rf.id) ?? 0,
+        reason: 'No test imports this file',
+      });
+    }
+  }
+
+  // All exported symbols
+  const allExportedRows = db.prepare(
+    `SELECT n.id, n.name, n.file_path, n.start_line, n.label
+     FROM nodes n
+     WHERE n.is_exported = 1
+       AND n.label IN ('Function','Class','Method','Interface','Const','TypeAlias','Enum','Variable')`
+  ).all() as ExportRow[];
+
+  // Runtime file IDs set for quick lookup
+  const runtimeFileIds = new Set(runtimeFiles.map(rf => rf.id));
+
+  // Map file_path -> file node id for runtime files
+  const runtimeFilePathToId = new Map<string, string>();
+  for (const rf of runtimeFiles) {
+    runtimeFilePathToId.set(rf.file_path, rf.id);
+  }
+
+  // Determine which file a symbol belongs to (by file_path)
+  const testedRuntimeFileIds = new Set<string>();
+  for (const rf of runtimeFiles) {
+    if (testReachable.has(rf.id)) {
+      testedRuntimeFileIds.add(rf.id);
+    }
+  }
+
+  const untestedExports: UntestedExport[] = [];
+  let totalRuntimeExports = 0;
+  let testedRuntimeExports = 0;
+
+  for (const exp of allExportedRows) {
+    if (!exp.file_path) continue;
+    const fileId = runtimeFilePathToId.get(exp.file_path);
+    if (!fileId) continue; // not a runtime file
+
+    totalRuntimeExports++;
+    if (testedRuntimeFileIds.has(fileId)) {
+      testedRuntimeExports++;
+    } else {
+      untestedExports.push({
+        nodeId: exp.id,
+        name: exp.name,
+        filePath: exp.file_path,
+        startLine: exp.start_line ?? null,
+        exportType: exp.label,
+      });
+    }
+  }
+
+  const totalRuntimeFiles = runtimeFiles.length;
+  const testedRuntimeFiles = runtimeFiles.filter(rf => testReachable.has(rf.id)).length;
+
+  const fileCoveragePct = totalRuntimeFiles > 0
+    ? (testedRuntimeFiles / totalRuntimeFiles) * 100
+    : 100;
+
+  const exportCoveragePct = totalRuntimeExports > 0
+    ? (testedRuntimeExports / totalRuntimeExports) * 100
+    : 100;
+
+  const summary = [
+    `${testedRuntimeFiles}/${totalRuntimeFiles} runtime files reachable by tests`,
+    `(${fileCoveragePct.toFixed(1)}% file coverage,`,
+    `${exportCoveragePct.toFixed(1)}% export coverage).`,
+    untestedFiles.length > 0
+      ? `${untestedFiles.length} untested file(s) found.`
+      : 'All runtime files are test-reachable.',
+  ].join(' ');
+
+  return {
+    untestedFiles,
+    untestedExports,
+    fileCoveragePct,
+    exportCoveragePct,
+    summary,
+  };
+}
+
+/** Format CoverageGapsResult as structured text with file:line hints for LLM navigation. */
+export function formatCoverageGaps(result: CoverageGapsResult, topN = 20): string {
+  const lines: string[] = [result.summary, ''];
+
+  if (result.untestedFiles.length > 0) {
+    // Sort untested files by inDegree descending — highest-impact first
+    const sorted = [...result.untestedFiles].sort((a, b) => b.inDegree - a.inDegree);
+    const shown = sorted.slice(0, topN);
+    lines.push(`Top untested files by import-count (${shown.length}/${result.untestedFiles.length} shown):`);
+    for (const f of shown) {
+      lines.push(`  ${f.filePath}  in-degree:${f.inDegree}`);
+    }
+    lines.push('');
+  }
+
+  if (result.untestedExports.length > 0) {
+    // Group untested exports by file
+    const byFile = new Map<string, UntestedExport[]>();
+    for (const exp of result.untestedExports) {
+      const key = exp.filePath ?? '(unknown)';
+      let group = byFile.get(key);
+      if (!group) { group = []; byFile.set(key, group); }
+      group.push(exp);
+    }
+
+    lines.push(`Untested exported symbols (${result.untestedExports.length}) grouped by file:`);
+    for (const [filePath, exports] of byFile) {
+      lines.push(`  ${filePath}`);
+      for (const exp of exports) {
+        const ref = exp.startLine != null ? `${filePath}:${exp.startLine}` : filePath;
+        lines.push(`    ${exp.exportType}  ${exp.name}  (${ref})`);
+      }
+    }
+    lines.push('');
+  }
+
+  lines.push('Fix: add tests importing the untested files, or mark files as non-runtime if they are build artifacts.');
+  return lines.join('\n').trimEnd();
+}