@fragments-sdk/cli 0.2.2

package/src/test/types.ts

@@ -0,0 +1,245 @@
+/**
+ * Types for the segments test CLI command
+ */
+
+import type { PlayFunction, SegmentVariant } from '../core/index.js';
+
+/**
+ * A test case discovered from segment files
+ */
+export interface TestCase {
+  /** Unique identifier for this test */
+  id: string;
+  /** Component name */
+  component: string;
+  /** Variant name */
+  variant: string;
+  /** Tags from the variant */
+  tags: string[];
+  /** The play function to execute */
+  play: PlayFunction;
+  /** Source file path */
+  sourceFile: string;
+  /** Story ID for navigation */
+  storyId?: string;
+}
+
+/**
+ * Result of a single step within a test
+ */
+export interface StepResult {
+  /** Step name */
+  name: string;
+  /** Step status */
+  status: 'passed' | 'failed' | 'skipped';
+  /** Duration in milliseconds */
+  duration: number;
+  /** Error if step failed */
+  error?: TestError;
+}
+
+/**
+ * Error information from a failed test
+ */
+export interface TestError {
+  /** Error message */
+  message: string;
+  /** Stack trace */
+  stack?: string;
+  /** Assertion details if applicable */
+  expected?: unknown;
+  /** Actual value if applicable */
+  actual?: unknown;
+}
+
+/**
+ * Accessibility violation from axe-core
+ */
+export interface A11yViolation {
+  /** Violation ID */
+  id: string;
+  /** Impact level */
+  impact: 'critical' | 'serious' | 'moderate' | 'minor';
+  /** Description */
+  description: string;
+  /** Help text */
+  help: string;
+  /** Help URL */
+  helpUrl: string;
+  /** Affected nodes */
+  nodes: Array<{
+    html: string;
+    target: string[];
+  }>;
+}
+
+/**
+ * Accessibility check result
+ */
+export interface A11yResult {
+  /** Number of violations */
+  violations: A11yViolation[];
+  /** Number of passing checks */
+  passes: number;
+}
+
+/**
+ * Result of a single test case execution
+ */
+export interface TestResult {
+  /** The test case that was run */
+  testCase: TestCase;
+  /** Overall test status */
+  status: 'passed' | 'failed' | 'skipped';
+  /** Total duration in milliseconds */
+  duration: number;
+  /** Results of individual steps */
+  steps: StepResult[];
+  /** Error if test failed */
+  error?: TestError;
+  /** Accessibility check result */
+  accessibility?: A11yResult;
+  /** Screenshot path for visual regression */
+  screenshotPath?: string;
+  /** Retry attempt number (0 = first attempt) */
+  retryAttempt?: number;
+}
+
+/**
+ * A test suite groups test results by component
+ */
+export interface TestSuite {
+  /** Component name */
+  name: string;
+  /** Test results in this suite */
+  tests: TestResult[];
+  /** Total duration for the suite */
+  duration: number;
+  /** Number of passed tests */
+  passed: number;
+  /** Number of failed tests */
+  failed: number;
+  /** Number of skipped tests */
+  skipped: number;
+}
+
+/**
+ * Overall result of a test run
+ */
+export interface TestRunResult {
+  /** Test suites organized by component */
+  suites: TestSuite[];
+  /** Total number of tests */
+  totalTests: number;
+  /** Number of passed tests */
+  totalPassed: number;
+  /** Number of failed tests */
+  totalFailed: number;
+  /** Number of skipped tests */
+  totalSkipped: number;
+  /** Total duration in milliseconds */
+  totalDuration: number;
+  /** Start timestamp */
+  startTime: Date;
+  /** End timestamp */
+  endTime: Date;
+  /** Total a11y violations across all tests */
+  totalA11yViolations?: number;
+}
+
+/**
+ * Options for test discovery
+ */
+export interface DiscoveryOptions {
+  /** Filter by component name */
+  component?: string;
+  /** Filter by tags (comma-separated) */
+  tags?: string[];
+  /** Grep pattern to match variant names */
+  grep?: string;
+  /** Exclude pattern */
+  exclude?: string;
+}
+
+/**
+ * Options for test execution
+ */
+export interface RunnerOptions {
+  /** Number of parallel browser contexts */
+  parallel: number;
+  /** Timeout per test in milliseconds */
+  timeout: number;
+  /** Number of retries for failed tests */
+  retries: number;
+  /** Stop on first failure */
+  bail: boolean;
+  /** Run accessibility checks */
+  a11y: boolean;
+  /** Capture screenshots for visual regression */
+  visual: boolean;
+  /** Update visual snapshots */
+  updateSnapshots: boolean;
+  /** Output directory for results */
+  outputDir: string;
+  /** Browser to use */
+  browser: 'chromium' | 'firefox' | 'webkit';
+  /** Headless mode */
+  headless: boolean;
+  /** Dev server URL (if already running) */
+  serverUrl?: string;
+  /** Port for dev server */
+  port: number;
+}
+
+/**
+ * Reporter interface for outputting test results
+ */
+export interface TestReporter {
+  /** Called when test run starts */
+  onRunStart?(testCount: number): void;
+  /** Called when a test starts */
+  onTestStart?(testCase: TestCase): void;
+  /** Called when a test completes */
+  onTestComplete?(result: TestResult): void;
+  /** Called when test run completes */
+  onRunComplete(result: TestRunResult): Promise<void> | void;
+}
+
+/**
+ * Configuration for the test command
+ */
+export interface TestConfig {
+  /** Discovery options */
+  discovery: DiscoveryOptions;
+  /** Runner options */
+  runner: RunnerOptions;
+  /** Reporter names */
+  reporters: string[];
+  /** Watch mode */
+  watch: boolean;
+  /** CI mode (non-interactive, exit codes) */
+  ci: boolean;
+}
+
+/**
+ * Event emitted during test execution
+ */
+export type TestEvent =
+  | { type: 'run-start'; testCount: number }
+  | { type: 'test-start'; testCase: TestCase }
+  | { type: 'test-complete'; result: TestResult }
+  | { type: 'run-complete'; result: TestRunResult };
+
+/**
+ * Browser pool context for parallel execution
+ */
+export interface BrowserContext {
+  /** Context ID */
+  id: number;
+  /** Whether context is currently in use */
+  busy: boolean;
+  /** Playwright browser context */
+  context: unknown; // Playwright BrowserContext
+  /** Page instance */
+  page: unknown; // Playwright Page
+}

package/src/test/watch.ts

@@ -0,0 +1,200 @@
+/**
+ * Watch mode - file watcher with selective re-run
+ */
+
+import { watch } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import pc from 'picocolors';
+import type { SegmentsConfig } from '../core/index.js';
+import { discoverSegmentFiles } from '../core/node.js';
+import type { TestCase, RunnerOptions, TestReporter } from './types.js';
+import { discoverTests } from './discovery.js';
+import { runTests } from './runner.js';
+
+export interface WatchOptions {
+  /** Debounce delay in milliseconds */
+  debounceMs?: number;
+  /** Clear console on each run */
+  clearConsole?: boolean;
+  /** Run all tests initially */
+  runOnStart?: boolean;
+}
+
+/**
+ * Start watch mode
+ */
+export async function startWatchMode(
+  config: SegmentsConfig,
+  configDir: string,
+  runnerOptions: RunnerOptions,
+  reporters: TestReporter[],
+  options: WatchOptions = {}
+): Promise<void> {
+  const { debounceMs = 300, clearConsole = true, runOnStart = true } = options;
+
+  let debounceTimer: NodeJS.Timeout | null = null;
+  let isRunning = false;
+  let pendingFiles = new Set<string>();
+
+  // Get files to watch
+  const segmentFiles = await discoverSegmentFiles(config, configDir);
+  const watchPaths = new Set<string>();
+
+  for (const file of segmentFiles) {
+    watchPaths.add(file.absolutePath);
+  }
+
+  // Also watch the directories containing segment files
+  const watchDirs = new Set<string>();
+  for (const path of watchPaths) {
+    const dir = resolve(path, '..');
+    watchDirs.add(dir);
+  }
+
+  console.log();
+  console.log(pc.cyan(pc.bold('Segments Test Runner - Watch Mode')));
+  console.log(pc.dim(`Watching ${watchPaths.size} files in ${watchDirs.size} directories`));
+  console.log(pc.dim('Press Ctrl+C to stop'));
+  console.log();
+
+  // Function to run tests
+  const runTestsForFiles = async (changedFiles: string[]): Promise<void> => {
+    if (isRunning) {
+      // Queue up changed files for next run
+      for (const file of changedFiles) {
+        pendingFiles.add(file);
+      }
+      return;
+    }
+
+    isRunning = true;
+
+    try {
+      if (clearConsole) {
+        console.clear();
+      }
+
+      console.log(pc.cyan('Changes detected, running tests...'));
+      console.log(pc.dim(`Changed: ${changedFiles.map((f) => relative(configDir, f)).join(', ')}`));
+      console.log();
+
+      // Discover tests (filter to changed files if possible)
+      const allTests = await discoverTests(config, configDir, {});
+
+      // Filter to tests from changed files
+      const changedRelativePaths = changedFiles.map((f) => relative(configDir, f));
+      const testsToRun = changedRelativePaths.length > 0
+        ? allTests.filter((t) => changedRelativePaths.some((p) => t.sourceFile.includes(p)))
+        : allTests;
+
+      if (testsToRun.length === 0) {
+        console.log(pc.yellow('No tests found in changed files'));
+        console.log();
+        return;
+      }
+
+      // Run the tests
+      await runTests(testsToRun, runnerOptions, reporters);
+    } catch (error) {
+      console.error(pc.red('Error running tests:'), error);
+    } finally {
+      isRunning = false;
+
+      // Check if there are pending files to run
+      if (pendingFiles.size > 0) {
+        const files = Array.from(pendingFiles);
+        pendingFiles.clear();
+        await runTestsForFiles(files);
+      }
+    }
+  };
+
+  // Run initial tests if configured
+  if (runOnStart) {
+    const allTests = await discoverTests(config, configDir, {});
+    if (allTests.length > 0) {
+      await runTests(allTests, runnerOptions, reporters);
+    } else {
+      console.log(pc.yellow('No tests with play functions found'));
+    }
+    console.log();
+    console.log(pc.dim('Watching for changes...'));
+    console.log();
+  }
+
+  // Set up file watchers
+  const watchers: ReturnType<typeof watch>[] = [];
+
+  for (const dir of watchDirs) {
+    try {
+      const watcher = watch(dir, { recursive: false }, (eventType, filename) => {
+        if (!filename) return;
+
+        const fullPath = resolve(dir, filename);
+
+        // Check if this is a segment file we care about
+        if (!watchPaths.has(fullPath)) return;
+
+        // Debounce the run
+        if (debounceTimer) {
+          clearTimeout(debounceTimer);
+        }
+
+        pendingFiles.add(fullPath);
+
+        debounceTimer = setTimeout(() => {
+          const files = Array.from(pendingFiles);
+          pendingFiles.clear();
+          runTestsForFiles(files);
+        }, debounceMs);
+      });
+
+      watchers.push(watcher);
+    } catch (error) {
+      console.warn(pc.yellow(`Warning: Could not watch directory ${dir}`), error);
+    }
+  }
+
+  // Handle process termination
+  const cleanup = () => {
+    console.log();
+    console.log(pc.dim('Stopping watch mode...'));
+
+    for (const watcher of watchers) {
+      watcher.close();
+    }
+
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+
+    process.exit(0);
+  };
+
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+
+  // Keep process alive
+  await new Promise(() => {
+    // This promise never resolves, keeping the process alive
+    // until terminated
+  });
+}
+
+/**
+ * Interactive watch mode with keyboard controls
+ */
+export async function startInteractiveWatchMode(
+  config: SegmentsConfig,
+  configDir: string,
+  runnerOptions: RunnerOptions,
+  reporters: TestReporter[]
+): Promise<void> {
+  let lastFailedTests: TestCase[] = [];
+
+  // Start basic watch mode
+  await startWatchMode(config, configDir, runnerOptions, reporters, {
+    runOnStart: true,
+    clearConsole: true,
+  });
+}

package/src/validators.ts

@@ -0,0 +1,152 @@
+import { segmentDefinitionSchema, BRAND, type SegmentsConfig } from './core/index.js';
+import {
+  discoverSegmentFiles,
+  discoverComponentFiles,
+  extractComponentName,
+  loadSegmentFile,
+  type DiscoveredFile,
+} from './core/node.js';
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationWarning[];
+}
+
+export interface ValidationError {
+  file: string;
+  message: string;
+  details?: string;
+}
+
+export interface ValidationWarning {
+  file: string;
+  message: string;
+}
+
+/**
+ * Validate segment file schema
+ */
+export async function validateSchema(
+  config: SegmentsConfig,
+  configDir: string
+): Promise<ValidationResult> {
+  const files = await discoverSegmentFiles(config, configDir);
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  for (const file of files) {
+    try {
+      const segment = await loadSegmentFile(file.absolutePath);
+
+      if (!segment) {
+        errors.push({
+          file: file.relativePath,
+          message: 'No default export found',
+          details: `Segment files must have a default export from defineSegment()`,
+        });
+        continue;
+      }
+
+      const result = segmentDefinitionSchema.safeParse(segment);
+
+      if (!result.success) {
+        const details = result.error.errors
+          .map((e) => `${e.path.join('.')}: ${e.message}`)
+          .join('; ');
+
+        errors.push({
+          file: file.relativePath,
+          message: 'Invalid segment schema',
+          details,
+        });
+      }
+    } catch (error) {
+      errors.push({
+        file: file.relativePath,
+        message: 'Failed to load segment file',
+        details: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Validate coverage - ensure all components have segments
+ */
+export async function validateCoverage(
+  config: SegmentsConfig,
+  configDir: string
+): Promise<ValidationResult> {
+  const segmentFiles = await discoverSegmentFiles(config, configDir);
+  const componentFiles = await discoverComponentFiles(config, configDir);
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  // Build set of documented component names
+  const documentedComponents = new Set<string>();
+
+  for (const file of segmentFiles) {
+    try {
+      const segment = await loadSegmentFile(file.absolutePath);
+
+      if (segment?.meta?.name) {
+        documentedComponents.add(segment.meta.name);
+      }
+    } catch {
+      // Skip files that fail to load - schema validation will catch these
+    }
+  }
+
+  // Check each component file
+  for (const file of componentFiles) {
+    const componentName = extractComponentName(file.relativePath);
+
+    // Check if there's a corresponding segment file
+    const segmentPath = file.relativePath.replace(
+      /\.(tsx?|jsx?)$/,
+      BRAND.fileExtension
+    );
+    const hasSegmentFile = segmentFiles.some(
+      (s) => s.relativePath === segmentPath
+    );
+
+    if (!hasSegmentFile && !documentedComponents.has(componentName)) {
+      warnings.push({
+        file: file.relativePath,
+        message: `Component "${componentName}" has no segment documentation`,
+      });
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Run all validations
+ */
+export async function validateAll(
+  config: SegmentsConfig,
+  configDir: string
+): Promise<ValidationResult> {
+  const [schemaResult, coverageResult] = await Promise.all([
+    validateSchema(config, configDir),
+    validateCoverage(config, configDir),
+  ]);
+
+  return {
+    valid: schemaResult.valid && coverageResult.valid,
+    errors: [...schemaResult.errors, ...coverageResult.errors],
+    warnings: [...schemaResult.warnings, ...coverageResult.warnings],
+  };
+}