@monoes/monograph 1.0.0 → 1.2.0

package/src/reporting/graph-report.ts

@@ -0,0 +1,432 @@
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import type { MonographDb } from '../storage/db.js';
+import { openDb, closeDb } from '../storage/db.js';
+import { checkStaleness } from '../staleness/git-staleness.js';
+import type { SuggestedQuestion } from '../types.js';
+
+export interface GraphReportResult {
+  markdown: string;
+  path: string;
+  stats: {
+    nodeCount: number;
+    edgeCount: number;
+    communityCount: number;
+  };
+}
+
+interface NodeTypeStat {
+  label: string;
+  count: number;
+}
+
+interface EdgeRelationStat {
+  relation: string;
+  count: number;
+}
+
+interface TopDegreeNode {
+  id: string;
+  name: string;
+  label: string;
+  degree: number;
+}
+
+interface CommunityStat {
+  id: number;
+  label: string | null;
+  memberCount: number;
+}
+
+function queryNodesByType(db: MonographDb): NodeTypeStat[] {
+  const rows = db.prepare(`
+    SELECT label, COUNT(*) as count FROM nodes GROUP BY label ORDER BY count DESC
+  `).all() as { label: string; count: number }[];
+  return rows;
+}
+
+function queryEdgesByRelation(db: MonographDb): EdgeRelationStat[] {
+  const rows = db.prepare(`
+    SELECT relation, COUNT(*) as count FROM edges GROUP BY relation ORDER BY count DESC
+  `).all() as { relation: string; count: number }[];
+  return rows;
+}
+
+function queryTopNodesByDegree(db: MonographDb, limit = 10): TopDegreeNode[] {
+  const rows = db.prepare(`
+    SELECT
+      n.id,
+      n.name,
+      n.label,
+      (
+        SELECT COUNT(*) FROM edges WHERE source_id = n.id
+      ) + (
+        SELECT COUNT(*) FROM edges WHERE target_id = n.id
+      ) AS degree
+    FROM nodes n
+    ORDER BY degree DESC
+    LIMIT ?
+  `).all(limit) as TopDegreeNode[];
+  return rows;
+}
+
+function queryConfidenceBreakdown(db: MonographDb): { confidence: string; count: number }[] {
+  const rows = db.prepare(`
+    SELECT confidence, COUNT(*) as count FROM edges GROUP BY confidence ORDER BY count DESC
+  `).all() as { confidence: string; count: number }[];
+  return rows;
+}
+
+function buildKnowledgeGapSection(db: MonographDb): string {
+  // Isolated nodes: nodes with no edges (excluding File/Folder structural nodes)
+  const isolated = db.prepare(`
+    SELECT n.id, n.name, n.label FROM nodes n
+    WHERE n.label NOT IN ('File','Folder')
+    AND n.id NOT IN (SELECT source_id FROM edges)
+    AND n.id NOT IN (SELECT target_id FROM edges)
+    LIMIT 20
+  `).all() as { id: string; name: string; label: string }[];
+
+  // Thin communities: community_id groups with fewer than 3 members
+  const thin = db.prepare(`
+    SELECT community_id, COUNT(*) as cnt FROM nodes
+    WHERE community_id IS NOT NULL
+    GROUP BY community_id
+    HAVING cnt < 3
+    LIMIT 10
+  `).all() as { community_id: number; cnt: number }[];
+
+  if (isolated.length === 0 && thin.length === 0) return '';
+
+  const lines = ['## Knowledge Gaps\n'];
+
+  if (isolated.length > 0) {
+    lines.push(`### Isolated Nodes (${isolated.length})\n`);
+    lines.push('Nodes with no edges — may indicate dead code or missing imports:\n');
+    for (const n of isolated.slice(0, 10)) {
+      lines.push(`- **${n.label}** \`${n.name}\``);
+    }
+    lines.push('');
+  }
+
+  if (thin.length > 0) {
+    lines.push(`### Thin Communities (${thin.length})\n`);
+    lines.push('Communities with fewer than 3 members — may need merging:\n');
+    for (const t of thin) {
+      lines.push(`- Community ${t.community_id}: ${t.cnt} member${t.cnt === 1 ? '' : 's'}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function buildConfidenceAuditSection(db: MonographDb): string {
+  const rows = queryConfidenceBreakdown(db);
+  if (rows.length === 0) return '';
+  const total = rows.reduce((s, r) => s + r.count, 0);
+  const lines = ['## Confidence Audit\n'];
+  lines.push('| Confidence | Count | Percentage |');
+  lines.push('|-----------|-------|------------|');
+  for (const r of rows) {
+    const pct = total > 0 ? ((r.count / total) * 100).toFixed(1) : '0.0';
+    lines.push(`| ${r.confidence} | ${r.count} | ${pct}% |`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+function queryCommunities(db: MonographDb): CommunityStat[] {
+  // Get communities from nodes (community_id column)
+  const rows = db.prepare(`
+    SELECT community_id as id, COUNT(*) as memberCount
+    FROM nodes
+    WHERE community_id IS NOT NULL
+    GROUP BY community_id
+    ORDER BY memberCount DESC
+  `).all() as { id: number; memberCount: number }[];
+
+  // Try to get labels from communities table
+  const labelMap = new Map<number, string | null>();
+  try {
+    const labels = db.prepare(`SELECT id, label FROM communities`).all() as { id: number; label: string | null }[];
+    for (const l of labels) labelMap.set(l.id, l.label);
+  } catch {
+    // communities table may not have data
+  }
+
+  return rows.map(r => ({ id: r.id, label: labelMap.get(r.id) ?? null, memberCount: r.memberCount }));
+}
+
+function queryNodeCount(db: MonographDb): number {
+  const row = db.prepare('SELECT COUNT(*) as n FROM nodes').get() as { n: number };
+  return row.n;
+}
+
+function queryEdgeCount(db: MonographDb): number {
+  const row = db.prepare('SELECT COUNT(*) as n FROM edges').get() as { n: number };
+  return row.n;
+}
+
+function buildMarkdown(
+  nodeCount: number,
+  edgeCount: number,
+  nodesByType: NodeTypeStat[],
+  edgesByRelation: EdgeRelationStat[],
+  topNodes: TopDegreeNode[],
+  communities: CommunityStat[],
+  staleFiles: string[],
+  confidenceSection = '',
+): string {
+  const timestamp = new Date().toISOString();
+  const lines: string[] = [];
+
+  lines.push(`# Graph Report`);
+  lines.push('');
+  lines.push(`_Generated: ${timestamp}_`);
+  lines.push('');
+
+  // Summary
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`| Metric | Value |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| Total nodes | ${nodeCount} |`);
+  lines.push(`| Total edges | ${edgeCount} |`);
+  lines.push(`| Communities | ${communities.length} |`);
+  lines.push('');
+
+  // Nodes by type
+  lines.push('## Nodes by Type');
+  lines.push('');
+  if (nodesByType.length > 0) {
+    lines.push('| Label | Count |');
+    lines.push('|-------|-------|');
+    for (const { label, count } of nodesByType) {
+      lines.push(`| ${label} | ${count} |`);
+    }
+  } else {
+    lines.push('_No nodes found._');
+  }
+  lines.push('');
+
+  // Edges by relation
+  lines.push('## Edges by Relation');
+  lines.push('');
+  if (edgesByRelation.length > 0) {
+    lines.push('| Relation | Count |');
+    lines.push('|----------|-------|');
+    for (const { relation, count } of edgesByRelation) {
+      lines.push(`| ${relation} | ${count} |`);
+    }
+  } else {
+    lines.push('_No edges found._');
+  }
+  lines.push('');
+
+  // Top 10 nodes by degree
+  lines.push('## Top Nodes by Degree');
+  lines.push('');
+  if (topNodes.length > 0) {
+    lines.push('| Rank | Name | Type | Degree |');
+    lines.push('|------|------|------|--------|');
+    topNodes.forEach((node, idx) => {
+      lines.push(`| ${idx + 1} | \`${node.name}\` | ${node.label} | ${node.degree} |`);
+    });
+  } else {
+    lines.push('_No nodes found._');
+  }
+  lines.push('');
+
+  // Communities
+  lines.push('## Communities');
+  lines.push('');
+  if (communities.length > 0) {
+    for (const c of communities) {
+      const name = c.label ?? `Community ${c.id}`;
+      lines.push(`- **${name}** (id: ${c.id}) — ${c.memberCount} members`);
+    }
+  } else {
+    lines.push('_No communities detected._');
+  }
+  lines.push('');
+
+  // Stale files
+  lines.push('## Stale Files');
+  lines.push('');
+  if (staleFiles.length > 0) {
+    for (const f of staleFiles) {
+      lines.push(`- \`${f}\``);
+    }
+  } else {
+    lines.push('_No stale files detected._');
+  }
+  lines.push('');
+
+  if (confidenceSection) {
+    lines.push(confidenceSection);
+  }
+
+  return lines.join('\n');
+}
+
+export function buildMarkdownWithQuestions(
+  nodeCount: number,
+  edgeCount: number,
+  nodesByType: NodeTypeStat[],
+  edgesByRelation: EdgeRelationStat[],
+  topNodes: TopDegreeNode[],
+  communities: CommunityStat[],
+  staleFiles: string[],
+  questions: SuggestedQuestion[],
+  confidenceSection = '',
+): string {
+  let md = buildMarkdown(nodeCount, edgeCount, nodesByType, edgesByRelation, topNodes, communities, staleFiles, confidenceSection);
+
+  if (questions.length === 0) return md;
+
+  const capped = questions.slice(0, 20);
+  const lines: string[] = ['## Suggested Questions', ''];
+  for (const q of capped) {
+    if (q.type === 'bridge_node') {
+      lines.push(`- **bridge_node**: \`${q.node.name}\` bridges community ${q.commA} and ${q.commB}`);
+    } else if (q.type === 'ambiguous_edge') {
+      lines.push(`- **ambiguous_edge**: \`${q.edge.sourceId}\` → \`${q.edge.targetId}\` — ${q.reason}`);
+    } else if (q.type === 'verify_inferred') {
+      lines.push(`- **verify_inferred**: \`${q.edge.sourceId}\` → \`${q.edge.targetId}\` (inferred from ${q.inferredFrom})`);
+    } else if (q.type === 'isolated_nodes') {
+      const names = q.nodes.map(n => `\`${n.name}\``).join(', ');
+      lines.push(`- **isolated_nodes**: ${names} — ${q.reason}`);
+    } else if (q.type === 'low_cohesion') {
+      lines.push(`- **low_cohesion**: community ${q.community.id} (cohesion: ${q.community.cohesionScore.toFixed(2)})`);
+    }
+  }
+  lines.push('');
+  md = md + '\n' + lines.join('\n');
+  return md;
+}
+
+/**
+ * Generates a graph report synchronously from an existing DB instance.
+ * Writes the markdown to outputPath/GRAPH_REPORT.md and returns the result.
+ */
+export function generateGraphReportFromDb(
+  db: MonographDb,
+  outputPath: string,
+): GraphReportResult {
+  const resolvedOutputPath = join(outputPath, 'GRAPH_REPORT.md');
+  const nodeCount = queryNodeCount(db);
+  const edgeCount = queryEdgeCount(db);
+  const nodesByType = queryNodesByType(db);
+  const edgesByRelation = queryEdgesByRelation(db);
+  const topNodes = queryTopNodesByDegree(db, 10);
+  const communities = queryCommunities(db);
+  const confidenceSection = buildConfidenceAuditSection(db);
+
+  const gapSection = buildKnowledgeGapSection(db);
+  const markdown = buildMarkdownWithQuestions(
+    nodeCount,
+    edgeCount,
+    nodesByType,
+    edgesByRelation,
+    topNodes,
+    communities,
+    [],
+    [],
+    confidenceSection,
+  ) + (gapSection ? '\n' + gapSection : '');
+
+  writeFileSync(resolvedOutputPath, markdown, 'utf8');
+
+  return {
+    markdown,
+    path: resolvedOutputPath,
+    stats: {
+      nodeCount,
+      edgeCount,
+      communityCount: communities.length,
+    },
+  };
+}
+
+/**
+ * Generates a GRAPH_REPORT.md summarizing the knowledge graph.
+ *
+ * Overload 1: accepts an existing DB instance and output directory (synchronous).
+ * Overload 2: accepts a repo path string and optional params (async, opens its own DB).
+ */
+export function generateGraphReport(db: MonographDb, outputPath: string): GraphReportResult;
+export function generateGraphReport(
+  repoPath: string,
+  outputPath?: string,
+  dbPath?: string,
+  questions?: SuggestedQuestion[],
+): Promise<GraphReportResult>;
+export function generateGraphReport(
+  dbOrRepoPath: MonographDb | string,
+  outputPath?: string,
+  dbPath?: string,
+  questions: SuggestedQuestion[] = [],
+): GraphReportResult | Promise<GraphReportResult> {
+  // Sync overload: first arg is a DB instance
+  if (typeof dbOrRepoPath !== 'string') {
+    const db = dbOrRepoPath;
+    return generateGraphReportFromDb(db, outputPath ?? '/tmp');
+  }
+
+  // Async overload: first arg is a repo path string
+  const repoPath = dbOrRepoPath;
+  const resolvedDbPath = dbPath ?? join(repoPath, '.monograph', 'graph.db');
+  const resolvedOutputPath = outputPath ?? join(repoPath, 'GRAPH_REPORT.md');
+
+  return (async () => {
+    const db = openDb(resolvedDbPath);
+    try {
+      const nodeCount = queryNodeCount(db);
+      const edgeCount = queryEdgeCount(db);
+      const nodesByType = queryNodesByType(db);
+      const edgesByRelation = queryEdgesByRelation(db);
+      const topNodes = queryTopNodesByDegree(db, 10);
+      const communities = queryCommunities(db);
+
+      // Stale files from git-staleness
+      let staleFiles: string[] = [];
+      try {
+        const stalenessReport = checkStaleness(db, repoPath);
+        if (stalenessReport.isStale && stalenessReport.changedSince.length > 0) {
+          staleFiles = stalenessReport.changedSince;
+        }
+      } catch {
+        // Staleness check is best-effort
+      }
+
+      const confidenceSection = buildConfidenceAuditSection(db);
+      const gapSection = buildKnowledgeGapSection(db);
+      const markdown = buildMarkdownWithQuestions(
+        nodeCount,
+        edgeCount,
+        nodesByType,
+        edgesByRelation,
+        topNodes,
+        communities,
+        staleFiles,
+        questions,
+        confidenceSection,
+      ) + (gapSection ? '\n' + gapSection : '');
+
+      writeFileSync(resolvedOutputPath, markdown, 'utf8');
+
+      return {
+        markdown,
+        path: resolvedOutputPath,
+        stats: {
+          nodeCount,
+          edgeCount,
+          communityCount: communities.length,
+        },
+      };
+    } finally {
+      closeDb(db);
+    }
+  })();
+}

package/src/results/fallow-results.ts

@@ -0,0 +1,152 @@
+import type { FallowIssueKind } from '../analysis/fallow-suppression.js';
+import type { EntryPointSource } from '../discover/entry-points.js';
+
+export type FallowDependencyLocation = 'dependencies' | 'devDependencies' | 'optionalDependencies' | 'peerDependencies';
+export type FallowMemberKind = 'method' | 'property' | 'getter' | 'setter' | 'constructor' | 'enum-member';
+export type FallowFlagKind = 'environment' | 'feature-flag' | 'experiment' | 'rollout';
+export type FallowFlagConfidence = 'low' | 'medium' | 'high';
+
+export interface FallowUnusedFile { filePath: string; line: number; col: number; }
+export interface FallowUnusedExport { filePath: string; line: number; col: number; exportName: string; spanStart: number; isReExport: boolean; isTypeOnly: boolean; }
+export interface FallowPrivateTypeLeak { filePath: string; line: number; col: number; exportName: string; privateType: string; }
+export interface FallowUnusedDependency { name: string; location: FallowDependencyLocation; usedInWorkspaces: string[]; }
+export interface FallowUnusedMember { filePath: string; line: number; col: number; memberName: string; parentName: string; kind: FallowMemberKind; }
+export interface FallowUnresolvedImport { filePath: string; line: number; col: number; specifier: string; specifierCol: number; }
+export interface FallowImportSite { filePath: string; line: number; col: number; }
+export interface FallowUnlistedDependency { name: string; importedFrom: FallowImportSite[]; }
+export interface FallowDuplicateLocation { filePath: string; line: number; col: number; exportName: string; }
+export interface FallowDuplicateExport { exportName: string; locations: FallowDuplicateLocation[]; }
+export interface FallowTypeOnlyDependency { name: string; location: FallowDependencyLocation; }
+export interface FallowTestOnlyDependency { name: string; location: FallowDependencyLocation; }
+export interface FallowCircularDependency { cycle: string[]; line: number; col: number; isCrossPackage: boolean; }
+export interface FallowBoundaryViolation { fromPath: string; toPath: string; fromZone: string; toZone: string; importSpecifier: string; line: number; col: number; }
+export type FallowSuppressionOrigin = { kind: 'inline'; line: number } | { kind: 'jsdoc'; line: number } | { kind: 'file-wide' };
+export interface FallowStaleSuppression { filePath: string; commentLine: number; issueKind: FallowIssueKind | null; origin: FallowSuppressionOrigin; }
+export interface FallowFeatureFlag { filePath: string; line: number; col: number; flagName: string; kind: FallowFlagKind; confidence: FallowFlagConfidence; value: string | boolean | null; condition: string | null; branchTrue: string | null; branchFalse: string | null; isNegated: boolean; isDynamic: boolean; isMultiVariant: boolean; }
+export interface FallowEntryPointSummary { path: string; source: EntryPointSource; }
+export interface FallowExportUsage { exportName: string; usageCount: number; }
+export interface FallowReferenceLocation { filePath: string; line: number; col: number; }
+
+export interface FallowAnalysisResults {
+  unusedFiles: FallowUnusedFile[];
+  unusedExports: FallowUnusedExport[];
+  unusedTypes: FallowUnusedExport[];
+  privateTypeLeaks: FallowPrivateTypeLeak[];
+  unusedDependencies: FallowUnusedDependency[];
+  unusedDevDependencies: FallowUnusedDependency[];
+  unusedEnumMembers: FallowUnusedMember[];
+  unusedClassMembers: FallowUnusedMember[];
+  unresolvedImports: FallowUnresolvedImport[];
+  unlistedDependencies: FallowUnlistedDependency[];
+  duplicateExports: FallowDuplicateExport[];
+  typeOnlyDependencies: FallowTypeOnlyDependency[];
+  testOnlyDependencies: FallowTestOnlyDependency[];
+  circularDependencies: FallowCircularDependency[];
+  boundaryViolations: FallowBoundaryViolation[];
+  staleSuppressions: FallowStaleSuppression[];
+  featureFlags: FallowFeatureFlag[];
+}
+
+export function makeEmptyFallowResults(): FallowAnalysisResults {
+  return {
+    unusedFiles: [],
+    unusedExports: [],
+    unusedTypes: [],
+    privateTypeLeaks: [],
+    unusedDependencies: [],
+    unusedDevDependencies: [],
+    unusedEnumMembers: [],
+    unusedClassMembers: [],
+    unresolvedImports: [],
+    unlistedDependencies: [],
+    duplicateExports: [],
+    typeOnlyDependencies: [],
+    testOnlyDependencies: [],
+    circularDependencies: [],
+    boundaryViolations: [],
+    staleSuppressions: [],
+    featureFlags: [],
+  };
+}
+
+export function totalFallowIssues(results: FallowAnalysisResults): number {
+  return (
+    results.unusedFiles.length +
+    results.unusedExports.length +
+    results.unusedTypes.length +
+    results.privateTypeLeaks.length +
+    results.unusedDependencies.length +
+    results.unusedDevDependencies.length +
+    results.unusedEnumMembers.length +
+    results.unusedClassMembers.length +
+    results.unresolvedImports.length +
+    results.unlistedDependencies.length +
+    results.duplicateExports.length +
+    results.typeOnlyDependencies.length +
+    results.testOnlyDependencies.length +
+    results.circularDependencies.length +
+    results.boundaryViolations.length +
+    results.staleSuppressions.length +
+    results.featureFlags.length
+  );
+}
+
+export function hasFallowIssues(results: FallowAnalysisResults): boolean {
+  return totalFallowIssues(results) > 0;
+}
+
+function cmpFileLineCol(
+  a: { filePath: string; line: number; col: number },
+  b: { filePath: string; line: number; col: number },
+): number {
+  if (a.filePath < b.filePath) return -1;
+  if (a.filePath > b.filePath) return 1;
+  if (a.line !== b.line) return a.line - b.line;
+  return a.col - b.col;
+}
+
+export function sortFallowResults(results: FallowAnalysisResults): void {
+  results.unusedFiles.sort(cmpFileLineCol);
+  results.unusedExports.sort(cmpFileLineCol);
+  results.unusedTypes.sort(cmpFileLineCol);
+  results.privateTypeLeaks.sort(cmpFileLineCol);
+  results.unusedEnumMembers.sort(cmpFileLineCol);
+  results.unusedClassMembers.sort(cmpFileLineCol);
+  results.unresolvedImports.sort(cmpFileLineCol);
+
+  results.unusedDependencies.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  results.unusedDevDependencies.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  results.typeOnlyDependencies.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  results.testOnlyDependencies.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+  results.unlistedDependencies.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+  results.duplicateExports.sort((a, b) => (a.exportName < b.exportName ? -1 : a.exportName > b.exportName ? 1 : 0));
+
+  results.circularDependencies.sort((a, b) => {
+    const ac = a.cycle[0] ?? '';
+    const bc = b.cycle[0] ?? '';
+    if (ac < bc) return -1;
+    if (ac > bc) return 1;
+    return a.line - b.line;
+  });
+
+  results.boundaryViolations.sort((a, b) => {
+    if (a.fromPath < b.fromPath) return -1;
+    if (a.fromPath > b.fromPath) return 1;
+    return a.line - b.line;
+  });
+
+  results.staleSuppressions.sort((a, b) => {
+    if (a.filePath < b.filePath) return -1;
+    if (a.filePath > b.filePath) return 1;
+    return a.commentLine - b.commentLine;
+  });
+
+  results.featureFlags.sort((a, b) => {
+    if (a.filePath < b.filePath) return -1;
+    if (a.filePath > b.filePath) return 1;
+    if (a.line !== b.line) return a.line - b.line;
+    return a.flagName < b.flagName ? -1 : a.flagName > b.flagName ? 1 : 0;
+  });
+}