@chemx/starter-kit 26.9.9-786 → 26.9.11-362

package/cli/audit/ast-visitors.js

@@ -0,0 +1,243 @@
+import * as t from '@babel/types';
+import { RULE_REGISTRY } from './rules-registry.js';
+import { countLogicalOperators } from './rules-helpers.js';
+
+export const createAstVisitors = ({ relativePath, violations }) => {
+  return {
+    Function(astPath) {
+      const isCustomHook = (
+        (astPath.node.id && /^use[A-Z0-9]/.test(astPath.node.id.name)) ||
+        (astPath.parentPath?.node?.id && /^use[A-Z0-9]/.test(astPath.parentPath.node.id.name))
+      );
+
+      // Pillar 3: Hook Saturation
+      let hookCount = 0;
+      astPath.traverse({
+        CallExpression(callPath) {
+          const callee = callPath.node.callee;
+          if (t.isIdentifier(callee) && /^use[A-Z0-9]/.test(callee.name)) {
+            if (callPath.getFunctionParent() === astPath) {
+              hookCount += 1;
+            }
+          }
+        }
+      });
+
+      if (hookCount > 5) {
+        const line = astPath.node.loc?.start.line || 1;
+        const meta = RULE_REGISTRY.HOOK_SATURATION;
+        violations.push({
+          filePath: relativePath,
+          line,
+          column: astPath.node.loc?.start.column || 1,
+          hazard: `Hook saturation detected (${hookCount} hooks > 5 limit)`,
+          rule: 'HOOK_SATURATION',
+          severity: meta.severity,
+          pillar: meta.pillar,
+          directive: meta.directive
+        });
+      }
+
+      // Pillar 3: Hook Return Overload (3 to 5 limit)
+      if (isCustomHook) {
+        astPath.traverse({
+          ReturnStatement(retPath) {
+            if (retPath.getFunctionParent() === astPath && t.isObjectExpression(retPath.node.argument)) {
+              const propCount = retPath.node.argument.properties.length;
+              if (propCount > 5) {
+                const line = retPath.node.loc?.start.line || 1;
+                const meta = RULE_REGISTRY.HOOK_RETURN_OVERLOAD;
+                violations.push({
+                  filePath: relativePath,
+                  line,
+                  column: retPath.node.loc?.start.column || 1,
+                  hazard: `Hook return saturation (${propCount} properties > 5 limit)`,
+                  rule: 'HOOK_RETURN_OVERLOAD',
+                  severity: meta.severity,
+                  pillar: meta.pillar,
+                  directive: meta.directive
+                });
+              }
+            }
+          }
+        });
+      }
+    },
+
+    // Pillar 2: Control Flow Complexity
+    JSXExpressionContainer(astPath) {
+      const expr = astPath.node.expression;
+      if (t.isLogicalExpression(expr) || t.isUnaryExpression(expr)) {
+        const opCount = countLogicalOperators(expr);
+        if (opCount > 2) {
+          const line = expr.loc?.start.line || astPath.node.loc?.start.line || 1;
+          const meta = RULE_REGISTRY.CONTROL_FLOW_INLINE_BOOLEAN;
+          violations.push({
+            filePath: relativePath,
+            line,
+            column: expr.loc?.start.column || 1,
+            hazard: `Inline boolean complexity (${opCount} logical operators > 2 limit)`,
+            rule: 'CONTROL_FLOW_INLINE_BOOLEAN',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+      }
+    },
+
+    ConditionalExpression(astPath) {
+      if (t.isConditionalExpression(astPath.node.consequent) || t.isConditionalExpression(astPath.node.alternate)) {
+        const line = astPath.node.loc?.start.line || 1;
+        const meta = RULE_REGISTRY.CONTROL_FLOW_NESTED_TERNARY;
+        violations.push({
+          filePath: relativePath,
+          line,
+          column: astPath.node.loc?.start.column || 1,
+          hazard: 'Nested ternary operator detected',
+          rule: 'CONTROL_FLOW_NESTED_TERNARY',
+          severity: meta.severity,
+          pillar: meta.pillar,
+          directive: meta.directive
+        });
+      }
+    },
+
+    // Pillar 5: Design System & Inline Styles
+    JSXAttribute(astPath) {
+      const attrName = astPath.node.name?.name;
+      if (attrName === 'style') {
+        const value = astPath.node.value;
+        if (t.isJSXExpressionContainer(value) && t.isObjectExpression(value.expression)) {
+          const line = astPath.node.loc?.start.line || 1;
+          const meta = RULE_REGISTRY.RAW_INLINE_STYLE;
+          violations.push({
+            filePath: relativePath,
+            line,
+            column: astPath.node.loc?.start.column || 1,
+            hazard: 'Raw inline style attribute detected in JSX',
+            rule: 'RAW_INLINE_STYLE',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+      } else if (attrName === 'className' || attrName === 'class') {
+        const value = astPath.node.value;
+        const strVal = t.isStringLiteral(value) ? value.value : '';
+        if (strVal && (strVal.includes('fa-') || strVal.includes('fa '))) {
+          if (/\btext-(primary|secondary|danger|warning|success|info|light|dark|\w+)\b/.test(strVal)) {
+            const line = astPath.node.loc?.start.line || 1;
+            const meta = RULE_REGISTRY.ICON_SVG_STYLE_LEAK;
+            violations.push({
+              filePath: relativePath,
+              line,
+              column: astPath.node.loc?.start.column || 1,
+              hazard: 'FontAwesome icon with text-* class breaks SVG fill',
+              rule: 'ICON_SVG_STYLE_LEAK',
+              severity: meta.severity,
+              pillar: meta.pillar,
+              directive: meta.directive
+            });
+          }
+        }
+      }
+    },
+
+    // Pillar 6 & Pillar 7: Call Expressions (Timers & Logging)
+    CallExpression(astPath) {
+      const callee = astPath.node.callee;
+
+      // Timer Discipline
+      if (t.isIdentifier(callee) && (callee.name === 'setInterval' || callee.name === 'setTimeout')) {
+        const args = astPath.node.arguments;
+        const delayArg = args[1];
+
+        // Render-hack check: setTimeout(fn, 0)
+        if (callee.name === 'setTimeout' && delayArg && t.isNumericLiteral(delayArg) && delayArg.value === 0) {
+          const line = astPath.node.loc?.start.line || 1;
+          const meta = RULE_REGISTRY.RENDER_HACK_TIMEOUT;
+          violations.push({
+            filePath: relativePath,
+            line,
+            column: astPath.node.loc?.start.column || 1,
+            hazard: 'Zero-delay render hack setTimeout(..., 0) detected',
+            rule: 'RENDER_HACK_TIMEOUT',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+
+        const fnParent = astPath.getFunctionParent();
+        let hasCleanup = false;
+        if (fnParent) {
+          fnParent.traverse({
+            ReturnStatement(retPath) {
+              if (retPath.node.argument) {
+                hasCleanup = true;
+              }
+            }
+          });
+        }
+
+        if (!hasCleanup) {
+          const line = astPath.node.loc?.start.line || 1;
+          const meta = RULE_REGISTRY.TIMER_DISCIPLINE;
+          violations.push({
+            filePath: relativePath,
+            line,
+            column: astPath.node.loc?.start.column || 1,
+            hazard: `Raw ${callee.name} lacking lifecycle scope disposal`,
+            rule: 'TIMER_DISCIPLINE',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+      }
+
+      // Unguarded Logging
+      if (
+        t.isMemberExpression(callee) &&
+        t.isIdentifier(callee.object) &&
+        callee.object.name === 'console' &&
+        t.isIdentifier(callee.property) &&
+        ['log', 'info', 'warn'].includes(callee.property.name)
+      ) {
+        const line = astPath.node.loc?.start.line || 1;
+        const meta = RULE_REGISTRY.UNGUARDED_LOGGING;
+        violations.push({
+          filePath: relativePath,
+          line,
+          column: astPath.node.loc?.start.column || 1,
+          hazard: `Unguarded console.${callee.property.name} statement`,
+          rule: 'UNGUARDED_LOGGING',
+          severity: meta.severity,
+          pillar: meta.pillar,
+          directive: meta.directive
+        });
+      }
+    },
+
+    // Pillar 4: Type Co-location
+    TSTypeLiteral(astPath) {
+      if (astPath.node.members.length > 3) {
+        if (!astPath.findParent((p) => p.isTSTypeAliasDeclaration() || p.isTSInterfaceDeclaration())) {
+          const line = astPath.node.loc?.start.line || 1;
+          const meta = RULE_REGISTRY.TYPE_COLOCATION;
+          violations.push({
+            filePath: relativePath,
+            line,
+            column: astPath.node.loc?.start.column || 1,
+            hazard: `Inlined anonymous complex type (${astPath.node.members.length} members)`,
+            rule: 'TYPE_COLOCATION',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+      }
+    }
+  };
+};

package/cli/audit/discussion-store.js

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureChemxDir } from './history.js';
+
+const DISCUSSION_FILE = 'discussion.json';
+
+export const getStoredDiscussion = (cwd = process.cwd()) => {
+  try {
+    const filePath = path.resolve(cwd, '.chemx', DISCUSSION_FILE);
+    if (!fs.existsSync(filePath)) return null;
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+};
+
+export const saveStoredDiscussion = (data, cwd = process.cwd()) => {
+  try {
+    const dir = ensureChemxDir(cwd);
+    const filePath = path.resolve(dir, DISCUSSION_FILE);
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const clearStoredDiscussion = (cwd = process.cwd()) => {
+  try {
+    const filePath = path.resolve(cwd, '.chemx', DISCUSSION_FILE);
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+};

package/cli/audit/history.d.ts

@@ -0,0 +1,63 @@
+import type { MolecularHealthScore, CodebaseMetrics, PillarStatus, ContextTokenAnalysis, AuditReport } from './types';
+
+export interface AuditSnapshot {
+  readonly id: string;
+  readonly timestamp: string;
+  readonly health: MolecularHealthScore;
+  readonly metrics: CodebaseMetrics;
+  readonly violations: {
+    readonly total: number;
+    readonly critical: number;
+    readonly high: number;
+    readonly medium: number;
+    readonly low: number;
+  };
+  readonly monoliths: {
+    readonly total: number;
+    readonly extreme: number;
+    readonly severe: number;
+    readonly warning: number;
+  };
+  readonly tokens: ContextTokenAnalysis;
+  readonly pillars: Record<string, {
+    readonly status: PillarStatus;
+    readonly violations: number;
+    readonly critical: number;
+  }>;
+}
+
+export interface PillarDelta {
+  readonly beforeStatus: PillarStatus;
+  readonly afterStatus: PillarStatus;
+  readonly beforeViolations: number;
+  readonly afterViolations: number;
+  readonly improved: boolean;
+}
+
+export interface TransformationDelta {
+  readonly scoreDelta: number;
+  readonly critDelta: number;
+  readonly totalDelta: number;
+  readonly monolithDelta: number;
+  readonly tokensDelta: number;
+  readonly pillarDeltas: Record<string, PillarDelta>;
+  readonly isImproved: boolean;
+}
+
+export interface SaveSnapshotResult {
+  readonly snapshot: AuditSnapshot;
+  readonly history: readonly AuditSnapshot[];
+  readonly baseline: AuditSnapshot | null;
+  readonly isNewBaseline: boolean;
+  readonly totalAudits: number;
+}
+
+export declare function ensureChemxDir(cwd?: string): string;
+export declare function createSnapshotFromReport(report: AuditReport): AuditSnapshot;
+export declare function getAuditHistory(cwd?: string): AuditSnapshot[];
+export declare function getAuditBaseline(cwd?: string): AuditSnapshot | null;
+export declare function setAuditBaseline(snapshot: AuditSnapshot, cwd?: string): AuditSnapshot;
+export declare function saveAuditSnapshot(report: AuditReport, cwd?: string): SaveSnapshotResult;
+export declare function calculateTransformationDelta(beforeSnapshot: AuditSnapshot, afterSnapshot: AuditSnapshot): TransformationDelta;
+export declare function formatTransformationTerminal(beforeSnapshot: AuditSnapshot, afterSnapshot: AuditSnapshot): string;
+export declare function formatHistoryTimelineTerminal(history: readonly AuditSnapshot[]): string;

package/cli/audit/history.js

@@ -0,0 +1,352 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { groupViolationsBySeverity } from './reporter.js';
+
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const CYAN = '\x1b[36m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+
+export const ensureChemxDir = (cwd = process.cwd()) => {
+  const dir = path.resolve(cwd, '.chemx');
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Ensure .chemx is gitignored if git repo exists
+  const gitDir = path.resolve(cwd, '.git');
+  if (fs.existsSync(gitDir)) {
+    const gitignorePath = path.resolve(cwd, '.gitignore');
+    try {
+      let content = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf-8') : '';
+      if (!content.includes('.chemx')) {
+        const trailingNewline = content.endsWith('\n') || content.length === 0 ? '' : '\n';
+        fs.appendFileSync(gitignorePath, `${trailingNewline}# Chemical X local telemetry & audit history\n.chemx/\n`, 'utf-8');
+      }
+    } catch {}
+  }
+
+  return dir;
+};
+
+export const createSnapshotFromReport = (report) => {
+  const { metrics, health, hotspots = [], violations = [], pillars = {}, contextAnalysis = {} } = report;
+  const { critical, high, medium, low } = groupViolationsBySeverity(violations);
+
+  const isExtremeMonolith = (h) => h.lineCount >= 2000;
+  const isSevereMonolith = (h) => h.lineCount >= 1000 && h.lineCount < 2000;
+  const isWarningMonolith = (h) => h.lineCount >= 500 && h.lineCount < 1000;
+
+  const extremeMonoliths = hotspots.filter(isExtremeMonolith).length;
+  const severeMonoliths = hotspots.filter(isSevereMonolith).length;
+  const warningMonoliths = hotspots.filter(isWarningMonolith).length;
+  const totalMonoliths = extremeMonoliths + severeMonoliths + warningMonoliths;
+
+  const pillarSummaries = {};
+  for (const [key, data] of Object.entries(pillars)) {
+    pillarSummaries[key] = {
+      status: data.status,
+      violations: data.violations,
+      critical: data.critical
+    };
+  }
+
+  return {
+    id: `audit-${Date.now()}`,
+    timestamp: new Date().toISOString(),
+    health: {
+      score: health.score,
+      grade: health.grade,
+      label: health.label
+    },
+    metrics: {
+      scannedFiles: metrics.scannedFiles,
+      totalLoc: metrics.totalLoc,
+      avgLoc: metrics.avgLoc,
+      moleculeCount: metrics.moleculeCount,
+      moleculeCompliantCount: metrics.moleculeCompliantCount,
+      moleculeCompliantPct: metrics.moleculeCompliantPct,
+      hookCount: metrics.hookCount
+    },
+    violations: {
+      total: violations.length,
+      critical: critical.length,
+      high: high.length,
+      medium: medium.length,
+      low: low.length
+    },
+    monoliths: {
+      total: totalMonoliths,
+      extreme: extremeMonoliths,
+      severe: severeMonoliths,
+      warning: warningMonoliths
+    },
+    tokens: {
+      estimatedTokens: contextAnalysis.estimatedTokens || 0,
+      estimatedExcessTokens: contextAnalysis.estimatedExcessTokens || 0,
+      potentialSavingsPct: contextAnalysis.potentialSavingsPct || 0,
+      riskLevel: contextAnalysis.riskLevel || 'LOW'
+    },
+    pillars: pillarSummaries
+  };
+};
+
+export const getAuditHistory = (cwd = process.cwd()) => {
+  const historyPath = path.resolve(cwd, '.chemx', 'history.json');
+  if (!fs.existsSync(historyPath)) return [];
+  try {
+    const raw = fs.readFileSync(historyPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+};
+
+export const getAuditBaseline = (cwd = process.cwd()) => {
+  const baselinePath = path.resolve(cwd, '.chemx', 'baseline.json');
+  if (fs.existsSync(baselinePath)) {
+    try {
+      const raw = fs.readFileSync(baselinePath, 'utf-8');
+      return JSON.parse(raw);
+    } catch {}
+  }
+  const history = getAuditHistory(cwd);
+  return history.length > 0 ? history[0] : null;
+};
+
+export const setAuditBaseline = (snapshot, cwd = process.cwd()) => {
+  ensureChemxDir(cwd);
+  const baselinePath = path.resolve(cwd, '.chemx', 'baseline.json');
+  fs.writeFileSync(baselinePath, JSON.stringify(snapshot, null, 2), 'utf-8');
+  return snapshot;
+};
+
+export const saveAuditSnapshot = (report, cwd = process.cwd()) => {
+  ensureChemxDir(cwd);
+  const snapshot = createSnapshotFromReport(report);
+  const history = getAuditHistory(cwd);
+
+  // Prevent duplicate snapshots if called multiple times within 5 seconds with same metrics
+  if (history.length > 0) {
+    const last = history[history.length - 1];
+    const timeDiff = Math.abs(Date.now() - new Date(last.timestamp).getTime());
+    const isSameMetrics =
+      last.health?.score === snapshot.health?.score &&
+      last.metrics?.totalLoc === snapshot.metrics?.totalLoc &&
+      last.violations?.total === snapshot.violations?.total;
+
+    if (timeDiff < 5000 && isSameMetrics) {
+      return {
+        snapshot: last,
+        history,
+        baseline: getAuditBaseline(cwd),
+        isNewBaseline: false,
+        totalAudits: history.length
+      };
+    }
+  }
+
+  history.push(snapshot);
+
+  // Keep last 50 snapshots
+  const trimmed = history.slice(-50);
+  const historyPath = path.resolve(cwd, '.chemx', 'history.json');
+  fs.writeFileSync(historyPath, JSON.stringify(trimmed, null, 2), 'utf-8');
+
+  // Auto-establish first run as baseline if none exists
+  const baselinePath = path.resolve(cwd, '.chemx', 'baseline.json');
+  let isNewBaseline = false;
+  if (!fs.existsSync(baselinePath)) {
+    fs.writeFileSync(baselinePath, JSON.stringify(snapshot, null, 2), 'utf-8');
+    isNewBaseline = true;
+  }
+
+  const baseline = getAuditBaseline(cwd);
+  return {
+    snapshot,
+    history: trimmed,
+    baseline,
+    isNewBaseline,
+    totalAudits: trimmed.length
+  };
+};
+
+export const calculateTransformationDelta = (beforeSnapshot, afterSnapshot) => {
+  const scoreBefore = beforeSnapshot.health.score;
+  const scoreAfter = afterSnapshot.health.score;
+  const scoreDelta = scoreAfter - scoreBefore;
+
+  const critBefore = beforeSnapshot.violations.critical;
+  const critAfter = afterSnapshot.violations.critical;
+  const critDelta = critAfter - critBefore;
+
+  const totalBefore = beforeSnapshot.violations.total;
+  const totalAfter = afterSnapshot.violations.total;
+  const totalDelta = totalAfter - totalBefore;
+
+  const monolithBefore = beforeSnapshot.monoliths.total;
+  const monolithAfter = afterSnapshot.monoliths.total;
+  const monolithDelta = monolithAfter - monolithBefore;
+
+  const tokensBefore = beforeSnapshot.tokens.estimatedExcessTokens;
+  const tokensAfter = afterSnapshot.tokens.estimatedExcessTokens;
+  const tokensDelta = tokensAfter - tokensBefore;
+
+  const pillarDeltas = {};
+  const allPillars = new Set([
+    ...Object.keys(beforeSnapshot.pillars || {}),
+    ...Object.keys(afterSnapshot.pillars || {})
+  ]);
+
+  for (const pillar of allPillars) {
+    const bPillar = beforeSnapshot.pillars?.[pillar] || { status: 'UNKNOWN', violations: 0 };
+    const aPillar = afterSnapshot.pillars?.[pillar] || { status: 'UNKNOWN', violations: 0 };
+    pillarDeltas[pillar] = {
+      beforeStatus: bPillar.status,
+      afterStatus: aPillar.status,
+      beforeViolations: bPillar.violations,
+      afterViolations: aPillar.violations,
+      improved: aPillar.violations < bPillar.violations || (bPillar.status !== 'PASSED' && aPillar.status === 'PASSED')
+    };
+  }
+
+  return {
+    scoreDelta,
+    critDelta,
+    totalDelta,
+    monolithDelta,
+    tokensDelta,
+    pillarDeltas,
+    isImproved: scoreDelta > 0 || critDelta < 0 || totalDelta < 0
+  };
+};
+
+export const formatTransformationTerminal = (beforeSnapshot, afterSnapshot) => {
+  const delta = calculateTransformationDelta(beforeSnapshot, afterSnapshot);
+  const lines = [];
+
+  const formatDeltaNumber = (val, invertPositiveGood = false) => {
+    if (val === 0) return `${DIM}0 (No change)${RESET}`;
+    const isGood = invertPositiveGood ? val < 0 : val > 0;
+    const sign = val > 0 ? `+${val}` : `${val}`;
+    const color = isGood ? GREEN : RED;
+    return `${color}${BOLD}${sign}${RESET}`;
+  };
+
+  lines.push('');
+  lines.push(`${CYAN}======================================================================${RESET}`);
+  lines.push(`${BOLD}${CYAN}   ARCHITECTURAL TRANSFORMATION : BEFORE & AFTER PROGRESSION${RESET}`);
+  lines.push(`${DIM}   Comparing baseline snapshot vs. latest refactored audit${RESET}`);
+  lines.push(`${CYAN}======================================================================${RESET}`);
+  lines.push('');
+
+  const dateBefore = new Date(beforeSnapshot.timestamp).toLocaleDateString();
+  const dateAfter = new Date(afterSnapshot.timestamp).toLocaleDateString();
+
+  lines.push(`   ${BOLD}Baseline Audit:${RESET}    ${DIM}${dateBefore} [${beforeSnapshot.id}]${RESET}`);
+  lines.push(`   ${BOLD}Latest Audit:${RESET}      ${GREEN}${dateAfter} [${afterSnapshot.id}]${RESET}`);
+  lines.push('');
+
+  lines.push(`${BOLD}   METRIC COMPARISON TABLE${RESET}`);
+  lines.push(`   ------------------------------------------------------------------`);
+  lines.push(`   ${'Metric'.padEnd(26)} ${'Before'.padEnd(16)} ${'After'.padEnd(16)} Delta`);
+  lines.push(`   ------------------------------------------------------------------`);
+
+  const scoreBeforeStr = `${beforeSnapshot.health.score} (${beforeSnapshot.health.grade})`;
+  const scoreAfterStr = `${afterSnapshot.health.score} (${afterSnapshot.health.grade})`;
+  lines.push(`   ${'Molecular Health (MHI)'.padEnd(26)} ${scoreBeforeStr.padEnd(16)} ${scoreAfterStr.padEnd(16)} ${formatDeltaNumber(delta.scoreDelta)}`);
+
+  const critBeforeStr = `${beforeSnapshot.violations.critical}`;
+  const critAfterStr = `${afterSnapshot.violations.critical}`;
+  lines.push(`   ${'Critical Hazards'.padEnd(26)} ${critBeforeStr.padEnd(16)} ${critAfterStr.padEnd(16)} ${formatDeltaNumber(delta.critDelta, true)}`);
+
+  const totalBeforeStr = `${beforeSnapshot.violations.total}`;
+  const totalAfterStr = `${afterSnapshot.violations.total}`;
+  lines.push(`   ${'Total Violations'.padEnd(26)} ${totalBeforeStr.padEnd(16)} ${totalAfterStr.padEnd(16)} ${formatDeltaNumber(delta.totalDelta, true)}`);
+
+  const monoBeforeStr = `${beforeSnapshot.monoliths.total}`;
+  const monoAfterStr = `${afterSnapshot.monoliths.total}`;
+  lines.push(`   ${'Monolith Files (>500 LOC)'.padEnd(26)} ${monoBeforeStr.padEnd(16)} ${monoAfterStr.padEnd(16)} ${formatDeltaNumber(delta.monolithDelta, true)}`);
+
+  const excessBeforeStr = `${beforeSnapshot.tokens.estimatedExcessTokens.toLocaleString()} tok`;
+  const excessAfterStr = `${afterSnapshot.tokens.estimatedExcessTokens.toLocaleString()} tok`;
+  lines.push(`   ${'Excess Token Burn'.padEnd(26)} ${excessBeforeStr.padEnd(16)} ${excessAfterStr.padEnd(16)} ${formatDeltaNumber(delta.tokensDelta, true)}`);
+
+  lines.push(`   ------------------------------------------------------------------`);
+  lines.push('');
+
+  const resolvePillarDeltaArrow = (pDelta) => {
+    if (pDelta.improved) {
+      return `${GREEN}▲ RESOLVED${RESET}`;
+    }
+    if (pDelta.beforeStatus === pDelta.afterStatus) {
+      return `${DIM}━ UNCHANGED${RESET}`;
+    }
+    return `${RED}▼ DEGRADED${RESET}`;
+  };
+
+  lines.push(`${BOLD}   7-PILLAR PROGRESSION${RESET}`);
+  lines.push(`   ------------------------------------------------------------------`);
+  for (const [pillar, pDelta] of Object.entries(delta.pillarDeltas)) {
+    const arrow = resolvePillarDeltaArrow(pDelta);
+    lines.push(`   ${pillar.padEnd(28)} ${pDelta.beforeStatus.padEnd(10)} -> ${pDelta.afterStatus.padEnd(10)} ${arrow}`);
+  }
+  lines.push(`   ------------------------------------------------------------------`);
+  lines.push('');
+
+  if (delta.isImproved) {
+    lines.push(`   ${GREEN}${BOLD}✔ CODEBASE SIGNIFICANTLY IMPROVED!${RESET}`);
+    lines.push(`   Post your transformation story to GitHub Discussions using the Share menu.`);
+  } else {
+    lines.push(`   ${YELLOW}ℹ Codebase metrics are stable or currently under refactoring.${RESET}`);
+  }
+  lines.push('');
+
+  return lines.join('\n');
+};
+
+export const formatHistoryTimelineTerminal = (history) => {
+  const lines = [];
+  lines.push('');
+  lines.push(`${CYAN}======================================================================${RESET}`);
+  lines.push(`${BOLD}${CYAN}   LOCAL AUDIT HISTORY TIMELINE (${history.length} RUNS RECORDED)${RESET}`);
+  lines.push(`${DIM}   Persistent snapshots stored in .chemx/history.json${RESET}`);
+  lines.push(`${CYAN}======================================================================${RESET}`);
+  lines.push('');
+
+  if (history.length === 0) {
+    lines.push('   No historical audits recorded yet.');
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  lines.push(`   ${'#'.padEnd(4)} ${'Date/Time'.padEnd(22)} ${'Score'.padEnd(12)} ${'Grade'.padEnd(10)} ${'Monoliths'.padEnd(12)} Hazards`);
+  lines.push(`   ------------------------------------------------------------------`);
+
+  const resolveScoreGradeColor = (score) => {
+    if (score >= 90) return GREEN;
+    if (score >= 70) return YELLOW;
+    return RED;
+  };
+
+  const renderTimelineRow = (snap, idx) => {
+    const num = `${idx + 1}`.padEnd(4);
+    const dateStr = new Date(snap.timestamp).toLocaleString().slice(0, 20).padEnd(22);
+    const scoreStr = `${snap.health.score}/100`.padEnd(12);
+    const gradeColor = resolveScoreGradeColor(snap.health.score);
+    const gradeStr = `${gradeColor}${snap.health.grade.padEnd(10)}${RESET}`;
+    const monoStr = `${snap.monoliths.total} files`.padEnd(12);
+    const hazStr = `${snap.violations.total} (Crit: ${snap.violations.critical})`;
+    lines.push(`   ${num} ${dateStr} ${scoreStr} ${gradeStr} ${monoStr} ${hazStr}`);
+  };
+
+  history.forEach(renderTimelineRow);
+
+  lines.push(`   ------------------------------------------------------------------`);
+  lines.push('');
+  return lines.join('\n');
+};