@monoes/monograph 1.5.6 → 1.5.7

package/src/graph/author-analytics.ts

@@ -1,217 +0,0 @@
-import { execSync, spawnSync } from 'child_process';
-import type { MonographDb } from '../storage/db.js';
-
-export type ChurnTrend = 'accelerating' | 'stable' | 'declining';
-
-export interface AuthorStats {
-  author: string;
-  commitCount: number;
-  filesOwned: number;       // files where this author has majority of commits
-  recentCommits: number;    // commits in last 30 days
-  churnTrend: ChurnTrend;
-  isBot: boolean;
-}
-
-export interface AuthorAnalyticsReport {
-  authors: AuthorStats[];
-  topOwners: AuthorStats[];   // top 5 by filesOwned
-  botAuthors: string[];
-  unownedFiles: number;       // files with no majority owner
-}
-
-const BOT_PATTERNS = ['[bot]', 'noreply', 'github-actions', 'dependabot', 'renovate'];
-
-function isBot(email: string): boolean {
-  const lower = email.toLowerCase();
-  return BOT_PATTERNS.some(p => lower.includes(p));
-}
-
-const EMPTY_REPORT: AuthorAnalyticsReport = {
-  authors: [],
-  topOwners: [],
-  botAuthors: [],
-  unownedFiles: 0,
-};
-
-export function computeAuthorAnalytics(repoPath: string, db: MonographDb): AuthorAnalyticsReport {
-  // ── Parse git log ──────────────────────────────────────────────────────────
-  let logOutput: string;
-  try {
-    logOutput = execSync('git log --format="%ae|%ad" --date=unix', {
-      cwd: repoPath,
-      encoding: 'utf-8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-  } catch {
-    return EMPTY_REPORT;
-  }
-
-  const now = Math.floor(Date.now() / 1000);
-  const thirtyDaysAgo = now - 86400 * 30;
-  const sixtyDaysAgo = now - 86400 * 60;
-
-  // commitCount, recentCommits, priorCommits per author
-  const commitCount = new Map<string, number>();
-  const recentCommits = new Map<string, number>();
-  const priorCommits = new Map<string, number>();
-
-  for (const line of logOutput.split('\n')) {
-    const trimmed = line.trim().replace(/^"|"$/g, '');
-    if (!trimmed) continue;
-    const pipeIdx = trimmed.indexOf('|');
-    if (pipeIdx === -1) continue;
-    const email = trimmed.slice(0, pipeIdx).trim();
-    const tsStr = trimmed.slice(pipeIdx + 1).trim();
-    const ts = parseInt(tsStr, 10);
-    if (!email || isNaN(ts)) continue;
-
-    commitCount.set(email, (commitCount.get(email) ?? 0) + 1);
-    if (ts > thirtyDaysAgo) {
-      recentCommits.set(email, (recentCommits.get(email) ?? 0) + 1);
-    } else if (ts > sixtyDaysAgo) {
-      priorCommits.set(email, (priorCommits.get(email) ?? 0) + 1);
-    }
-  }
-
-  if (commitCount.size === 0) return EMPTY_REPORT;
-
-  // ── File ownership ─────────────────────────────────────────────────────────
-  // Get File nodes with degree > 2 — use JOIN+GROUP BY instead of correlated subquery
-  const fileRows = db.prepare(`
-    SELECT n.id, n.name, n.file_path
-    FROM nodes n
-    JOIN (
-      SELECT id, COUNT(*) AS deg
-      FROM (
-        SELECT source_id AS id FROM edges
-        UNION ALL
-        SELECT target_id AS id FROM edges
-      )
-      GROUP BY id
-      HAVING COUNT(*) > 2
-    ) deg_tbl ON deg_tbl.id = n.id
-    WHERE n.label = 'File'
-      AND n.file_path IS NOT NULL
-    LIMIT 200
-  `).all() as { id: string; name: string; file_path: string }[];
-
-  // Map: file path → winning author email (majority owner) or null
-  const fileOwner = new Map<string, string | null>();
-  const filesOwnedByAuthor = new Map<string, number>();
-
-  for (const file of fileRows) {
-    const filePath = file.file_path;
-    if (!filePath) { fileOwner.set(file.id, null); continue; }
-
-    let fileLog: string;
-    try {
-      const result = spawnSync('git', ['log', '--follow', '--format=%ae', '--', filePath], {
-        cwd: repoPath,
-        encoding: 'utf-8',
-      });
-      if (result.status !== 0 || result.error) {
-        fileOwner.set(file.id, null);
-        continue;
-      }
-      fileLog = result.stdout;
-    } catch {
-      fileOwner.set(file.id, null);
-      continue;
-    }
-
-    const authorCounts = new Map<string, number>();
-    for (const ae of fileLog.split('\n')) {
-      const e = ae.trim().replace(/^"|"$/g, '');
-      if (!e) continue;
-      authorCounts.set(e, (authorCounts.get(e) ?? 0) + 1);
-    }
-
-    let totalCommitsOnFile = 0;
-    for (const c of authorCounts.values()) totalCommitsOnFile += c;
-
-    let winner: string | null = null;
-    for (const [ae, c] of authorCounts) {
-      if (totalCommitsOnFile > 0 && c / totalCommitsOnFile > 0.5) {
-        winner = ae;
-        break;
-      }
-    }
-    fileOwner.set(file.id, winner);
-    if (winner) {
-      filesOwnedByAuthor.set(winner, (filesOwnedByAuthor.get(winner) ?? 0) + 1);
-    }
-  }
-
-  // ── Count unowned files ────────────────────────────────────────────────────
-  let unownedFiles = 0;
-  for (const owner of fileOwner.values()) {
-    if (owner === null) unownedFiles++;
-  }
-
-  // ── Build author stats ─────────────────────────────────────────────────────
-  const authors: AuthorStats[] = [];
-  const botAuthors: string[] = [];
-
-  for (const [email, count] of commitCount) {
-    const recent = recentCommits.get(email) ?? 0;
-    const prior = priorCommits.get(email) ?? 0;
-
-    let churnTrend: ChurnTrend;
-    if (recent > prior * 1.2) churnTrend = 'accelerating';
-    else if (recent < prior * 0.8) churnTrend = 'declining';
-    else churnTrend = 'stable';
-
-    const bot = isBot(email);
-    if (bot) botAuthors.push(email);
-
-    authors.push({
-      author: email,
-      commitCount: count,
-      filesOwned: filesOwnedByAuthor.get(email) ?? 0,
-      recentCommits: recent,
-      churnTrend,
-      isBot: bot,
-    });
-  }
-
-  // Sort by filesOwned desc, then commitCount desc
-  authors.sort((a, b) => b.filesOwned - a.filesOwned || b.commitCount - a.commitCount);
-
-  const topOwners = authors.filter(a => !a.isBot).slice(0, 5);
-
-  return { authors, topOwners, botAuthors, unownedFiles };
-}
-
-/** Format AuthorAnalyticsReport as structured text for LLM navigation. */
-export function formatAuthorAnalytics(report: AuthorAnalyticsReport): string {
-  if (report.authors.length === 0) {
-    return 'Author analytics: no commit history found.';
-  }
-
-  const lines: string[] = [
-    `Author analytics: ${report.authors.length} contributor(s), ${report.unownedFiles} unowned file(s).`,
-    '',
-  ];
-
-  if (report.topOwners.length > 0) {
-    lines.push('Top file owners (non-bot):');
-    for (const a of report.topOwners) {
-      const trend = a.churnTrend === 'accelerating' ? ' [↑ accelerating]'
-        : a.churnTrend === 'declining' ? ' [↓ declining]' : '';
-      lines.push(`  ${a.author}  files:${a.filesOwned}  commits:${a.commitCount}  recent30d:${a.recentCommits}${trend}`);
-    }
-    lines.push('');
-  }
-
-  if (report.botAuthors.length > 0) {
-    lines.push(`Bot/automation authors (${report.botAuthors.length}): ${report.botAuthors.join(', ')}`);
-    lines.push('');
-  }
-
-  if (report.unownedFiles > 0) {
-    lines.push(`Unowned files: ${report.unownedFiles} file(s) have no majority author (> 50% commits).`);
-    lines.push('Consider adding CODEOWNERS entries for these files.');
-  }
-
-  return lines.join('\n').trimEnd();
-}

package/src/graph/baseline.ts

@@ -1,432 +0,0 @@
-import type Database from 'better-sqlite3';
-import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { join } from 'path';
-import { createHash } from 'crypto';
-
-function fingerprintFinding(type: string, ...parts: string[]): string {
-  return createHash('sha256').update([type, ...parts].join('::')).digest('hex').slice(0, 16);
-}
-
-export interface BaselineFinding {
-  /** Stable identifier: e.g. "file:src/foo.ts:export:bar" or "community:12:orphan" */
-  key: string;
-  type: 'unreachable_export' | 'isolated_node' | 'ambiguous_edge' | 'bridge_node' | 'surprise' | 'god_node' | 'other';
-  nodeId: string;
-  nodeName: string;
-  filePath: string | null;
-  startLine: number | null;
-  savedAt: string; // ISO timestamp
-  /** 16-hex SHA-256 fingerprint for stable deduplication across runs */
-  fingerprint?: string;
-}
-
-export interface BaselineData {
-  version: 1;
-  savedAt: string;
-  projectPath: string;
-  findings: BaselineFinding[];
-}
-
-export interface ComparedFinding extends BaselineFinding {
-  introduced: boolean; // true = new in this run, not in baseline
-}
-
-/**
- * Save the current set of findings as a baseline JSON file.
- * @param baselinePath - path to write (e.g. .monomind/baseline.json)
- * @param findings - current findings to persist
- * @param projectPath - repo path for identification
- */
-export function saveBaseline(
-  baselinePath: string,
-  findings: BaselineFinding[],
-  projectPath: string,
-): void {
-  const data: BaselineData = {
-    version: 1,
-    savedAt: new Date().toISOString(),
-    projectPath,
-    findings,
-  };
-  writeFileSync(baselinePath, JSON.stringify(data, null, 2), 'utf-8');
-}
-
-/**
- * Load an existing baseline file.
- */
-export function loadBaseline(baselinePath: string): BaselineData | null {
-  if (!existsSync(baselinePath)) return null;
-  try {
-    return JSON.parse(readFileSync(baselinePath, 'utf-8')) as BaselineData;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Compare a list of current findings against a baseline.
- * Returns each finding annotated with introduced:true/false.
- */
-export function compareWithBaseline(
-  currentFindings: BaselineFinding[],
-  baseline: BaselineData | null,
-): ComparedFinding[] {
-  if (!baseline) {
-    // No baseline — all findings are "introduced"
-    return currentFindings.map(f => ({ ...f, introduced: true }));
-  }
-  // Primary: match by fingerprint (for baselines that have it)
-  const baselineFingerprints = new Set(
-    baseline.findings
-      .filter(f => f.fingerprint)
-      .map(f => f.fingerprint as string),
-  );
-  // Fallback: match by key (for old baselines without fingerprint)
-  const baselineKeys = new Set(baseline.findings.map(f => f.key));
-  return currentFindings.map(f => {
-    if (f.fingerprint && baselineFingerprints.size > 0) {
-      return { ...f, introduced: !baselineFingerprints.has(f.fingerprint) };
-    }
-    return { ...f, introduced: !baselineKeys.has(f.key) };
-  });
-}
-
-/**
- * Extract findings from the database to build a baseline.
- * Collects: isolated nodes (no edges), nodes with only INFERRED edges,
- * god nodes (degree > 50).
- */
-export function extractFindingsFromDb(
-  db: Database.Database,
-  projectPath: string,
-): BaselineFinding[] {
-  const findings: BaselineFinding[] = [];
-
-  // Isolated nodes (no incoming or outgoing edges)
-  const isolated = db.prepare(`
-    SELECT n.id, n.name, n.file_path, n.start_line, n.label
-    FROM nodes n
-    WHERE NOT EXISTS (SELECT 1 FROM edges e WHERE e.source_id = n.id OR e.target_id = n.id)
-    AND n.label IN ('Function', 'Class', 'Method', 'Interface', 'Variable', 'Module', 'File')
-    LIMIT 500
-  `).all() as { id: string; name: string; file_path: string | null; start_line: number | null; label: string }[];
-
-  for (const n of isolated) {
-    findings.push({
-      key: `isolated:${n.file_path ?? n.id}:${n.name}`,
-      type: 'isolated_node',
-      nodeId: n.id,
-      nodeName: n.name,
-      filePath: n.file_path,
-      startLine: n.start_line ?? null,
-      savedAt: new Date().toISOString(),
-      fingerprint: fingerprintFinding('isolated_node', n.file_path ?? '', n.id),
-    });
-  }
-
-  // God nodes (degree > 50)
-  const gods = db.prepare(`
-    SELECT n.id, n.name, n.file_path, n.start_line, d.deg as degree
-    FROM nodes n
-    JOIN (
-      SELECT node_id, SUM(cnt) AS deg FROM (
-        SELECT source_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY source_id
-        UNION ALL
-        SELECT target_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY target_id
-      ) GROUP BY node_id
-      HAVING deg > 50
-      ORDER BY deg DESC
-      LIMIT 100
-    ) d ON d.node_id = n.id
-    ORDER BY d.deg DESC
-  `).all() as { id: string; name: string; file_path: string | null; start_line: number | null; degree: number }[];
-
-  for (const n of gods) {
-    findings.push({
-      key: `god_node:${n.file_path ?? n.id}:${n.name}`,
-      type: 'god_node',
-      nodeId: n.id,
-      nodeName: n.name,
-      filePath: n.file_path,
-      startLine: n.start_line ?? null,
-      savedAt: new Date().toISOString(),
-      fingerprint: fingerprintFinding('god_node', n.file_path ?? '', n.id),
-    });
-  }
-
-  // Surprise edges: non-EXTRACTED confidence (cross-community low-confidence edges)
-  const surprises = db.prepare(`
-    SELECT DISTINCT e.id as edge_id, e.source_id, e.target_id, e.confidence,
-           n.name as src_name, n.file_path as src_file, n.start_line as src_line
-    FROM edges e
-    JOIN nodes n ON n.id = e.source_id
-    WHERE e.confidence != 'EXTRACTED'
-    LIMIT 200
-  `).all() as { edge_id: string; source_id: string; target_id: string; confidence: string; src_name: string; src_file: string | null; src_line: number | null }[];
-
-  for (const e of surprises) {
-    findings.push({
-      key: `surprise:${e.source_id}:${e.target_id}`,
-      type: 'surprise',
-      nodeId: e.source_id,
-      nodeName: e.src_name,
-      filePath: e.src_file,
-      startLine: e.src_line ?? null,
-      savedAt: new Date().toISOString(),
-      fingerprint: fingerprintFinding('surprise', e.source_id, e.target_id),
-    });
-  }
-
-  // Bridge nodes: nodes whose edges span 2+ distinct foreign communities.
-  // Pre-aggregate cross-community counts per direction to avoid 4-way cross product.
-  const bridges = db.prepare(`
-    SELECT n.id, n.name, n.file_path, n.start_line
-    FROM nodes n
-    JOIN (
-      SELECT node_id, COUNT(DISTINCT foreign_community) AS cross_cnt FROM (
-        SELECT e.source_id AS node_id, n2.community_id AS foreign_community
-        FROM edges e
-        JOIN nodes n1 ON n1.id = e.source_id AND n1.community_id IS NOT NULL
-        JOIN nodes n2 ON n2.id = e.target_id AND n2.community_id IS NOT NULL AND n2.community_id != n1.community_id
-        UNION ALL
-        SELECT e.target_id AS node_id, n1.community_id AS foreign_community
-        FROM edges e
-        JOIN nodes n1 ON n1.id = e.source_id AND n1.community_id IS NOT NULL
-        JOIN nodes n2 ON n2.id = e.target_id AND n2.community_id IS NOT NULL AND n1.community_id != n2.community_id
-      ) GROUP BY node_id
-      HAVING cross_cnt >= 2
-    ) b ON b.node_id = n.id
-    LIMIT 100
-  `).all() as { id: string; name: string; file_path: string | null; start_line: number | null }[];
-
-  for (const n of bridges) {
-    findings.push({
-      key: `bridge_node:${n.file_path ?? n.id}:${n.name}`,
-      type: 'bridge_node',
-      nodeId: n.id,
-      nodeName: n.name,
-      filePath: n.file_path,
-      startLine: n.start_line ?? null,
-      savedAt: new Date().toISOString(),
-      fingerprint: fingerprintFinding('bridge_node', n.file_path ?? '', n.id),
-    });
-  }
-
-  // Unreachable exports: exported nodes with no incoming edges
-  const unreachableExports = db.prepare(`
-    SELECT n.id, n.name, n.file_path, n.start_line
-    FROM nodes n
-    WHERE n.is_exported = 1
-    AND n.label IN ('Function', 'Class', 'Method', 'Interface', 'Variable')
-    AND NOT EXISTS (SELECT 1 FROM edges e WHERE e.target_id = n.id)
-    LIMIT 300
-  `).all() as { id: string; name: string; file_path: string | null; start_line: number | null }[];
-
-  for (const n of unreachableExports) {
-    findings.push({
-      key: `unreachable_export:${n.file_path ?? n.id}:${n.name}`,
-      type: 'unreachable_export',
-      nodeId: n.id,
-      nodeName: n.name,
-      filePath: n.file_path,
-      startLine: n.start_line ?? null,
-      savedAt: new Date().toISOString(),
-      fingerprint: fingerprintFinding('unreachable_export', n.file_path ?? '', n.id),
-    });
-  }
-
-  // Ambiguous edges: edges with AMBIGUOUS confidence
-  const ambiguousEdges = db.prepare(`
-    SELECT DISTINCT e.id as edge_id, e.source_id, e.target_id,
-           n.name as src_name, n.file_path as src_file, n.start_line as src_line
-    FROM edges e
-    JOIN nodes n ON n.id = e.source_id
-    WHERE e.confidence = 'AMBIGUOUS'
-    LIMIT 200
-  `).all() as { edge_id: string; source_id: string; target_id: string; src_name: string; src_file: string | null; src_line: number | null }[];
-
-  for (const e of ambiguousEdges) {
-    findings.push({
-      key: `ambiguous_edge:${e.source_id}:${e.target_id}`,
-      type: 'ambiguous_edge',
-      nodeId: e.source_id,
-      nodeName: e.src_name,
-      filePath: e.src_file,
-      startLine: e.src_line ?? null,
-      savedAt: new Date().toISOString(),
-      fingerprint: fingerprintFinding('ambiguous_edge', e.source_id, e.target_id),
-    });
-  }
-
-  return findings;
-}
-
-/**
- * Default baseline path relative to a project directory.
- * If a name is provided, the file is saved as `baseline-{name}.json`.
- */
-export function defaultBaselinePath(projectDir: string, name?: string): string {
-  const filename = name ? `baseline-${name}.json` : 'baseline.json';
-  return join(projectDir, '.monomind', filename);
-}
-
-// ── Vital Signs Trend ─────────────────────────────────────────────────────────
-
-export type TrendDirection = 'improving' | 'declining' | 'stable';
-
-export interface TrendMetric {
-  metric: string;
-  previous: number;
-  current: number;
-  delta: number;
-  direction: TrendDirection;
-  symbol: '↑' | '↓' | '→';
-}
-
-export interface TrendReport {
-  metrics: TrendMetric[];
-  overallDirection: TrendDirection;
-}
-
-/**
- * Extended baseline data with vital-sign counters.
- * These fields are optional so existing baseline files remain compatible.
- */
-export interface BaselineVitals {
-  nodeCount?: number;
-  edgeCount?: number;
-  communityCount?: number;
-  godNodeCount?: number;
-  surpriseCount?: number;
-  hotspotCount?: number;
-  unreachableNodeCount?: number;
-}
-
-/**
- * Domain-aware polarity for each metric.
- * true  = higher value is better (improving)
- * false = lower value is better (improving)
- */
-const METRIC_HIGHER_IS_BETTER: Record<string, boolean> = {
-  nodeCount: true,
-  edgeCount: false,        // neutral; treated as stable unless large change
-  communityCount: true,
-  godNodeCount: false,
-  surpriseCount: false,
-  hotspotCount: false,
-  unreachableNodeCount: false,
-};
-
-function trendDirection(
-  metric: string,
-  delta: number,
-): { direction: TrendDirection; symbol: '↑' | '↓' | '→' } {
-  if (delta === 0) return { direction: 'stable', symbol: '→' };
-
-  // edgeCount is neutral — always stable regardless of direction
-  if (metric === 'edgeCount') return { direction: 'stable', symbol: '→' };
-
-  const higherIsBetter = METRIC_HIGHER_IS_BETTER[metric] ?? true;
-
-  if (delta > 0) {
-    return higherIsBetter
-      ? { direction: 'improving', symbol: '↑' }
-      : { direction: 'declining', symbol: '↑' };
-  }
-  // delta < 0
-  return higherIsBetter
-    ? { direction: 'declining', symbol: '↓' }
-    : { direction: 'improving', symbol: '↓' };
-}
-
-/**
- * Compute a trend report by comparing two BaselineData snapshots.
- * Each baseline must carry BaselineVitals fields (nodeCount, edgeCount, …).
- */
-export function computeTrend(
-  before: BaselineData & BaselineVitals,
-  after: BaselineData & BaselineVitals,
-): TrendReport {
-  const metricKeys: Array<keyof BaselineVitals> = [
-    'nodeCount',
-    'edgeCount',
-    'communityCount',
-    'godNodeCount',
-    'surpriseCount',
-    'hotspotCount',
-    'unreachableNodeCount',
-  ];
-
-  const metrics: TrendMetric[] = [];
-
-  for (const key of metricKeys) {
-    const prev = before[key] ?? 0;
-    const curr = after[key] ?? 0;
-    const delta = curr - prev;
-    const { direction, symbol } = trendDirection(key, delta);
-    metrics.push({ metric: key, previous: prev, current: curr, delta, direction, symbol });
-  }
-
-  // Overall direction: majority vote (improving/declining/stable)
-  const counts = { improving: 0, declining: 0, stable: 0 };
-  for (const m of metrics) counts[m.direction]++;
-
-  let overallDirection: TrendDirection = 'stable';
-  if (counts.improving > counts.declining && counts.improving > counts.stable) {
-    overallDirection = 'improving';
-  } else if (counts.declining > counts.improving && counts.declining > counts.stable) {
-    overallDirection = 'declining';
-  }
-
-  return { metrics, overallDirection };
-}
-
-/** Format a list of ComparedFindings as structured text with file:line hints. */
-export function formatComparedFindings(findings: ComparedFinding[], showAll = false): string {
-  if (findings.length === 0) return 'Baseline comparison: no findings.';
-
-  const newFindings = findings.filter(f => f.introduced);
-  const existing = findings.filter(f => !f.introduced);
-
-  const lines: string[] = [
-    `Baseline comparison: ${findings.length} total finding(s) — ${newFindings.length} new, ${existing.length} known.`,
-    '',
-  ];
-
-  if (newFindings.length > 0) {
-    lines.push(`New findings (${newFindings.length}):`);
-    for (const f of newFindings) {
-      const ref = f.filePath
-        ? f.startLine != null ? `${f.filePath}:${f.startLine}` : f.filePath
-        : f.nodeId;
-      lines.push(`  [${f.type}]  ${f.nodeName}  ${ref}`);
-    }
-    lines.push('');
-  }
-
-  if (showAll && existing.length > 0) {
-    lines.push(`Known findings (${existing.length}):`);
-    for (const f of existing) {
-      const ref = f.filePath
-        ? f.startLine != null ? `${f.filePath}:${f.startLine}` : f.filePath
-        : f.nodeId;
-      lines.push(`  [${f.type}]  ${f.nodeName}  ${ref}`);
-    }
-    lines.push('');
-  }
-
-  return lines.join('\n').trimEnd();
-}
-
-/** Format a TrendReport as structured text for LLM consumption. */
-export function formatTrendReport(report: TrendReport): string {
-  const lines: string[] = [
-    `Graph trend: ${report.overallDirection}`,
-    '',
-  ];
-  for (const m of report.metrics) {
-    const deltaStr = m.delta > 0 ? `+${m.delta}` : `${m.delta}`;
-    lines.push(`  ${m.symbol} ${m.metric}: ${m.previous} → ${m.current} (${deltaStr})  [${m.direction}]`);
-  }
-  return lines.join('\n');
-}