@fragments-sdk/cli 0.7.0 → 0.7.2

package/src/core/index.ts

@@ -9,9 +9,9 @@ export type { Brand, Defaults } from "./constants.js";
 
 // Types
 export type {
-  SegmentComponent,
-  SegmentMeta,
-  SegmentUsage,
+  FragmentComponent,
+  FragmentMeta,
+  FragmentUsage,
   PropType,
   PropDefinition,
   ControlType,
@@ -20,20 +20,19 @@ export type {
   VariantLoader,
   PlayFunction,
   PlayFunctionContext,
-  SegmentVariant,
-  SegmentDefinition,
+  FragmentVariant,
+  FragmentDefinition,
   FragmentsConfig,
-  SegmentsConfig, // @deprecated - use FragmentsConfig
   RegistryOptions,
-  CompiledSegment,
-  CompiledSegmentsFile,
+  CompiledFragment,
+  CompiledFragmentsFile,
   BlockDefinition,
   CompiledBlock,
   RecipeDefinition, // @deprecated - use BlockDefinition
   CompiledRecipe, // @deprecated - use CompiledBlock
   // Contract and provenance types
-  SegmentContract,
-  SegmentGenerated,
+  FragmentContract,
+  FragmentGenerated,
   // AI metadata type
   AIMetadata,
   // Screenshot types
@@ -81,18 +80,18 @@ export type {
 
 // Schema validation (Zod is browser-safe)
 export {
-  segmentMetaSchema,
-  segmentUsageSchema,
+  fragmentMetaSchema,
+  fragmentUsageSchema,
   propDefinitionSchema,
   componentRelationSchema,
-  segmentVariantSchema,
-  segmentDefinitionSchema,
-  segmentsConfigSchema,
+  fragmentVariantSchema,
+  fragmentDefinitionSchema,
+  fragmentsConfigSchema,
   figmaPropMappingSchema,
   // Contract and provenance schemas
-  segmentContractSchema,
-  segmentGeneratedSchema,
-  segmentBanSchema,
+  fragmentContractSchema,
+  fragmentGeneratedSchema,
+  fragmentBanSchema,
   blockDefinitionSchema,
   recipeDefinitionSchema, // @deprecated - use blockDefinitionSchema
   // AI metadata schema
@@ -100,12 +99,12 @@ export {
 } from "./schema.js";
 
 // Main API
-export { defineSegment, defineFragment, compileSegment, defineBlock, compileBlock, defineRecipe, compileRecipe } from "./defineSegment.js";
-export type { InferProps } from "./defineSegment.js";
+export { defineFragment, compileFragment, defineBlock, compileBlock, defineRecipe, compileRecipe } from "./defineFragment.js";
+export type { InferProps } from "./defineFragment.js";
 
 // Story adapter (runtime conversion of Storybook modules)
 export {
-  storyModuleToSegment,
+  storyModuleToFragment,
   setPreviewConfig,
   getPreviewConfig,
   // Re-export @storybook/csf utilities
@@ -136,12 +135,12 @@ export { figma, isFigmaPropMapping, resolveFigmaMapping } from "./figma.js";
 export type {
   Fragment,
   FragmentFigma,
-  FragmentUsage,
+  FragmentUsage as FragmentJsonUsage,
   FragmentDoNotItem,
   FragmentPattern,
   FragmentAccessibility,
   FragmentRelated,
-  FragmentMeta,
+  FragmentMeta as FragmentJsonMeta,
   FragmentIndex,
   FragmentRegistry,
   RegistryComponentEntry,

package/src/core/loader.ts

@@ -2,15 +2,12 @@ import { writeFile, unlink } from 'node:fs/promises';
 import { dirname, basename, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { build, type Plugin } from 'esbuild';
-import type { SegmentDefinition } from './types.js';
+import type { FragmentDefinition } from './types.js';
 import { BRAND } from './constants.js';
 
-// Inline implementation of defineSegment that will be injected into bundled files
-// This allows segment files to work without @fragments/core being installed
-const DEFINE_SEGMENT_SHIM = `
-export function defineSegment(def) {
-  return def;
-}
+// Inline implementation of defineFragment that will be injected into bundled files
+// This allows fragment files to work without @fragments/core being installed
+const DEFINE_FRAGMENT_SHIM = `
 export function defineFragment(def) {
   return def;
 }
@@ -24,9 +21,9 @@ export function defineRecipe(def) {
 
 /**
  * Creates an esbuild plugin that replaces @fragments/core imports with an inline shim.
- * This allows segment files to be loaded without @fragments/core being installed in the target project.
+ * This allows fragment files to be loaded without @fragments/core being installed in the target project.
  */
-function createSegmentsCoreShimPlugin(): Plugin {
+function createFragmentsCoreShimPlugin(): Plugin {
   return {
     name: BRAND.vitePluginNamespace,
     setup(build) {
@@ -41,7 +38,7 @@ function createSegmentsCoreShimPlugin(): Plugin {
       // Return the shim content
       build.onLoad({ filter: /.*/, namespace: BRAND.vitePluginNamespace }, () => {
         return {
-          contents: DEFINE_SEGMENT_SHIM,
+          contents: DEFINE_FRAGMENT_SHIM,
           loader: 'js',
         };
       });
@@ -50,12 +47,12 @@ function createSegmentsCoreShimPlugin(): Plugin {
 }
 
 /**
- * Load a segment file, handling TSX/TS transformation automatically.
+ * Load a fragment file, handling TSX/TS transformation automatically.
  * Uses esbuild to bundle and transform TypeScript/JSX before importing.
  */
-export async function loadSegmentFile(
+export async function loadFragmentFile(
   absolutePath: string
-): Promise<SegmentDefinition | null> {
+): Promise<FragmentDefinition | null> {
   const ext = absolutePath.split('.').pop()?.toLowerCase();
   const needsTransform = ext === 'tsx' || ext === 'ts' || ext === 'jsx';
 
@@ -70,10 +67,10 @@ export async function loadSegmentFile(
   const sourceDir = dirname(absolutePath);
   const baseName = basename(absolutePath, `.${ext}`);
   // Use .cjs extension to ensure CommonJS evaluation
-  const tempFile = join(sourceDir, `.${baseName}.segments-temp-${Date.now()}.cjs`);
+  const tempFile = join(sourceDir, `.${baseName}.fragments-temp-${Date.now()}.cjs`);
 
   try {
-    // Use esbuild to bundle the segment file
+    // Use esbuild to bundle the fragment file
     // We inject a shim for @fragments/core so it doesn't need to be installed
     // Using CommonJS format to avoid ESM/CJS interop issues with node_modules
     await build({
@@ -84,8 +81,8 @@ export async function loadSegmentFile(
       target: 'es2022',
       jsx: 'automatic',
       platform: 'node',
-      plugins: [createSegmentsCoreShimPlugin()],
-      // Externalize all node_modules - we only need segment metadata, not component code
+      plugins: [createFragmentsCoreShimPlugin()],
+      // Externalize all node_modules - we only need fragment metadata, not component code
       packages: 'external',
       // Also explicitly list patterns for nested imports
       external: [
@@ -129,19 +126,19 @@ export async function loadSegmentFile(
 }
 
 /**
- * Load multiple segment files in parallel with error handling.
+ * Load multiple fragment files in parallel with error handling.
  */
-export async function loadSegmentFiles(
+export async function loadFragmentFiles(
   absolutePaths: string[]
-): Promise<Map<string, SegmentDefinition | Error>> {
-  const results = new Map<string, SegmentDefinition | Error>();
+): Promise<Map<string, FragmentDefinition | Error>> {
+  const results = new Map<string, FragmentDefinition | Error>();
 
   await Promise.all(
     absolutePaths.map(async (path) => {
       try {
-        const segment = await loadSegmentFile(path);
-        if (segment) {
-          results.set(path, segment);
+        const fragment = await loadFragmentFile(path);
+        if (fragment) {
+          results.set(path, fragment);
         } else {
           results.set(path, new Error('No default export found'));
         }

package/src/core/node.ts

@@ -8,13 +8,13 @@ export { loadConfig, findConfigFile } from './config.js';
 
 // Discovery
 export {
-  discoverSegmentFiles,
+  discoverFragmentFiles,
   discoverBlockFiles,
   discoverRecipeFiles, // @deprecated - use discoverBlockFiles
   discoverComponentFiles,
   discoverInstalledFragments,
   extractComponentName,
-  // New: Component discovery from source files (no segment files needed)
+  // New: Component discovery from source files (no fragment files needed)
   discoverComponentsFromSource,
   discoverComponentsFromBarrel,
   discoverAllComponents,
@@ -23,11 +23,11 @@ export {
 export type { DiscoveredFile, DiscoveredComponent } from './discovery.js';
 
 // Loader (TSX/TS support)
-export { loadSegmentFile, loadSegmentFiles } from './loader.js';
+export { loadFragmentFile, loadFragmentFiles } from './loader.js';
 
 // AST Parser (no execution, static analysis only)
-export { parseSegmentFile } from './parser.js';
-export type { ParsedSegmentMetadata } from './parser.js';
+export { parseFragmentFile } from './parser.js';
+export type { ParsedFragmentMetadata } from './parser.js';
 
 // Preview loader (Storybook .storybook/preview.tsx support)
 export {

package/src/core/parser.ts

@@ -1,19 +1,19 @@
 /**
- * AST-Based Segment Parser
+ * AST-Based Fragment Parser
  *
- * Extracts segment metadata from .segment.tsx files WITHOUT executing them.
- * This allows `segments build` to work without any project dependencies.
+ * Extracts fragment metadata from .fragment.tsx files WITHOUT executing them.
+ * This allows `fragments build` to work without any project dependencies.
  *
  * Uses TypeScript's compiler API to parse and analyze the AST.
  */
 
 import ts from "typescript";
-import type { SegmentMeta, SegmentUsage, PropDefinition, AIMetadata } from "./types.js";
+import type { FragmentMeta, FragmentUsage, PropDefinition, AIMetadata, FragmentContract } from "./types.js";
 
 /**
- * Parsed segment metadata (extracted statically from AST)
+ * Parsed fragment metadata (extracted statically from AST)
  */
-export interface ParsedSegmentMetadata {
+export interface ParsedFragmentMetadata {
   /** Component import path (e.g., "./Button" or "@/components/Button") */
   componentImport: string | null;
 
@@ -21,10 +21,10 @@ export interface ParsedSegmentMetadata {
   componentName: string | null;
 
   /** Component metadata */
-  meta: Partial<SegmentMeta>;
+  meta: Partial<FragmentMeta>;
 
   /** Usage guidelines */
-  usage: Partial<SegmentUsage>;
+  usage: Partial<FragmentUsage>;
 
   /** Props documentation */
   props: Record<string, Partial<PropDefinition>>;
@@ -48,22 +48,25 @@ export interface ParsedSegmentMetadata {
   /** AI-specific metadata for playground context generation */
   ai?: AIMetadata;
 
+  /** Agent-optimized contract metadata */
+  contract?: FragmentContract;
+
   /** Parse warnings */
   warnings: string[];
 }
 
 /**
- * Parse a segment file and extract metadata without executing it.
+ * Parse a fragment file and extract metadata without executing it.
  */
-export function parseSegmentFile(
+export function parseFragmentFile(
   fileContent: string,
   filePath?: string
-): ParsedSegmentMetadata {
+): ParsedFragmentMetadata {
   const warnings: string[] = [];
 
   // Parse the file
   const sourceFile = ts.createSourceFile(
-    filePath ?? "segment.tsx",
+    filePath ?? "fragment.tsx",
     fileContent,
     ts.ScriptTarget.Latest,
     true,
@@ -73,11 +76,11 @@ export function parseSegmentFile(
   // Find imports
   const imports = extractImports(sourceFile);
 
-  // Find the defineSegment call
-  const defineSegmentCall = findDefineSegmentCall(sourceFile);
+  // Find the defineFragment call
+  const defineFragmentCall = findDefineFragmentCall(sourceFile);
 
-  if (!defineSegmentCall) {
-    warnings.push("No defineSegment() call found");
+  if (!defineFragmentCall) {
+    warnings.push("No defineFragment() call found");
     return {
       componentImport: null,
       componentName: null,
@@ -91,9 +94,9 @@ export function parseSegmentFile(
   }
 
   // Extract the argument (object literal)
-  const arg = defineSegmentCall.arguments[0];
+  const arg = defineFragmentCall.arguments[0];
   if (!arg || !ts.isObjectLiteralExpression(arg)) {
-    warnings.push("defineSegment() argument is not an object literal");
+    warnings.push("defineFragment() argument is not an object literal");
     return {
       componentImport: null,
       componentName: null,
@@ -135,6 +138,9 @@ export function parseSegmentFile(
   // Extract AI metadata
   const ai = extractAIMetadata(arg, warnings);
 
+  // Extract contract metadata
+  const contract = extractContractMetadata(arg);
+
   return {
     componentImport,
     componentName,
@@ -144,6 +150,7 @@ export function parseSegmentFile(
     variants,
     relations,
     ai,
+    contract,
     warnings,
   };
 }
@@ -185,9 +192,9 @@ function extractImports(sourceFile: ts.SourceFile): Map<string, string> {
 }
 
 /**
- * Find the defineSegment() call in the source file.
+ * Find the defineFragment() call in the source file.
  */
-function findDefineSegmentCall(
+function findDefineFragmentCall(
   sourceFile: ts.SourceFile
 ): ts.CallExpression | null {
   let result: ts.CallExpression | null = null;
@@ -195,7 +202,7 @@ function findDefineSegmentCall(
   function visit(node: ts.Node): void {
     if (ts.isCallExpression(node)) {
       const expression = node.expression;
-      if (ts.isIdentifier(expression) && expression.text === "defineSegment") {
+      if (ts.isIdentifier(expression) && expression.text === "defineFragment") {
         result = node;
         return;
       }
@@ -226,19 +233,19 @@ function findProperty(
 }
 
 /**
- * Extract meta object from defineSegment call.
+ * Extract meta object from defineFragment call.
  */
 function extractMeta(
   arg: ts.ObjectLiteralExpression,
   warnings: string[]
-): Partial<SegmentMeta> {
+): Partial<FragmentMeta> {
   const metaProp = findProperty(arg, "meta");
   if (!metaProp || !ts.isObjectLiteralExpression(metaProp)) {
     warnings.push("No meta object found");
     return {};
   }
 
-  const meta: Partial<SegmentMeta> = {};
+  const meta: Partial<FragmentMeta> = {};
 
   // Extract string properties
   const name = extractStringProperty(metaProp, "name");
@@ -250,7 +257,7 @@ function extractMeta(
   const category = extractStringProperty(metaProp, "category");
   if (category) meta.category = category;
 
-  const status = extractStringProperty(metaProp, "status") as SegmentMeta["status"];
+  const status = extractStringProperty(metaProp, "status") as FragmentMeta["status"];
   if (status) meta.status = status;
 
   const since = extractStringProperty(metaProp, "since");
@@ -268,12 +275,12 @@ function extractMeta(
 }
 
 /**
- * Extract usage object from defineSegment call.
+ * Extract usage object from defineFragment call.
  */
 function extractUsage(
   arg: ts.ObjectLiteralExpression,
   warnings: string[]
-): Partial<SegmentUsage> {
+): Partial<FragmentUsage> {
   const usageProp = findProperty(arg, "usage");
   if (!usageProp || !ts.isObjectLiteralExpression(usageProp)) {
     return { when: [], whenNot: [] };
@@ -288,7 +295,7 @@ function extractUsage(
 }
 
 /**
- * Extract props object from defineSegment call.
+ * Extract props object from defineFragment call.
  */
 function extractProps(
   arg: ts.ObjectLiteralExpression,
@@ -348,7 +355,7 @@ function extractPropDefinition(
 }
 
 /**
- * Extract variants array from defineSegment call.
+ * Extract variants array from defineFragment call.
  */
 function extractVariants(
   arg: ts.ObjectLiteralExpression,
@@ -483,7 +490,7 @@ function extractRenderCode(
 }
 
 /**
- * Extract relations array from defineSegment call.
+ * Extract relations array from defineFragment call.
  */
 function extractRelations(
   arg: ts.ObjectLiteralExpression,
@@ -516,7 +523,7 @@ function extractRelations(
 }
 
 /**
- * Extract AI metadata from defineSegment call.
+ * Extract AI metadata from defineFragment call.
  */
 function extractAIMetadata(
   arg: ts.ObjectLiteralExpression,
@@ -561,6 +568,39 @@ function extractAIMetadata(
   return undefined;
 }
 
+/**
+ * Extract contract metadata from defineFragment call.
+ */
+function extractContractMetadata(
+  arg: ts.ObjectLiteralExpression,
+): FragmentContract | undefined {
+  const contractProp = findProperty(arg, "contract");
+  if (!contractProp || !ts.isObjectLiteralExpression(contractProp)) {
+    return undefined;
+  }
+
+  const contract: FragmentContract = {};
+
+  // Extract propsSummary array
+  const propsSummary = extractStringArray(contractProp, "propsSummary");
+  if (propsSummary.length > 0) {
+    contract.propsSummary = propsSummary;
+  }
+
+  // Extract a11yRules array
+  const a11yRules = extractStringArray(contractProp, "a11yRules");
+  if (a11yRules.length > 0) {
+    contract.a11yRules = a11yRules;
+  }
+
+  // Only return if we have any fields
+  if (Object.keys(contract).length > 0) {
+    return contract;
+  }
+
+  return undefined;
+}
+
 /**
  * Extract a string property from an object literal.
  */

package/src/core/previewLoader.ts

@@ -91,7 +91,7 @@ export async function loadPreviewConfig(
     return config;
   } catch (error) {
     console.warn(
-      `[Segments] Failed to load preview config from ${previewPath}:`,
+      `[Fragments] Failed to load preview config from ${previewPath}:`,
       error instanceof Error ? error.message : error
     );
     return {};

package/src/core/schema.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 /**
- * Zod schemas for runtime validation of segment definitions
+ * Zod schemas for runtime validation of fragment definitions
  */
 
 // Figma property mapping schemas
@@ -46,7 +46,7 @@ export const figmaPropMappingSchema = z.discriminatedUnion('__type', [
   figmaTextContentMappingSchema,
 ]);
 
-export const segmentMetaSchema = z.object({
+export const fragmentMetaSchema = z.object({
   name: z.string().min(1),
   description: z.string().min(1),
   category: z.string().min(1),
@@ -57,7 +57,7 @@ export const segmentMetaSchema = z.object({
   figmaProps: z.record(figmaPropMappingSchema).optional(),
 });
 
-export const segmentUsageSchema = z.object({
+export const fragmentUsageSchema = z.object({
   when: z.array(z.string()).min(1),
   whenNot: z.array(z.string()).min(1),
   guidelines: z.array(z.string()).optional(),
@@ -104,7 +104,7 @@ export const componentRelationSchema = z.object({
   note: z.string().min(1),
 });
 
-export const segmentVariantSchema = z.object({
+export const fragmentVariantSchema = z.object({
   name: z.string().min(1),
   description: z.string().min(1),
   render: z.function().returns(z.unknown()),
@@ -115,7 +115,7 @@ export const segmentVariantSchema = z.object({
 /**
  * Schema for banned patterns in codebase
  */
-export const segmentBanSchema = z.object({
+export const fragmentBanSchema = z.object({
   pattern: z.string().min(1),
   message: z.string().min(1),
 });
@@ -123,17 +123,17 @@ export const segmentBanSchema = z.object({
 /**
  * Schema for agent-optimized contract metadata
  */
-export const segmentContractSchema = z.object({
+export const fragmentContractSchema = z.object({
   propsSummary: z.array(z.string()).optional(),
   a11yRules: z.array(z.string()).optional(),
-  bans: z.array(segmentBanSchema).optional(),
+  bans: z.array(fragmentBanSchema).optional(),
   scenarioTags: z.array(z.string()).optional(),
 });
 
 /**
- * Schema for provenance tracking of generated segments
+ * Schema for provenance tracking of generated fragments
  */
-export const segmentGeneratedSchema = z.object({
+export const fragmentGeneratedSchema = z.object({
   source: z.enum(['storybook', 'manual', 'ai']),
   sourceFile: z.string().optional(),
   confidence: z.number().min(0).max(1).optional(),
@@ -162,23 +162,23 @@ export const blockDefinitionSchema = z.object({
   tags: z.array(z.string()).optional(),
 });
 
-export const segmentDefinitionSchema = z.object({
+export const fragmentDefinitionSchema = z.object({
   component: z.any(), // Allow any component type (function, class, forwardRef, etc.)
-  meta: segmentMetaSchema,
-  usage: segmentUsageSchema,
+  meta: fragmentMetaSchema,
+  usage: fragmentUsageSchema,
   props: z.record(propDefinitionSchema),
   relations: z.array(componentRelationSchema).optional(),
-  variants: z.array(segmentVariantSchema), // Allow empty variants array
-  contract: segmentContractSchema.optional(),
+  variants: z.array(fragmentVariantSchema), // Allow empty variants array
+  contract: fragmentContractSchema.optional(),
   ai: aiMetadataSchema.optional(),
-  _generated: segmentGeneratedSchema.optional(),
+  _generated: fragmentGeneratedSchema.optional(),
 });
 
 /**
  * Config schema - validates required fields, passes through optional config objects.
  * Type definitions are in types.ts - schema just ensures basic structure.
  */
-export const segmentsConfigSchema = z.object({
+export const fragmentsConfigSchema = z.object({
   include: z.array(z.string()).min(1),
   exclude: z.array(z.string()).optional(),
   components: z.array(z.string()).optional(),