@monoes/monograph 1.1.0 → 1.2.0

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,203 @@
+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;
+  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;
+  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.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,
+        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,
+  };
+}

package/src/analysis/cycles.ts

@@ -0,0 +1,264 @@
+import type { MonographDb } from '../storage/db.js';
+
+export interface DependencyCycle {
+  files: string[];         // file paths forming the cycle, in order
+  length: number;
+  isCrossCommunity: boolean;  // true if files span multiple communities
+  edgeRelations: string[];    // relations used in the cycle edges
+}
+
+export interface CycleDetectionResult {
+  cycles: DependencyCycle[];
+  totalCycles: number;
+  filesInCycles: number;
+  longestCycle: number;
+  crossCommunityCycles: number;
+}
+
+interface NodeRow {
+  id: string;
+  file_path: string | null;
+  community_id: number | null;
+}
+
+interface EdgeRow {
+  source_id: string;
+  target_id: string;
+  relation: string;
+}
+
+/**
+ * Iterative Tarjan's SCC algorithm to avoid stack overflow on large graphs.
+ * Returns arrays of node IDs, each array is one SCC.
+ */
+function tarjanSCC(adjacency: Map<string, string[]>, nodes: string[]): string[][] {
+  const index: Map<string, number> = new Map();
+  const lowlink: Map<string, number> = new Map();
+  const onStack: Set<string> = new Set();
+  const stack: string[] = [];
+  const sccs: string[][] = [];
+  let counter = 0;
+
+  // Iterative DFS using explicit call stack
+  for (const startNode of nodes) {
+    if (index.has(startNode)) continue;
+
+    // Each frame: [nodeId, neighborIndex, parent]
+    type Frame = { node: string; neighborIdx: number };
+    const callStack: Frame[] = [{ node: startNode, neighborIdx: 0 }];
+
+    index.set(startNode, counter);
+    lowlink.set(startNode, counter);
+    counter++;
+    stack.push(startNode);
+    onStack.add(startNode);
+
+    while (callStack.length > 0) {
+      const frame = callStack[callStack.length - 1];
+      const { node } = frame;
+      const neighbors = adjacency.get(node) ?? [];
+
+      if (frame.neighborIdx < neighbors.length) {
+        const neighbor = neighbors[frame.neighborIdx];
+        frame.neighborIdx++;
+
+        if (!index.has(neighbor)) {
+          index.set(neighbor, counter);
+          lowlink.set(neighbor, counter);
+          counter++;
+          stack.push(neighbor);
+          onStack.add(neighbor);
+          callStack.push({ node: neighbor, neighborIdx: 0 });
+        } else if (onStack.has(neighbor)) {
+          const curLow = lowlink.get(node)!;
+          const neighborIdx = index.get(neighbor)!;
+          if (neighborIdx < curLow) {
+            lowlink.set(node, neighborIdx);
+          }
+        }
+      } else {
+        // Done with this node — pop and propagate lowlink to parent
+        callStack.pop();
+        if (callStack.length > 0) {
+          const parent = callStack[callStack.length - 1].node;
+          const parentLow = lowlink.get(parent)!;
+          const nodeLow = lowlink.get(node)!;
+          if (nodeLow < parentLow) {
+            lowlink.set(parent, nodeLow);
+          }
+        }
+
+        // If this is an SCC root, pop the stack
+        if (lowlink.get(node) === index.get(node)) {
+          const scc: string[] = [];
+          let w: string;
+          do {
+            w = stack.pop()!;
+            onStack.delete(w);
+            scc.push(w);
+          } while (w !== node);
+          sccs.push(scc);
+        }
+      }
+    }
+  }
+
+  return sccs;
+}
+
+/**
+ * Enumerate elementary cycles within a given SCC using DFS.
+ * Caps at maxCycles to avoid exponential blowup.
+ */
+function findCyclesInSCC(
+  scc: string[],
+  adjacency: Map<string, string[]>,
+  maxCycles: number
+): string[][] {
+  const sccSet = new Set(scc);
+  const cycles: string[][] = [];
+  const seen = new Set<string>();
+
+  for (const startNode of scc) {
+    if (cycles.length >= maxCycles) break;
+
+    const path: string[] = [startNode];
+    const onPath = new Set<string>([startNode]);
+
+    const dfs = (node: string): void => {
+      if (cycles.length >= maxCycles) return;
+      const neighbors = adjacency.get(node) ?? [];
+      for (const neighbor of neighbors) {
+        if (!sccSet.has(neighbor)) continue;
+        if (neighbor === startNode && path.length > 1) {
+          // Found a cycle — normalize via smallest-index-first rotation
+          const canonical = canonicalRotation([...path]);
+          const key = canonical.join('\0');
+          if (!seen.has(key)) {
+            seen.add(key);
+            cycles.push([...path, startNode]);
+          }
+        } else if (!onPath.has(neighbor)) {
+          path.push(neighbor);
+          onPath.add(neighbor);
+          dfs(neighbor);
+          path.pop();
+          onPath.delete(neighbor);
+        }
+      }
+    };
+
+    dfs(startNode);
+  }
+
+  return cycles;
+}
+
+function canonicalRotation(cycle: string[]): string[] {
+  // Find index of lexicographically smallest element
+  let minIdx = 0;
+  for (let i = 1; i < cycle.length; i++) {
+    if (cycle[i] < cycle[minIdx]) minIdx = i;
+  }
+  return [...cycle.slice(minIdx), ...cycle.slice(0, minIdx)];
+}
+
+export function detectCycles(db: MonographDb): CycleDetectionResult {
+  // Load all File nodes
+  const nodeRows = db.prepare(
+    `SELECT id, file_path, community_id FROM nodes WHERE label = 'File'`
+  ).all() as NodeRow[];
+
+  const nodeMap = new Map<string, NodeRow>();
+  for (const row of nodeRows) {
+    nodeMap.set(row.id, row);
+  }
+
+  // Load all IMPORTS and RE_EXPORTS edges between File nodes
+  const edgeRows = db.prepare(
+    `SELECT e.source_id, e.target_id, e.relation
+     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 EdgeRow[];
+
+  // Build adjacency list
+  const adjacency = new Map<string, string[]>();
+  const edgeRelationMap = new Map<string, string>(); // "src\0tgt" -> relation
+
+  for (const row of nodeRows) {
+    adjacency.set(row.id, []);
+  }
+
+  for (const edge of edgeRows) {
+    const neighbors = adjacency.get(edge.source_id);
+    if (neighbors) {
+      neighbors.push(edge.target_id);
+    }
+    edgeRelationMap.set(`${edge.source_id}\0${edge.target_id}`, edge.relation);
+  }
+
+  // Run Tarjan's SCC
+  const nodeIds = nodeRows.map(n => n.id);
+  const sccs = tarjanSCC(adjacency, nodeIds);
+
+  // Only SCCs with size > 1 are actual cycles
+  const cycleSCCs = sccs.filter(scc => scc.length > 1);
+
+  const cycles: DependencyCycle[] = [];
+  const filesInCyclesSet = new Set<string>();
+
+  for (const scc of cycleSCCs) {
+    const elementaryCycles = findCyclesInSCC(scc, adjacency, 20);
+    for (const cyclePath of elementaryCycles) {
+      // cyclePath is [...nodes, startNode] — last element = first
+      const cycleNodes = cyclePath.slice(0, -1);
+
+      for (const nodeId of cycleNodes) {
+        filesInCyclesSet.add(nodeId);
+      }
+
+      // Collect file paths
+      const files = cycleNodes.map(id => nodeMap.get(id)?.file_path ?? id);
+
+      // isCrossCommunity: any two nodes with different community_id
+      const communityIds = cycleNodes
+        .map(id => nodeMap.get(id)?.community_id)
+        .filter((c): c is number => c !== null && c !== undefined);
+      const uniqueCommunities = new Set(communityIds);
+      const isCrossCommunity = uniqueCommunities.size > 1;
+
+      // Collect edge relations used in this cycle
+      const edgeRelations: string[] = [];
+      for (let i = 0; i < cyclePath.length - 1; i++) {
+        const key = `${cyclePath[i]}\0${cyclePath[i + 1]}`;
+        const rel = edgeRelationMap.get(key);
+        if (rel && !edgeRelations.includes(rel)) {
+          edgeRelations.push(rel);
+        }
+      }
+
+      cycles.push({
+        files,
+        length: cycleNodes.length,
+        isCrossCommunity,
+        edgeRelations,
+      });
+    }
+  }
+
+  // Sort by length ascending
+  cycles.sort((a, b) => a.length - b.length);
+
+  const longestCycle = cycles.length > 0 ? cycles.reduce((a, c) => Math.max(a, c.length), 0) : 0;
+  const crossCommunityCycles = cycles.filter(c => c.isCrossCommunity).length;
+
+  return {
+    cycles,
+    totalCycles: cycles.length,
+    filesInCycles: filesInCyclesSet.size,
+    longestCycle,
+    crossCommunityCycles,
+  };
+}

package/src/analysis/dep-classification.ts

@@ -0,0 +1,133 @@
+import type { MonographDb } from '../storage/db.js';
+
+export interface PackageDepClassification {
+  packageName: string;
+  usedAsValue: boolean;       // has any non-type-only import
+  usedAsTypeOnly: boolean;    // has any type-only import
+  recommendation: 'keep-as-dep' | 'move-to-devdeps' | 'type-only' | 'unused';
+  importCount: number;
+  typeOnlyImportCount: number;
+}
+
+export interface DepClassificationResult {
+  packages: PackageDepClassification[];
+  typeOnlyCount: number;      // packages only used in type positions
+  mixedCount: number;         // packages used in both
+  valueOnlyCount: number;
+}
+
+interface EdgeRow {
+  relation: string;
+  confidence: string | null;
+  src: string;
+  tgt: string;
+  tgt_name: string;
+  properties: string | null;
+}
+
+function isExternalPackage(tgtName: string, tgtFilePath: string): boolean {
+  // External if the file_path doesn't start with '/' or '.'
+  // and doesn't look like a relative import
+  if (!tgtFilePath) {
+    // Fall back to name heuristic: starts with alpha, no path separators
+    return /^[a-zA-Z@]/.test(tgtName) && !tgtName.includes('/') || /^@[a-zA-Z]/.test(tgtName);
+  }
+  return !tgtFilePath.startsWith('/') && !tgtFilePath.startsWith('.');
+}
+
+function extractPackageName(tgt: string): string {
+  // Handle scoped packages like @scope/name
+  if (tgt.startsWith('@')) {
+    const parts = tgt.split('/');
+    return parts.slice(0, 2).join('/');
+  }
+  // Plain packages: take only the package name portion (before any '/')
+  return tgt.split('/')[0];
+}
+
+export function classifyDependencies(db: MonographDb): DepClassificationResult {
+  const rows = db.prepare(`
+    SELECT e.relation, e.confidence, n_src.file_path as src, n_tgt.file_path as tgt, n_tgt.name as tgt_name, e.properties
+    FROM edges e
+    JOIN nodes n_src ON n_src.id = e.source_id
+    JOIN nodes n_tgt ON n_tgt.id = e.target_id
+    WHERE e.relation = 'IMPORTS'
+  `).all() as EdgeRow[];
+
+  // Aggregate per external package
+  const packageMap = new Map<string, { valueImports: number; typeImports: number }>();
+
+  for (const row of rows) {
+    const tgtPath = row.tgt ?? '';
+    const tgtName = row.tgt_name ?? '';
+
+    if (!isExternalPackage(tgtName, tgtPath)) continue;
+
+    const packageName = extractPackageName(tgtName || tgtPath);
+    if (!packageName) continue;
+
+    // Check if type-only: parse properties JSON for isTypeOnly flag
+    let isTypeOnly = false;
+    if (row.properties) {
+      try {
+        const props = JSON.parse(row.properties) as Record<string, unknown>;
+        isTypeOnly = props['isTypeOnly'] === true;
+      } catch {
+        // fall through — infer from confidence
+      }
+    }
+    // Note: INFERRED confidence is NOT a reliable signal for type-only imports —
+    // re-export propagation and wildcard synthesis both emit INFERRED edges for real
+    // runtime imports. Only trust the explicit isTypeOnly property.
+
+    const existing = packageMap.get(packageName) ?? { valueImports: 0, typeImports: 0 };
+    if (isTypeOnly) {
+      existing.typeImports++;
+    } else {
+      existing.valueImports++;
+    }
+    packageMap.set(packageName, existing);
+  }
+
+  const packages: PackageDepClassification[] = [];
+
+  for (const [packageName, counts] of packageMap) {
+    const usedAsValue = counts.valueImports > 0;
+    const usedAsTypeOnly = counts.typeImports > 0;
+
+    let recommendation: PackageDepClassification['recommendation'];
+    if (usedAsValue && usedAsTypeOnly) {
+      recommendation = 'keep-as-dep';
+    } else if (usedAsValue && !usedAsTypeOnly) {
+      recommendation = 'keep-as-dep';
+    } else if (!usedAsValue && usedAsTypeOnly) {
+      recommendation = 'type-only';
+    } else {
+      recommendation = 'unused';
+    }
+
+    packages.push({
+      packageName,
+      usedAsValue,
+      usedAsTypeOnly,
+      recommendation,
+      importCount: counts.valueImports + counts.typeImports,
+      typeOnlyImportCount: counts.typeImports,
+    });
+  }
+
+  // Sort: 'type-only' first, then 'unused', then rest
+  const ORDER: Record<string, number> = { 'type-only': 0, 'unused': 1, 'move-to-devdeps': 2, 'keep-as-dep': 3 };
+  packages.sort((a, b) => (ORDER[a.recommendation] ?? 3) - (ORDER[b.recommendation] ?? 3));
+
+  const typeOnlyCount = packages.filter(p => p.recommendation === 'type-only').length;
+  const mixedCount = packages.filter(p => p.usedAsValue && p.usedAsTypeOnly).length;
+  const valueOnlyCount = packages.filter(p => p.usedAsValue && !p.usedAsTypeOnly).length;
+
+  return {
+    packages,
+    typeOnlyCount,
+    mixedCount,
+    valueOnlyCount,
+  };
+}