@monoes/monograph 1.5.6 → 1.5.8

package/src/analysis/churn-trend.ts

@@ -1,57 +0,0 @@
-export type ChurnTrend = 'accelerating' | 'stable' | 'cooling';
-
-const ACCELERATING_RATIO = 1.5;
-const COOLING_RATIO = 0.67;
-
-export function computeChurnTrend(timestampsEpochSec: number[]): ChurnTrend {
-  if (timestampsEpochSec.length < 2) return 'stable';
-  // Single pass: compute min, max, and partition counts simultaneously (O(N) vs O(4N) before)
-  let minTs = timestampsEpochSec[0];
-  let maxTs = timestampsEpochSec[0];
-  for (let i = 1; i < timestampsEpochSec.length; i++) {
-    const ts = timestampsEpochSec[i];
-    if (ts < minTs) minTs = ts;
-    if (ts > maxTs) maxTs = ts;
-  }
-  if (maxTs === minTs) return 'stable';
-  const midpoint = minTs + (maxTs - minTs) / 2;
-  let recent = 0, older = 0;
-  for (const ts of timestampsEpochSec) {
-    if (ts > midpoint) recent++; else older++;
-  }
-  if (older < 1) return 'stable';
-  const ratio = recent / older;
-  if (ratio > ACCELERATING_RATIO) return 'accelerating';
-  if (ratio < COOLING_RATIO) return 'cooling';
-  return 'stable';
-}
-
-export function churnTrendLabel(trend: ChurnTrend): string {
-  return trend === 'accelerating' ? '↑ accelerating' : trend === 'cooling' ? '↓ cooling' : '→ stable';
-}
-
-export function churnTrendFromFileSeries(fileTimestamps: number[][]): ChurnTrend {
-  // Avoid allocating an intermediate flat array — inline the min/max/count logic
-  if (fileTimestamps.length === 0) return 'stable';
-  let minTs = Infinity, maxTs = -Infinity, total = 0;
-  for (const series of fileTimestamps) {
-    for (const ts of series) {
-      if (ts < minTs) minTs = ts;
-      if (ts > maxTs) maxTs = ts;
-      total++;
-    }
-  }
-  if (total < 2 || maxTs === minTs) return 'stable';
-  const midpoint = minTs + (maxTs - minTs) / 2;
-  let recent = 0, older = 0;
-  for (const series of fileTimestamps) {
-    for (const ts of series) {
-      if (ts > midpoint) recent++; else older++;
-    }
-  }
-  if (older < 1) return 'stable';
-  const ratio = recent / older;
-  if (ratio > ACCELERATING_RATIO) return 'accelerating';
-  if (ratio < COOLING_RATIO) return 'cooling';
-  return 'stable';
-}

package/src/analysis/churn.ts

@@ -1,263 +0,0 @@
-import { execSync } from 'child_process';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from 'fs';
-import { join, relative } from 'path';
-
-export type ChurnTrend = 'accelerating' | 'stable' | 'cooling';
-
-export interface SinceDuration {
-  raw: string;
-  days: number;
-}
-
-export interface AuthorContribution {
-  authorIdx: number;
-  weightedCommits: number;
-}
-
-export interface FileChurn {
-  path: string;
-  totalCommits: number;
-  weightedCommits: number;
-  authors: AuthorContribution[];
-  trend: ChurnTrend;
-}
-
-export interface ChurnResult {
-  files: FileChurn[];
-  authorPool: string[];
-  since: SinceDuration;
-}
-
-export function parseSince(s: string): SinceDuration {
-  const dMatch = s.match(/^(\d+)d$/);
-  if (dMatch) return { raw: s, days: parseInt(dMatch[1], 10) };
-
-  const wMatch = s.match(/^(\d+)w$/);
-  if (wMatch) return { raw: s, days: parseInt(wMatch[1], 10) * 7 };
-
-  const mMatch = s.match(/^(\d+)m$/);
-  if (mMatch) return { raw: s, days: parseInt(mMatch[1], 10) * 30 };
-
-  const yMatch = s.match(/^(\d+)y$/);
-  if (yMatch) return { raw: s, days: parseInt(yMatch[1], 10) * 365 };
-
-  // ISO date string
-  const parsed = Date.parse(s);
-  if (!isNaN(parsed)) {
-    const days = Math.ceil((Date.now() - parsed) / 86400000);
-    return { raw: s, days };
-  }
-
-  // Fallback: try to parse as plain number of days
-  const num = parseInt(s, 10);
-  if (!isNaN(num)) return { raw: s, days: num };
-
-  return { raw: s, days: 30 };
-}
-
-export function computeRecencyWeight(ageDays: number): number {
-  return Math.exp(-Math.LN2 * ageDays / 90);
-}
-
-export function classifyChurnTrend(
-  recentWeighted: number,
-  olderWeighted: number,
-  commitCount = 2,
-): ChurnTrend {
-  // A file with 0-1 commits in the window has no "older" phase to compare against —
-  // classifying it as 'cooling' (declining activity) is nonsensical for something
-  // that was just created or touched once.
-  if (commitCount <= 1) return 'stable';
-  if (olderWeighted === 0) {
-    return recentWeighted > 0 ? 'accelerating' : 'stable';
-  }
-  const ratio = recentWeighted / olderWeighted;
-  if (ratio > 1.5) return 'accelerating';
-  if (ratio < 0.67) return 'cooling';
-  return 'stable';
-}
-
-/** Coarse day-granularity bucket for the current moment, e.g. "2026-07-08". */
-function todayBucket(): string {
-  return new Date().toISOString().slice(0, 10);
-}
-
-/**
- * Delete churn cache files whose date bucket is older than `maxAgeDays` — the
- * weighted-commit numbers decay with time even at a fixed HEAD, and without this
- * a repo idle for weeks would keep serving stale cache, while cache files from
- * every past HEAD/day combination would accumulate forever.
- */
-function pruneChurnCache(cacheDir: string, maxAgeDays = 3): void {
-  let entries: string[];
-  try {
-    entries = readdirSync(cacheDir);
-  } catch {
-    return;
-  }
-  const now = Date.now();
-  for (const entry of entries) {
-    const m = entry.match(/^churn-.+-(\d{4}-\d{2}-\d{2})\.json$/);
-    if (!m) continue;
-    const bucketMs = Date.parse(m[1]);
-    if (isNaN(bucketMs)) continue;
-    if ((now - bucketMs) / 86400000 > maxAgeDays) {
-      try {
-        unlinkSync(join(cacheDir, entry));
-      } catch {
-        // non-fatal — best-effort prune
-      }
-    }
-  }
-}
-
-export async function analyzeChurn(
-  root: string,
-  since: SinceDuration | string,
-): Promise<ChurnResult> {
-  const sinceDuration: SinceDuration =
-    typeof since === 'string' ? parseSince(since) : since;
-
-  // Cache lookup — keyed by HEAD SHA + window size + a coarse day bucket, so
-  // entries naturally invalidate as time passes even at the same HEAD (the
-  // recency weighting is time-dependent, not just HEAD-dependent).
-  const cacheDir = join(root, '.monograph', 'cache');
-  const dateBucket = todayBucket();
-  pruneChurnCache(cacheDir);
-  let treeHash = '';
-  try {
-    treeHash = execSync('git rev-parse HEAD', { cwd: root }).toString().trim();
-    const cacheFile = join(cacheDir, `churn-${treeHash}-${sinceDuration.days}-${dateBucket}.json`);
-    if (existsSync(cacheFile)) {
-      try {
-        const cached = JSON.parse(readFileSync(cacheFile, 'utf8'));
-        return cached as ChurnResult;
-      } catch {
-        // cache corrupt, recompute
-      }
-    }
-  } catch {
-    // git not available or no commits
-  }
-
-  // Build since date string for git log
-  const sinceDate = new Date(Date.now() - sinceDuration.days * 86400000);
-  const sinceDateStr = sinceDate.toISOString().slice(0, 10);
-
-  // Get all commits with file paths
-  let logOutput = '';
-  try {
-    logOutput = execSync(
-      `git log --after="${sinceDateStr}" --name-only --format="%ae|%ai"`,
-      { cwd: root, maxBuffer: 50 * 1024 * 1024 },
-    ).toString();
-  } catch {
-    return { files: [], authorPool: [], since: sinceDuration };
-  }
-
-  const now = Date.now();
-
-  // Parse log output into per-file commit lists: { email, dateStr }[]
-  const fileCommits = new Map<string, Array<{ email: string; dateStr: string }>>();
-  const authorIndexMap = new Map<string, number>();
-  const authorPool: string[] = [];
-
-  const lines = logOutput.split('\n');
-  let currentEmail = '';
-  let currentDateStr = '';
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-
-    if (trimmed.includes('|')) {
-      // Header line: email|date
-      const pipeIdx = trimmed.indexOf('|');
-      currentEmail = trimmed.slice(0, pipeIdx).trim();
-      currentDateStr = trimmed.slice(pipeIdx + 1).trim();
-    } else {
-      // File path line
-      const filePath = trimmed;
-      if (!fileCommits.has(filePath)) {
-        fileCommits.set(filePath, []);
-      }
-      fileCommits.get(filePath)!.push({ email: currentEmail, dateStr: currentDateStr });
-    }
-  }
-
-  // Build FileChurn entries
-  const files: FileChurn[] = [];
-
-  for (const [path, commits] of fileCommits) {
-    if (commits.length === 0) continue;
-
-    // Sort commits by date descending (newest first)
-    const sortedCommits = commits.slice().sort((a, b) => {
-      return Date.parse(b.dateStr) - Date.parse(a.dateStr);
-    });
-
-    // Compute weighted commits per author and trend
-    const authorWeights = new Map<number, number>();
-    let totalWeighted = 0;
-
-    // Split by TIME (midpoint of the `since` window), not by commit-array index —
-    // otherwise 10 commits all from the last week still get split 5-old/5-recent,
-    // misrepresenting genuinely-recent-only activity as having an "older" phase.
-    const windowMidpoint = now - (sinceDuration.days * 86400000) / 2;
-    let recentWeighted = 0;
-    let olderWeighted = 0;
-
-    for (let i = 0; i < sortedCommits.length; i++) {
-      const commit = sortedCommits[i];
-      const commitDate = Date.parse(commit.dateStr);
-      const ageDays = (now - commitDate) / 86400000;
-      const weight = computeRecencyWeight(ageDays);
-
-      // Author index
-      if (!authorIndexMap.has(commit.email)) {
-        authorIndexMap.set(commit.email, authorPool.length);
-        authorPool.push(commit.email);
-      }
-      const authorIdx = authorIndexMap.get(commit.email)!;
-
-      const existing = authorWeights.get(authorIdx) ?? 0;
-      authorWeights.set(authorIdx, existing + weight);
-      totalWeighted += weight;
-
-      if (commitDate >= windowMidpoint) {
-        recentWeighted += weight;
-      } else {
-        olderWeighted += weight;
-      }
-    }
-
-    const trend = classifyChurnTrend(recentWeighted, olderWeighted, sortedCommits.length);
-
-    const authors: AuthorContribution[] = Array.from(authorWeights.entries()).map(
-      ([authorIdx, weightedCommits]) => ({ authorIdx, weightedCommits }),
-    );
-
-    files.push({
-      path,
-      totalCommits: commits.length,
-      weightedCommits: totalWeighted,
-      authors,
-      trend,
-    });
-  }
-
-  const result: ChurnResult = { files, authorPool, since: sinceDuration };
-
-  // Write cache
-  if (treeHash) {
-    try {
-      mkdirSync(cacheDir, { recursive: true });
-      const cacheFile = join(cacheDir, `churn-${treeHash}-${sinceDuration.days}-${dateBucket}.json`);
-      writeFileSync(cacheFile, JSON.stringify(result), 'utf8');
-    } catch {
-      // cache write failure is non-fatal
-    }
-  }
-
-  return result;
-}

package/src/analysis/cluster-quality.ts

@@ -1,142 +0,0 @@
-/**
- * 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 using the community-level formula:
- *   Q = Σ_c [e_c / m - (a_c / 2m)²]
- * where e_c = intra-community edges, a_c = sum of degrees in community c, m = total edges.
- *
- * O(E + N) instead of O(N²).
- * Returns a value in (-0.5, 1].
- */
-export function modularityScore(
-  memberships: Map<string, number>,
-  edges: Edge[],
-): number {
-  if (edges.length === 0 || memberships.size === 0) return 0;
-
-  const adj = buildAdjacency(edges);
-  const m = edges.length; // directed edges count (each undirected pair counted once in input)
-
-  // Sum of degrees per community and intra-community edge count
-  const communityDegreeSum = new Map<number, number>();
-  const intraCommunityEdges = new Map<number, number>();
-
-  for (const [nodeId, cid] of memberships) {
-    const deg = adj.get(nodeId)?.size ?? 0;
-    communityDegreeSum.set(cid, (communityDegreeSum.get(cid) ?? 0) + deg);
-  }
-
-  for (const { sourceId, targetId } of edges) {
-    const cs = memberships.get(sourceId);
-    const ct = memberships.get(targetId);
-    if (cs !== undefined && ct !== undefined && cs === ct) {
-      intraCommunityEdges.set(cs, (intraCommunityEdges.get(cs) ?? 0) + 1);
-    }
-  }
-
-  const twoM = 2 * m;
-  let Q = 0;
-  for (const [cid, degSum] of communityDegreeSum) {
-    const ec = intraCommunityEdges.get(cid) ?? 0;
-    Q += ec / m - (degSum / twoM) ** 2;
-  }
-
-  return Q;
-}

package/src/analysis/combined.ts

@@ -1,41 +0,0 @@
-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;
-}
-
-// monolean: stub — resolves which analyses to run but doesn't execute them.
-// Wire up when dead-code/duplication detectors are called from a unified entry point.
-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

@@ -1,41 +0,0 @@
-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 };
-}