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

package/cli/audit/reporter-markdown.js

@@ -0,0 +1,137 @@
+import { buildMasterPrompt } from './prompts.js';
+import {
+  groupViolationsBySeverity,
+  resolveHealthHearts,
+  resolveMarkdownStatusIcon,
+  resolveMarkdownMonolithText,
+  PILLAR_EMOJIS,
+  NUMBER_EMOJIS
+} from './reporter-utils.js';
+
+export const generateMarkdownReport = (report) => {
+  const { metrics, health, pillars, contextAnalysis, hotspots, violations } = report;
+  const { critical, high, medium, low } = groupViolationsBySeverity(violations);
+  const lines = [];
+
+  lines.push('# Chemical X Protocol: Architectural Audit Report');
+  lines.push('');
+  lines.push('> *Comprehensive static analysis report enforcing Chemical X Molecular Architecture standards.*');
+  lines.push('');
+  lines.push('## 1. Executive Summary & Scorecard');
+  lines.push('');
+  lines.push('| Metric | Value | Status |');
+  lines.push('| :--- | :--- | :--- |');
+  const hearts = resolveHealthHearts(health?.grade, health?.score, false);
+  lines.push(`| **Life / Health Meter** | ${hearts} (Grade **${health.grade}**) | ${health.score} / 100 (${health.label}) |`);
+  lines.push(`| **Molecular Health Index** | **${health.score} / 100** | Grade: **${health.grade}** (${health.label}) |`);
+  lines.push(`| **Scanned Files** | ${metrics.scannedFiles} source files | Verified |`);
+  lines.push(`| **Total Lines of Code** | ${metrics.totalLoc} lines of code | Avg ${metrics.avgLoc} lines/file |`);
+  lines.push(`| **Largest File** | \`${metrics.largestFile.filePath || 'None'}\` | ${metrics.largestFile.lineCount} lines |`);
+  lines.push(`| **Context Token Overhead** | ~${contextAnalysis.estimatedTokens.toLocaleString()} tokens | Est. Bloat: ~${contextAnalysis.estimatedExcessTokens.toLocaleString()} tokens |`);
+  lines.push(`| **Token Reduction Target** | **${contextAnalysis.potentialSavingsPct}%** | Risk Level: **${contextAnalysis.riskLevel}** |`);
+  if (contextAnalysis.excessCostPerPass !== undefined) {
+    lines.push(`| **Monolith Cost per Turn** | **$${contextAnalysis.excessCostPerPass.toFixed(3)}** | Model: ${contextAnalysis.pricingModel} |`);
+    lines.push(`| **Projected Dev Context Tax** | **$${contextAnalysis.monthlyWastePerDev.toFixed(2)} / mo** | Est. $${contextAnalysis.weeklyWastePerDev.toFixed(2)} / week per engineer |`);
+  }
+  lines.push(`| **Total Hazards Flagged** | **${violations.length}** | Critical: ${critical.length}, High: ${high.length}, Med: ${medium.length}, Low: ${low.length} |`);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('## 2. 7-Pillar Architectural Compliance Matrix');
+  lines.push('');
+  lines.push('| Pillar | Status | Violations | Critical | High | Med | Low |');
+  lines.push('| :--- | :---: | :---: | :---: | :---: | :---: | :---: |');
+
+  for (const [pillarName, data] of Object.entries(pillars)) {
+    const icon = PILLAR_EMOJIS[pillarName] || '🏛️';
+    const statusIcon = resolveMarkdownStatusIcon(data.status);
+    const violationsText = data.violations === 0 ? '🟢 0' : `⚠️ **${data.violations}**`;
+    lines.push(`| ${icon} ${pillarName} | ${statusIcon} | ${violationsText} | ${data.critical} | ${data.high} | ${data.medium} | ${data.low} |`);
+  }
+
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('## 3. Top Refactoring Hotspots');
+  lines.push('');
+  if (hotspots.length === 0) {
+    lines.push('No hotspot files identified. All analyzed files remain within architectural line budgets.');
+  } else {
+    lines.push('| Priority | File Path | Line Count | Violations | Monolith Hazard |');
+    lines.push('| :---: | :--- | :---: | :---: | :---: |');
+    hotspots.forEach((h, idx) => {
+      const monolithText = resolveMarkdownMonolithText(h.lineCount);
+      const priorityBadge = NUMBER_EMOJIS[idx] || `${idx + 1}`;
+      lines.push(`| ${priorityBadge} | \`${h.filePath}\` | ${h.lineCount} | ${h.violationCount} | ${monolithText} |`);
+    });
+  }
+
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('## 4. Architectural Hazard Inventory (Grouped by Severity)');
+  lines.push('');
+
+  if (violations.length === 0) {
+    lines.push('Zero context hazard violations detected across all line budgets, hooks, and AST rules.');
+  } else {
+    if (critical.length > 0) {
+      lines.push('### Critical Hazards (Immediate Action Required)');
+      lines.push('');
+      lines.push('| Location | Rule | Hazard Description | Directive |');
+      lines.push('| :--- | :--- | :--- | :--- |');
+      for (const v of critical) {
+        lines.push(`| \`${v.filePath}:${v.line}:${v.column}\` | \`${v.rule}\` | ${v.hazard} | ${v.directive} |`);
+      }
+      lines.push('');
+    }
+
+    if (high.length > 0 || medium.length > 0) {
+      lines.push('### High & Medium Hazards (Architecture Debts)');
+      lines.push('');
+      lines.push('| Location | Severity | Rule | Hazard Description | Directive |');
+      lines.push('| :--- | :---: | :--- | :--- | :--- |');
+      for (const v of [...high, ...medium]) {
+        lines.push(`| \`${v.filePath}:${v.line}:${v.column}\` | ${v.severity} | \`${v.rule}\` | ${v.hazard} | ${v.directive} |`);
+      }
+      lines.push('');
+    }
+
+    if (low.length > 0) {
+      lines.push('### Low & Hygiene Issues (Typography & Logging)');
+      lines.push('');
+      lines.push('| Location | Rule | Hazard Description | Directive |');
+      lines.push('| :--- | :--- | :--- | :--- |');
+      for (const v of low) {
+        lines.push(`| \`${v.filePath}:${v.line}:${v.column}\` | \`${v.rule}\` | ${v.hazard} | ${v.directive} |`);
+      }
+      lines.push('');
+    }
+  }
+
+  lines.push('---');
+  lines.push('');
+  lines.push('## 5. Remediation Roadmap');
+  lines.push('');
+  lines.push('1. **Decompose Monoliths**: Break down any file exceeding 500 lines into single-responsibility capsules.');
+  lines.push('2. **Cap Molecule Size**: Ensure all molecule components (`m-*`) remain strictly under 100 lines.');
+  lines.push('3. **Two-Stage Boolean Logic**: Replace complex multi-clause expressions with atomic boolean variables.');
+  lines.push('4. **Lifecycle-Safe Timers**: Migrate raw `setInterval` and `setTimeout` calls to self-cleaning composables.');
+  lines.push('');
+
+  const masterPrompt = buildMasterPrompt(report);
+  if (masterPrompt) {
+    lines.push('---');
+    lines.push('');
+    lines.push('## 6. 🤖 Copy-Paste AI Agent Refactoring Directives');
+    lines.push('');
+    lines.push('Feed the prompt below directly into your AI coding agent (Cursor, Windsurf, Claude, Copilot, or Antigravity) to surgically refactor flagged hazards:');
+    lines.push('');
+    lines.push('```markdown');
+    lines.push(masterPrompt);
+    lines.push('```');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+};

package/cli/audit/reporter-utils.js

@@ -0,0 +1,125 @@
+export const CYAN = '\x1b[38;2;98;201;255m';
+export const GREEN = '\x1b[32m';
+export const YELLOW = '\x1b[33m';
+export const RED = '\x1b[31m';
+export const ORANGE = '\x1b[38;5;208m';
+export const DIM = '\x1b[2m';
+export const BOLD = '\x1b[1m';
+export const RESET = '\x1b[0m';
+
+export const groupViolationsBySeverity = (violations) => {
+  const critical = [];
+  const high = [];
+  const medium = [];
+  const low = [];
+
+  for (const v of violations) {
+    if (v.severity === 'CRITICAL') critical.push(v);
+    else if (v.severity === 'HIGH') high.push(v);
+    else if (v.severity === 'MEDIUM') medium.push(v);
+    else low.push(v);
+  }
+
+  return { critical, high, medium, low };
+};
+
+export const getSeverityBadge = (severity) => {
+  switch (severity) {
+    case 'CRITICAL':
+      return `${RED}[CRITICAL]${RESET}`;
+    case 'HIGH':
+      return `${ORANGE}[HIGH]${RESET}`;
+    case 'MEDIUM':
+      return `${ORANGE}[MEDIUM]${RESET}`;
+    case 'LOW':
+      return `${YELLOW}[LOW]${RESET}`;
+    default:
+      return `[${severity}]`;
+  }
+};
+
+export const getStatusBadge = (status) => {
+  switch (status) {
+    case 'PASSED':
+      return `${GREEN}✔ PASS${RESET}`;
+    case 'WARN':
+      return `${YELLOW}⚠ WARN${RESET}`;
+    case 'FAILED':
+      return `${RED}✕ FAIL${RESET}`;
+    default:
+      return status;
+  }
+};
+
+export const resolveGradeColor = (scoreOrGrade) => {
+  if (typeof scoreOrGrade === 'string') {
+    const g = scoreOrGrade.toUpperCase();
+    if (g.startsWith('A')) return GREEN;
+    if (g === 'B' || g === 'C') return YELLOW;
+    if (g === 'D') return ORANGE;
+    return RED;
+  }
+  if (scoreOrGrade >= 90) return GREEN;
+  if (scoreOrGrade >= 70) return YELLOW;
+  return RED;
+};
+
+export const resolveRiskColor = (riskLevel) => {
+  if (riskLevel === 'HIGH') return RED;
+  if (riskLevel === 'MODERATE') return YELLOW;
+  return GREEN;
+};
+
+export const resolveHotspotBadge = (lineCount) => {
+  if (lineCount >= 2000) return ` ${RED}[CRITICAL MONOLITH >= 2,000 lines of code]${RESET}`;
+  if (lineCount >= 1000) return ` ${ORANGE}[SEVERE MONOLITH >= 1,000 lines of code]${RESET}`;
+  if (lineCount > 500) return ` ${YELLOW}[MONOLITH WARNING > 500 lines of code]${RESET}`;
+  return '';
+};
+
+export const resolveHealthHearts = (grade, score = 0, isAnsi = true) => {
+  const g = String(grade || '').toUpperCase();
+  let filled = 1;
+  if (g.startsWith('A') || score >= 90) filled = 5;
+  else if (g.startsWith('B') || score >= 80) filled = 4;
+  else if (g.startsWith('C') || score >= 70) filled = 3;
+  else if (g.startsWith('D') || score >= 60) filled = 2;
+  else filled = score === 0 ? 0 : 1;
+
+  const empty = 5 - filled;
+  if (!isAnsi) {
+    return '❤︎'.repeat(filled) + '♡'.repeat(empty);
+  }
+  const redHearts = `${RED}${BOLD}` + '❤︎'.repeat(filled) + RESET;
+  const dimHearts = `${DIM}` + '♡'.repeat(empty) + RESET;
+  return `${redHearts}${dimHearts}`;
+};
+
+export const PILLAR_EMOJIS = {
+  'Line Budgets & Monolith Decomposition': '📏',
+  'Control Flow & Boolean Logic': '🔀',
+  'Reactivity & Composable Contracts': '⚛️',
+  'Type Architecture & Data Integrity': '🛡️',
+  'Design System & Styling Hygiene': '🎨',
+  'Timers & Macro-Task Discipline': '⏱️',
+  'Global Hygiene & Typography': '🧹'
+};
+
+export const NUMBER_EMOJIS = ['1️⃣', '2️⃣', '3️⃣', '4️⃣', '5️⃣', '6️⃣', '7️⃣', '8️⃣', '9️⃣', '🔟'];
+
+export const resolvePriorityBadge = (idx) => {
+  return NUMBER_EMOJIS[idx] || `${idx + 1}`;
+};
+
+export const resolveMarkdownStatusIcon = (status) => {
+  if (status === 'PASSED') return '🟢 **PASSED**';
+  if (status === 'WARN') return '🟡 **WARN**';
+  return '🔴 **FAILED**';
+};
+
+export const resolveMarkdownMonolithText = (lineCount) => {
+  if (lineCount >= 2000) return '🔴 **CRITICAL (>= 2,000 lines of code)**';
+  if (lineCount >= 1000) return '🟠 **SEVERE (>= 1,000 lines of code)**';
+  if (lineCount > 500) return '🟡 **WARNING (> 500 lines of code)**';
+  return '🟢 Compliant';
+};