@fragments-sdk/cli 0.7.0 → 0.7.2

package/src/commands/scan.ts

@@ -1,5 +1,5 @@
 /**
- * fragments scan - Zero-config segments.json generation from source code
+ * fragments scan - Zero-config fragments.json generation from source code
  *
  * Automatically extracts component documentation by:
  * 1. Discovering components from source files and barrel exports
@@ -7,7 +7,7 @@
  * 3. Scanning codebase for usage patterns
  * 4. Parsing Storybook stories for examples
  * 5. Inferring component relationships from usage data
- * 6. Generating complete segments.json without manual documentation
+ * 6. Generating complete fragments.json without manual documentation
  */
 
 import { writeFile, mkdir } from "node:fs/promises";
@@ -15,8 +15,8 @@ import { resolve, join, dirname, relative } from "node:path";
 import pc from "picocolors";
 import {
   BRAND,
-  type CompiledSegmentsFile,
-  type CompiledSegment,
+  type CompiledFragmentsFile,
+  type CompiledFragment,
   type PropDefinition,
 } from "../core/index.js";
 import {
@@ -32,7 +32,7 @@ import {
   generateComponentContext,
   generateEnhancementSuggestions,
   filterBoilerplate,
-  convertToSegmentProps,
+  convertToFragmentProps,
   type UsageAnalysis,
   type ComponentRelation,
   type PropsExtractionResult,
@@ -42,7 +42,7 @@ import {
 export interface ScanOptions {
   /** Path to config file */
   config?: string;
-  /** Output file path (default: segments.json) */
+  /** Output file path (default: fragments.json) */
   output?: string;
   /** Component patterns to scan */
   componentPatterns?: string[];
@@ -71,7 +71,7 @@ export interface ScanResult {
 }
 
 /**
- * Scan codebase and generate segments.json directly from source
+ * Scan codebase and generate fragments.json directly from source
  */
 export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
   const startTime = Date.now();
@@ -86,17 +86,17 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
   try {
     const loaded = await loadConfig(options.config);
     configDir = loaded.configDir;
-    outputFile = options.output || loaded.config.outFile || "segments.json";
+    outputFile = options.output || loaded.config.outFile || "fragments.json";
     componentPatterns = options.componentPatterns || loaded.config.components;
   } catch {
     // No config file, use defaults
     configDir = process.cwd();
-    outputFile = options.output || "segments.json";
+    outputFile = options.output || "fragments.json";
     componentPatterns = options.componentPatterns;
   }
 
   console.log(pc.cyan(`\n${BRAND.name} Scan\n`));
-  console.log(pc.dim("Zero-config segments.json generation from source code\n"));
+  console.log(pc.dim("Zero-config fragments.json generation from source code\n"));
 
   // Phase 1: Discover components
   console.log(pc.dim("Phase 1: Discovering components..."));
@@ -133,7 +133,7 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
 
   // Phase 2: Extract props from TypeScript
   console.log(pc.dim("\nPhase 2: Extracting props from TypeScript..."));
-  const propsMap = new Map<string, ReturnType<typeof convertToSegmentProps>>();
+  const propsMap = new Map<string, ReturnType<typeof convertToFragmentProps>>();
   const propsResults = new Map<string, PropsExtractionResult>();
   let propsExtracted = 0;
 
@@ -146,7 +146,7 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
       propsResults.set(comp.name, extraction);
 
       if (extraction.success && extraction.props.length > 0) {
-        propsMap.set(comp.name, convertToSegmentProps(extraction.props));
+        propsMap.set(comp.name, convertToFragmentProps(extraction.props));
         propsExtracted++;
       }
     } catch (e) {
@@ -238,13 +238,13 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
     console.log(pc.dim("\nPhase 4: Skipping Storybook parsing"));
   }
 
-  // Phase 5: Generate segments
-  console.log(pc.dim("\nPhase 5: Generating segments..."));
-  const segments: Record<string, CompiledSegment> = {};
+  // Phase 5: Generate fragments
+  console.log(pc.dim("\nPhase 5: Generating fragments..."));
+  const fragments: Record<string, CompiledFragment> = {};
 
   for (const comp of components) {
     try {
-      const segment = generateSegmentFromData(
+      const fragment = generateFragmentFromData(
         comp,
         configDir,
         propsMap.get(comp.name),
@@ -253,7 +253,7 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
         storiesMap.get(comp.name)
       );
 
-      segments[comp.name] = segment;
+      fragments[comp.name] = fragment;
     } catch (e) {
       errors.push({
         component: comp.name,
@@ -266,10 +266,10 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
   const outputPath = resolve(configDir, outputFile);
   await mkdir(dirname(outputPath), { recursive: true });
 
-  const output: CompiledSegmentsFile = {
+  const output: CompiledFragmentsFile = {
     version: "1.0.0",
     generatedAt: new Date().toISOString(),
-    segments,
+    fragments,
   };
 
   await writeFile(outputPath, JSON.stringify(output, null, 2));
@@ -278,9 +278,9 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
 
   // Summary
   console.log(pc.dim("\n────────────────────────────────────────"));
-  console.log(pc.green(`\n✓ Generated segments.json in ${elapsed}s`));
+  console.log(pc.green(`\n✓ Generated fragments.json in ${elapsed}s`));
   console.log(pc.dim(`  Output: ${relative(process.cwd(), outputPath)}`));
-  console.log(pc.dim(`  Components: ${Object.keys(segments).length}`));
+  console.log(pc.dim(`  Components: ${Object.keys(fragments).length}`));
   console.log(pc.dim(`  Props extracted: ${propsExtracted}`));
   console.log(pc.dim(`  Usages found: ${usagesFound}`));
   console.log(pc.dim(`  Relations inferred: ${allRelations.size}`));
@@ -307,7 +307,7 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
   return {
     success: errors.length === 0,
     outputPath,
-    componentCount: Object.keys(segments).length,
+    componentCount: Object.keys(fragments).length,
     propsExtracted,
     usagesFound,
     relationsInferred: allRelations.size,
@@ -318,16 +318,16 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
 }
 
 /**
- * Generate a CompiledSegment from extracted data
+ * Generate a CompiledFragment from extracted data
  */
-function generateSegmentFromData(
+function generateFragmentFromData(
   comp: DiscoveredComponent,
   configDir: string,
   props: Record<string, PropDefinition> | undefined,
   usageAnalysis: UsageAnalysis["components"][string] | undefined,
   relations: ComponentRelation[] | undefined,
   storyFile: ParsedStoryFile | undefined
-): CompiledSegment {
+): CompiledFragment {
   // Generate context for AI suggestions
   const context = generateComponentContext(
     comp.name,
@@ -352,7 +352,7 @@ function generateSegmentFromData(
   const status = inferStatus(comp.relativePath);
 
   // Build variants from stories
-  const variants: CompiledSegment["variants"] = [];
+  const variants: CompiledFragment["variants"] = [];
   if (storyFile?.stories) {
     for (const story of storyFile.stories) {
       variants.push({
@@ -364,7 +364,7 @@ function generateSegmentFromData(
   }
 
   // Build relations
-  const compiledRelations: CompiledSegment["relations"] = [];
+  const compiledRelations: CompiledFragment["relations"] = [];
   if (relations && relations.length > 0) {
     for (const rel of relations.slice(0, 10)) {
       compiledRelations.push({

package/src/commands/storygen.ts

@@ -1,13 +1,13 @@
 /**
- * fragments storygen - Generate Storybook stories from segment definitions
+ * fragments storygen - Generate Storybook stories from fragment definitions
  */
 
 import { writeFile, mkdir } from 'node:fs/promises';
 import { resolve, join, relative } from 'node:path';
 import pc from 'picocolors';
 import { BRAND } from '../core/index.js';
-import type { SegmentDefinition } from '../core/index.js';
-import { loadConfig, discoverSegmentFiles, loadSegmentFile } from '../core/node.js';
+import type { FragmentDefinition } from '../core/index.js';
+import { loadConfig, discoverFragmentFiles, loadFragmentFile } from '../core/node.js';
 
 /**
  * Options for storygen command
@@ -17,7 +17,7 @@ export interface StorygenOptions {
   config?: string;
   /** Output directory */
   output?: string;
-  /** Watch for segment changes and regenerate */
+  /** Watch for fragment changes and regenerate */
   watch?: boolean;
   /** Story format (csf3) */
   format?: string;
@@ -42,11 +42,11 @@ export async function storygen(options: StorygenOptions = {}): Promise<StorygenR
 
   console.log(pc.cyan(`\n${BRAND.name} Story Generator\n`));
 
-  // Discover segment files
-  const segmentFiles = await discoverSegmentFiles(config, configDir);
+  // Discover fragment files
+  const fragmentFiles = await discoverFragmentFiles(config, configDir);
 
-  if (segmentFiles.length === 0) {
-    console.log(pc.yellow('No segment files found.\n'));
+  if (fragmentFiles.length === 0) {
+    console.log(pc.yellow('No fragment files found.\n'));
     return { success: true, generated: 0, outputDir: output };
   }
 
@@ -55,14 +55,14 @@ export async function storygen(options: StorygenOptions = {}): Promise<StorygenR
 
   let generated = 0;
 
-  // Generate function for a single segment
+  // Generate function for a single fragment
   const generateStory = async (file: { absolutePath: string; relativePath: string }) => {
     try {
-      const segment = await loadSegmentFile(file.absolutePath);
-      if (!segment) return false;
+      const fragment = await loadFragmentFile(file.absolutePath);
+      if (!fragment) return false;
 
-      const storyContent = generateCSF3Story(segment, file.relativePath);
-      const storyName = `${segment.meta.name}.stories.tsx`;
+      const storyContent = generateCSF3Story(fragment, file.relativePath);
+      const storyName = `${fragment.meta.name}.stories.tsx`;
       const storyPath = join(outputDir, storyName);
 
       await writeFile(storyPath, storyContent);
@@ -77,7 +77,7 @@ export async function storygen(options: StorygenOptions = {}): Promise<StorygenR
   // Initial generation
   console.log(pc.dim(`Generating stories to ${relative(process.cwd(), outputDir)}/\n`));
 
-  for (const file of segmentFiles) {
+  for (const file of fragmentFiles) {
     if (await generateStory(file)) {
       generated++;
     }
@@ -88,10 +88,10 @@ export async function storygen(options: StorygenOptions = {}): Promise<StorygenR
 
   // Watch mode
   if (watch) {
-    console.log(pc.dim('Watching for segment changes... (Ctrl+C to stop)\n'));
+    console.log(pc.dim('Watching for fragment changes... (Ctrl+C to stop)\n'));
 
     const chokidar = await import('chokidar');
-    const patterns = segmentFiles.map(f => f.absolutePath);
+    const patterns = fragmentFiles.map(f => f.absolutePath);
 
     const watcher = chokidar.watch(patterns, {
       ignoreInitial: true,
@@ -99,7 +99,7 @@ export async function storygen(options: StorygenOptions = {}): Promise<StorygenR
     });
 
     watcher.on('change', async (changedPath: string) => {
-      const file = segmentFiles.find(f => f.absolutePath === changedPath);
+      const file = fragmentFiles.find(f => f.absolutePath === changedPath);
       if (file) {
         console.log(pc.dim(`\nChanged: ${relative(process.cwd(), changedPath)}`));
         await generateStory(file);
@@ -109,10 +109,10 @@ export async function storygen(options: StorygenOptions = {}): Promise<StorygenR
     watcher.on('add', async (addedPath: string) => {
       console.log(pc.dim(`\nAdded: ${relative(process.cwd(), addedPath)}`));
       // Re-discover to get the new file's relative path
-      const newFiles = await discoverSegmentFiles(config, configDir);
+      const newFiles = await discoverFragmentFiles(config, configDir);
       const file = newFiles.find(f => f.absolutePath === addedPath);
       if (file) {
-        segmentFiles.push(file);
+        fragmentFiles.push(file);
         await generateStory(file);
       }
     });
@@ -125,10 +125,10 @@ export async function storygen(options: StorygenOptions = {}): Promise<StorygenR
 }
 
 /**
- * Generate a CSF3 story file from a segment definition
+ * Generate a CSF3 story file from a fragment definition
  */
-function generateCSF3Story(segment: SegmentDefinition, relativePath: string): string {
-  const { meta, variants, props, usage } = segment;
+function generateCSF3Story(fragment: FragmentDefinition, relativePath: string): string {
+  const { meta, variants, props, usage } = fragment;
   const componentName = meta.name;
 
   // Build argTypes from props
@@ -178,11 +178,11 @@ ${usage.whenNot?.map(w => `- ${w}`).join('\n') || ''}`
   return `/**
  * Auto-generated Storybook stories from ${relativePath}
  *
- * DO NOT EDIT - regenerate with: segments storygen
+ * DO NOT EDIT - regenerate with: fragments storygen
  */
 
 import type { Meta, StoryObj } from '@storybook/react';
-import { ${componentName} } from '${relativePath.replace(/\.segment\.tsx$/, '/index.js')}';
+import { ${componentName} } from '${relativePath.replace(/\.fragment\.tsx$/, '/index.js')}';
 
 const meta: Meta<typeof ${componentName}> = {
   title: '${meta.category ? `${meta.category.charAt(0).toUpperCase() + meta.category.slice(1)}/` : ''}${componentName}',

package/src/commands/validate.ts

@@ -1,5 +1,5 @@
 /**
- * fragments validate - Validate segment files
+ * fragments validate - Validate fragment files
  */
 
 import pc from 'picocolors';
@@ -13,7 +13,7 @@ import { validateSchema, validateCoverage, validateAll } from '../validators.js'
 export interface ValidateOptions {
   /** Path to config file */
   config?: string;
-  /** Validate segment schema only */
+  /** Validate fragment schema only */
   schema?: boolean;
   /** Validate coverage only */
   coverage?: boolean;

package/src/commands/verify.ts

@@ -1,7 +1,7 @@
 /**
  * fragments verify - Verify component compliance for CI pipelines
  *
- * Uses the /segments/compliance endpoint to get real token compliance data
+ * Uses the /fragments/compliance endpoint to get real token compliance data
  * based on computed styles compared against the design token registry.
  */
 
@@ -13,7 +13,7 @@ import {
   DevServerConnectionError,
   type ComplianceResult,
   type ViolationItem,
-  type SegmentInfo,
+  type FragmentInfo,
 } from '../shared/index.js';
 
 /**
@@ -95,16 +95,16 @@ export async function verify(
     );
   }
 
-  // Fetch all segments
-  let segments = await client.getSegments();
+  // Fetch all fragments
+  let fragments = await client.getFragments();
 
   // Filter by component if specified
   if (component) {
-    segments = segments.filter(
+    fragments = fragments.filter(
       s => s.name.toLowerCase() === component.toLowerCase()
     );
 
-    if (segments.length === 0) {
+    if (fragments.length === 0) {
       const error = { error: `Component "${component}" not found` };
       if (ci) {
         console.log(JSON.stringify(error));
@@ -115,8 +115,8 @@ export async function verify(
     }
   }
 
-  // Check compliance for each segment
-  for (const seg of segments) {
+  // Check compliance for each fragment
+  for (const seg of fragments) {
     try {
       // Get real compliance from the server
       const complianceResult = await client.getCompliance({

package/src/core/auto-props.ts

@@ -64,18 +64,18 @@ function resolveModulePath(basePath: string): string | null {
 }
 
 /**
- * Resolve a component source file from the segment file path + component import path.
+ * Resolve a component source file from the fragment file path + component import path.
  * Supports relative imports like ".", "./Button", "../components/Button".
  */
 export function resolveComponentSourcePath(
-  segmentFileAbsolutePath: string,
+  fragmentFileAbsolutePath: string,
   componentImportPath: string | null
 ): string | null {
   if (!componentImportPath) return null;
   if (!componentImportPath.startsWith(".")) return null;
 
-  const segmentDir = dirname(segmentFileAbsolutePath);
-  const basePath = resolve(segmentDir, componentImportPath);
+  const fragmentDir = dirname(fragmentFileAbsolutePath);
+  const basePath = resolve(fragmentDir, componentImportPath);
   return resolveModulePath(basePath);
 }