@monoes/monograph 1.5.5 → 1.5.7

package/src/health/ownership-risk.ts

@@ -1,98 +0,0 @@
-export interface ContributorRecord {
-  email: string;
-  commits: number;
-  lastCommit: string;
-}
-
-export interface OwnershipRisk {
-  busFactor: number;
-  contributorCount: number;
-  topContributor?: string;
-  topContributorShare: number;
-  isDrifted: boolean;
-  isStale: boolean;
-  staleDays: number;
-}
-
-export const BOT_PATTERNS: RegExp[] = [
-  /dependabot/i,
-  /renovate/i,
-  /github-actions/i,
-  /\[bot\]/i,
-  /greenkeeper/i,
-  /snyk-bot/i,
-  /semantic-release-bot/i,
-  /allcontributors/i,
-];
-
-export function isBot(email: string, name?: string): boolean {
-  const target = name != null ? `${email} ${name}` : email;
-  return BOT_PATTERNS.some(p => p.test(target));
-}
-
-export function computeBusFactor(contributors: ContributorRecord[]): number {
-  const total = contributors.reduce((sum, c) => sum + c.commits, 0);
-  if (total === 0) return 0;
-
-  const sorted = [...contributors].sort((a, b) => b.commits - a.commits);
-  let acc = 0;
-  let count = 0;
-  for (const c of sorted) {
-    acc += c.commits;
-    count++;
-    if (acc / total >= 0.5) break;
-  }
-  return count;
-}
-
-const STALE_DAYS_THRESHOLD = 180;
-const MS_PER_DAY = 86_400_000;
-
-export function computeOwnershipRisk(
-  contributors: ContributorRecord[],
-  referenceDate?: string,
-): OwnershipRisk {
-  const now = referenceDate != null ? new Date(referenceDate).getTime() : Date.now();
-
-  const human = contributors.filter(c => !isBot(c.email));
-
-  if (human.length === 0) {
-    return {
-      busFactor: 0,
-      contributorCount: 0,
-      topContributorShare: 0,
-      isDrifted: false,
-      isStale: true,
-      staleDays: Infinity,
-    };
-  }
-
-  const total = human.reduce((sum, c) => sum + c.commits, 0);
-  const sorted = [...human].sort((a, b) => b.commits - a.commits);
-
-  const busFactor = computeBusFactor(human);
-  const top = sorted[0];
-  const topContributorShare = total > 0 ? top.commits / total : 0;
-
-  const lastCommitMs = new Date(top.lastCommit).getTime();
-  const staleDays = Math.max(0, Math.floor((now - lastCommitMs) / MS_PER_DAY));
-  const isStale = staleDays > STALE_DAYS_THRESHOLD;
-
-  // Drift: current top-committer differs from the contributor with the oldest last-commit
-  // (proxy for "original owner" when first-commit timestamps aren't available).
-  const byAge = [...human].sort(
-    (a, b) => new Date(a.lastCommit).getTime() - new Date(b.lastCommit).getTime(),
-  );
-  const originalTop = byAge[0];
-  const isDrifted = sorted.length > 1 && originalTop !== undefined && originalTop.email !== sorted[0]!.email;
-
-  return {
-    busFactor,
-    contributorCount: human.length,
-    topContributor: top.email,
-    topContributorShare,
-    isDrifted,
-    isStale,
-    staleDays,
-  };
-}

package/src/health/ownership.ts

@@ -1,174 +0,0 @@
-import { execSync } from 'child_process';
-
-export type EmailMode = 'raw' | 'handle' | 'hash';
-
-export const DRIFT_MIN_FILE_AGE_DAYS = 30;
-export const DRIFT_MAX_ORIGINAL_SHARE = 0.10;
-
-export interface ContributorEntry {
-  email: string;
-  weightedCommits: number;
-  totalCommits: number;
-}
-
-export interface OwnershipMetrics {
-  busFactor: number;
-  driftedHotspots: string[];
-  contributorCount: number;
-  botFilteredCount: number;
-}
-
-export function normalizeEmail(email: string, mode: EmailMode): string {
-  if (mode === 'raw') {
-    return email;
-  }
-
-  if (mode === 'handle') {
-    const githubNoreplyMatch = email.match(/\d+\+(.+)@users\.noreply\.github\.com/);
-    if (githubNoreplyMatch) {
-      return githubNoreplyMatch[1];
-    }
-    const atIdx = email.indexOf('@');
-    return atIdx >= 0 ? email.slice(0, atIdx) : email;
-  }
-
-  // mode === 'hash': FNV-1a 32-bit
-  let h = 2166136261;
-  for (let i = 0; i < email.length; i++) {
-    const byte = email.charCodeAt(i);
-    h = Math.imul(h ^ byte, 16777619) >>> 0;
-  }
-  return h.toString(16).padStart(8, '0');
-}
-
-export function computeBusFactor(contributors: ContributorEntry[]): number {
-  if (contributors.length === 0) return 0;
-
-  const sorted = [...contributors].sort((a, b) => b.weightedCommits - a.weightedCommits);
-  const total = sorted.reduce((sum, c) => sum + c.weightedCommits, 0);
-
-  if (total === 0) return 0;
-
-  let cumulative = 0;
-  let count = 0;
-  for (const contributor of sorted) {
-    cumulative += contributor.weightedCommits;
-    count++;
-    if (cumulative / total >= 0.5) {
-      break;
-    }
-  }
-
-  return count;
-}
-
-export function detectDrift(
-  filePath: string,
-  contributors: ContributorEntry[],
-  originalAuthor: string,
-  fileAgeDays: number,
-): boolean {
-  if (fileAgeDays < DRIFT_MIN_FILE_AGE_DAYS) {
-    return false;
-  }
-
-  const totalWeighted = contributors.reduce((sum, c) => sum + c.weightedCommits, 0);
-  if (totalWeighted === 0) {
-    return false;
-  }
-
-  const originalEntry = contributors.find((c) => c.email === originalAuthor);
-  if (!originalEntry) {
-    return true;
-  }
-
-  const originalShare = originalEntry.weightedCommits / totalWeighted;
-  return originalShare <= DRIFT_MAX_ORIGINAL_SHARE;
-}
-
-export function isBotEmail(email: string): boolean {
-  const lower = email.toLowerCase();
-  return (
-    lower.includes('bot@') ||
-    lower.includes('noreply@') ||
-    lower.includes('[bot]') ||
-    lower.includes('dependabot') ||
-    lower.includes('renovate')
-  );
-}
-
-export function computeOwnershipMetrics(
-  contributors: ContributorEntry[][],
-  hotspotPaths: string[],
-  originalAuthors: Map<string, string>,
-  fileAgeDays: Map<string, number>,
-): OwnershipMetrics {
-  // Flatten all contributors across files, deduplicate by email
-  const allEmails = new Set<string>();
-  const botEmails = new Set<string>();
-
-  for (const fileContributors of contributors) {
-    for (const c of fileContributors) {
-      allEmails.add(c.email);
-      if (isBotEmail(c.email)) {
-        botEmails.add(c.email);
-      }
-    }
-  }
-
-  // Compute bus factor from aggregated contributor data (across all files)
-  const aggregated = new Map<string, ContributorEntry>();
-  for (const fileContributors of contributors) {
-    for (const c of fileContributors) {
-      if (isBotEmail(c.email)) continue;
-      const existing = aggregated.get(c.email);
-      if (existing) {
-        existing.weightedCommits += c.weightedCommits;
-        existing.totalCommits += c.totalCommits;
-      } else {
-        aggregated.set(c.email, { ...c });
-      }
-    }
-  }
-
-  const aggregatedList = Array.from(aggregated.values());
-  const busFactor = computeBusFactor(aggregatedList);
-
-  // Detect drifted hotspots
-  const driftedHotspots: string[] = [];
-  for (let i = 0; i < hotspotPaths.length; i++) {
-    const path = hotspotPaths[i];
-    const fileContributors = contributors[i] ?? [];
-    const originalAuthor = originalAuthors.get(path) ?? '';
-    const ageDays = fileAgeDays.get(path) ?? 0;
-
-    if (detectDrift(path, fileContributors, originalAuthor, ageDays)) {
-      driftedHotspots.push(path);
-    }
-  }
-
-  const humanEmails = new Set([...allEmails].filter((e) => !isBotEmail(e)));
-
-  return {
-    busFactor,
-    driftedHotspots,
-    contributorCount: humanEmails.size,
-    botFilteredCount: botEmails.size,
-  };
-}
-
-// ── Round 9: contributor identifier format ─────────────────────────────────
-
-export type ContributorIdentifierFormat = 'fullEmail' | 'domainEmail' | 'displayName';
-
-/** Normalize a raw git author string to the specified identifier format. */
-export function normalizeContributorId(raw: string, format: ContributorIdentifierFormat): string {
-  const email = raw.match(/<([^>]+)>/)?.[1] ?? raw;
-  if (format === 'fullEmail') return email.toLowerCase();
-  if (format === 'domainEmail') {
-    const domain = email.split('@')[1] ?? email;
-    return domain.toLowerCase();
-  }
-  // displayName: strip the <email> part if present
-  return raw.replace(/<[^>]+>/, '').trim() || email;
-}

package/src/health/quality-gate.ts

@@ -1,57 +0,0 @@
-export interface QualityGateConfig {
-  minScore?: number;          // 0–100: fail if health score < minScore
-  failOnRegression?: boolean;
-}
-
-export type QualityGateStatus = 'pass' | 'fail' | 'warn';
-
-export interface QualityGateResult {
-  status: QualityGateStatus;
-  score: number;
-  minScore?: number;
-  failures: string[];
-  warnings: string[];
-}
-
-export function evaluateQualityGate(
-  score: number,
-  grade: string,
-  gate: QualityGateConfig,
-  regressions?: Array<{ metric: string; baseline: number; current: number }>,
-): QualityGateResult {
-  const failures: string[] = [];
-  const warnings: string[] = [];
-
-  if (gate.minScore != null && score < gate.minScore) {
-    failures.push(`Health score ${score} is below minimum threshold ${gate.minScore}`);
-  }
-
-  if (gate.failOnRegression && regressions && regressions.length > 0) {
-    for (const r of regressions) {
-      failures.push(`Regression detected: ${r.metric} went from ${r.baseline} to ${r.current}`);
-    }
-  }
-
-  if (grade === 'D' || grade === 'F') {
-    warnings.push(`Low health grade: ${grade}`);
-  }
-
-  const status: QualityGateStatus =
-    failures.length > 0 ? 'fail' : warnings.length > 0 ? 'warn' : 'pass';
-
-  return {
-    status,
-    score,
-    minScore: gate.minScore,
-    failures,
-    warnings,
-  };
-}
-
-export function formatQualityGateResult(result: QualityGateResult): string {
-  const icon = result.status === 'pass' ? '✓' : result.status === 'warn' ? '⚠' : '✗';
-  const lines = [`${icon} Quality gate: ${result.status.toUpperCase()} (score: ${result.score})`];
-  for (const f of result.failures) lines.push(`  ✗ ${f}`);
-  for (const w of result.warnings) lines.push(`  ⚠ ${w}`);
-  return lines.join('\n');
-}

package/src/health/risk-profile.ts

@@ -1,39 +0,0 @@
-export interface RiskProfile {
-  low: number;
-  medium: number;
-  high: number;
-  veryHigh: number;
-}
-
-export function computeSizeRiskProfile(lineCounts: number[]): RiskProfile {
-  const p: RiskProfile = { low: 0, medium: 0, high: 0, veryHigh: 0 };
-  for (const n of lineCounts) {
-    if (n <= 15)      p.low++;
-    else if (n <= 30) p.medium++;
-    else if (n <= 60) p.high++;
-    else              p.veryHigh++;
-  }
-  return p;
-}
-
-export function computeInterfacingRiskProfile(paramCounts: number[]): RiskProfile {
-  const p: RiskProfile = { low: 0, medium: 0, high: 0, veryHigh: 0 };
-  for (const n of paramCounts) {
-    if (n <= 2)      p.low++;
-    else if (n <= 4) p.medium++;
-    else if (n <= 6) p.high++;
-    else             p.veryHigh++;
-  }
-  return p;
-}
-
-export function computeCouplingConcentration(fanInScores: number[]): { p95: number; highPct: number } {
-  if (fanInScores.length === 0) return { p95: 0, highPct: 0 };
-  const sorted = [...fanInScores].sort((a, b) => a - b);
-  const p95Idx = Math.floor(sorted.length * 0.95);
-  const p95 = sorted[p95Idx] ?? 0;
-  const floor = Math.max(10, p95);
-  const high = fanInScores.filter(s => s >= floor).length;
-  const highPct = high / fanInScores.length;
-  return { p95, highPct };
-}

package/src/health/runtime-coverage-report.ts

@@ -1,101 +0,0 @@
-// Extended runtime coverage report model with confidence scoring,
-// multi-source evidence, hot-path tracking, and blast-radius analysis.
-
-export type RuntimeCoverageConfidence = 'high' | 'medium' | 'low' | 'unavailable';
-export type RuntimeCoverageWatermark = 'hotPath' | 'warm' | 'cold' | 'unknown';
-export type RuntimeCoverageDataSource = 'cloudApi' | 'localSidecar' | 'istanbulFile' | 'none';
-
-export interface RuntimeCoverageHotPath {
-  endpoint: string;
-  requestsPerDay: number;
-}
-
-export interface RuntimeCoverageBlastRadiusEntry {
-  filePath: string;
-  fanIn: number;
-}
-
-export interface RuntimeCoverageImportanceEntry {
-  filePath: string;
-  score: number;
-}
-
-export interface RuntimeCoverageEvidence {
-  callCount: number | null;
-  lastCalledAt: string | null;
-  coveragePct: number | null;
-  requestsPerDay: number | null;
-}
-
-export interface RuntimeCoverageCaptureQuality {
-  confidence: RuntimeCoverageConfidence;
-  dataSource: RuntimeCoverageDataSource;
-}
-
-export interface RuntimeCoverageMessage {
-  code: string;
-  text: string;
-  learnMoreUrl?: string;
-}
-
-export interface RuntimeCoverageFinding {
-  filePath: string;
-  watermark: RuntimeCoverageWatermark;
-  evidence: RuntimeCoverageEvidence;
-  quality: RuntimeCoverageCaptureQuality;
-  messages: RuntimeCoverageMessage[];
-  hotPaths: RuntimeCoverageHotPath[];
-  blastRadius: RuntimeCoverageBlastRadiusEntry[];
-  importance: RuntimeCoverageImportanceEntry[];
-  recommendedAction: string;
-}
-
-export interface RuntimeCoverageSummary {
-  totalFiles: number;
-  hotPathFiles: number;
-  warmFiles: number;
-  coldFiles: number;
-  unknownFiles: number;
-  averageCoveragePct: number | null;
-  dataSource: RuntimeCoverageDataSource;
-}
-
-export interface RuntimeCoverageReport {
-  findings: RuntimeCoverageFinding[];
-  summary: RuntimeCoverageSummary;
-  generatedAt: string;
-}
-
-export function buildRuntimeCoverageSummary(findings: RuntimeCoverageFinding[]): RuntimeCoverageSummary {
-  const counts = { hotPath: 0, warm: 0, cold: 0, unknown: 0 };
-  let totalPct = 0;
-  let pctCount = 0;
-  let dataSource: RuntimeCoverageDataSource = 'none';
-
-  for (const f of findings) {
-    counts[f.watermark as keyof typeof counts]++;
-    if (f.evidence.coveragePct !== null) {
-      totalPct += f.evidence.coveragePct;
-      pctCount++;
-    }
-    if (f.quality.dataSource !== 'none') dataSource = f.quality.dataSource;
-  }
-
-  return {
-    totalFiles: findings.length,
-    hotPathFiles: counts.hotPath,
-    warmFiles: counts.warm,
-    coldFiles: counts.cold,
-    unknownFiles: counts.unknown,
-    averageCoveragePct: pctCount > 0 ? totalPct / pctCount : null,
-    dataSource,
-  };
-}
-
-export function createRuntimeCoverageReport(findings: RuntimeCoverageFinding[]): RuntimeCoverageReport {
-  return {
-    findings,
-    summary: buildRuntimeCoverageSummary(findings),
-    generatedAt: new Date().toISOString(),
-  };
-}

package/src/health/runtime-coverage.ts

@@ -1,71 +0,0 @@
-export type RuntimeCoverageVerdict =
-  | 'SafeToDelete'
-  | 'ReviewRequired'
-  | 'CoverageUnavailable'
-  | 'LowTraffic'
-  | 'Active'
-  | 'Unknown';
-
-export type RuntimeCoverageRiskBand = 'Critical' | 'High' | 'Medium' | 'Low';
-
-export type RuntimeCoverageAction = 'Delete' | 'Review' | 'Keep' | 'Monitor';
-
-export interface RuntimeSignal {
-  filePath: string;
-  requestsPerDay?: number;
-  lastSeenDaysAgo?: number;
-}
-
-export interface RuntimeCoverageReportVerdict {
-  path: string;
-  staticVerdict: 'unused' | 'used' | 'unknown';
-  runtimeVerdict: RuntimeCoverageVerdict;
-  riskBand: RuntimeCoverageRiskBand;
-  recommendedAction: RuntimeCoverageAction;
-}
-
-export function classifyRuntimeVerdict(
-  signal: RuntimeSignal | undefined
-): RuntimeCoverageVerdict {
-  if (signal === undefined) return 'CoverageUnavailable';
-  if (signal.requestsPerDay === 0) return 'LowTraffic';
-  if (signal.lastSeenDaysAgo !== undefined && signal.lastSeenDaysAgo > 30) return 'LowTraffic';
-  if (signal.requestsPerDay !== undefined && signal.requestsPerDay > 10) return 'Active';
-  return 'Unknown';
-}
-
-export function classifyRiskBand(
-  staticVerdict: string,
-  runtimeVerdict: RuntimeCoverageVerdict
-): RuntimeCoverageRiskBand {
-  if (staticVerdict === 'unused') {
-    if (runtimeVerdict === 'LowTraffic' || runtimeVerdict === 'CoverageUnavailable') return 'Critical';
-    if (runtimeVerdict === 'Unknown') return 'High';
-    if (runtimeVerdict === 'Active') return 'Medium';
-  }
-  return 'Low';
-}
-
-export function recommendAction(
-  riskBand: RuntimeCoverageRiskBand,
-  runtimeVerdict: RuntimeCoverageVerdict
-): RuntimeCoverageAction {
-  if (riskBand === 'Critical') {
-    if (runtimeVerdict === 'LowTraffic') return 'Delete';
-    return 'Review';
-  }
-  if (riskBand === 'High') return 'Review';
-  if (riskBand === 'Medium') return 'Monitor';
-  return 'Keep';
-}
-
-export function classifyRuntimeCoverage(
-  path: string,
-  staticVerdict: 'unused' | 'used' | 'unknown',
-  signal?: RuntimeSignal
-): RuntimeCoverageReportVerdict {
-  const runtimeVerdict = classifyRuntimeVerdict(signal);
-  const riskBand = classifyRiskBand(staticVerdict, runtimeVerdict);
-  const recommendedAction = recommendAction(riskBand, runtimeVerdict);
-  return { path, staticVerdict, runtimeVerdict, riskBand, recommendedAction };
-}

package/src/health/scores.ts

@@ -1,72 +0,0 @@
-export type CoverageTier = 'none' | 'partial' | 'high';
-
-export const HIGH_COVERAGE_WATERMARK = 70.0;
-
-export function coverageTierFromPct(pct: number): CoverageTier {
-  if (pct <= 0) return 'none';
-  if (pct >= HIGH_COVERAGE_WATERMARK) return 'high';
-  return 'partial';
-}
-
-export type ExceededThreshold =
-  | 'cyclomatic' | 'cognitive' | 'both' | 'crap'
-  | 'cyclomatic_crap' | 'cognitive_crap' | 'all';
-
-export function exceededThresholdFromBools(cyclomatic: boolean, cognitive: boolean, crap: boolean): ExceededThreshold {
-  if (cyclomatic && cognitive && crap) return 'all';
-  if (cyclomatic && cognitive) return 'both';
-  if (cyclomatic && crap) return 'cyclomatic_crap';
-  if (cognitive && crap) return 'cognitive_crap';
-  if (cyclomatic) return 'cyclomatic';
-  if (cognitive) return 'cognitive';
-  if (crap) return 'crap';
-  throw new Error('at least one threshold must be exceeded');
-}
-
-export function includesCyclomatic(t: ExceededThreshold): boolean {
-  return (['cyclomatic','both','cyclomatic_crap','all'] as ExceededThreshold[]).includes(t);
-}
-
-export function includesCognitive(t: ExceededThreshold): boolean {
-  return (['cognitive','both','cognitive_crap','all'] as ExceededThreshold[]).includes(t);
-}
-
-export function includesCrap(t: ExceededThreshold): boolean {
-  return (['crap','cyclomatic_crap','cognitive_crap','all'] as ExceededThreshold[]).includes(t);
-}
-
-export type FindingSeverity = 'moderate' | 'high' | 'critical';
-
-export const DEFAULT_CRAP_HIGH = 50.0;
-export const DEFAULT_CRAP_CRITICAL = 100.0;
-export const DEFAULT_COGNITIVE_HIGH = 25;
-export const DEFAULT_COGNITIVE_CRITICAL = 40;
-export const DEFAULT_CYCLOMATIC_HIGH = 30;
-export const DEFAULT_CYCLOMATIC_CRITICAL = 50;
-
-export interface FindingSeverityOpts {
-  cognitive: number;
-  cyclomatic: number;
-  crap?: number;
-  cognitiveHigh?: number;
-  cognitiveCritical?: number;
-  cyclomaticHigh?: number;
-  cyclomaticCritical?: number;
-}
-
-export function computeFindingSeverity(opts: FindingSeverityOpts): FindingSeverity {
-  const {
-    cognitive, cyclomatic, crap,
-    cognitiveHigh = DEFAULT_COGNITIVE_HIGH,
-    cognitiveCritical = DEFAULT_COGNITIVE_CRITICAL,
-    cyclomaticHigh = DEFAULT_CYCLOMATIC_HIGH,
-    cyclomaticCritical = DEFAULT_CYCLOMATIC_CRITICAL,
-  } = opts;
-
-  const cogSev: FindingSeverity = cognitive >= cognitiveCritical ? 'critical' : cognitive >= cognitiveHigh ? 'high' : 'moderate';
-  const cycSev: FindingSeverity = cyclomatic >= cyclomaticCritical ? 'critical' : cyclomatic >= cyclomaticHigh ? 'high' : 'moderate';
-  const crapSev: FindingSeverity = crap === undefined ? 'moderate' : crap >= DEFAULT_CRAP_CRITICAL ? 'critical' : crap >= DEFAULT_CRAP_HIGH ? 'high' : 'moderate';
-
-  const order: FindingSeverity[] = ['moderate','high','critical'];
-  return [cogSev, cycSev, crapSev].reduce((a, b) => order.indexOf(a) >= order.indexOf(b) ? a : b);
-}

package/src/health/scoring-types.ts

@@ -1,48 +0,0 @@
-export interface PerFunctionCrap {
-  functionName: string;
-  crap: number;
-  cyclomatic: number;
-  coveragePct: number;
-  line?: number;
-}
-
-export interface CoverageGapData {
-  filePath: string;
-  coveragePct: number;
-  coveredLines: number;
-  totalLines: number;
-  uncoveredFunctions: string[];
-}
-
-export interface FileScoreBundle {
-  filePath: string;
-  fanIn: number;
-  fanOut: number;
-  maintainabilityIndex?: number;
-  complexityDensity: number;
-  churnScore?: number;
-  perFunctionCrap: PerFunctionCrap[];
-  coverageGap?: CoverageGapData;
-  lineCount: number;
-  inCycle: boolean;
-  deadCodeRatio: number;
-}
-
-export function computeComplexityDensity(totalCyclomatic: number, lineCount: number): number {
-  return totalCyclomatic / Math.max(lineCount, 1);
-}
-
-export function computeDeadCodeRatio(unusedExports: number, totalExports: number): number {
-  return Math.min(unusedExports / Math.max(totalExports, 1), 1.0);
-}
-
-export function computeMaintainabilityIndex(
-  halsteadVolume: number,
-  cyclomaticComplexity: number,
-  lineCount: number,
-): number {
-  const v = Math.max(halsteadVolume, 1);
-  const loc = Math.max(lineCount, 1);
-  const mi = 171 - 5.2 * Math.log(v) - 0.23 * cyclomaticComplexity - 16.2 * Math.log(loc);
-  return Math.min(Math.max(mi, 0), 100);
-}