@fragments-sdk/cli 0.2.2

package/src/build.ts

@@ -0,0 +1,248 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import type {
+  SegmentsConfig,
+  CompiledSegmentsFile,
+  CompiledSegment,
+  CompiledRecipe,
+} from "./core/index.js";
+import { BRAND, compileRecipe } from "./core/index.js";
+import type { RecipeDefinition } from "./core/index.js";
+import {
+  discoverSegmentFiles,
+  discoverRecipeFiles,
+  parseSegmentFile,
+  loadSegmentFile,
+  generateRegistry,
+  generateContextMd,
+} from "./core/node.js";
+
+export interface BuildResult {
+  success: boolean;
+  outputPath: string;
+  segmentCount: number;
+  errors: Array<{ file: string; error: string }>;
+  warnings: Array<{ file: string; warning: string }>;
+}
+
+/**
+ * Build compiled fragments.json file for AI consumption.
+ *
+ * Uses AST parsing to extract metadata WITHOUT executing fragment files.
+ * This means the build works without any project dependencies installed.
+ */
+export async function buildSegments(
+  config: SegmentsConfig,
+  configDir: string
+): Promise<BuildResult> {
+  const files = await discoverSegmentFiles(config, configDir);
+  const errors: Array<{ file: string; error: string }> = [];
+  const warnings: Array<{ file: string; warning: string }> = [];
+  const segments: CompiledSegmentsFile["segments"] = {};
+
+  for (const file of files) {
+    try {
+      // Read file content as text
+      const content = await readFile(file.absolutePath, "utf-8");
+
+      // Parse using AST (no execution)
+      const parsed = parseSegmentFile(content, file.relativePath);
+
+      // Collect warnings
+      for (const warning of parsed.warnings) {
+        warnings.push({ file: file.relativePath, warning });
+      }
+
+      // Check for required fields
+      if (!parsed.meta.name) {
+        errors.push({
+          file: file.relativePath,
+          error: "Missing meta.name in fragment definition",
+        });
+        continue;
+      }
+
+      // Build compiled fragment from parsed metadata
+      const compiled: CompiledSegment = {
+        filePath: file.relativePath,
+        meta: {
+          name: parsed.meta.name,
+          description: parsed.meta.description ?? "",
+          category: parsed.meta.category ?? "Uncategorized",
+          status: parsed.meta.status,
+          tags: parsed.meta.tags,
+          since: parsed.meta.since,
+          figma: parsed.meta.figma,
+        },
+        usage: {
+          when: parsed.usage.when ?? [],
+          whenNot: parsed.usage.whenNot ?? [],
+          guidelines: parsed.usage.guidelines,
+          accessibility: parsed.usage.accessibility,
+        },
+        props: Object.fromEntries(
+          Object.entries(parsed.props).map(([name, prop]) => [
+            name,
+            {
+              type: prop.type ?? "custom",
+              description: prop.description ?? "",
+              default: prop.default,
+              required: prop.required,
+              values: prop.values,
+              constraints: prop.constraints,
+            },
+          ])
+        ),
+        relations: parsed.relations.map((rel) => ({
+          component: rel.component,
+          relationship: rel.relationship as
+            | "alternative"
+            | "sibling"
+            | "parent"
+            | "child"
+            | "composition",
+          note: rel.note,
+        })),
+        variants: parsed.variants.map((v) => ({
+          name: v.name,
+          description: v.description,
+          ...(v.code && { code: v.code }),
+          ...(v.figma && { figma: v.figma }),
+          ...(v.args && { args: v.args }),
+        })),
+      };
+
+      segments[parsed.meta.name] = compiled;
+    } catch (error) {
+      errors.push({
+        file: file.relativePath,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  // Discover and compile recipe files
+  const recipes: Record<string, CompiledRecipe> = {};
+  try {
+    const recipeFiles = await discoverRecipeFiles(configDir, config.exclude);
+    for (const file of recipeFiles) {
+      try {
+        // loadSegmentFile uses esbuild to bundle+evaluate, returns default export
+        // CJS/ESM interop may double-wrap the default export
+        let raw = await loadSegmentFile(file.absolutePath) as unknown as Record<string, unknown> | null;
+        // Unwrap double-default from CJS interop
+        if (raw && 'default' in raw && typeof raw.default === 'object') {
+          raw = raw.default as Record<string, unknown>;
+        }
+        const def = raw;
+        if (def && typeof def === 'object' && 'name' in def && 'code' in def && 'components' in def) {
+          const compiled = compileRecipe(def as unknown as RecipeDefinition, file.relativePath);
+          recipes[compiled.name] = compiled;
+        }
+      } catch (error) {
+        warnings.push({
+          file: file.relativePath,
+          warning: `Failed to load recipe: ${error instanceof Error ? error.message : String(error)}`,
+        });
+      }
+    }
+  } catch {
+    // Recipe discovery failure is non-fatal
+  }
+
+  const output: CompiledSegmentsFile = {
+    version: "1.0.0",
+    generatedAt: new Date().toISOString(),
+    segments,
+    ...(Object.keys(recipes).length > 0 && { recipes }),
+  };
+
+  const outputPath = resolve(configDir, config.outFile ?? BRAND.outFile);
+  await writeFile(outputPath, JSON.stringify(output));
+
+  return {
+    success: errors.length === 0,
+    outputPath,
+    segmentCount: Object.keys(segments).length,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Result of building the .fragments directory
+ */
+export interface FragmentsBuildResult {
+  success: boolean;
+  indexPath: string;
+  registryPath: string;
+  contextPath: string;
+  componentCount: number;
+  errors: Array<{ file: string; error: string }>;
+  warnings: Array<{ file: string; warning: string }>;
+}
+
+/**
+ * Build the .fragments/ directory with index.json, registry.json, and context.md
+ *
+ * This generates:
+ * - .fragments/index.json - Minimal name → path mapping (tiny, for quick lookups)
+ * - .fragments/registry.json - Component index with paths and enrichment references
+ * - .fragments/context.md - AI-ready consolidated context file
+ */
+export async function buildFragmentsDir(
+  config: SegmentsConfig,
+  configDir: string
+): Promise<FragmentsBuildResult> {
+  const fragmentsDir = join(configDir, BRAND.dataDir);
+  const componentsDir = join(fragmentsDir, BRAND.componentsDir);
+
+  // Create directories
+  await mkdir(fragmentsDir, { recursive: true });
+  await mkdir(componentsDir, { recursive: true });
+
+  // Generate registry with config options
+  const registryResult = await generateRegistry({
+    projectRoot: configDir,
+    componentPatterns: config.components || ["src/**/*.tsx", "src/**/*.ts"],
+    storyPatterns: config.include || ["src/**/*.stories.tsx"],
+    fragmentsDir,
+    registryOptions: config.registry || {},
+  });
+
+  const errors = [...registryResult.errors];
+  const warnings = [...registryResult.warnings];
+
+  // Write index.json (minimal name → path)
+  const indexPath = join(fragmentsDir, "index.json");
+  await writeFile(indexPath, JSON.stringify(registryResult.index, null, 2));
+
+  // Write registry.json (full metadata)
+  const registryPath = join(fragmentsDir, BRAND.registryFile);
+  await writeFile(registryPath, JSON.stringify(registryResult.registry, null, 2));
+
+  // Generate context.md - focus on semantic knowledge, skip props (AI can read source)
+  const contextResult = generateContextMd(registryResult.registry, {
+    format: "markdown",
+    compact: false,
+    include: {
+      props: false, // AI can read TypeScript directly
+      relations: true,
+      code: false,
+    },
+  });
+
+  // Write context.md
+  const contextPath = join(fragmentsDir, BRAND.contextFile);
+  await writeFile(contextPath, contextResult.content);
+
+  return {
+    success: errors.length === 0,
+    indexPath,
+    registryPath,
+    contextPath,
+    componentCount: registryResult.registry.componentCount,
+    errors,
+    warnings,
+  };
+}

package/src/commands/a11y.ts

@@ -0,0 +1,302 @@
+/**
+ * fragments a11y - Run accessibility checks on all component variants
+ *
+ * Uses the /fragments/a11y endpoint to get axe-core accessibility results
+ * for all components in the design system.
+ */
+
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+import { loadConfig } from '../core/node.js';
+import {
+  createDevServerClient,
+  DevServerConnectionError,
+} from '../shared/index.js';
+
+/**
+ * Options for a11y command
+ */
+export interface A11yOptions {
+  /** Path to config file */
+  config?: string;
+  /** Output JSON format */
+  json?: boolean;
+  /** CI mode - exit code 1 if any critical/serious violations */
+  ci?: boolean;
+  /** Check specific component only */
+  component?: string;
+  /** Dev server port */
+  port?: number | string;
+}
+
+/**
+ * A11y result for a single variant
+ */
+export interface A11yVariantResult {
+  /** Variant name */
+  variant: string;
+  /** Number of violations */
+  violations: number;
+  /** Number of passes */
+  passes: number;
+  /** Number of incomplete checks */
+  incomplete: number;
+  /** Violation summary by severity */
+  summary: {
+    total: number;
+    critical: number;
+    serious: number;
+    moderate: number;
+    minor: number;
+  };
+}
+
+/**
+ * A11y result for a component
+ */
+export interface A11yComponentResult {
+  /** Component name */
+  component: string;
+  /** Results for each variant */
+  results: A11yVariantResult[];
+  /** Overall status */
+  status: 'PASS' | 'WARN' | 'FAIL';
+  /** Total violations across all variants */
+  totalViolations: number;
+  /** Total critical violations */
+  totalCritical: number;
+  /** Total serious violations */
+  totalSerious: number;
+}
+
+/**
+ * Summary of a11y results
+ */
+export interface A11ySummary {
+  /** Total number of components */
+  totalComponents: number;
+  /** Number of accessible components (no critical/serious) */
+  accessibleComponents: number;
+  /** Percentage of accessible components */
+  accessiblePercent: number;
+  /** All component results */
+  components: A11yComponentResult[];
+  /** Total violations across all components */
+  totalViolations: number;
+  /** Total critical violations */
+  totalCritical: number;
+  /** Total serious violations */
+  totalSerious: number;
+  /** Total moderate violations */
+  totalModerate: number;
+  /** Total minor violations */
+  totalMinor: number;
+  /** Whether CI check passed (no critical/serious) */
+  passed: boolean;
+}
+
+/**
+ * Run the a11y command
+ */
+export async function a11y(options: A11yOptions = {}): Promise<A11ySummary> {
+  const { config: configPath, json = false, ci = false, component, port = 6006 } = options;
+
+  // Load config
+  await loadConfig(configPath);
+
+  const client = createDevServerClient(port);
+  const componentResults: A11yComponentResult[] = [];
+
+  if (!json) {
+    console.log(pc.cyan(`\n${BRAND.name} Accessibility Report\n`));
+  }
+
+  // Check if dev server is reachable
+  const isReachable = await client.ping();
+  if (!isReachable) {
+    throw new DevServerConnectionError(
+      `Cannot connect to dev server at http://localhost:${port}`,
+      `http://localhost:${port}`
+    );
+  }
+
+  // Fetch all segments
+  const segments = await client.getSegments();
+
+  if (segments.length === 0) {
+    if (json) {
+      console.log(JSON.stringify({ error: 'No fragments found', components: [] }));
+    } else {
+      console.log(pc.yellow('No fragments found.\n'));
+    }
+    return {
+      totalComponents: 0,
+      accessibleComponents: 0,
+      accessiblePercent: 100,
+      components: [],
+      totalViolations: 0,
+      totalCritical: 0,
+      totalSerious: 0,
+      totalModerate: 0,
+      totalMinor: 0,
+      passed: true,
+    };
+  }
+
+  // Filter to specific component if requested
+  const componentsToCheck = component
+    ? segments.filter(s => s.name.toLowerCase() === component.toLowerCase())
+    : segments;
+
+  if (component && componentsToCheck.length === 0) {
+    const error = `Component '${component}' not found. Available: ${segments.map(s => s.name).join(', ')}`;
+    if (json) {
+      console.log(JSON.stringify({ error }));
+    } else {
+      console.log(pc.red(error));
+    }
+    throw new Error(error);
+  }
+
+  if (!json) {
+    console.log(pc.dim(`Checking ${componentsToCheck.length} component(s) for accessibility issues...\n`));
+  }
+
+  // Check each component
+  for (const seg of componentsToCheck) {
+    try {
+      // Get a11y results from the server
+      const a11yResult = await client.getA11y(seg.name);
+
+      let totalViolations = 0;
+      let totalCritical = 0;
+      let totalSerious = 0;
+
+      for (const result of a11yResult.results) {
+        totalViolations += result.summary.total;
+        totalCritical += result.summary.critical;
+        totalSerious += result.summary.serious;
+      }
+
+      // Determine status
+      let status: 'PASS' | 'WARN' | 'FAIL' = 'PASS';
+      if (totalCritical > 0 || totalSerious > 0) {
+        status = 'FAIL';
+      } else if (totalViolations > 0) {
+        status = 'WARN';
+      }
+
+      componentResults.push({
+        component: seg.name,
+        results: a11yResult.results,
+        status,
+        totalViolations,
+        totalCritical,
+        totalSerious,
+      });
+    } catch (error) {
+      // Handle individual component errors
+      componentResults.push({
+        component: seg.name,
+        results: [],
+        status: 'FAIL',
+        totalViolations: 0,
+        totalCritical: 0,
+        totalSerious: 0,
+      });
+    }
+  }
+
+  // Calculate summary
+  const accessibleComponents = componentResults.filter(c => c.status !== 'FAIL').length;
+  const totalViolations = componentResults.reduce((sum, c) => sum + c.totalViolations, 0);
+  const totalCritical = componentResults.reduce((sum, c) => sum + c.totalCritical, 0);
+  const totalSerious = componentResults.reduce((sum, c) => sum + c.totalSerious, 0);
+
+  // Calculate moderate and minor from all results
+  let totalModerate = 0;
+  let totalMinor = 0;
+  for (const comp of componentResults) {
+    for (const result of comp.results) {
+      totalModerate += result.summary.moderate;
+      totalMinor += result.summary.minor;
+    }
+  }
+
+  const summary: A11ySummary = {
+    totalComponents: componentResults.length,
+    accessibleComponents,
+    accessiblePercent: componentResults.length > 0
+      ? Math.round((accessibleComponents / componentResults.length) * 100)
+      : 100,
+    components: componentResults,
+    totalViolations,
+    totalCritical,
+    totalSerious,
+    totalModerate,
+    totalMinor,
+    passed: totalCritical === 0 && totalSerious === 0,
+  };
+
+  if (json) {
+    // JSON output for CI/automation
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    // Table output for humans
+    console.log(pc.bold(
+      'Component'.padEnd(20) +
+      'Variants'.padEnd(10) +
+      'Violations'.padEnd(12) +
+      'Critical'.padEnd(10) +
+      'Serious'.padEnd(10) +
+      'Status'
+    ));
+    console.log(pc.dim('─'.repeat(72)));
+
+    for (const result of componentResults) {
+      const statusColor = result.status === 'PASS'
+        ? pc.green
+        : result.status === 'WARN'
+          ? pc.yellow
+          : pc.red;
+
+      const variantCount = result.results.length || 1;
+
+      console.log(
+        result.component.padEnd(20) +
+        String(variantCount).padEnd(10) +
+        String(result.totalViolations).padEnd(12) +
+        String(result.totalCritical).padEnd(10) +
+        String(result.totalSerious).padEnd(10) +
+        statusColor(result.status)
+      );
+    }
+
+    console.log(pc.dim('─'.repeat(72)));
+
+    console.log();
+    console.log(pc.bold('Summary:'));
+    console.log(`  ${accessibleComponents}/${componentResults.length} components accessible (${summary.accessiblePercent}%)`);
+    console.log(`  Total violations: ${totalViolations} (${totalCritical} critical, ${totalSerious} serious, ${totalModerate} moderate, ${totalMinor} minor)`);
+
+    if (!summary.passed) {
+      console.log();
+      console.log(pc.red('✗ 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'));
+    } else {
+      console.log();
+      console.log(pc.green('✓ All components pass accessibility checks'));
+    }
+
+    console.log();
+  }
+
+  // In CI mode, throw if there are critical/serious violations
+  if (ci && !summary.passed) {
+    throw new Error(`Accessibility check failed: ${totalCritical} critical, ${totalSerious} serious violations found`);
+  }
+
+  return summary;
+}