@fragments-sdk/cli 0.5.2 → 0.7.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;

package/src/commands/graph.ts

@@ -0,0 +1,274 @@
+/**
+ * `fragments graph` — query the component relationship graph from the CLI.
+ *
+ * Loads fragments.json, instantiates the ComponentGraphEngine, and runs
+ * the requested query mode. Output formats: table (colored terminal), json, dot.
+ */
+
+import pc from 'picocolors';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { CompiledSegmentsFile } from '../core/index.js';
+import { BRAND } from '../core/index.js';
+import { loadConfig } from '../core/node.js';
+import {
+  ComponentGraphEngine,
+  deserializeGraph,
+} from '@fragments-sdk/context/graph';
+import type { GraphEdgeType } from '@fragments-sdk/context/graph';
+
+export interface GraphCommandOptions {
+  config?: string;
+  mode?: string;
+  target?: string;
+  edgeTypes?: string;
+  depth?: number;
+  format?: 'table' | 'json' | 'dot';
+}
+
+export async function graph(
+  component: string | undefined,
+  options: GraphCommandOptions,
+): Promise<void> {
+  const { config, configDir } = await loadConfig(options.config);
+  const outputPath = resolve(configDir, config.outFile ?? BRAND.outFile);
+
+  let data: CompiledSegmentsFile;
+  try {
+    const content = await readFile(outputPath, 'utf-8');
+    data = JSON.parse(content) as CompiledSegmentsFile;
+  } catch {
+    console.error(
+      pc.red(`Error: Could not load ${BRAND.outFile}. Run \`${BRAND.cliCommand} build\` first.`),
+    );
+    process.exit(1);
+  }
+
+  if (!data.graph) {
+    console.error(
+      pc.red(`Error: No graph data in ${BRAND.outFile}. Rebuild with the latest CLI.`),
+    );
+    process.exit(1);
+  }
+
+  const graph = deserializeGraph(data.graph);
+  const blocks = data.blocks
+    ? Object.fromEntries(
+        Object.entries(data.blocks).map(([k, v]) => [k, { components: v.components }]),
+      )
+    : undefined;
+  const engine = new ComponentGraphEngine(graph, blocks);
+
+  const mode = options.mode ?? (component ? 'dependencies' : 'health');
+  const format = options.format ?? 'table';
+  const edgeTypes = options.edgeTypes
+    ? (options.edgeTypes.split(',') as GraphEdgeType[])
+    : undefined;
+
+  // Validate component exists for modes that require it
+  const needsComponent = ['dependencies', 'dependents', 'impact', 'path', 'composition', 'alternatives'];
+  if (needsComponent.includes(mode) && !component) {
+    console.error(pc.red(`Error: "${mode}" mode requires a component name.`));
+    process.exit(1);
+  }
+  if (component && !engine.hasNode(component)) {
+    console.error(pc.red(`Error: Component "${component}" not found in graph.`));
+    process.exit(1);
+  }
+
+  switch (mode) {
+    case 'health': {
+      const health = engine.getHealth();
+      if (format === 'json') {
+        console.log(JSON.stringify(health, null, 2));
+        return;
+      }
+
+      console.log(pc.bold('\nComponent Graph Health\n'));
+      console.log(`  ${pc.cyan('Nodes:')}     ${health.nodeCount}`);
+      console.log(`  ${pc.cyan('Edges:')}     ${health.edgeCount}`);
+      console.log(`  ${pc.cyan('Avg degree:')} ${health.averageDegree}`);
+      console.log(`  ${pc.cyan('Islands:')}   ${health.connectedComponents.length}`);
+      console.log(`  ${pc.cyan('Coverage:')}  ${health.compositionCoverage}% in blocks`);
+      console.log(`  ${pc.cyan('Orphans:')}   ${health.orphans.length > 0 ? health.orphans.join(', ') : pc.green('none')}`);
+
+      if (health.hubs.length > 0) {
+        console.log(`\n  ${pc.bold('Top hubs:')}`);
+        for (const hub of health.hubs.slice(0, 5)) {
+          console.log(`    ${pc.yellow(hub.name)} — ${hub.degree} connections`);
+        }
+      }
+      console.log();
+      break;
+    }
+
+    case 'dependencies': {
+      const deps = engine.dependencies(component!, edgeTypes);
+      if (format === 'json') {
+        console.log(JSON.stringify({ component, dependencies: deps }, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`\nDependencies of ${component}\n`));
+      if (deps.length === 0) {
+        console.log('  No outgoing dependencies.');
+      } else {
+        for (const dep of deps) {
+          console.log(`  ${pc.yellow(dep.target)} ${pc.dim(`(${dep.type})`)}${dep.note ? ` — ${dep.note}` : ''}`);
+        }
+      }
+      console.log();
+      break;
+    }
+
+    case 'dependents': {
+      const deps = engine.dependents(component!, edgeTypes);
+      if (format === 'json') {
+        console.log(JSON.stringify({ component, dependents: deps }, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`\nDependents of ${component}\n`));
+      if (deps.length === 0) {
+        console.log('  No incoming dependents.');
+      } else {
+        for (const dep of deps) {
+          console.log(`  ${pc.yellow(dep.source)} ${pc.dim(`(${dep.type})`)}${dep.note ? ` — ${dep.note}` : ''}`);
+        }
+      }
+      console.log();
+      break;
+    }
+
+    case 'impact': {
+      const result = engine.impact(component!, options.depth ?? 3);
+      if (format === 'json') {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`\nImpact analysis: ${component}\n`));
+      console.log(`  ${pc.red(`${result.totalAffected}`)} affected components, ${pc.red(`${result.affectedBlocks.length}`)} affected blocks\n`);
+
+      if (result.affected.length > 0) {
+        console.log(`  ${pc.bold('Affected components:')}`);
+        for (const entry of result.affected) {
+          const indent = '  '.repeat(entry.depth + 1);
+          console.log(`${indent}${pc.yellow(entry.component)} ${pc.dim(`(depth ${entry.depth}, via ${entry.edgeType})`)}`);
+        }
+      }
+
+      if (result.affectedBlocks.length > 0) {
+        console.log(`\n  ${pc.bold('Affected blocks:')} ${result.affectedBlocks.join(', ')}`);
+      }
+      console.log();
+      break;
+    }
+
+    case 'path': {
+      if (!options.target) {
+        console.error(pc.red('Error: --target is required for path mode.'));
+        process.exit(1);
+      }
+
+      const result = engine.path(component!, options.target);
+      if (format === 'json') {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`\nPath: ${component} → ${options.target}\n`));
+      if (!result.found) {
+        console.log(`  ${pc.red('No path found.')}`);
+      } else {
+        console.log(`  ${result.path.map(n => pc.yellow(n)).join(pc.dim(' → '))}`);
+        if (result.edges.length > 0) {
+          console.log(`  ${pc.dim(`(${result.edges.map(e => e.type).join(' → ')})`)}`);
+        }
+      }
+      console.log();
+      break;
+    }
+
+    case 'composition': {
+      const tree = engine.composition(component!);
+      if (format === 'json') {
+        console.log(JSON.stringify(tree, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`\nComposition: ${component}\n`));
+      console.log(`  ${pc.cyan('Pattern:')}    ${tree.compositionPattern ?? 'unknown'}`);
+      if (tree.parent) {
+        console.log(`  ${pc.cyan('Parent:')}     ${tree.parent}`);
+      }
+      if (tree.subComponents.length > 0) {
+        console.log(`  ${pc.cyan('Sub-components:')}`);
+        for (const sub of tree.subComponents) {
+          const isRequired = tree.requiredChildren.includes(sub);
+          console.log(`    ${pc.yellow(sub)}${isRequired ? pc.red(' (required)') : ''}`);
+        }
+      }
+      if (tree.siblings.length > 0) {
+        console.log(`  ${pc.cyan('Siblings:')}   ${tree.siblings.join(', ')}`);
+      }
+      if (tree.blocks.length > 0) {
+        console.log(`  ${pc.cyan('In blocks:')}  ${tree.blocks.join(', ')}`);
+      }
+      console.log();
+      break;
+    }
+
+    case 'alternatives': {
+      const alts = engine.alternatives(component!);
+      if (format === 'json') {
+        console.log(JSON.stringify({ component, alternatives: alts }, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`\nAlternatives for ${component}\n`));
+      if (alts.length === 0) {
+        console.log('  No known alternatives.');
+      } else {
+        for (const alt of alts) {
+          console.log(`  ${pc.yellow(alt.component)}${alt.note ? ` — ${alt.note}` : ''}`);
+        }
+      }
+      console.log();
+      break;
+    }
+
+    case 'islands': {
+      const islands = engine.islands();
+      if (format === 'json') {
+        console.log(JSON.stringify({ islands }, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`\nConnected Islands (${islands.length})\n`));
+      for (let i = 0; i < islands.length; i++) {
+        console.log(`  ${pc.cyan(`Island ${i + 1}`)} (${islands[i].length} components): ${islands[i].join(', ')}`);
+      }
+      console.log();
+      break;
+    }
+
+    default:
+      console.error(pc.red(`Unknown mode: "${mode}". Valid: health, dependencies, dependents, impact, path, composition, alternatives, islands`));
+      process.exit(1);
+  }
+
+  // Graphviz dot output
+  if (format === 'dot') {
+    const lines = ['digraph ComponentGraph {', '  rankdir=LR;', '  node [shape=box, style=rounded];'];
+    for (const node of graph.nodes) {
+      lines.push(`  "${node.name}" [label="${node.name}\\n(${node.category})"];`);
+    }
+    for (const edge of graph.edges) {
+      const style = edge.type === 'alternative-to' ? 'dashed' : 'solid';
+      lines.push(`  "${edge.source}" -> "${edge.target}" [label="${edge.type}", style=${style}];`);
+    }
+    lines.push('}');
+    console.log(lines.join('\n'));
+  }
+}