@fragments-sdk/cli 0.5.2 → 0.6.0

package/src/commands/a11y.ts

@@ -5,6 +5,7 @@
  * for all components in the design system.
  */
 
+import fs from 'node:fs';
 import pc from 'picocolors';
 import { BRAND } from '../core/index.js';
 import { loadConfig } from '../core/node.js';
@@ -12,6 +13,7 @@ import {
   createDevServerClient,
   DevServerConnectionError,
 } from '../shared/index.js';
+import { generateA11yReport } from './a11y-report.js';
 
 /**
  * Options for a11y command
@@ -27,6 +29,14 @@ export interface A11yOptions {
   component?: string;
   /** Dev server port */
   port?: number | string;
+  /** Output format: table (default), json, or github (markdown) */
+  format?: 'table' | 'json' | 'github';
+  /** WCAG standard level to check against */
+  standard?: 'AA' | 'AAA';
+  /** Generate standalone HTML compliance report */
+  report?: boolean;
+  /** Output path for the HTML report */
+  output?: string;
 }
 
 /**
@@ -69,6 +79,18 @@ export interface A11yComponentResult {
   totalSerious: number;
 }
 
+/**
+ * A11y score breakdown
+ */
+export interface A11yScore {
+  /** Numeric score 0–100 */
+  score: number;
+  /** Percentage of components meeting AA */
+  aaPercent: number;
+  /** Percentage of components meeting AAA */
+  aaaPercent: number;
+}
+
 /**
  * Summary of a11y results
  */
@@ -93,13 +115,98 @@ export interface A11ySummary {
   totalMinor: number;
   /** Whether CI check passed (no critical/serious) */
   passed: boolean;
+  /** Computed a11y score */
+  score?: A11yScore;
+}
+
+/**
+ * Calculate an accessibility score from the summary.
+ *
+ * Starts at 100 and subtracts per violation:
+ *   critical: -10, serious: -5, moderate: -2, minor: -1
+ */
+export function calculateA11yScore(summary: A11ySummary): A11yScore {
+  const deductions =
+    summary.totalCritical * 10 +
+    summary.totalSerious * 5 +
+    summary.totalModerate * 2 +
+    summary.totalMinor * 1;
+
+  const score = Math.max(0, 100 - deductions);
+
+  // AA = no critical/serious violations
+  const aaComponents = summary.components.filter(
+    c => c.totalCritical === 0 && c.totalSerious === 0
+  ).length;
+  const aaPercent = summary.totalComponents > 0
+    ? Math.round((aaComponents / summary.totalComponents) * 100)
+    : 100;
+
+  // AAA = no violations at all
+  const aaaComponents = summary.components.filter(
+    c => c.totalViolations === 0
+  ).length;
+  const aaaPercent = summary.totalComponents > 0
+    ? Math.round((aaaComponents / summary.totalComponents) * 100)
+    : 100;
+
+  return { score, aaPercent, aaaPercent };
+}
+
+/**
+ * Format summary as GitHub-flavored Markdown.
+ */
+export function formatGitHub(summary: A11ySummary): string {
+  const score = summary.score ?? calculateA11yScore(summary);
+  const badge = summary.passed ? 'passing' : 'failing';
+  const badgeColor = summary.passed ? 'brightgreen' : 'red';
+  const lines: string[] = [];
+
+  lines.push(`## ${BRAND.name} Accessibility Report`);
+  lines.push('');
+  lines.push(`![a11y](https://img.shields.io/badge/a11y-${badge}-${badgeColor})`);
+  lines.push(`**Score:** ${score.score}/100 | **AA:** ${score.aaPercent}% | **AAA:** ${score.aaaPercent}%`);
+  lines.push('');
+
+  // Component table
+  lines.push('| Component | Variants | Violations | Critical | Serious | Status |');
+  lines.push('|-----------|----------|------------|----------|---------|--------|');
+
+  for (const result of summary.components) {
+    const statusIcon = result.status === 'PASS' ? 'PASS' : result.status === 'WARN' ? 'WARN' : 'FAIL';
+    const variantCount = result.results.length || 1;
+    lines.push(
+      `| ${result.component} | ${variantCount} | ${result.totalViolations} | ${result.totalCritical} | ${result.totalSerious} | ${statusIcon} |`
+    );
+  }
+
+  lines.push('');
+  lines.push(`**Summary:** ${summary.accessibleComponents}/${summary.totalComponents} components accessible (${summary.accessiblePercent}%)`);
+  lines.push(`**Violations:** ${summary.totalViolations} total (${summary.totalCritical} critical, ${summary.totalSerious} serious, ${summary.totalModerate} moderate, ${summary.totalMinor} minor)`);
+
+  if (summary.totalCritical + summary.totalSerious > 0) {
+    lines.push('');
+    lines.push(`**Blocking:** ${summary.totalCritical + summary.totalSerious} critical/serious issues must be fixed`);
+  }
+
+  lines.push('');
+
+  return lines.join('\n');
 }
 
 /**
  * Run the a11y command
  */
 export async function a11y(options: A11yOptions = {}): Promise<A11ySummary> {
-  const { config: configPath, json = false, ci = false, component, port = 6006 } = options;
+  const {
+    config: configPath,
+    json = false,
+    ci = false,
+    component,
+    port = 6006,
+    format = json ? 'json' : 'table',
+    standard = 'AA',
+  } = options;
 
   // Load config
   await loadConfig(configPath);
@@ -107,7 +214,9 @@ export async function a11y(options: A11yOptions = {}): Promise<A11ySummary> {
   const client = createDevServerClient(port);
   const componentResults: A11yComponentResult[] = [];
 
-  if (!json) {
+  const isJsonOutput = format === 'json' || json;
+
+  if (!isJsonOutput && format !== 'github') {
     console.log(pc.cyan(`\n${BRAND.name} Accessibility Report\n`));
   }
 
@@ -124,7 +233,7 @@ export async function a11y(options: A11yOptions = {}): Promise<A11ySummary> {
   const segments = await client.getSegments();
 
   if (segments.length === 0) {
-    if (json) {
+    if (isJsonOutput) {
       console.log(JSON.stringify({ error: 'No fragments found', components: [] }));
     } else {
       console.log(pc.yellow('No fragments found.\n'));
@@ -150,7 +259,7 @@ export async function a11y(options: A11yOptions = {}): Promise<A11ySummary> {
 
   if (component && componentsToCheck.length === 0) {
     const error = `Component '${component}' not found. Available: ${segments.map(s => s.name).join(', ')}`;
-    if (json) {
+    if (isJsonOutput) {
       console.log(JSON.stringify({ error }));
     } else {
       console.log(pc.red(error));
@@ -158,7 +267,7 @@ export async function a11y(options: A11yOptions = {}): Promise<A11ySummary> {
     throw new Error(error);
   }
 
-  if (!json) {
+  if (!isJsonOutput && format !== 'github') {
     console.log(pc.dim(`Checking ${componentsToCheck.length} component(s) for accessibility issues...\n`));
   }
 
@@ -186,6 +295,11 @@ export async function a11y(options: A11yOptions = {}): Promise<A11ySummary> {
         status = 'WARN';
       }
 
+      // In AAA mode, any violation is a failure
+      if (standard === 'AAA' && totalViolations > 0) {
+        status = 'FAIL';
+      }
+
       componentResults.push({
         component: seg.name,
         results: a11yResult.results,
@@ -194,7 +308,7 @@ export async function a11y(options: A11yOptions = {}): Promise<A11ySummary> {
         totalCritical,
         totalSerious,
       });
-    } catch (error) {
+    } catch {
       // Handle individual component errors
       componentResults.push({
         component: seg.name,
@@ -223,6 +337,10 @@ export async function a11y(options: A11yOptions = {}): Promise<A11ySummary> {
     }
   }
 
+  const passed = standard === 'AAA'
+    ? totalViolations === 0
+    : totalCritical === 0 && totalSerious === 0;
+
   const summary: A11ySummary = {
     totalComponents: componentResults.length,
     accessibleComponents,
@@ -235,14 +353,18 @@ export async function a11y(options: A11yOptions = {}): Promise<A11ySummary> {
     totalSerious,
     totalModerate,
     totalMinor,
-    passed: totalCritical === 0 && totalSerious === 0,
+    passed,
   };
 
-  if (json) {
-    // JSON output for CI/automation
+  summary.score = calculateA11yScore(summary);
+
+  // --- Output ---
+  if (format === 'github') {
+    console.log(formatGitHub(summary));
+  } else if (isJsonOutput) {
     console.log(JSON.stringify(summary, null, 2));
   } else {
-    // Table output for humans
+    // Rich table output
     console.log(pc.bold(
       'Component'.padEnd(20) +
       'Variants'.padEnd(10) +
@@ -273,6 +395,30 @@ export async function a11y(options: A11yOptions = {}): Promise<A11ySummary> {
     }
 
     console.log(pc.dim('─'.repeat(72)));
+    console.log();
+
+    // Violation breakdown with dotted leaders
+    const categories = [
+      { label: 'Critical', count: totalCritical, color: pc.red },
+      { label: 'Serious', count: totalSerious, color: pc.red },
+      { label: 'Moderate', count: totalModerate, color: pc.yellow },
+      { label: 'Minor', count: totalMinor, color: pc.dim },
+    ];
+
+    for (const cat of categories) {
+      if (cat.count > 0) {
+        const dots = '.'.repeat(Math.max(1, 30 - cat.label.length));
+        console.log(`  ${cat.label} ${pc.dim(dots)} ${cat.color(String(cat.count))}`);
+      }
+    }
+
+    // Score box
+    const { score, aaPercent, aaaPercent } = summary.score;
+    console.log();
+    console.log(pc.bold(`  Score: ${score}/100`));
+    console.log(`  AA compliance .... ${aaPercent}%`);
+    console.log(`  AAA compliance ... ${aaaPercent}%`);
+    console.log(`  Standard ......... WCAG ${standard}`);
 
     console.log();
     console.log(pc.bold('Summary:'));
@@ -281,19 +427,27 @@ export async function a11y(options: A11yOptions = {}): Promise<A11ySummary> {
 
     if (!summary.passed) {
       console.log();
-      console.log(pc.red('✗ Accessibility check failed - critical/serious violations found'));
+      console.log(pc.red('x Accessibility check failed - critical/serious violations found'));
     } else if (totalViolations > 0) {
       console.log();
-      console.log(pc.yellow('⚠ Minor/moderate violations found - consider fixing for better accessibility'));
+      console.log(pc.yellow('! Minor/moderate violations found - consider fixing for better accessibility'));
     } else {
       console.log();
-      console.log(pc.green('✓ All components pass accessibility checks'));
+      console.log(pc.green('v All components pass accessibility checks'));
     }
 
     console.log();
   }
 
-  // In CI mode, throw if there are critical/serious violations
+  // Generate HTML report if requested
+  if (options.report) {
+    const outputPath = options.output ?? 'a11y-report.html';
+    const html = generateA11yReport(summary);
+    fs.writeFileSync(outputPath, html, 'utf-8');
+    console.log(pc.green('v Report generated: ' + outputPath));
+  }
+
+  // In CI mode, throw if check did not pass
   if (ci && !summary.passed) {
     throw new Error(`Accessibility check failed: ${totalCritical} critical, ${totalSerious} serious violations found`);
   }

package/src/commands/build.ts

@@ -101,6 +101,14 @@ export async function build(options: BuildOptions = {}): Promise<BuildResult> {
       console.log();
     }
 
+    if (result.warnings.length > 0) {
+      console.log(pc.yellow('Build warnings:\n'));
+      for (const warning of result.warnings) {
+        console.log(`  ${pc.yellow('⚠')} ${warning.file}: ${warning.warning}`);
+      }
+      console.log();
+    }
+
     segmentCount = result.segmentCount;
     outputPath = result.outputPath;
 
@@ -123,6 +131,14 @@ export async function build(options: BuildOptions = {}): Promise<BuildResult> {
       console.log();
     }
 
+    if (fragmentsResult.warnings.length > 0) {
+      console.log(pc.yellow('Registry warnings:\n'));
+      for (const warning of fragmentsResult.warnings) {
+        console.log(`  ${pc.yellow('⚠')} ${warning.file}: ${warning.warning}`);
+      }
+      console.log();
+    }
+
     componentCount = fragmentsResult.componentCount;
     registryPath = fragmentsResult.registryPath;
     contextPath = fragmentsResult.contextPath;