@soulbatical/tetra-dev-toolkit 1.20.22 → 1.20.24

package/bin/tetra-style-audit.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra Style Compliance — detect styling drift in consumer projects.
+ *
+ * Scans frontend source files and checks for hardcoded layout dimensions,
+ * raw Tailwind color classes, hex colors, custom card patterns, and other
+ * things Tetra already solves via PageContainer, AppShell theme config, and
+ * CSS tokens (--tetra-bg, --tetra-text, --tetra-border, --tetra-accent, etc.).
+ *
+ * Usage:
+ *   tetra-style-audit                          # Audit current project
+ *   tetra-style-audit --path /path/to/project  # Audit specific project
+ *   tetra-style-audit --json                   # JSON output for CI
+ *   tetra-style-audit --ci                     # GitHub Actions annotations
+ *   tetra-style-audit --strict                 # Fail on warnings too
+ *   tetra-style-audit --fix-hint               # Show suggested fix per violation
+ *   tetra-style-audit --files "src/**\/*.tsx"  # Restrict to specific files
+ *
+ * Exit codes:
+ *   0 = clean (no critical violations)
+ *   1 = critical violations found (or any if --strict)
+ */
+
+import { program } from 'commander'
+import chalk from 'chalk'
+import {
+  runStyleComplianceAudit,
+  formatReport,
+  formatReportJSON,
+  formatCIAnnotations,
+} from '../lib/audits/style-compliance-audit.js'
+
+program
+  .name('tetra-style-audit')
+  .description('Detect styling drift from the Tetra design system')
+  .version('1.0.0')
+  .option('--path <dir>', 'Project root directory (default: cwd)')
+  .option('--json', 'JSON output for CI')
+  .option('--ci', 'GitHub Actions annotations for failures')
+  .option('--strict', 'Fail on any violation including warnings (default: only critical)')
+  .option('--fix-hint', 'Show suggested fix for each violation')
+  .option('--files <glob>', 'Restrict scan to specific files (glob pattern)')
+  .action(async (options) => {
+    try {
+      const projectRoot = options.path || process.cwd()
+
+      if (!options.json) {
+        console.log(chalk.gray('\n  Scanning for style drift...'))
+      }
+
+      const report = await runStyleComplianceAudit(projectRoot, {
+        filesGlob: options.files,
+      })
+
+      // Output
+      if (options.json) {
+        console.log(formatReportJSON(report))
+      } else {
+        console.log(formatReport(report, chalk, { fixHint: options.fixHint }))
+
+        if (options.ci) {
+          const annotations = formatCIAnnotations(report)
+          if (annotations) {
+            console.log(annotations)
+          }
+        }
+      }
+
+      // Exit code
+      const { summary } = report
+      if (options.strict) {
+        process.exit(summary.totalCritical > 0 || summary.totalWarnings > 0 ? 1 : 0)
+      } else {
+        process.exit(summary.totalCritical > 0 ? 1 : 0)
+      }
+    } catch (err) {
+      console.error(chalk.red(`\n  ERROR: ${err.message}\n`))
+      if (!options.json) {
+        console.error(chalk.gray(`  ${err.stack}`))
+      }
+      process.exit(1)
+    }
+  })
+
+program.parse()

package/lib/audits/style-compliance-audit.js

@@ -0,0 +1,629 @@
+/**
+ * Style Compliance Audit — scans a Tetra consumer project for styling drift.
+ *
+ * Detects hardcoded layout dimensions, raw Tailwind color classes, hex colors,
+ * custom card patterns, and other things Tetra already solves via PageContainer,
+ * AppShell theme config, and CSS tokens (--tetra-bg, --tetra-text, etc.).
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { join, relative } from 'path'
+import { glob } from 'glob'
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/** Files under these paths get relaxed rules (only critical #3 and #4). */
+const RELAXED_PATTERNS = [
+  /\/(auth)\//,
+  /\/\(auth\)\//,
+  /\/invite\//,
+  /\/onboarding\//,
+]
+
+/** Files under these paths are skipped entirely. */
+const SKIP_PATTERNS = [
+  /\/marketing\//,
+  /\/public\//,
+  /\/landing\//,
+]
+
+/**
+ * Inline element tags whose padding classes are always legitimate UI-level
+ * padding (badges, inputs, buttons, tabs, links, labels).
+ */
+const INLINE_ELEMENT_TAGS = ['span', 'button', 'input', 'textarea', 'select', 'label', 'a']
+
+// ============================================================================
+// HELPERS — page-root detection
+// ============================================================================
+
+/**
+ * Find the line index of the `return` statement inside the default export
+ * function body. Returns -1 if not found (non-page file).
+ *
+ * Strategy: scan for `export default function` or `export default (`, then
+ * find the first `return` keyword that follows it.
+ */
+function findReturnLineIndex(lines) {
+  let inDefaultExport = false
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (!inDefaultExport) {
+      if (/export\s+default\s+(function|\()/.test(line) || /export\s+default\s+\w/.test(line)) {
+        inDefaultExport = true
+      }
+    }
+    if (inDefaultExport) {
+      // Match `return (` or `return <` (start of JSX return)
+      if (/\breturn\s*[\(<]/.test(line) || (/\breturn\b/.test(line) && /<[A-Za-z]/.test(lines[i + 1] ?? ''))) {
+        return i
+      }
+    }
+  }
+  return -1
+}
+
+/**
+ * Return true when the given line contains a JSX tag that is one of the
+ * known inline/form element tags (whitelisted for padding).
+ */
+function lineHasInlineElementTag(line) {
+  return INLINE_ELEMENT_TAGS.some((tag) => new RegExp(`<${tag}[\\s/>]`).test(line))
+}
+
+/**
+ * Return true when the line looks like a legitimate prose width constraint:
+ * element has both a prose/article context AND a max-w-* class.
+ */
+function lineIsProseWidth(line) {
+  return /\bprose\b/.test(line) || /<article[\s>]/.test(line)
+}
+
+// ============================================================================
+// RULE DEFINITIONS
+// ============================================================================
+
+/** CRITICAL violations block CI. */
+const CRITICAL_RULES = [
+  {
+    id: 'hardcoded-page-width',
+    label: 'hardcoded page width',
+    fixHint: 'Use AppShell config.layout.pageMaxWidth or fullWidthPaths instead',
+    pageOnly: true,
+    /**
+     * @param {string} line
+     * @param {object|null} ctx
+     * @param {{ returnLineIndex: number, lineIndex: number }} pageCtx
+     */
+    check(line, ctx, pageCtx) {
+      // Only flag within first 30 lines after return (page-root area)
+      if (pageCtx && pageCtx.returnLineIndex >= 0) {
+        if (pageCtx.lineIndex > pageCtx.returnLineIndex + 30) return null
+      }
+      // Whitelist prose / article contexts
+      if (lineIsProseWidth(line)) return null
+
+      if (/className\s*=/.test(line) && /\bmax-w-(xs|sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|full|screen-\S+)\b/.test(line)) {
+        return line.match(/\bmax-w-(xs|sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|full|screen-\S+)\b/)?.[0] ?? 'max-w-*'
+      }
+      // container mx-auto in className
+      if (/className\s*=/.test(line) && /\bcontainer\b/.test(line) && /\bmx-auto\b/.test(line)) {
+        return 'container mx-auto'
+      }
+      return null
+    },
+  },
+  {
+    id: 'hardcoded-page-padding',
+    label: 'hardcoded page padding',
+    fixHint: 'Use AppShell config.layout.pagePadding preset instead',
+    pageOnly: true,
+    check(line, ctx, pageCtx) {
+      // Only flag within first 30 lines after return (page-root area)
+      if (pageCtx && pageCtx.returnLineIndex >= 0) {
+        if (pageCtx.lineIndex > pageCtx.returnLineIndex + 30) return null
+      }
+      // Whitelist inline/form element tags — their padding is component-level
+      if (lineHasInlineElementTag(line)) return null
+
+      if (/className\s*=/.test(line) && /\b(p|px|py|pt|pb|pl|pr)-\d+\b/.test(line)) {
+        return line.match(/\b(p|px|py|pt|pb|pl|pr)-\d+\b/)?.[0] ?? 'p-*'
+      }
+      return null
+    },
+  },
+  {
+    id: 'hardcoded-hex-color',
+    label: 'hardcoded hex color',
+    fixHint: 'Use CSS token var(--tetra-accent) / var(--tetra-bg) etc., or set via AppShell theme config',
+    check(line) {
+      // Skip tetra-style-audit-disable-next-line handled upstream
+      // Inline style attr with hex
+      if (/style\s*=/.test(line) && /#[0-9a-fA-F]{3,8}\b/.test(line)) {
+        return line.match(/#[0-9a-fA-F]{3,8}\b/)?.[0] ?? '#hex'
+      }
+      // Tailwind arbitrary hex [#...]
+      if (/\[#[0-9a-fA-F]{3,8}\]/.test(line)) {
+        return line.match(/\[#[0-9a-fA-F]{3,8}\]/)?.[0] ?? '[#hex]'
+      }
+      return null
+    },
+  },
+  {
+    id: 'raw-tailwind-colors',
+    label: 'raw Tailwind color class',
+    fixHint: 'Replace with token classes (bg-background, text-foreground, border-border) or var(--tetra-*) tokens',
+    check(line) {
+      // Whitelist: transparent, current, inherit, and Tetra semantic tokens like text-primary-foreground
+      if (/\btext-primary-foreground\b/.test(line)) return null
+
+      const COLOR_NAMES = [
+        'white', 'black',
+        'gray', 'slate', 'zinc', 'neutral', 'stone',
+        'red', 'orange', 'amber', 'yellow', 'lime', 'green', 'emerald',
+        'teal', 'cyan', 'sky', 'blue', 'indigo', 'violet', 'purple',
+        'fuchsia', 'pink', 'rose',
+      ]
+      const colorRe = new RegExp(
+        `\\b(bg|text|border)-(${COLOR_NAMES.join('|')})-(\\d{2,3}|\\d{3}|\\d{2})\\b|\\b(bg|text|border)-(white|black)\\b`
+      )
+      // Must appear in className context
+      if (/className\s*=|class\s*=/.test(line) && colorRe.test(line)) {
+        const m = line.match(colorRe)
+        return m?.[0] ?? 'raw color class'
+      }
+      return null
+    },
+  },
+  {
+    id: 'custom-globals-override',
+    label: 'custom CSS color system overriding Tetra tokens',
+    fixHint: 'Set theme via AppShell theme prop; only override tokens in :root { --tetra-accent-subtle: ... } style',
+    cssOnly: true,
+    check(line, ctx) {
+      // Flag when defining core color variables outside the expected Tetra override pattern
+      const tetraVars = /--tetra-(accent|bg|text|border|bg-subtle)|--background\b|--foreground\b|--primary\b|--card\b/
+      if (tetraVars.test(line) && /:\s/.test(line)) {
+        // Allow if inside :root or html.dark (checked by context flag)
+        if (ctx && ctx.insideRootBlock) return null
+        return line.match(tetraVars)?.[0] ?? '--tetra-*'
+      }
+      return null
+    },
+  },
+  {
+    id: 'custom-card-classes',
+    label: 'hand-rolled card pattern',
+    fixHint: 'Use AutoCard or Card from @soulbatical/tetra-ui instead',
+    check(line) {
+      // rounded-xl border bg-card shadow or rounded-lg border border-gray-*
+      if (/className\s*=/.test(line)) {
+        if (/\brounded-(xl|lg|2xl)\b/.test(line) && /\bborder\b/.test(line) && /\b(shadow|bg-card|bg-white)\b/.test(line)) {
+          return 'rounded-* border bg-card/bg-white shadow'
+        }
+        if (/\brounded-(xl|lg)\b/.test(line) && /\bborder\b/.test(line) && /border-(gray|slate|zinc|neutral)-\d+/.test(line)) {
+          return 'rounded-* border border-gray-*'
+        }
+      }
+      return null
+    },
+  },
+]
+
+/** WARNING violations are reported but don't block CI by default. */
+const WARNING_RULES = [
+  {
+    id: 'inline-style-attr',
+    label: 'inline style attribute',
+    fixHint: 'Prefer className; if needed use var(--tetra-*) tokens in style props',
+    check(line) {
+      if (/style\s*=\s*\{\{/.test(line)) {
+        // Allow var(--tetra-*) usage
+        if (/var\(--tetra-/.test(line)) return null
+        return 'style={{ ... }}'
+      }
+      return null
+    },
+  },
+  {
+    id: 'hex-in-css',
+    label: 'hex color in CSS outside :root/html.dark',
+    fixHint: 'Move hex values into :root or html.dark CSS token blocks',
+    cssOnly: true,
+    check(line, ctx) {
+      if (ctx && ctx.insideRootBlock) return null
+      if (/#[0-9a-fA-F]{3,8}\b/.test(line) && /:\s/.test(line)) {
+        return line.match(/#[0-9a-fA-F]{3,8}\b/)?.[0] ?? '#hex'
+      }
+      return null
+    },
+  },
+  {
+    id: 'duplicate-page-header',
+    label: 'custom page header (use PageHeader from tetra-ui)',
+    fixHint: 'Import PageHeader from @soulbatical/tetra-ui',
+    check(line) {
+      if (/<h1\b[^>]*className\s*=[^>]*\btext-(2xl|3xl|4xl)\b[^>]*\bfont-bold\b/.test(line) ||
+          /<h1\b[^>]*className\s*=[^>]*\bfont-bold\b[^>]*\btext-(2xl|3xl|4xl)\b/.test(line)) {
+        return '<h1 className="text-2xl font-bold ...">'
+      }
+      return null
+    },
+  },
+  {
+    id: 'nested-padding-consider-component',
+    label: 'nested padding — consider extracting to a component',
+    fixHint: 'This padding is deep inside a page; consider extracting to a reusable component',
+    strictOnly: true,
+    check(line, ctx, pageCtx) {
+      // Only fires on page files, for lines BEYOND the first 30 lines after return
+      if (!pageCtx || pageCtx.returnLineIndex < 0) return null
+      if (pageCtx.lineIndex <= pageCtx.returnLineIndex + 30) return null
+      // Skip inline/form elements — their padding is always legitimate
+      if (lineHasInlineElementTag(line)) return null
+      if (/className\s*=/.test(line) && /\b(p|px|py|pt|pb|pl|pr)-\d+\b/.test(line)) {
+        return line.match(/\b(p|px|py|pt|pb|pl|pr)-\d+\b/)?.[0] ?? 'p-*'
+      }
+      return null
+    },
+  },
+]
+
+// ============================================================================
+// HELPERS
+// ============================================================================
+
+function isRelaxedPath(filePath) {
+  return RELAXED_PATTERNS.some((p) => p.test(filePath))
+}
+
+function isSkippedPath(filePath) {
+  return SKIP_PATTERNS.some((p) => p.test(filePath))
+}
+
+function isPageFile(filePath) {
+  return /app\/.*\/(page|layout)\.(tsx|jsx)$/.test(filePath)
+}
+
+function isCssFile(filePath) {
+  return /\.(css)$/.test(filePath)
+}
+
+/**
+ * Load extra whitelist entries from .tetra-style-whitelist.json in project root.
+ */
+function loadProjectWhitelist(projectRoot) {
+  const path = join(projectRoot, '.tetra-style-whitelist.json')
+  if (!existsSync(path)) return []
+  try {
+    const raw = readFileSync(path, 'utf-8')
+    return JSON.parse(raw).styleWhitelist || []
+  } catch {
+    return []
+  }
+}
+
+function isWhitelisted(filePath, projectWhitelist) {
+  for (const entry of projectWhitelist) {
+    const prefix = entry.path.replace(/\/\*\*$/, '').replace(/\/\*$/, '')
+    if (filePath.includes(prefix)) return true
+  }
+  return false
+}
+
+// ============================================================================
+// FILE SCANNER
+// ============================================================================
+
+async function scanFiles(projectRoot, filesGlob) {
+  if (filesGlob) {
+    return await glob(filesGlob, { cwd: projectRoot, ignore: ['**/node_modules/**', '**/.next/**', '**/dist/**', '**/build/**'] })
+  }
+
+  const patterns = [
+    'frontend/src/**/*.tsx',
+    'frontend/src/**/*.jsx',
+    'frontend/src/**/*.ts',
+    'frontend/src/**/*.js',
+    'frontend/src/**/*.css',
+  ]
+
+  const files = []
+  for (const pattern of patterns) {
+    const found = await glob(pattern, {
+      cwd: projectRoot,
+      ignore: ['**/node_modules/**', '**/.next/**', '**/dist/**', '**/build/**'],
+    })
+    files.push(...found)
+  }
+  return [...new Set(files)]
+}
+
+// ============================================================================
+// LINE-BY-LINE AUDIT
+// ============================================================================
+
+/**
+ * Track :root / html.dark block context for CSS files.
+ */
+function buildCssContext(lines, lineIndex) {
+  // Walk backwards to find if we're inside a :root or html.dark block
+  let braceDepth = 0
+  let insideRootBlock = false
+  for (let i = lineIndex; i >= 0; i--) {
+    const l = lines[i]
+    for (const ch of [...l].reverse()) {
+      if (ch === '}') braceDepth++
+      if (ch === '{') {
+        if (braceDepth === 0) {
+          // This opening brace owns us — check selector
+          if (/:root\b|html\.dark\b/.test(lines[i])) {
+            insideRootBlock = true
+          }
+          break
+        }
+        braceDepth--
+      }
+    }
+    if (braceDepth === 0 && insideRootBlock !== undefined) break
+  }
+  return { insideRootBlock }
+}
+
+/**
+ * Audit the content of a single file. Returns array of findings.
+ * Each finding: { id, label, severity, line, lineNumber, match, fixHint }
+ *
+ * @param {string} content
+ * @param {string} filePath
+ * @param {boolean} relaxed
+ * @param {{ strict?: boolean }} options
+ */
+function auditFileContent(content, filePath, relaxed, options = {}) {
+  const findings = []
+  const lines = content.split('\n')
+  const css = isCssFile(filePath)
+  const page = isPageFile(filePath)
+
+  // Find where the default export's return statement is (for page-root scoping)
+  const returnLineIndex = page ? findReturnLineIndex(lines) : -1
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const lineNumber = i + 1
+
+    // Disable comment check
+    if (i > 0 && /tetra-style-audit-disable-next-line/.test(lines[i - 1])) continue
+    if (/tetra-style-audit-disable-next-line/.test(line)) continue
+
+    const ctx = css ? buildCssContext(lines, i) : null
+    const pageCtx = page ? { returnLineIndex, lineIndex: i } : null
+
+    // Determine which rules apply
+    const criticalRules = CRITICAL_RULES.filter((r) => {
+      if (r.cssOnly && !css) return false
+      if (!r.cssOnly && css) return false
+      if (r.pageOnly && !page) return false
+      if (relaxed && r.pageOnly) return false // skip layout rules for relaxed paths
+      return true
+    })
+
+    const warningRules = WARNING_RULES.filter((r) => {
+      if (r.cssOnly && !css) return false
+      if (!r.cssOnly && css) return false
+      if (relaxed) return false // skip warnings for relaxed paths
+      if (r.strictOnly && !options.strict) return false
+      // nested-padding-consider-component only applies to page files
+      if (r.id === 'nested-padding-consider-component' && !page) return false
+      return true
+    })
+
+    for (const rule of criticalRules) {
+      const match = rule.check(line, ctx, pageCtx)
+      if (match) {
+        findings.push({
+          id: rule.id,
+          label: rule.label,
+          severity: 'critical',
+          line: line.trim(),
+          lineNumber,
+          match,
+          fixHint: rule.fixHint,
+        })
+      }
+    }
+
+    for (const rule of warningRules) {
+      const match = rule.check(line, ctx, pageCtx)
+      if (match) {
+        findings.push({
+          id: rule.id,
+          label: rule.label,
+          severity: 'warning',
+          line: line.trim(),
+          lineNumber,
+          match,
+          fixHint: rule.fixHint,
+        })
+      }
+    }
+  }
+
+  return findings
+}
+
+// ============================================================================
+// MAIN AUDIT
+// ============================================================================
+
+/**
+ * Run the full style compliance audit.
+ *
+ * @param {string} projectRoot
+ * @param {{ filesGlob?: string, strict?: boolean }} options
+ * @returns {Promise<{ results: FileResult[], summary: Summary }>}
+ */
+export async function runStyleComplianceAudit(projectRoot, options = {}) {
+  const projectWhitelist = loadProjectWhitelist(projectRoot)
+  const allFiles = await scanFiles(projectRoot, options.filesGlob)
+
+  const results = []
+
+  for (const filePath of allFiles.sort()) {
+    if (isSkippedPath(filePath) || isWhitelisted(filePath, projectWhitelist)) {
+      results.push({
+        file: filePath,
+        status: 'skipped',
+        reason: isSkippedPath(filePath) ? 'marketing/public path' : 'whitelisted',
+        findings: [],
+      })
+      continue
+    }
+
+    const relaxed = isRelaxedPath(filePath)
+    const fullPath = join(projectRoot, filePath)
+    let content = ''
+    try {
+      content = readFileSync(fullPath, 'utf-8')
+    } catch {
+      results.push({ file: filePath, status: 'error', reason: 'could not read file', findings: [] })
+      continue
+    }
+
+    const findings = auditFileContent(content, filePath, relaxed, options)
+    const criticalCount = findings.filter((f) => f.severity === 'critical').length
+    const warningCount = findings.filter((f) => f.severity === 'warning').length
+
+    let status
+    if (criticalCount > 0) {
+      status = 'violation'
+    } else if (warningCount > 0) {
+      status = 'warning'
+    } else {
+      status = 'clean'
+    }
+
+    results.push({ file: filePath, status, reason: null, findings })
+  }
+
+  // Summary
+  const scanned = results.filter((r) => r.status !== 'skipped' && r.status !== 'error')
+  const totalCritical = scanned.reduce((n, r) => n + r.findings.filter((f) => f.severity === 'critical').length, 0)
+  const totalWarnings = scanned.reduce((n, r) => n + r.findings.filter((f) => f.severity === 'warning').length, 0)
+  const filesWithViolations = scanned.filter((r) => r.status === 'violation').length
+  const filesWithWarnings = scanned.filter((r) => r.status === 'warning').length
+  const cleanFiles = scanned.filter((r) => r.status === 'clean').length
+
+  return {
+    results,
+    summary: {
+      filesScanned: scanned.length,
+      filesSkipped: results.filter((r) => r.status === 'skipped').length,
+      filesWithViolations,
+      filesWithWarnings,
+      cleanFiles,
+      totalCritical,
+      totalWarnings,
+    },
+  }
+}
+
+// ============================================================================
+// FORMATTERS
+// ============================================================================
+
+/**
+ * Format the report as pretty terminal output.
+ *
+ * @param {object} report
+ * @param {object} chalk
+ * @param {{ fixHint?: boolean }} options
+ */
+export function formatReport(report, chalk, options = {}) {
+  const lines = []
+  const { results, summary } = report
+
+  lines.push('')
+  lines.push(chalk.blue.bold('  Style Compliance Audit'))
+  lines.push(chalk.blue('  ' + '═'.repeat(24)))
+  lines.push('')
+
+  // Only print files that have findings
+  const filesWithFindings = results.filter(
+    (r) => r.status === 'violation' || r.status === 'warning'
+  )
+
+  if (filesWithFindings.length === 0) {
+    lines.push(chalk.green('  No style violations found.'))
+  }
+
+  for (const r of filesWithFindings) {
+    lines.push(chalk.white.bold(`  ${r.file}`))
+
+    for (const f of r.findings) {
+      const icon = f.severity === 'critical' ? chalk.red('    ✗') : chalk.yellow('    ⚠')
+      const idStr = f.severity === 'critical'
+        ? chalk.red(f.id)
+        : chalk.yellow(f.id)
+      lines.push(`${icon} ${idStr} ${chalk.gray(`(line ${f.lineNumber})`)}`)
+      lines.push(chalk.gray(`        ${f.match}`))
+      if (options.fixHint && f.fixHint) {
+        lines.push(chalk.cyan(`        → ${f.fixHint}`))
+      }
+    }
+
+    lines.push('')
+  }
+
+  lines.push(chalk.gray('  ' + '─'.repeat(39)))
+  lines.push(
+    chalk.white(
+      `  ${summary.filesScanned} files scanned · ` +
+      chalk.red.bold(`${summary.totalCritical} critical`) +
+      ` · ` +
+      chalk.yellow(`${summary.totalWarnings} warnings`)
+    )
+  )
+  lines.push('')
+
+  if (summary.totalCritical > 0) {
+    lines.push(
+      chalk.red.bold(
+        `  ✗ ${summary.totalCritical} critical violation${summary.totalCritical > 1 ? 's' : ''} found. Fix before merging.`
+      )
+    )
+    lines.push('')
+  } else {
+    lines.push(chalk.green.bold('  All files pass critical style checks.'))
+    lines.push('')
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Format the report as JSON.
+ */
+export function formatReportJSON(report) {
+  return JSON.stringify(report, null, 2)
+}
+
+/**
+ * Output GitHub Actions annotations for violations.
+ */
+export function formatCIAnnotations(report) {
+  const annotations = []
+
+  for (const r of report.results) {
+    for (const f of r.findings) {
+      const level = f.severity === 'critical' ? 'error' : 'warning'
+      annotations.push(
+        `::${level} file=${r.file},line=${f.lineNumber},title=Style Compliance ${f.id}::${f.match} — ${f.fixHint || f.label}`
+      )
+    }
+  }
+
+  return annotations.join('\n')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.20.22",
+  "version": "1.20.24",
   "publishConfig": {
     "access": "restricted"
   },
@@ -43,7 +43,8 @@
     "tetra-test-audit": "./bin/tetra-test-audit.js",
     "tetra-check-pages": "./bin/tetra-check-pages.js",
     "tetra-check-views": "./bin/tetra-check-views.js",
-    "tetra-doctor": "./bin/tetra-doctor.js"
+    "tetra-doctor": "./bin/tetra-doctor.js",
+    "tetra-style-audit": "./bin/tetra-style-audit.js"
   },
   "files": [
     "bin/",