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

package/cli/audit/social-publisher.js

@@ -0,0 +1,193 @@
+import {
+  DISCUSSION_CATEGORY,
+  DISCUSSION_CATEGORY_SLUG,
+  ORG_DISCUSSIONS_URL,
+  DEFAULT_DISCUSSION_REPO
+} from './social-constants.js';
+
+import {
+  getStoredDiscussion,
+  saveStoredDiscussion,
+  clearStoredDiscussion
+} from './discussion-store.js';
+
+import {
+  findMatchedCategory,
+  publishDiscussionViaHttp,
+  viewDiscussionViaHttp,
+  postDiscussionCommentViaHttp,
+  editDiscussionViaHttp
+} from './social-http.js';
+
+import {
+  publishDiscussionViaGh,
+  viewDiscussionViaGh,
+  postDiscussionCommentViaGh,
+  editDiscussionViaGh,
+  findExistingDiscussionViaGh
+} from './social-gh.js';
+
+export {
+  DISCUSSION_CATEGORY,
+  DISCUSSION_CATEGORY_SLUG,
+  ORG_DISCUSSIONS_URL,
+  DEFAULT_DISCUSSION_REPO
+} from './social-constants.js';
+
+export {
+  getStoredDiscussion,
+  saveStoredDiscussion,
+  clearStoredDiscussion
+} from './discussion-store.js';
+
+export {
+  findMatchedCategory,
+  publishDiscussionViaHttp,
+  viewDiscussionViaHttp,
+  postDiscussionCommentViaHttp,
+  editDiscussionViaHttp
+} from './social-http.js';
+
+export {
+  publishDiscussionViaGh,
+  viewDiscussionViaGh,
+  postDiscussionCommentViaGh,
+  editDiscussionViaGh,
+  findExistingDiscussionViaGh
+} from './social-gh.js';
+
+export const formatArchiveComment = (previousTitle, previousBody) => {
+  const archiveTimestamp = new Date().toUTCString();
+  return [
+    '## 📜 Previous Audit Snapshot (Archived)',
+    '',
+    `> **Archived on:** ${archiveTimestamp}`,
+    `> **Previous Status:** ${previousTitle || 'Prior Report'}`,
+    '',
+    '---',
+    '',
+    previousBody
+  ].join('\n');
+};
+
+export const publishDiscussion = async (repo, title, body, category = DISCUSSION_CATEGORY) => {
+  const envToken = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+  if (envToken) {
+    const httpResult = await publishDiscussionViaHttp(envToken, repo, title, body, category);
+    if (httpResult.success) {
+      return httpResult;
+    }
+  }
+
+  return publishDiscussionViaGh(repo, title, body, category);
+};
+
+export const publishOrUpdateDiscussion = async (
+  repo = DEFAULT_DISCUSSION_REPO,
+  title,
+  body,
+  category = DISCUSSION_CATEGORY,
+  options = {}
+) => {
+  const envToken = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+  const stored = getStoredDiscussion();
+  const targetRepo = repo || DEFAULT_DISCUSSION_REPO;
+
+  let existingDiscussion = null;
+
+  if (stored && stored.number && (!stored.repo || stored.repo === targetRepo)) {
+    if (envToken) {
+      existingDiscussion = await viewDiscussionViaHttp(envToken, targetRepo, stored.number);
+    }
+    if (!existingDiscussion) {
+      existingDiscussion = viewDiscussionViaGh(targetRepo, stored.number);
+    }
+  }
+
+  if (!existingDiscussion && options.projectName) {
+    existingDiscussion = findExistingDiscussionViaGh(targetRepo, options.projectName);
+  }
+
+  if (existingDiscussion && existingDiscussion.number) {
+    const discussionNumber = existingDiscussion.number;
+    const discussionId = existingDiscussion.id || stored?.discussionId;
+    const previousBody = existingDiscussion.body || '';
+
+    const hasPreviousBody = previousBody.trim().length > 0;
+    if (hasPreviousBody) {
+      const archiveComment = formatArchiveComment(existingDiscussion.title, previousBody);
+
+      if (envToken && discussionId) {
+        await postDiscussionCommentViaHttp(envToken, discussionId, archiveComment);
+      } else {
+        postDiscussionCommentViaGh(targetRepo, discussionNumber, archiveComment);
+      }
+    }
+
+    let editSuccess = false;
+    if (envToken && discussionId) {
+      editSuccess = await editDiscussionViaHttp(envToken, discussionId, title, body);
+    }
+    if (!editSuccess) {
+      editSuccess = editDiscussionViaGh(targetRepo, discussionNumber, title, body);
+    }
+
+    const fallbackUrl = `https://github.com/${targetRepo}/discussions/${discussionNumber}`;
+    const discussionUrl = existingDiscussion.url || stored?.url || fallbackUrl;
+
+    if (editSuccess) {
+      saveStoredDiscussion({
+        repo: targetRepo,
+        number: discussionNumber,
+        discussionId,
+        url: discussionUrl,
+        projectName: options.projectName || stored?.projectName || '',
+        website: options.website || stored?.website || '',
+        title,
+        lastPublishedAt: new Date().toISOString()
+      });
+
+      return {
+        success: true,
+        url: discussionUrl,
+        updated: true,
+        discussionNumber,
+        error: null
+      };
+    }
+  }
+
+  const pubResult = await publishDiscussion(targetRepo, title, body, category);
+  if (pubResult.success && pubResult.url) {
+    const match = pubResult.url.match(/\/discussions\/(\d+)/);
+    const parsedNumber = match ? parseInt(match[1], 10) : null;
+    const discussionNumber = pubResult.number || parsedNumber;
+
+    saveStoredDiscussion({
+      repo: targetRepo,
+      number: discussionNumber,
+      discussionId: pubResult.id || null,
+      url: pubResult.url,
+      projectName: options.projectName || '',
+      website: options.website || '',
+      title,
+      lastPublishedAt: new Date().toISOString()
+    });
+
+    return {
+      success: true,
+      url: pubResult.url,
+      updated: false,
+      discussionNumber,
+      error: null
+    };
+  }
+
+  return {
+    success: false,
+    url: null,
+    updated: false,
+    discussionNumber: null,
+    error: pubResult.error
+  };
+};

package/cli/audit/social.d.ts

@@ -0,0 +1,66 @@
+import type { AuditReport } from './types';
+import type { AuditSnapshot } from './history';
+
+export interface DiscussionContent {
+  readonly title: string;
+  readonly category: string;
+  readonly categorySlug: string;
+  readonly body: string;
+}
+
+export interface GitRepoInfo {
+  readonly owner: string;
+  readonly repo: string;
+  readonly nameWithOwner: string;
+  readonly url: string;
+}
+
+export declare const DISCUSSION_CATEGORY: string;
+export declare const DISCUSSION_CATEGORY_SLUG: string;
+export declare const ORG_DISCUSSIONS_URL: string;
+export declare const DEFAULT_DISCUSSION_REPO: string;
+
+export declare function parseGitRemoteUrl(url: string): GitRepoInfo | null;
+export declare function detectGitRepoInfo(cwd?: string): GitRepoInfo;
+export declare function detectGitHubUser(preferredUser?: string): string;
+export declare function copyToClipboard(text: string): boolean;
+export declare function resolveBadgeColor(score: number): string;
+export declare function resolveHotspotTierText(lineCount: number): string;
+export declare function resolvePillarProgressionBadge(isImproved: boolean, beforeStatus: string, afterStatus: string): string;
+export declare function formatWebUrl(url: string): string;
+export declare function generateDiscussionContent(report: AuditReport, username: string, projectName?: string, repoUrl?: string, liveUrl?: string): DiscussionContent;
+export declare function generateTransformationDiscussionContent(beforeSnapshot: AuditSnapshot, afterSnapshot: AuditSnapshot, username: string, projectName?: string, repoUrl?: string, liveUrl?: string): DiscussionContent;
+export declare function publishDiscussionViaGh(repo: string, title: string, body: string, category?: string): { success: boolean; url: string | null; error?: string | null };
+export declare function publishDiscussionViaHttp(token: string, repo: string, title: string, body: string, categoryName?: string): Promise<{ success: boolean; url: string | null; error?: string | null }>;
+export declare function publishDiscussion(repo: string, title: string, body: string, category?: string): Promise<{ success: boolean; url: string | null; error?: string | null }>;
+
+export interface StoredDiscussion {
+  readonly repo: string;
+  readonly number: number | null;
+  readonly discussionId?: string | null;
+  readonly url: string;
+  readonly projectName?: string;
+  readonly website?: string;
+  readonly title: string;
+  readonly lastPublishedAt: string;
+}
+
+export interface DiscussionPublishResult {
+  readonly success: boolean;
+  readonly url: string | null;
+  readonly updated?: boolean;
+  readonly discussionNumber?: number | null;
+  readonly error?: string | null;
+}
+
+export declare function getStoredDiscussion(cwd?: string): StoredDiscussion | null;
+export declare function saveStoredDiscussion(data: StoredDiscussion, cwd?: string): boolean;
+export declare function clearStoredDiscussion(cwd?: string): boolean;
+export declare function formatArchiveComment(previousTitle: string, previousBody: string): string;
+export declare function publishOrUpdateDiscussion(
+  repo?: string,
+  title?: string,
+  body?: string,
+  category?: string,
+  options?: { readonly projectName?: string; readonly website?: string }
+): Promise<DiscussionPublishResult>;

package/cli/audit/social.js

@@ -0,0 +1,254 @@
+import { groupViolationsBySeverity } from './reporter.js';
+import { PILLAR_EMOJIS } from './reporter-utils.js';
+
+export {
+  parseGitRemoteUrl,
+  detectGitRepoInfo,
+  detectGitHubUser,
+  copyToClipboard
+} from './social-git.js';
+
+export {
+  publishDiscussionViaHttp,
+  publishDiscussionViaGh,
+  publishDiscussion,
+  publishOrUpdateDiscussion,
+  viewDiscussionViaGh,
+  viewDiscussionViaHttp,
+  postDiscussionCommentViaGh,
+  postDiscussionCommentViaHttp,
+  editDiscussionViaGh,
+  editDiscussionViaHttp,
+  findExistingDiscussionViaGh,
+  formatArchiveComment,
+  getStoredDiscussion,
+  saveStoredDiscussion,
+  clearStoredDiscussion
+} from './social-publisher.js';
+
+export const DISCUSSION_CATEGORY = 'npx chemx audit';
+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 const resolveHotspotTierText = (lineCount) => {
+  if (lineCount >= 2000) return '🔴 **CRITICAL (>= 2,000 LOC)**';
+  if (lineCount >= 1000) return '🟠 **SEVERE (>= 1,000 LOC)**';
+  if (lineCount > 500) return '🟡 **WARNING (> 500 LOC)**';
+  return '🟢 Compliant';
+};
+
+export const resolvePillarProgressionBadge = (isImproved, beforeStatus, afterStatus) => {
+  if (isImproved) return '🟢 **RESOLVED**';
+  if (beforeStatus === afterStatus) return '⚪ **UNCHANGED**';
+  return '🔴 **DEGRADED**';
+};
+
+const isExtremeMonolith = (h) => h.lineCount >= 2000;
+const isSevereMonolith = (h) => h.lineCount >= 1000 && h.lineCount < 2000;
+const isWarningMonolith = (h) => h.lineCount >= 500 && h.lineCount < 1000;
+
+export const formatWebUrl = (url) => {
+  if (!url || typeof url !== 'string') return '';
+  const trimmed = url.trim();
+  if (!trimmed) return '';
+  const href = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+  return `[${href}](${href})`;
+};
+
+export const generateDiscussionContent = (report, username, projectName = 'Codebase', repoUrl = '', liveUrl = '') => {
+  const { health, metrics, pillars, hotspots, contextAnalysis, violations } = report;
+  const isHighScoring = health.score >= 80;
+  const badgeColor = resolveBadgeColor(health.score);
+  const encodedGrade = encodeURIComponent(`${health.score}/100 (${health.grade})`);
+
+  const category = DISCUSSION_CATEGORY;
+  const categorySlug = DISCUSSION_CATEGORY_SLUG;
+  const prefix = isHighScoring ? '[Showcase]' : '[Teardown]';
+  const title = `${prefix} ${projectName} : MHI ${health.score}/100 [Grade: ${health.grade}]`;
+
+  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)`);
+  lines.push('');
+  lines.push(`* **Audited by**: @${username}`);
+  const resolvedRepoUrl = repoUrl || (/^[\w\-.]+\/[\w\-.]+$/.test(projectName) ? `https://github.com/${projectName}` : '');
+  if (resolvedRepoUrl) {
+    lines.push(`* **Repository**: [${resolvedRepoUrl}](${resolvedRepoUrl})`);
+  }
+  if (liveUrl) {
+    const formattedWeb = formatWebUrl(liveUrl);
+    if (formattedWeb) {
+      lines.push(`* **Website**: ${formattedWeb}`);
+    }
+  }
+  lines.push(`* **Molecular Health Index**: **${health.score} / 100** (Grade: **${health.grade}** - ${health.label})`);
+  lines.push(`* **Source Files Analyzed**: ${metrics.scannedFiles} files (${metrics.totalLoc} total LOC)`);
+  lines.push(`* **Token Reduction Potential**: **${contextAnalysis.potentialSavingsPct}%** (Estimated ${contextAnalysis.estimatedTokens.toLocaleString()} tokens)`);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('## 1. 7-Pillar Architectural Matrix');
+  lines.push('');
+  lines.push('| Pillar | Status | Hazards |');
+  lines.push('| :--- | :---: | :---: |');
+
+  const resolveStatusDisplay = (status) => {
+    if (status === 'PASSED') return '🟢 **PASSED**';
+    if (status === 'WARN') return '🟡 **WARN**';
+    return '🔴 **FAILED**';
+  };
+
+  const resolveHazardsDisplay = (count, status) => {
+    if (count === 0) return '🟢 0';
+    if (status === 'FAILED') return `🔴 **${count}**`;
+    return `🟡 **${count}**`;
+  };
+
+  for (const [pillarName, data] of Object.entries(pillars)) {
+    const icon = PILLAR_EMOJIS[pillarName] || '🏛️';
+    const statusText = resolveStatusDisplay(data.status);
+    const hazardsText = resolveHazardsDisplay(data.violations, data.status);
+    lines.push(`| ${icon} ${pillarName} | ${statusText} | ${hazardsText} |`);
+  }
+  lines.push('');
+
+  const { critical, high, medium, low } = groupViolationsBySeverity(violations);
+  const extremeMonoliths = hotspots.filter(isExtremeMonolith).length;
+  const severeMonoliths = hotspots.filter(isSevereMonolith).length;
+  const warningMonoliths = hotspots.filter(isWarningMonolith).length;
+  const totalMonoliths = extremeMonoliths + severeMonoliths + warningMonoliths;
+
+  lines.push('---');
+  lines.push('');
+  lines.push('## 2. Monolith & Architectural Hazard Summary');
+  lines.push('');
+  lines.push(`* **Monolith Files (> 500 LOC)**: **${totalMonoliths} files**`);
+  if (totalMonoliths > 0) {
+    lines.push(`  * Warning Tier (500 - 999 LOC): ${warningMonoliths} files`);
+    lines.push(`  * Severe Tier (1,000 - 1,999 LOC): ${severeMonoliths} files`);
+    lines.push(`  * Extreme Monoliths (2,000+ LOC): ${extremeMonoliths} files`);
+  }
+  lines.push(`* **Hazard Breakdown**: Critical: **${critical.length}** | High/Med: **${high.length + medium.length}** | Low: **${low.length}**`);
+  lines.push('');
+
+  lines.push('---');
+  lines.push('');
+  if (isHighScoring) {
+    lines.push('### Community Takeaway');
+    lines.push('This project follows Chemical X Molecular Architecture principles with isolated capsules and self-cleaning hooks.');
+  } else {
+    lines.push('### Seeking Refactoring Feedback');
+    lines.push('Looking for recommendations on breaking down flagged monolithic debts into crystalline molecule capsules (< 100 LOC). Any advice is welcome!');
+  }
+  lines.push('');
+  lines.push('*Audited using [Chemical X Protocol Starter Kit](https://github.com/Chemical-X-Protocol/awesome-secret-sauce).*');
+
+  return {
+    title,
+    category,
+    categorySlug,
+    body: lines.join('\n')
+  };
+};
+
+export const generateTransformationDiscussionContent = (
+  beforeSnapshot,
+  afterSnapshot,
+  username,
+  projectName = 'Codebase',
+  repoUrl = '',
+  liveUrl = ''
+) => {
+  const scoreBefore = beforeSnapshot.health.score;
+  const scoreAfter = afterSnapshot.health.score;
+  const scoreDelta = scoreAfter - scoreBefore;
+
+  const critDelta = afterSnapshot.violations.critical - beforeSnapshot.violations.critical;
+  const totalDelta = afterSnapshot.violations.total - beforeSnapshot.violations.total;
+  const monoDelta = afterSnapshot.monoliths.total - beforeSnapshot.monoliths.total;
+  const tokensDelta = afterSnapshot.tokens.estimatedExcessTokens - beforeSnapshot.tokens.estimatedExcessTokens;
+
+  const category = DISCUSSION_CATEGORY;
+  const categorySlug = DISCUSSION_CATEGORY_SLUG;
+  const title = `[Transformation] ${projectName} : ${beforeSnapshot.health.grade} (${scoreBefore}) -> ${afterSnapshot.health.grade} (${scoreAfter})`;
+
+  const formatDelta = (val, invertGood = false) => {
+    if (val === 0) return '0 (No change)';
+    const isGood = invertGood ? val < 0 : val > 0;
+    const sign = val > 0 ? `+${val}` : `${val}`;
+    return isGood ? `🟢 **${sign}**` : `🔴 **${sign}**`;
+  };
+
+  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('');
+  lines.push(`* **Audited by**: @${username}`);
+  const resolvedRepoUrl = repoUrl || (/^[\w\-.]+\/[\w\-.]+$/.test(projectName) ? `https://github.com/${projectName}` : '');
+  if (resolvedRepoUrl) {
+    lines.push(`* **Repository**: [${resolvedRepoUrl}](${resolvedRepoUrl})`);
+  }
+  if (liveUrl) {
+    const formattedWeb = formatWebUrl(liveUrl);
+    if (formattedWeb) {
+      lines.push(`* **Website**: ${formattedWeb}`);
+    }
+  }
+  lines.push(`* **Transformation Summary**: Upgraded codebase from **Grade ${beforeSnapshot.health.grade} (${scoreBefore}/100)** to **Grade ${afterSnapshot.health.grade} (${scoreAfter}/100)**.`);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('## 1. Before vs. After Metric Comparison');
+  lines.push('');
+  lines.push('| Metric | Before (Baseline) | After (Refactored) | Delta |');
+  lines.push('| :--- | :---: | :---: | :---: |');
+  lines.push(`| **Molecular Health (MHI)** | ${scoreBefore} / 100 (${beforeSnapshot.health.grade}) | ${scoreAfter} / 100 (${afterSnapshot.health.grade}) | ${formatDelta(scoreDelta)} |`);
+  lines.push(`| **Critical Hazards** | ${beforeSnapshot.violations.critical} | ${afterSnapshot.violations.critical} | ${formatDelta(critDelta, true)} |`);
+  lines.push(`| **Total Violations** | ${beforeSnapshot.violations.total} | ${afterSnapshot.violations.total} | ${formatDelta(totalDelta, true)} |`);
+  lines.push(`| **Monolith Files (>500 LOC)** | ${beforeSnapshot.monoliths.total} | ${afterSnapshot.monoliths.total} | ${formatDelta(monoDelta, true)} |`);
+  lines.push(`| **Excess Token Burn** | ${beforeSnapshot.tokens.estimatedExcessTokens.toLocaleString()} tok | ${afterSnapshot.tokens.estimatedExcessTokens.toLocaleString()} tok | ${formatDelta(tokensDelta, true)} |`);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('## 2. 7-Pillar Progression');
+  lines.push('');
+  lines.push('| Pillar | Before Status | After Status | Progression |');
+  lines.push('| :--- | :---: | :---: | :---: |');
+
+  const allPillars = new Set([
+    ...Object.keys(beforeSnapshot.pillars || {}),
+    ...Object.keys(afterSnapshot.pillars || {})
+  ]);
+
+  for (const pillar of allPillars) {
+    const b = beforeSnapshot.pillars?.[pillar] || { status: 'UNKNOWN', violations: 0 };
+    const a = afterSnapshot.pillars?.[pillar] || { status: 'UNKNOWN', violations: 0 };
+    const icon = PILLAR_EMOJIS[pillar] || '🏛️';
+    const isImproved = a.violations < b.violations || (b.status !== 'PASSED' && a.status === 'PASSED');
+    const badge = resolvePillarProgressionBadge(isImproved, b.status, a.status);
+    lines.push(`| ${icon} ${pillar} | ${b.status} | ${a.status} | ${badge} |`);
+  }
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('### Community Takeaway');
+  lines.push('Refactored using Chemical X Molecular Architecture standards. Monoliths decomposed into crystalline domain capsules (< 100 LOC) with self-cleaning hooks.');
+  lines.push('');
+  lines.push('*Transformation tracked via [Chemical X Protocol Starter Kit](https://github.com/Chemical-X-Protocol/awesome-secret-sauce).*');
+
+  return {
+    title,
+    category,
+    categorySlug,
+    body: lines.join('\n')
+  };
+};

package/cli/audit/types.d.ts

@@ -0,0 +1,131 @@
+export type SeverityLevel = 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
+export type PillarStatus = 'PASSED' | 'WARN' | 'FAILED';
+export type RiskLevel = 'LOW' | 'MODERATE' | 'HIGH';
+
+export interface HazardViolation {
+  readonly filePath: string;
+  readonly line: number;
+  readonly column: number;
+  readonly hazard: string;
+  readonly rule: string;
+  readonly severity: SeverityLevel;
+  readonly pillar: string;
+  readonly directive: string;
+}
+
+export interface FileStat {
+  readonly fullPath: string;
+  readonly relativePath: string;
+  readonly lineCount: number;
+  readonly charCount: number;
+  readonly isMolecule: boolean;
+}
+
+export interface CodebaseMetrics {
+  readonly scannedFiles: number;
+  readonly totalLoc: number;
+  readonly avgLoc: number;
+  readonly largestFile: {
+    readonly filePath: string;
+    readonly lineCount: number;
+  };
+  readonly moleculeCount: number;
+  readonly moleculeCompliantCount: number;
+  readonly moleculeCompliantPct: number;
+  readonly hookCount: number;
+}
+
+export interface MolecularHealthScore {
+  readonly score: number;
+  readonly grade: string;
+  readonly label: string;
+}
+
+export type QuantumHealthScore = MolecularHealthScore;
+
+export interface PillarData {
+  readonly pillarKey: string;
+  violations: number;
+  critical: number;
+  high: number;
+  medium: number;
+  low: number;
+  status: PillarStatus;
+}
+
+export interface ContextTokenAnalysis {
+  readonly estimatedTokens: number;
+  readonly estimatedExcessTokens: number;
+  readonly potentialSavingsPct: number;
+  readonly riskLevel: RiskLevel;
+}
+
+export interface HotspotFile {
+  readonly filePath: string;
+  readonly violationCount: number;
+  readonly lineCount: number;
+  readonly isMonolith: boolean;
+  readonly monolithTier?: 'CRITICAL' | 'SEVERE' | 'WARNING' | null;
+}
+
+export interface AuditReport {
+  readonly scannedFiles: number;
+  readonly totalViolations: number;
+  readonly metrics: CodebaseMetrics;
+  readonly health: MolecularHealthScore;
+  readonly pillars: Record<string, PillarData>;
+  readonly contextAnalysis: ContextTokenAnalysis;
+  readonly hotspots: readonly HotspotFile[];
+  readonly violations: readonly HazardViolation[];
+}
+
+export interface AuditOptions {
+  readonly dir?: string;
+  readonly json?: boolean;
+  readonly markdown?: boolean;
+  readonly outputFile?: string;
+  readonly strict?: boolean;
+}
+
+export interface SeverityGroupedViolations {
+  readonly critical: readonly HazardViolation[];
+  readonly high: readonly HazardViolation[];
+  readonly medium: readonly HazardViolation[];
+  readonly low: readonly HazardViolation[];
+}
+
+export declare function groupViolationsBySeverity(violations: readonly HazardViolation[]): SeverityGroupedViolations;
+export declare function auditCode(content: string, filePath: string, relativePath: string): HazardViolation[];
+export declare function auditFile(filePath: string, relativePath: string): HazardViolation[];
+export declare function scanDirectory(targetDir: string, baseDir: string): HazardViolation[];
+export declare function runAudit(targetDir?: string, options?: AuditOptions): AuditReport;
+export declare function formatTerminalReport(report: AuditReport): string;
+export declare function generateMarkdownReport(report: AuditReport): string;
+export declare function resolveTopSectionColor(report: AuditReport): string;
+export declare function formatScorecardSection(report: AuditReport, themeColor?: string | null): string;
+export declare function formatCriticalSection(report: AuditReport): string;
+export declare function formatHighMediumSection(report: AuditReport): string;
+export declare function formatLowSection(report: AuditReport): string;
+export declare function formatPillarsSection(report: AuditReport, themeColor?: string | null): string;
+export declare function formatHotspotsSection(report: AuditReport, themeColor?: string | null): string;
+export declare function formatContextAnalysisSection(report: AuditReport, themeColor?: string | null): string;
+export declare function formatFailuresSection(report: AuditReport): string;
+export declare function formatPassesSection(report: AuditReport): string;
+export declare function formatGradeFSection(report: AuditReport): string;
+export declare function formatGradeDSection(report: AuditReport): string;
+export declare function formatGradeCSection(report: AuditReport): string;
+export declare function formatGradeBSection(report: AuditReport): string;
+export declare function formatGradeASection(report: AuditReport): string;
+export declare function getChemicalXAsciiBanner(gradeOrReport?: string | AuditReport | null): string;
+
+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 declare function buildMasterPrompt(report: AuditReport): string;
+export declare function formatPromptBox(title: string, promptText: string): string;
+
+export * from './history';
+

package/cli/audit.d.ts

@@ -1,25 +1,4 @@
-export interface HazardViolation {
-  filePath: string;
-  line: number;
-  hazard: string;
-  rule: string;
-  directive: string;
-}
+export * from './audit/types';
+import defaultAudit from './audit/types';
 
-export interface AuditReport {
-  scannedFiles: number;
-  totalViolations: number;
-  violations: HazardViolation[];
-}
-
-export declare function auditFile(filePath: string, relativePath: string): HazardViolation[];
-export declare function scanDirectory(targetDir: string, baseDir: string): HazardViolation[];
-export declare function runAudit(targetDir?: string): AuditReport;
-
-declare const _default: {
-  auditFile: typeof auditFile;
-  scanDirectory: typeof scanDirectory;
-  runAudit: typeof runAudit;
-};
-
-export default _default;
+export default defaultAudit;