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

package/cli/audit.js

@@ -1,189 +1,52 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { parse } from '@babel/parser';
-import traverse from '@babel/traverse';
-import * as t from '@babel/types';
-
-const countLogicalOperators = (node) => {
-  let count = 0;
-  if (t.isLogicalExpression(node)) {
-    count += 1;
-    count += countLogicalOperators(node.left);
-    count += countLogicalOperators(node.right);
-  } else if (t.isUnaryExpression(node) && node.operator === '!') {
-    count += 1;
-    count += countLogicalOperators(node.argument);
-  }
-  return count;
-};
-
-const extractParseableCode = (content, ext) => {
-  if (ext === '.vue') {
-    const scriptMatch = content.match(/<script\b[^>]*>([\s\S]*?)<\/script>/i);
-    return scriptMatch ? scriptMatch[1] : '';
-  }
-  return content;
-};
-
-export const auditFile = (filePath, relativePath) => {
-  const violations = [];
-  const content = fs.readFileSync(filePath, 'utf-8');
-  const lines = content.split('\n');
-  const lineCount = lines.length;
-  const ext = path.extname(filePath);
-
-  // 1. Line Budget Checks
-  const isMolecule = relativePath.includes('molecules') || relativePath.includes('/m-');
-  if (lineCount > 500) {
-    violations.push({
-      filePath: relativePath,
-      line: 1,
-      hazard: `File line budget exceeded (${lineCount} > 500 lines)`,
-      rule: 'LINE_BUDGET_FILE',
-      directive: 'Decompose monolith into domain capsules and molecules'
-    });
-  } else if (isMolecule && lineCount > 100) {
-    violations.push({
-      filePath: relativePath,
-      line: 1,
-      hazard: `Molecule capsule budget exceeded (${lineCount} > 100 lines)`,
-      rule: 'LINE_BUDGET_MOLECULE',
-      directive: 'Split molecule into focused sub-molecules or extract state to hook'
-    });
-  }
-
-  const codeToParse = extractParseableCode(content, ext);
-  if (!codeToParse.trim()) {
-    return violations;
-  }
-
-  let ast;
-  try {
-    ast = parse(codeToParse, {
-      sourceType: 'module',
-      plugins: ['typescript', 'jsx']
-    });
-  } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err);
-    violations.push({
-      filePath: relativePath,
-      line: 1,
-      hazard: `Parse error: ${errorMsg}`,
-      rule: 'SYNTAX_PARSE_ERROR',
-      directive: 'Fix syntax errors before static analysis'
-    });
-    return violations;
-  }
-
-  const traverseFn = traverse.default || traverse;
-
-  traverseFn(ast, {
-    // 2. Hook Saturation Check
-    Function(astPath) {
-      let hookCount = 0;
-      astPath.traverse({
-        CallExpression(callPath) {
-          if (t.isIdentifier(callPath.node.callee) && /^use[A-Z0-9]/.test(callPath.node.callee.name)) {
-            if (callPath.getFunctionParent() === astPath) {
-              hookCount += 1;
-            }
-          }
-        }
-      });
-
-      if (hookCount > 5) {
-        const line = astPath.node.loc?.start.line || 1;
-        violations.push({
-          filePath: relativePath,
-          line,
-          hazard: `Hook saturation detected (${hookCount} hooks > 5 limit)`,
-          rule: 'HOOK_SATURATION',
-          directive: 'Extract related state and effects into dedicated domain hooks'
-        });
-      }
-    },
-
-    // 3. 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;
-          violations.push({
-            filePath: relativePath,
-            line,
-            hazard: `Inline boolean complexity (${opCount} logical operators > 2 limit)`,
-            rule: 'CONTROL_FLOW_INLINE_BOOLEAN',
-            directive: 'Compose booleans into Stage 1 concepts and Stage 2 decision variables'
-          });
-        }
-      }
-    },
-
-    ConditionalExpression(astPath) {
-      if (t.isConditionalExpression(astPath.node.consequent) || t.isConditionalExpression(astPath.node.alternate)) {
-        const line = astPath.node.loc?.start.line || 1;
-        violations.push({
-          filePath: relativePath,
-          line,
-          hazard: 'Nested ternary operator detected',
-          rule: 'CONTROL_FLOW_NESTED_TERNARY',
-          directive: 'Extract display states into computed descriptor objects or early returns'
-        });
-      }
-    },
-
-    // 4. Timer Discipline
-    CallExpression(astPath) {
-      const callee = astPath.node.callee;
-      if (t.isIdentifier(callee) && (callee.name === 'setInterval' || callee.name === 'setTimeout')) {
-        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;
-          violations.push({
-            filePath: relativePath,
-            line,
-            hazard: `Raw ${callee.name} lacking lifecycle scope disposal`,
-            rule: 'TIMER_DISCIPLINE',
-            directive: 'Wrap timers in self-cleaning hooks returning cleanup disposers'
-          });
-        }
-      }
-    },
-
-    // 5. 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;
-          violations.push({
-            filePath: relativePath,
-            line,
-            hazard: `Inlined anonymous complex type (${astPath.node.members.length} members)`,
-            rule: 'TYPE_COLOCATION',
-            directive: 'Define co-located domain interfaces in types/*.d.ts'
-          });
-        }
-      }
-    }
-  });
-
-  return violations;
-};
-
-const IGNORED_DIRS = new Set(['node_modules', 'dist', 'build', 'vendor', '.git', '.next', '.turbo', '.output', 'out']);
+import { auditCode, PILLARS, RULE_REGISTRY } from './audit/rules.js';
+import {
+  calculateMolecularHealthScore,
+  calculateQuantumHealthScore,
+  calculatePillarBreakdown,
+  calculateTokenBurnAnalytics,
+  calculateHotspots
+} from './audit/metrics.js';
+import {
+  formatTerminalReport,
+  generateMarkdownReport,
+  groupViolationsBySeverity,
+  resolveTopSectionColor,
+  formatScorecardSection,
+  formatCriticalSection,
+  formatHighMediumSection,
+  formatLowSection,
+  formatPillarsSection,
+  formatHotspotsSection,
+  formatContextAnalysisSection,
+  formatFailuresSection,
+  formatPassesSection,
+  formatGradeFSection,
+  formatGradeDSection,
+  formatGradeCSection,
+  formatGradeBSection,
+  formatGradeASection,
+  getChemicalXAsciiBanner,
+  getAsciiGradeLines,
+  formatAsciiGrade,
+  getReportCardAsciiLines,
+  REPORT_CARD_ASCII
+} from './audit/reporter.js';
+
+const IGNORED_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  'vendor',
+  '.git',
+  '.next',
+  '.turbo',
+  '.output',
+  '.nuxt',
+  '.cache',
+  'out'
+]);
 
 const isSourceFile = (name) => {
   return (
@@ -195,9 +58,19 @@ const isSourceFile = (name) => {
   );
 };
 
-export const scanDirectory = (targetDir, baseDir) => {
-  let results = [];
-  if (!fs.existsSync(targetDir)) return results;
+export const auditFile = (filePath, relativePath) => {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  return auditCode(content, filePath, relativePath);
+};
+
+export const scanTree = (targetDir, baseDir) => {
+  let violations = [];
+  let fileStats = [];
+  let totalHooks = 0;
+
+  if (!fs.existsSync(targetDir)) {
+    return { violations, fileStats, totalHooks };
+  }
 
   const entries = fs.readdirSync(targetDir, { withFileTypes: true });
   for (const entry of entries) {
@@ -206,48 +79,172 @@ export const scanDirectory = (targetDir, baseDir) => {
 
     if (entry.isDirectory()) {
       if (!IGNORED_DIRS.has(entry.name)) {
-        results = results.concat(scanDirectory(fullPath, baseDir));
+        const sub = scanTree(fullPath, baseDir);
+        violations = violations.concat(sub.violations);
+        fileStats = fileStats.concat(sub.fileStats);
+        totalHooks += sub.totalHooks;
       }
     } else if (isSourceFile(entry.name)) {
-      results = results.concat(auditFile(fullPath, relPath));
+      const content = fs.readFileSync(fullPath, 'utf-8');
+      const lines = content.split('\n');
+      const isMolecule = relPath.includes('molecules') || relPath.includes('/m-') || entry.name.startsWith('m-');
+
+      fileStats.push({
+        fullPath,
+        relativePath: relPath,
+        lineCount: lines.length,
+        charCount: content.length,
+        isMolecule
+      });
+
+      // Count hook declarations / invocations for metric
+      const hookMatches = content.match(/\buse[A-Z0-9]\w*\b/g);
+      if (hookMatches) {
+        totalHooks += hookMatches.length;
+      }
+
+      const fileViolations = auditCode(content, fullPath, relPath);
+      violations = violations.concat(fileViolations);
     }
   }
-  return results;
+
+  return { violations, fileStats, totalHooks };
+};
+
+export const scanDirectory = (targetDir, baseDir) => {
+  const { violations } = scanTree(targetDir, baseDir);
+  return violations;
 };
 
-const countTotalScannedFiles = (targetDir) => {
-  let count = 0;
-  if (!fs.existsSync(targetDir)) return count;
+export const runAudit = (targetDir = 'src', options = {}) => {
+  const cwd = process.cwd();
+  const absoluteTarget = path.resolve(cwd, targetDir);
+  const { violations, fileStats, totalHooks } = scanTree(absoluteTarget, cwd);
 
-  const entries = fs.readdirSync(targetDir, { withFileTypes: true });
-  for (const entry of entries) {
-    const fullPath = path.join(targetDir, entry.name);
-    if (entry.isDirectory()) {
-      if (!IGNORED_DIRS.has(entry.name)) {
-        count += countTotalScannedFiles(fullPath);
+  const scannedFiles = fileStats.length;
+  const totalLoc = fileStats.reduce((acc, f) => acc + f.lineCount, 0);
+  const avgLoc = scannedFiles > 0 ? Math.round(totalLoc / scannedFiles) : 0;
+
+  let largestFile = { filePath: '', lineCount: 0 };
+  let moleculeCount = 0;
+  let moleculeCompliantCount = 0;
+
+  for (const f of fileStats) {
+    if (f.lineCount > largestFile.lineCount) {
+      largestFile = { filePath: f.relativePath, lineCount: f.lineCount };
+    }
+    if (f.isMolecule) {
+      moleculeCount += 1;
+      if (f.lineCount <= 100) {
+        moleculeCompliantCount += 1;
       }
-    } else if (isSourceFile(entry.name)) {
-      count += 1;
     }
   }
-  return count;
-};
 
-export const runAudit = (targetDir = 'src') => {
-  const cwd = process.cwd();
-  const absoluteTarget = path.resolve(cwd, targetDir);
-  const violations = scanDirectory(absoluteTarget, cwd);
-  const scannedFiles = countTotalScannedFiles(absoluteTarget);
+  const moleculeCompliantPct = moleculeCount > 0
+    ? Math.round((moleculeCompliantCount / moleculeCount) * 100)
+    : 100;
+
+  const metrics = {
+    scannedFiles,
+    totalLoc,
+    avgLoc,
+    largestFile,
+    moleculeCount,
+    moleculeCompliantCount,
+    moleculeCompliantPct,
+    hookCount: totalHooks
+  };
 
-  return {
+  const health = calculateMolecularHealthScore(violations, scannedFiles);
+  const pillars = calculatePillarBreakdown(violations);
+  const contextAnalysis = calculateTokenBurnAnalytics(fileStats, options);
+  const hotspots = calculateHotspots(violations, fileStats, 5);
+
+  const report = {
     scannedFiles,
     totalViolations: violations.length,
+    metrics,
+    health,
+    pillars,
+    contextAnalysis,
+    hotspots,
     violations
   };
+
+  if (options.outputFile) {
+    const outPath = path.resolve(cwd, options.outputFile);
+    const mdContent = generateMarkdownReport(report);
+    fs.writeFileSync(outPath, mdContent, 'utf-8');
+  }
+
+  return report;
+};
+
+export * from './audit/social.js';
+export * from './audit/prompts.js';
+export * from './audit/history.js';
+
+export {
+  calculateMolecularHealthScore,
+  calculateQuantumHealthScore,
+  calculatePillarBreakdown,
+  calculateTokenBurnAnalytics,
+  calculateHotspots,
+  PILLARS,
+  RULE_REGISTRY,
+  formatTerminalReport,
+  generateMarkdownReport,
+  groupViolationsBySeverity,
+  resolveTopSectionColor,
+  formatScorecardSection,
+  formatCriticalSection,
+  formatHighMediumSection,
+  formatLowSection,
+  formatPillarsSection,
+  formatHotspotsSection,
+  formatContextAnalysisSection,
+  formatFailuresSection,
+  formatPassesSection,
+  formatGradeFSection,
+  formatGradeDSection,
+  formatGradeCSection,
+  formatGradeBSection,
+  formatGradeASection,
+  getChemicalXAsciiBanner,
+  getAsciiGradeLines,
+  formatAsciiGrade,
+  getReportCardAsciiLines,
+  REPORT_CARD_ASCII
 };
 
 export default {
   auditFile,
   scanDirectory,
-  runAudit
+  runAudit,
+  formatTerminalReport,
+  generateMarkdownReport,
+  groupViolationsBySeverity,
+  resolveTopSectionColor,
+  formatScorecardSection,
+  formatCriticalSection,
+  formatHighMediumSection,
+  formatLowSection,
+  formatPillarsSection,
+  formatHotspotsSection,
+  formatContextAnalysisSection,
+  formatFailuresSection,
+  formatPassesSection,
+  formatGradeFSection,
+  formatGradeDSection,
+  formatGradeCSection,
+  formatGradeBSection,
+  formatGradeASection,
+  getChemicalXAsciiBanner,
+  getAsciiGradeLines,
+  formatAsciiGrade,
+  getReportCardAsciiLines,
+  REPORT_CARD_ASCII,
+  PILLARS,
+  RULE_REGISTRY
 };

package/cli/help.d.ts

@@ -0,0 +1 @@
+export declare function printHelp(): void;

package/cli/help.js

@@ -0,0 +1,136 @@
+import { renderBanner } from './terminal.js';
+
+export const printHelp = () => {
+  renderBanner('Chemical X Protocol: CLI Usage & Reference');
+
+  const BOLD = '\x1b[1m';
+  const CYAN = '\x1b[36m';
+  const DIM = '\x1b[2m';
+  const YELLOW = '\x1b[33m';
+  const GREEN = '\x1b[32m';
+  const RESET = '\x1b[0m';
+
+  const out = [
+    `${BOLD}USAGE${RESET}`,
+    `  ${CYAN}npx chemx${RESET} <command> [options]`,
+    `  ${CYAN}npm create chemx${RESET} [directory]`,
+    '',
+    `${BOLD}COMMANDS${RESET}`,
+    `  ${CYAN}audit${RESET} [options]`,
+    `      Run the 7-Pillar Molecular Architecture static analysis audit.`,
+    `      Scans AST for line budgets, control flow booleans, nested ternaries,`,
+    `      hook limits, self-cleaning timers, and Anti-Tailwind-Soup compliance.`,
+    `      Computes Molecular Health Index (MHI: 0-100) and letter grades (A+ to F).`,
+    `      Defaults to interactive zero-scroll Gum terminal dashboard.`,
+    '',
+    `  ${CYAN}generate${RESET} <m-name>  ${DIM}(aliases: capsule, add)${RESET}`,
+    `      Scaffold an isolated crystalline molecule capsule directory:`,
+    `        ${DIM}- ${RESET}<m-name>/<m-name>.tsx  ${DIM}(declarative component < 50 lines of code)${RESET}`,
+    `        ${DIM}- ${RESET}<m-name>/types.d.ts     ${DIM}(props and emits interfaces)${RESET}`,
+    `        ${DIM}- ${RESET}<m-name>/index.ts        ${DIM}(clean public barrel export)${RESET}`,
+    `      Free evaluation mode supported with non-blocking license reminder.`,
+    `      Example: ${CYAN}npx chemx generate m-user-avatar${RESET}`,
+    '',
+    `  ${CYAN}init${RESET} [directory]`,
+    `      ${YELLOW}[PAID]${RESET} Drop full Chemical X blueprints, core hooks (toResult,`,
+    `      useAsyncData, useSelfCleaningTimer), and AGENTS.md directives into`,
+    `      an existing codebase. Default destination: ${CYAN}src/chemical-x${RESET}.`,
+    `      Requires Single Dev ($27) or Team Power Puff ($97: Unlimited Lifetime) license.`,
+    '',
+    `  ${CYAN}create${RESET} [directory]  ${DIM}(or: npm create chemx [directory])${RESET}`,
+    `      ${YELLOW}[PAID]${RESET} Scaffold a complete, clean-slate project wired with full`,
+    `      Chemical X molecular standards, pre-commit line budget hooks, and rules.`,
+    `      Requires Single Dev ($27) or Team Power Puff ($97: Unlimited Lifetime) license.`,
+    '',
+    `  ${CYAN}install-hooks${RESET} [directory]  ${DIM}(aliases: hook, setup-ci)${RESET}`,
+    `      ${GREEN}[FREE]${RESET} Install git pre-commit hook (.git/hooks/pre-commit) and`,
+    `      GitHub Actions CI workflow (.github/workflows/chemx-audit.yml).`,
+    `      Enforces 500-line file ceilings, 100-line molecule budgets, and configurable`,
+    `      minimum grade/score thresholds with automatic AI prompt clipboard copying.`,
+    `      Example: ${CYAN}npx chemx install-hooks${RESET}`,
+    '',
+    `  ${CYAN}help${RESET}, ${CYAN}--help${RESET}, ${CYAN}-h${RESET}`,
+    `      Display this comprehensive CLI documentation and options guide.`,
+    '',
+    `${BOLD}AUDIT OPTIONS & FLAGS${RESET}`,
+    `  ${CYAN}--dir=<path>${RESET}`,
+    `      Directory to analyze. Defaults to ${CYAN}src${RESET} if present, else current working directory.`,
+    `      Example: ${CYAN}npx chemx audit --dir=apps/web/src${RESET}`,
+    '',
+    `  ${CYAN}--json${RESET}`,
+    `      Output structured machine-readable JSON report to stdout.`,
+    `      Ideal for CI/CD pipelines, automated gating, and custom tooling.`,
+    '',
+    `  ${CYAN}--markdown${RESET}, ${CYAN}--md${RESET}`,
+    `      Output formatted GitHub Flavored Markdown report to stdout.`,
+    '',
+    `  ${CYAN}--output=<file>${RESET}, ${CYAN}-o=<file>${RESET}`,
+    `      Save formatted Markdown report directly to the specified file path.`,
+    `      Example: ${CYAN}npx chemx audit --output=AUDIT_REPORT.md${RESET}`,
+    '',
+    `  ${CYAN}--unroll${RESET}, ${CYAN}--all${RESET}`,
+    `      Stream full unrolled report directly to terminal without interactive Gum menu.`,
+    '',
+    `  ${CYAN}--share${RESET}, ${CYAN}--post${RESET}`,
+    `      Publish or update report on GitHub Discussions without entering dashboard.`,
+    `      Automatically archives prior audit snapshots as discussion comments.`,
+    '',
+    `  ${CYAN}--strict${RESET}`,
+    `      Strict CI failure mode: exits with status 1 on ANY violation, including`,
+    `      Low hygiene issues (typography and console logging).`,
+    '',
+    `  ${CYAN}--min-grade=<tier>${RESET}`,
+    `      Fail audit if Molecular Health Index grade falls below tier (A+, A, B, C, D).`,
+    `      Default: None (or B when executed via pre-commit gatekeeper).`,
+    '',
+    `  ${CYAN}--min-score=<0-100>${RESET}`,
+    `      Fail audit if Molecular Health Index score falls below number (e.g. 80).`,
+    '',
+    `  ${CYAN}--model=<claude|gpt4o|blended>${RESET}`,
+    `      Pricing baseline for context burn dollar calculations ($3.00/1M blended).`,
+    '',
+    `  ${CYAN}--prompt-on-fail${RESET}, ${CYAN}--copy-prompt${RESET}`,
+    `      Automatically copy the synthesized AI refactoring prompt to system clipboard`,
+    `      when architectural violations or threshold failures are detected.`,
+    '',
+    `  ${CYAN}--license=<key>${RESET}`,
+    `      Pass Chemical X Sponsor or Team license key non-interactively via CLI.`,
+    `      Tiers: Single Dev ($27) | Team Power Puff ($97: Unlimited Lifetime).`,
+    '',
+    `${BOLD}ENVIRONMENT VARIABLES${RESET}`,
+    `  ${GREEN}CHEMX_MIN_GRADE${RESET}`,
+    `      Default minimum grade threshold for pre-commit gatekeeper (default: B).`,
+    '',
+    `  ${GREEN}CHEMX_MIN_SCORE${RESET}`,
+    `      Default minimum score threshold for pre-commit gatekeeper (default: 80).`,
+    '',
+    `  ${GREEN}GH_TOKEN${RESET} / ${GREEN}GITHUB_TOKEN${RESET}`,
+    `      GitHub personal access token for automated discussion publishing via GraphQL.`,
+    `      If omitted, the CLI automatically delegates to local ${CYAN}gh${RESET} CLI authentication.`,
+    '',
+    `  ${GREEN}CHEMICAL_X_API_URL${RESET}`,
+    `      Custom licensing edge verification endpoint. Default: ${CYAN}https://chemicalx.xophz.com${RESET}.`,
+    '',
+    `${BOLD}EXAMPLES${RESET}`,
+    `  ${DIM}# Run interactive audit dashboard with ASCII banner and health scorecard:${RESET}`,
+    `  ${CYAN}npx chemx audit${RESET}`,
+    '',
+    `  ${DIM}# Scan a sub-package in strict mode for CI gating:${RESET}`,
+    `  ${CYAN}npx chemx audit --dir=packages/core --strict${RESET}`,
+    '',
+    `  ${DIM}# Export markdown scorecard to file:${RESET}`,
+    `  ${CYAN}npx chemx audit --markdown --output=AUDIT.md${RESET}`,
+    '',
+    `  ${DIM}# Pipe JSON metrics to jq:${RESET}`,
+    `  ${CYAN}npx chemx audit --json | jq .health${RESET}`,
+    '',
+    `  ${DIM}# Generate a new molecule capsule:${RESET}`,
+    `  ${CYAN}npx chemx generate m-spark-kpi${RESET}`,
+    '',
+    `  ${DIM}# Scaffold a new project:${RESET}`,
+    `  ${CYAN}npm create chemx my-awesome-app${RESET}`,
+    ''
+  ].join('\n');
+
+  process.stdout.write(out + '\n');
+};