@fragments-sdk/cli 0.7.0 → 0.7.2

package/src/test/index.ts

@@ -5,7 +5,7 @@
 import { resolve, join } from 'node:path';
 import { mkdir } from 'node:fs/promises';
 import pc from 'picocolors';
-import type { SegmentsConfig } from '../core/index.js';
+import type { FragmentsConfig } from '../core/index.js';
 import type {
   TestConfig,
   DiscoveryOptions,
@@ -77,7 +77,7 @@ const DEFAULT_OPTIONS = {
  * Run the test command
  */
 export async function runTestCommand(
-  config: SegmentsConfig,
+  config: FragmentsConfig,
   configDir: string,
   options: TestCommandOptions
 ): Promise<number> {
@@ -138,7 +138,7 @@ export async function runTestCommand(
     }
 
     console.log();
-    console.log(pc.dim('Add play functions to your segment variants to enable testing.'));
+    console.log(pc.dim('Add play functions to your fragment variants to enable testing.'));
     console.log();
 
     return opts.ci ? 0 : 0; // Not a failure if no tests
@@ -201,7 +201,7 @@ function createReporters(
         reporters.push(
           createJUnitReporter({
             outputPath: join(outputDir, 'junit.xml'),
-            suiteName: 'Segments Tests',
+            suiteName: 'Fragments Tests',
           })
         );
         break;
@@ -234,7 +234,7 @@ function createReporters(
  * List available tests without running them
  */
 export async function listTests(
-  config: SegmentsConfig,
+  config: FragmentsConfig,
   configDir: string,
   options: Pick<TestCommandOptions, 'component' | 'tags' | 'grep' | 'exclude'>
 ): Promise<void> {

package/src/test/reporters/console.ts

@@ -29,7 +29,7 @@ export function createConsoleReporter(options: ConsoleReporterOptions = {}): Tes
       startTime = Date.now();
 
       console.log();
-      console.log(pc.cyan(pc.bold('Segments Test Runner')));
+      console.log(pc.cyan(pc.bold('Fragments Test Runner')));
       console.log(pc.dim(`Running ${count} test${count === 1 ? '' : 's'}...`));
       console.log();
     },

package/src/test/reporters/junit.ts

@@ -26,7 +26,7 @@ export interface JUnitReporterOptions {
  * Create a JUnit XML reporter
  */
 export function createJUnitReporter(options: JUnitReporterOptions): TestReporter {
-  const { outputPath, suiteName = 'Segments Tests', includeProperties = true } = options;
+  const { outputPath, suiteName = 'Fragments Tests', includeProperties = true } = options;
 
   return {
     async onRunComplete(result: TestRunResult) {

package/src/test/runner.ts

@@ -383,18 +383,18 @@ async function executePlayFunction(
 ): Promise<{ steps: StepResult[]; error?: TestError }> {
   const result = await page.evaluate(
     async ({ component, variant, timeout }: { component: string; variant: string; timeout: number }) => {
-      // Find the segment definition in the global registry
-      const registry = (window as unknown as { __SEGMENTS_REGISTRY__?: Map<string, unknown> })
-        .__SEGMENTS_REGISTRY__;
+      // Find the fragment definition in the global registry
+      const registry = (window as unknown as { __FRAGMENTS_REGISTRY__?: Map<string, unknown> })
+        .__FRAGMENTS_REGISTRY__;
 
       if (!registry) {
         return {
           steps: [],
-          error: { message: 'Segments registry not found. Make sure the viewer is loaded.' },
+          error: { message: 'Fragments registry not found. Make sure the viewer is loaded.' },
         };
       }
 
-      const segment = registry.get(component) as {
+      const fragment = registry.get(component) as {
         variants?: Array<{
           name: string;
           play?: (ctx: {
@@ -405,14 +405,14 @@ async function executePlayFunction(
         }>;
       } | undefined;
 
-      if (!segment) {
+      if (!fragment) {
         return {
           steps: [],
           error: { message: `Component "${component}" not found in registry` },
         };
       }
 
-      const variantDef = segment.variants?.find((v) => v.name === variant);
+      const variantDef = fragment.variants?.find((v) => v.name === variant);
       if (!variantDef || !variantDef.play) {
         return {
           steps: [],

package/src/test/types.ts

@@ -1,11 +1,11 @@
 /**
- * Types for the segments test CLI command
+ * Types for the fragments test CLI command
  */
 
-import type { PlayFunction, SegmentVariant } from '../core/index.js';
+import type { PlayFunction, FragmentVariant } from '../core/index.js';
 
 /**
- * A test case discovered from segment files
+ * A test case discovered from fragment files
  */
 export interface TestCase {
   /** Unique identifier for this test */

package/src/test/watch.ts

@@ -5,8 +5,8 @@
 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 { FragmentsConfig } from '../core/index.js';
+import { discoverFragmentFiles } from '../core/node.js';
 import type { TestCase, RunnerOptions, TestReporter } from './types.js';
 import { discoverTests } from './discovery.js';
 import { runTests } from './runner.js';
@@ -24,7 +24,7 @@ export interface WatchOptions {
  * Start watch mode
  */
 export async function startWatchMode(
-  config: SegmentsConfig,
+  config: FragmentsConfig,
   configDir: string,
   runnerOptions: RunnerOptions,
   reporters: TestReporter[],
@@ -37,14 +37,14 @@ export async function startWatchMode(
   const pendingFiles = new Set<string>();
 
   // Get files to watch
-  const segmentFiles = await discoverSegmentFiles(config, configDir);
+  const fragmentFiles = await discoverFragmentFiles(config, configDir);
   const watchPaths = new Set<string>();
 
-  for (const file of segmentFiles) {
+  for (const file of fragmentFiles) {
     watchPaths.add(file.absolutePath);
   }
 
-  // Also watch the directories containing segment files
+  // Also watch the directories containing fragment files
   const watchDirs = new Set<string>();
   for (const path of watchPaths) {
     const dir = resolve(path, '..');
@@ -52,7 +52,7 @@ export async function startWatchMode(
   }
 
   console.log();
-  console.log(pc.cyan(pc.bold('Segments Test Runner - Watch Mode')));
+  console.log(pc.cyan(pc.bold('Fragments 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();
@@ -132,7 +132,7 @@ export async function startWatchMode(
 
         const fullPath = resolve(dir, filename);
 
-        // Check if this is a segment file we care about
+        // Check if this is a fragment file we care about
         if (!watchPaths.has(fullPath)) return;
 
         // Debounce the run
@@ -185,7 +185,7 @@ export async function startWatchMode(
  * Interactive watch mode with keyboard controls
  */
 export async function startInteractiveWatchMode(
-  config: SegmentsConfig,
+  config: FragmentsConfig,
   configDir: string,
   runnerOptions: RunnerOptions,
   reporters: TestReporter[]

package/src/validators.ts

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

package/src/viewer/__tests__/render-utils.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect } from "vitest";
 import {
   serializeValue,
   serializePropsToJsx,
-  findSegmentByName,
+  findFragmentByName,
   getAvailableComponents,
   generateRenderScript,
 } from "../render-utils.js";
@@ -112,66 +112,66 @@ describe("serializePropsToJsx", () => {
   });
 });
 
-describe("findSegmentByName", () => {
-  const mockSegments = [
-    { path: "Button.segment.tsx", segment: { meta: { name: "Button" } } },
-    { path: "Card.segment.tsx", segment: { meta: { name: "Card" } } },
-    { path: "Alert.segment.tsx", segment: { meta: { name: "Alert" } } },
+describe("findFragmentByName", () => {
+  const mockFragments = [
+    { path: "Button.fragment.tsx", fragment: { meta: { name: "Button" } } },
+    { path: "Card.fragment.tsx", fragment: { meta: { name: "Card" } } },
+    { path: "Alert.fragment.tsx", fragment: { meta: { name: "Alert" } } },
   ];
 
-  it("finds segment by exact name", () => {
-    const result = findSegmentByName("Button", mockSegments);
-    expect(result).toEqual({ name: "Button", path: "Button.segment.tsx" });
+  it("finds fragment by exact name", () => {
+    const result = findFragmentByName("Button", mockFragments);
+    expect(result).toEqual({ name: "Button", path: "Button.fragment.tsx" });
   });
 
-  it("finds segment case-insensitively", () => {
-    expect(findSegmentByName("button", mockSegments)).toEqual({
+  it("finds fragment case-insensitively", () => {
+    expect(findFragmentByName("button", mockFragments)).toEqual({
       name: "Button",
-      path: "Button.segment.tsx",
+      path: "Button.fragment.tsx",
     });
-    expect(findSegmentByName("BUTTON", mockSegments)).toEqual({
+    expect(findFragmentByName("BUTTON", mockFragments)).toEqual({
       name: "Button",
-      path: "Button.segment.tsx",
+      path: "Button.fragment.tsx",
     });
-    expect(findSegmentByName("BuTtOn", mockSegments)).toEqual({
+    expect(findFragmentByName("BuTtOn", mockFragments)).toEqual({
       name: "Button",
-      path: "Button.segment.tsx",
+      path: "Button.fragment.tsx",
     });
   });
 
   it("returns null for non-existent component", () => {
-    expect(findSegmentByName("NonExistent", mockSegments)).toBeNull();
-    expect(findSegmentByName("", mockSegments)).toBeNull();
+    expect(findFragmentByName("NonExistent", mockFragments)).toBeNull();
+    expect(findFragmentByName("", mockFragments)).toBeNull();
   });
 
-  it("handles empty segments array", () => {
-    expect(findSegmentByName("Button", [])).toBeNull();
+  it("handles empty fragments array", () => {
+    expect(findFragmentByName("Button", [])).toBeNull();
   });
 });
 
 describe("getAvailableComponents", () => {
   it("returns sorted list of component names", () => {
-    const segments = [
-      { segment: { meta: { name: "Zebra" } } },
-      { segment: { meta: { name: "Alert" } } },
-      { segment: { meta: { name: "Button" } } },
+    const fragments = [
+      { fragment: { meta: { name: "Zebra" } } },
+      { fragment: { meta: { name: "Alert" } } },
+      { fragment: { meta: { name: "Button" } } },
     ];
-    expect(getAvailableComponents(segments)).toEqual([
+    expect(getAvailableComponents(fragments)).toEqual([
       "Alert",
       "Button",
       "Zebra",
     ]);
   });
 
-  it("returns empty array for empty segments", () => {
+  it("returns empty array for empty fragments", () => {
     expect(getAvailableComponents([])).toEqual([]);
   });
 });
 
 describe("generateRenderScript", () => {
   it("generates script with correct import path", () => {
-    const script = generateRenderScript("/path/to/Button.segment.tsx", "Button", {});
-    expect(script).toContain('import("/path/to/Button.segment.tsx")');
+    const script = generateRenderScript("/path/to/Button.fragment.tsx", "Button", {});
+    expect(script).toContain('import("/path/to/Button.fragment.tsx")');
   });
 
   it("generates script with empty props object when no props", () => {

package/src/viewer/__tests__/viewer-integration.test.ts

@@ -68,11 +68,11 @@ describe("@fragments/core alias resolution", () => {
     expect(existsSync(corePath)).toBe(true);
   });
 
-  it("core/index.ts exports storyModuleToSegment", async () => {
+  it("core/index.ts exports storyModuleToFragment", async () => {
     const corePath = resolve(cliPackageRoot, "src/core/index.ts");
     const content = await readFile(corePath, "utf-8");
-    // The virtual module imports { storyModuleToSegment, setPreviewConfig }
-    expect(content).toContain("storyModuleToSegment");
+    // The virtual module imports { storyModuleToFragment, setPreviewConfig }
+    expect(content).toContain("storyModuleToFragment");
   });
 
   it("core/index.ts exports setPreviewConfig", async () => {
@@ -91,7 +91,7 @@ describe("virtual module @fragments/core import", () => {
 
     // The generated virtual module string should reference @fragments/core
     expect(content).toContain(
-      'import { storyModuleToSegment, setPreviewConfig } from "@fragments/core"'
+      'import { storyModuleToFragment, setPreviewConfig } from "@fragments/core"'
     );
   });
 

package/src/viewer/cli/health.ts

@@ -42,9 +42,9 @@ function parseOptions(args: string[]): HealthCommandOptions {
 }
 
 /**
- * Load segments from the project
+ * Load fragments from the project
  */
-async function loadSegments(): Promise<Array<{ path: string; segment: any }>> {
+async function loadFragments(): Promise<Array<{ path: string; fragment: any }>> {
   const configResult = await loadConfig();
 
   if (!configResult) {
@@ -53,28 +53,28 @@ async function loadSegments(): Promise<Array<{ path: string; segment: any }>> {
 
   const { config } = configResult;
 
-  // Try to load compiled segments
-  const segmentsPath = path.resolve(process.cwd(), config.outFile || `${BRAND.dataDir}/${BRAND.outFile}`);
-
-  if (fs.existsSync(segmentsPath)) {
-    const data = JSON.parse(fs.readFileSync(segmentsPath, 'utf-8'));
-    return Object.entries(data.segments || {}).map(([name, segment]: [string, any]) => ({
-      path: segment.filePath || name,
-      segment: {
-        meta: segment.meta || { name, description: '', category: '' },
-        usage: segment.usage || { when: [], whenNot: [] },
-        props: segment.props || {},
-        variants: segment.variants || [],
-        relations: segment.relations,
-        contract: segment.contract,
-        _generated: segment._generated,
+  // Try to load compiled fragments
+  const fragmentsPath = path.resolve(process.cwd(), config.outFile || `${BRAND.dataDir}/${BRAND.outFile}`);
+
+  if (fs.existsSync(fragmentsPath)) {
+    const data = JSON.parse(fs.readFileSync(fragmentsPath, 'utf-8'));
+    return Object.entries(data.fragments || {}).map(([name, fragment]: [string, any]) => ({
+      path: fragment.filePath || name,
+      fragment: {
+        meta: fragment.meta || { name, description: '', category: '' },
+        usage: fragment.usage || { when: [], whenNot: [] },
+        props: fragment.props || {},
+        variants: fragment.variants || [],
+        relations: fragment.relations,
+        contract: fragment.contract,
+        _generated: fragment._generated,
         component: () => null, // Placeholder
       },
     }));
   }
 
-  // Fallback: return empty if no compiled segments
-  console.log(pc.yellow(`No compiled segments found. Run \`${BRAND.cliCommand} build\` first for complete analysis.`));
+  // Fallback: return empty if no compiled fragments
+  console.log(pc.yellow(`No compiled fragments found. Run \`${BRAND.cliCommand} build\` first for complete analysis.`));
   return [];
 }
 
@@ -200,13 +200,13 @@ export async function healthCommand(args: string[]): Promise<void> {
   spinner.start();
 
   try {
-    // Load segments
-    spinner.update('Loading segments...');
-    const segments = await loadSegments();
+    // Load fragments
+    spinner.update('Loading fragments...');
+    const fragments = await loadFragments();
 
-    if (segments.length === 0) {
-      spinner.stop(false, 'No segments found');
-      console.log(pc.yellow(`\nNo components to analyze. Create segment files or run \`${BRAND.cliCommand} build\`.\n`));
+    if (fragments.length === 0) {
+      spinner.stop(false, 'No fragments found');
+      console.log(pc.yellow(`\nNo components to analyze. Create fragment files or run \`${BRAND.cliCommand} build\`.\n`));
       return;
     }
 
@@ -220,7 +220,7 @@ export async function healthCommand(args: string[]): Promise<void> {
     // Generate report
     spinner.update('Generating health report...');
     const report = generateHealthReport({
-      segments,
+      fragments,
       usageScan,
       // Note: Drift reports would require running the viewer and extracting styles
       // For CLI, we focus on what can be statically analyzed