@chemx/starter-kit 26.9.12-93 → 26.9.13-272

package/cli/audit/social-gh.js

@@ -3,6 +3,7 @@ import {
   DISCUSSION_CATEGORY,
   DISCUSSION_CATEGORY_SLUG
 } from './social-constants.js';
+import { matchesDiscussionTitle } from './rules-predicates.js';
 
 export const publishDiscussionViaGh = (repo, title, body, category = DISCUSSION_CATEGORY) => {
   try {
@@ -110,12 +111,7 @@ export const findExistingDiscussionViaGh = (repo, projectName) => {
       const targetLower = projectName.toLowerCase();
       const match = list.find((d) => {
         const titleLower = (d.title || '').toLowerCase();
-        return (
-          titleLower.includes(` ${targetLower} :`) ||
-          titleLower.includes(` ${targetLower} [`) ||
-          titleLower.includes(`: ${targetLower}`) ||
-          titleLower.includes(`${targetLower} audit`)
-        );
+        return matchesDiscussionTitle(titleLower, targetLower);
       });
       return match || null;
     }

package/cli/audit/social-publisher.js

@@ -59,7 +59,7 @@ export {
 export const formatArchiveComment = (previousTitle, previousBody) => {
   const archiveTimestamp = new Date().toUTCString();
   return [
-    '## 📜 Previous Audit Snapshot (Archived)',
+    '## ⏱️ Audit Checkpoint Snapshot (Archived)',
     '',
     `> **Archived on:** ${archiveTimestamp}`,
     `> **Previous Status:** ${previousTitle || 'Prior Report'}`,

package/cli/audit/social.js

@@ -1,5 +1,10 @@
 import { groupViolationsBySeverity } from './reporter.js';
-import { PILLAR_EMOJIS } from './reporter-utils.js';
+import {
+  PILLAR_EMOJIS,
+  formatPillarReactionBadgesMarkdown,
+  formatPillarShieldBadges,
+  resolveBadgeColor
+} from './reporter-utils.js';
 
 export {
   parseGitRemoteUrl,
@@ -31,11 +36,7 @@ export const DISCUSSION_CATEGORY_SLUG = 'npx-chemx-audit';
 export const ORG_DISCUSSIONS_URL = 'https://github.com/orgs/Chemical-X-Protocol/discussions';
 export const DEFAULT_DISCUSSION_REPO = 'Chemical-X-Protocol/.github';
 
-export const resolveBadgeColor = (score) => {
-  if (score >= 90) return '06b6d4';
-  if (score >= 70) return 'f59e0b';
-  return 'ef4444';
-};
+export { resolveBadgeColor };
 
 export const resolveHotspotTierText = (lineCount) => {
   if (lineCount >= 2000) return '🔴 **CRITICAL (>= 2,000 lines of code)**';
@@ -101,8 +102,13 @@ export const generateDiscussionContent = (report, username, projectName = 'Codeb
   const lines = [];
   lines.push(`# ${isHighScoring ? 'Crystalline' : 'Architecture'} Audit Report: ${projectName}`);
   lines.push('');
-  lines.push(`[![Chemical X MHI](https://img.shields.io/badge/Chemical%20X%20MHI-${encodedGrade}-${badgeColor}?style=for-the-badge)](https://chemicalx.xophz.com) [![AI Slop Index](https://img.shields.io/badge/AI%20Slop%20Index-${encodedSlop}-${slopBadgeColor}?style=for-the-badge)](https://chemicalx.xophz.com)`);
+  lines.push(`[![Chemical X Showcase](https://img.shields.io/badge/Chemical%20X-Showcase-62c9ff?style=for-the-badge)](https://chemicalx.xophz.com) [![Chemical X MHI](https://img.shields.io/badge/Chemical%20X%20MHI-${encodedGrade}-${badgeColor}?style=for-the-badge)](https://chemicalx.xophz.com) [![AI Slop Index](https://img.shields.io/badge/AI%20Slop%20Index-${encodedSlop}-${slopBadgeColor}?style=for-the-badge)](https://chemicalx.xophz.com)`);
   lines.push('');
+  const pillarShields = formatPillarShieldBadges(pillars);
+  if (pillarShields) {
+    lines.push(pillarShields);
+    lines.push('');
+  }
   lines.push(`* **Audited by**: @${username}`);
   const resolvedRepoUrl = repoUrl || (/^[\w\-.]+\/[\w\-.]+$/.test(projectName) ? `https://github.com/${projectName}` : '');
   if (resolvedRepoUrl) {
@@ -241,11 +247,21 @@ export const generateTransformationDiscussionContent = (
     return isGood ? `🟢 **${sign}**` : `🔴 **${sign}**`;
   };
 
+  const beforeColor = resolveBadgeColor(scoreBefore);
+  const afterColor = resolveBadgeColor(scoreAfter);
+  const encodedBeforeGrade = encodeURIComponent(`${scoreBefore}/100 (${beforeSnapshot.health.grade})`);
+  const encodedAfterGrade = encodeURIComponent(`${scoreAfter}/100 (${afterSnapshot.health.grade})`);
+
   const lines = [];
   lines.push(`# 🚀 Architectural Transformation: ${projectName}`);
   lines.push('');
-  lines.push(`[![Chemical X Transformation](https://img.shields.io/badge/Chemical%20X-Transformation%20Showcase-62c9ff?style=for-the-badge)](https://chemicalx.xophz.com)`);
+  lines.push(`[![Chemical X Transformation](https://img.shields.io/badge/Chemical%20X-Transformation%20Showcase-62c9ff?style=for-the-badge)](https://chemicalx.xophz.com) [![Before MHI](https://img.shields.io/badge/Before%20MHI-${encodedBeforeGrade}-${beforeColor}?style=for-the-badge)](https://chemicalx.xophz.com) [![After MHI](https://img.shields.io/badge/After%20MHI-${encodedAfterGrade}-${afterColor}?style=for-the-badge)](https://chemicalx.xophz.com)`);
   lines.push('');
+  const afterPillarShields = formatPillarShieldBadges(afterSnapshot.pillars);
+  if (afterPillarShields) {
+    lines.push(afterPillarShields);
+    lines.push('');
+  }
   lines.push(`* **Audited by**: @${username}`);
   const resolvedRepoUrl = repoUrl || (/^[\w\-.]+\/[\w\-.]+$/.test(projectName) ? `https://github.com/${projectName}` : '');
   if (resolvedRepoUrl) {
@@ -263,7 +279,7 @@ export const generateTransformationDiscussionContent = (
   lines.push('');
   lines.push('## 1. Before vs. After Metric Comparison');
   lines.push('');
-  lines.push('| Metric | Before (Baseline) | After (Refactored) | Delta |');
+  lines.push('| Metric | Before (Baseline Floor) | After (Refactored) | Delta |');
   lines.push('| :--- | :---: | :---: | :---: |');
   lines.push(`| **Molecular Health (MHI)** | ${scoreBefore} / 100 (${beforeSnapshot.health.grade}) | ${scoreAfter} / 100 (${afterSnapshot.health.grade}) | ${formatDelta(scoreDelta)} |`);
   const slopBefore = beforeSnapshot.aiSlop?.score ?? 100;

package/cli/audit/types.d.ts

@@ -87,6 +87,41 @@ export interface AiSlopScore {
   };
 }
 
+export interface PatternOccurrence {
+  readonly filePath: string;
+  readonly line: number;
+  readonly column?: number;
+}
+
+export interface PatternCandidate {
+  readonly id: string;
+  readonly type: 'UI_STRUCTURE' | 'STATE_UNION' | 'PREDICATE_LOGIC' | 'HOOK_SIGNATURE';
+  readonly label: string;
+  readonly detail: string;
+  readonly suggestedCapsule: string;
+  readonly recommendation: string;
+  readonly fileCount: number;
+  readonly totalHits: number;
+  readonly hasHotspot: boolean;
+  readonly impactScore: number;
+  readonly occurrences: readonly PatternOccurrence[];
+}
+
+export interface RoadmapItem {
+  readonly title: string;
+  readonly target: string;
+  readonly action: string;
+  readonly locations: readonly string[];
+}
+
+export interface RoadmapPhase {
+  readonly step: number;
+  readonly phase: string;
+  readonly roi: string;
+  readonly rationale: string;
+  readonly items: readonly RoadmapItem[];
+}
+
 export interface AuditReport {
   readonly scannedFiles: number;
   readonly totalViolations: number;
@@ -96,6 +131,8 @@ export interface AuditReport {
   readonly pillars: Record<string, PillarData>;
   readonly contextAnalysis: ContextTokenAnalysis;
   readonly hotspots: readonly HotspotFile[];
+  readonly patterns?: readonly PatternCandidate[];
+  readonly roadmap?: readonly RoadmapPhase[];
   readonly violations: readonly HazardViolation[];
 }
 
@@ -123,14 +160,24 @@ export declare function calculateAiSlopScore(violations: readonly HazardViolatio
 export * from './reporter';
 export * from './social';
 
-export declare function buildGradeFPrompt(report: AuditReport): string;
-export declare function buildGradeDPrompt(report: AuditReport): string;
-export declare function buildGradeCPrompt(report: AuditReport): string;
-export declare function buildGradeBPrompt(report: AuditReport): string;
+export interface PromptOptions {
+  readonly excludeAiSlop?: boolean;
+}
+
+export declare function formatGroupedPromptViolations(violations?: readonly HazardViolation[]): string[];
+export declare function buildGradeFPrompt(report: AuditReport, options?: PromptOptions): string;
+export declare function buildGradeDPrompt(report: AuditReport, options?: PromptOptions): string;
+export declare function buildGradeCPrompt(report: AuditReport, options?: PromptOptions): string;
+export declare function buildGradeBPrompt(report: AuditReport, options?: PromptOptions): string;
 export declare function buildAiSlopPrompt(report: AuditReport): string;
 export declare function buildHotspotsPrompt(report: AuditReport): string;
 export declare function buildMasterPrompt(report: AuditReport): string;
 export declare function formatPromptBox(title: string, promptText: string): string;
 
-export * from './history';
+export declare function buildRemediationRoadmap(report: AuditReport): RoadmapPhase[];
+export declare function formatRoadmapSection(report: AuditReport, themeColor?: string | null): string;
+export declare function formatRoadmapMarkdown(report: AuditReport): string;
+export declare function buildSelfHealingRoadmapPrompt(report: AuditReport): string;
 
+export * from './history';
+export * from './rules-predicates';

package/cli/audit.js

@@ -1,6 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { auditCode, PILLARS, RULE_REGISTRY } from './audit/rules.js';
+import { createPatternRegistry } from './audit/pattern-detector.js';
+import {
+  buildRemediationRoadmap,
+  formatRoadmapSection,
+  formatRoadmapMarkdown,
+  buildSelfHealingRoadmapPrompt
+} from './audit/roadmap.js';
 import {
   calculateMolecularHealthScore,
   calculateQuantumHealthScore,
@@ -38,8 +45,24 @@ import {
   getAsciiGradeLines,
   formatAsciiGrade,
   getReportCardAsciiLines,
-  REPORT_CARD_ASCII
+  REPORT_CARD_ASCII,
+  formatPillarReactionBadgesTerminal,
+  formatPillarReactionBadgesMarkdown,
+  formatPillarShieldBadges,
+  resolveBadgeColor,
+  PILLAR_SHORT_NAMES
 } from './audit/reporter.js';
+import {
+  buildGradeFPrompt,
+  buildGradeDPrompt,
+  buildGradeCPrompt,
+  buildGradeBPrompt,
+  buildAiSlopPrompt,
+  buildHotspotsPrompt,
+  buildMasterPrompt,
+  formatPromptBox,
+  formatGroupedPromptViolations
+} from './audit/prompts.js';
 
 const IGNORED_DIRS = new Set([
   'node_modules',
@@ -70,10 +93,11 @@ export const auditFile = (filePath, relativePath) => {
   return auditCode(content, filePath, relativePath);
 };
 
-export const scanTree = (targetDir, baseDir) => {
+export const scanTree = (targetDir, baseDir, scanOptions = {}) => {
   let violations = [];
   let fileStats = [];
   let totalHooks = 0;
+  const { patternRegistry } = scanOptions;
 
   if (!fs.existsSync(targetDir)) {
     return { violations, fileStats, totalHooks };
@@ -86,7 +110,7 @@ export const scanTree = (targetDir, baseDir) => {
 
     if (entry.isDirectory()) {
       if (!IGNORED_DIRS.has(entry.name)) {
-        const sub = scanTree(fullPath, baseDir);
+        const sub = scanTree(fullPath, baseDir, scanOptions);
         violations = violations.concat(sub.violations);
         fileStats = fileStats.concat(sub.fileStats);
         totalHooks += sub.totalHooks;
@@ -110,7 +134,7 @@ export const scanTree = (targetDir, baseDir) => {
         totalHooks += hookMatches.length;
       }
 
-      const fileViolations = auditCode(content, fullPath, relPath);
+      const fileViolations = auditCode(content, fullPath, relPath, { patternRegistry });
       violations = violations.concat(fileViolations);
     }
   }
@@ -126,7 +150,8 @@ export const scanDirectory = (targetDir, baseDir) => {
 export const runAudit = (targetDir = 'src', options = {}) => {
   const cwd = process.cwd();
   const absoluteTarget = path.resolve(cwd, targetDir);
-  const { violations, fileStats, totalHooks } = scanTree(absoluteTarget, cwd);
+  const patternRegistry = createPatternRegistry();
+  const { violations, fileStats, totalHooks } = scanTree(absoluteTarget, cwd, { patternRegistry });
 
   const scannedFiles = fileStats.length;
   const totalLoc = fileStats.reduce((acc, f) => acc + f.lineCount, 0);
@@ -168,6 +193,8 @@ export const runAudit = (targetDir = 'src', options = {}) => {
   const contextAnalysis = calculateTokenBurnAnalytics(fileStats, options);
   const hotspots = calculateHotspots(violations, fileStats, 5);
   const aiSlop = calculateAiSlopScore(violations, scannedFiles);
+  const patterns = patternRegistry.resolveHarmonizationCandidates(hotspots);
+  const roadmap = buildRemediationRoadmap({ hotspots, violations, patterns });
 
   const report = {
     targetDir,
@@ -180,6 +207,8 @@ export const runAudit = (targetDir = 'src', options = {}) => {
     pillars,
     contextAnalysis,
     hotspots,
+    patterns,
+    roadmap,
     violations
   };
 
@@ -233,9 +262,30 @@ export {
   getAsciiGradeLines,
   formatAsciiGrade,
   getReportCardAsciiLines,
-  REPORT_CARD_ASCII
+  REPORT_CARD_ASCII,
+  formatPillarReactionBadgesTerminal,
+  formatPillarReactionBadgesMarkdown,
+  formatPillarShieldBadges,
+  resolveBadgeColor,
+  PILLAR_SHORT_NAMES,
+  buildGradeFPrompt,
+  buildGradeDPrompt,
+  buildGradeCPrompt,
+  buildGradeBPrompt,
+  buildAiSlopPrompt,
+  buildHotspotsPrompt,
+  buildMasterPrompt,
+  formatPromptBox,
+  formatGroupedPromptViolations,
+  createPatternRegistry,
+  buildRemediationRoadmap,
+  formatRoadmapSection,
+  formatRoadmapMarkdown,
+  buildSelfHealingRoadmapPrompt
 };
 
+export * from './audit/rules-predicates.js';
+
 export default {
   auditFile,
   scanDirectory,
@@ -269,6 +319,25 @@ export default {
   formatAsciiGrade,
   getReportCardAsciiLines,
   REPORT_CARD_ASCII,
+  formatPillarReactionBadgesTerminal,
+  formatPillarReactionBadgesMarkdown,
+  formatPillarShieldBadges,
+  resolveBadgeColor,
+  PILLAR_SHORT_NAMES,
   PILLARS,
-  RULE_REGISTRY
+  RULE_REGISTRY,
+  buildGradeFPrompt,
+  buildGradeDPrompt,
+  buildGradeCPrompt,
+  buildGradeBPrompt,
+  buildAiSlopPrompt,
+  buildHotspotsPrompt,
+  buildMasterPrompt,
+  formatPromptBox,
+  formatGroupedPromptViolations,
+  createPatternRegistry,
+  buildRemediationRoadmap,
+  formatRoadmapSection,
+  formatRoadmapMarkdown,
+  buildSelfHealingRoadmapPrompt
 };

package/cli/badge.js

@@ -53,7 +53,7 @@ export const generateHtmlBadgeSnippet = (label, grade, discussionUrl = null) =>
   const targetHref = discussionUrl || 'https://chemicalx.xophz.com';
   const targetTitle = discussionUrl ? 'Verified Chemical X Audit Report on GitHub Discussions' : 'Verified by Chemical X Protocol';
 
-  return `<a href="${targetHref}" target="_blank" rel="noopener noreferrer" style="display:inline-flex;align-items:center;gap:8px;padding:4px 12px;border-radius:9999px;font-family:monospace;font-size:11px;text-decoration:none;border:1px solid rgba(255,255,255,0.15);background:rgba(15,23,42,0.65);backdrop-filter:blur(8px);color:#e2e8f0;transition:all 0.2s ease;" title="${targetTitle}">
+  return `<a href="${targetHref}" target="_blank" rel="noopener noreferrer" style="display:inline-flex;align-items:center;gap:8px;padding:4px 12px;border-radius:9999px;font-family:monospace;font-size:11px;text-decoration:none;border:1px solid rgba(56,189,248,0.35);background:rgba(9,13,22,0.85);backdrop-filter:blur(8px);color:#e2e8f0;transition:all 0.2s ease;" title="${targetTitle}">
   <span style="width:8px;height:8px;border-radius:50%;background:#a3e635;box-shadow:0 0 6px rgba(163,230,53,0.6);"></span>
   <span>${label}</span>
   <span style="padding:2px 7px;border-radius:9999px;font-weight:bold;font-size:10px;background:rgba(163,230,53,0.15);color:#a3e635;border:1px solid rgba(163,230,53,0.3);">${grade}</span>
@@ -155,7 +155,14 @@ export default ChemicalXBadge;
 export const generateSvgBadgeSnippet = (label, grade) => {
   const width = Math.max(280, label.length * 8 + 60);
   return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="28" viewBox="0 0 ${width} 28" fill="none">
-  <rect width="${width}" height="28" rx="14" fill="#090d16" stroke="#26354a" stroke-width="1"/>
+  <defs>
+    <linearGradient id="chemx-comic" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#f43f85"/>
+      <stop offset="50%" stop-color="#38bdf8"/>
+      <stop offset="100%" stop-color="#a3e635"/>
+    </linearGradient>
+  </defs>
+  <rect width="${width}" height="28" rx="14" fill="#090d16" stroke="url(#chemx-comic)" stroke-width="1.2"/>
   <circle cx="16" cy="14" r="4" fill="#a3e635"/>
   <text x="28" y="17" fill="#cbd5e1" font-family="monospace" font-size="11" font-weight="500">${label}</text>
   <rect x="${width - 44}" y="6" width="34" height="16" rx="8" fill="#a3e635" fill-opacity="0.18" stroke="#a3e635" stroke-opacity="0.4"/>

package/cli/build/detector.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const findFileUpward = (fileName, startDir) => {
+  let currentDir = path.resolve(startDir);
+  while (true) {
+    const candidate = path.join(currentDir, fileName);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(currentDir);
+    if (parent === currentDir) break;
+    currentDir = parent;
+  }
+  return null;
+};
+
+const resolvePackageManager = (cwd) => {
+  const hasPnpmLock = Boolean(findFileUpward('pnpm-lock.yaml', cwd));
+  const hasYarnLock = Boolean(findFileUpward('yarn.lock', cwd));
+  const hasBunLock = Boolean(findFileUpward('bun.lockb', cwd) || findFileUpward('bun.lock', cwd));
+
+  if (hasPnpmLock) return 'pnpm';
+  if (hasYarnLock) return 'yarn';
+  if (hasBunLock) return 'bun';
+  return 'npm';
+};
+
+const loadLocalPackageJson = (cwd) => {
+  const pkgPath = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+};
+
+export const detectProjectBuildCommand = (customCmd, cwd = process.cwd()) => {
+  const hasCustomCommand = Boolean(customCmd && customCmd.trim().length > 0);
+  if (hasCustomCommand) return customCmd.trim();
+
+  const pm = resolvePackageManager(cwd);
+  const pkg = loadLocalPackageJson(cwd);
+  const scripts = (pkg && pkg.scripts) || {};
+
+  const hasBuildScript = Boolean(scripts.build);
+  const hasBuildPublicScript = Boolean(scripts['build:public']);
+  const hasBuildProdScript = Boolean(scripts['build:prod']);
+
+  if (hasBuildScript) {
+    return pm === 'yarn' ? 'yarn build' : `${pm} run build`;
+  }
+  if (hasBuildPublicScript) {
+    return pm === 'yarn' ? 'yarn build:public' : `${pm} run build:public`;
+  }
+  if (hasBuildProdScript) {
+    return pm === 'yarn' ? 'yarn build:prod' : `${pm} run build:prod`;
+  }
+
+  const hasViteConfig = fs.existsSync(path.join(cwd, 'vite.config.js')) ||
+    fs.existsSync(path.join(cwd, 'vite.config.ts')) ||
+    fs.existsSync(path.join(cwd, 'vite.config.mjs'));
+  if (hasViteConfig) return 'npx vite build';
+
+  const hasTsConfig = fs.existsSync(path.join(cwd, 'tsconfig.json'));
+  if (hasTsConfig) return 'npx tsc --noEmit';
+
+  return `${pm} run build`;
+};

package/cli/build/executor.js

@@ -0,0 +1,58 @@
+import { spawn } from 'node:child_process';
+
+export const executeBuild = (command, cwd = process.cwd(), options = {}) => {
+  return new Promise((resolve) => {
+    const startTime = Date.now();
+    let stdoutBuffer = '';
+    let stderrBuffer = '';
+
+    const isRawStream = Boolean(options.raw);
+
+    const child = spawn(command, {
+      shell: true,
+      cwd,
+      stdio: ['inherit', 'pipe', 'pipe'],
+      env: { ...process.env, FORCE_COLOR: '1' }
+    });
+
+    child.stdout.on('data', (chunk) => {
+      const text = chunk.toString();
+      stdoutBuffer += text;
+      if (isRawStream) {
+        process.stdout.write(text);
+      }
+    });
+
+    child.stderr.on('data', (chunk) => {
+      const text = chunk.toString();
+      stderrBuffer += text;
+      if (isRawStream) {
+        process.stderr.write(text);
+      }
+    });
+
+    child.on('error', (err) => {
+      const durationMs = Date.now() - startTime;
+      stderrBuffer += `\nProcess error: ${err.message}\n`;
+      resolve({
+        exitCode: 1,
+        stdout: stdoutBuffer,
+        stderr: stderrBuffer,
+        durationMs,
+        command
+      });
+    });
+
+    child.on('close', (code) => {
+      const durationMs = Date.now() - startTime;
+      const normalizedCode = code === null ? 1 : code;
+      resolve({
+        exitCode: normalizedCode,
+        stdout: stdoutBuffer,
+        stderr: stderrBuffer,
+        durationMs,
+        command
+      });
+    });
+  });
+};

package/cli/build/grouper.js

@@ -0,0 +1,78 @@
+import { stripAnsi } from '../terminal.js';
+
+const buildDiagnosticKey = (d) => {
+  return `${d.category}|${d.file || ''}|${d.line || 0}|${d.column || 0}|${d.code || ''}|${d.message}`;
+};
+
+export const deduplicateDiagnostics = (diagnostics) => {
+  const seen = new Set();
+  const unique = [];
+
+  for (const item of diagnostics) {
+    const key = buildDiagnosticKey(item);
+    if (!seen.has(key)) {
+      seen.add(key);
+      unique.push(item);
+    }
+  }
+
+  return unique;
+};
+
+export const computeSummaryCounts = (diagnostics) => {
+  let errorCount = 0;
+  let warningCount = 0;
+  const uniqueFiles = new Set();
+
+  for (const item of diagnostics) {
+    if (item.severity === 'ERROR') errorCount += 1;
+    if (item.severity === 'WARNING') warningCount += 1;
+    if (item.file) uniqueFiles.add(item.file);
+  }
+
+  return {
+    total: diagnostics.length,
+    errors: errorCount,
+    warnings: warningCount,
+    files: uniqueFiles.size
+  };
+};
+
+export const computeCategoryBreakdown = (diagnostics) => {
+  const categories = {};
+  for (const item of diagnostics) {
+    categories[item.category] = (categories[item.category] || 0) + 1;
+  }
+  return categories;
+};
+
+export const extractRawTailLines = (stdout, stderr, maxLines = 15) => {
+  const combined = `${stdout}\n${stderr}`;
+  const lines = combined
+    .split(/\r?\n/)
+    .map((l) => stripAnsi(l).trim())
+    .filter((l) => l.length > 0);
+  return lines.slice(-maxLines);
+};
+
+export const groupBuildDiagnostics = (rawDiagnostics, executionResult) => {
+  const unique = deduplicateDiagnostics(rawDiagnostics);
+  const counts = computeSummaryCounts(unique);
+  const categories = computeCategoryBreakdown(unique);
+
+  const shouldCaptureTail = executionResult.exitCode !== 0 && unique.length === 0;
+  const rawTail = shouldCaptureTail
+    ? extractRawTailLines(executionResult.stdout, executionResult.stderr)
+    : [];
+
+  return {
+    success: executionResult.exitCode === 0,
+    exitCode: executionResult.exitCode,
+    durationMs: executionResult.durationMs,
+    command: executionResult.command,
+    counts,
+    categories,
+    diagnostics: unique,
+    rawTail
+  };
+};