@fragments-sdk/cli 0.7.0 → 0.7.2

package/src/core/composition.test.ts

@@ -1,8 +1,8 @@
 import { describe, it, expect } from "vitest";
 import { analyzeComposition } from "./composition.js";
-import type { CompiledSegment } from "./types.js";
+import type { CompiledFragment } from "./types.js";
 
-function makeSegment(overrides: Partial<CompiledSegment> & { meta: CompiledSegment["meta"] }): CompiledSegment {
+function makeFragment(overrides: Partial<CompiledFragment> & { meta: CompiledFragment["meta"] }): CompiledFragment {
   return {
     filePath: "src/components/Test.tsx",
     usage: { when: [], whenNot: [] },
@@ -12,8 +12,8 @@ function makeSegment(overrides: Partial<CompiledSegment> & { meta: CompiledSegme
   };
 }
 
-const baseSegments: Record<string, CompiledSegment> = {
-  Button: makeSegment({
+const baseFragments: Record<string, CompiledFragment> = {
+  Button: makeFragment({
     meta: { name: "Button", description: "A button", category: "actions", status: "stable" },
     relations: [
       { component: "IconButton", relationship: "alternative", note: "Use for icon-only actions" },
@@ -24,19 +24,19 @@ const baseSegments: Record<string, CompiledSegment> = {
       whenNot: ["Use Link for navigation"],
     },
   }),
-  IconButton: makeSegment({
+  IconButton: makeFragment({
     meta: { name: "IconButton", description: "Icon-only button", category: "actions", status: "stable" },
     relations: [
       { component: "Button", relationship: "alternative", note: "Use for labeled actions" },
     ],
   }),
-  ButtonGroup: makeSegment({
+  ButtonGroup: makeFragment({
     meta: { name: "ButtonGroup", description: "Groups buttons", category: "actions", status: "stable" },
     relations: [
       { component: "Button", relationship: "child", note: "Contains buttons" },
     ],
   }),
-  TextField: makeSegment({
+  TextField: makeFragment({
     meta: { name: "TextField", description: "Text input", category: "forms", status: "stable" },
     relations: [
       { component: "Form", relationship: "parent", note: "Should be inside a Form" },
@@ -47,22 +47,22 @@ const baseSegments: Record<string, CompiledSegment> = {
       whenNot: ["Use TextArea for multiline input"],
     },
   }),
-  Form: makeSegment({
+  Form: makeFragment({
     meta: { name: "Form", description: "Form container", category: "forms", status: "stable" },
   }),
-  Label: makeSegment({
+  Label: makeFragment({
     meta: { name: "Label", description: "Form label", category: "forms", status: "stable" },
   }),
-  Alert: makeSegment({
+  Alert: makeFragment({
     meta: { name: "Alert", description: "Feedback alert", category: "feedback", status: "stable" },
   }),
-  Toast: makeSegment({
+  Toast: makeFragment({
     meta: { name: "Toast", description: "Toast notification", category: "feedback", status: "experimental" },
   }),
-  OldButton: makeSegment({
+  OldButton: makeFragment({
     meta: { name: "OldButton", description: "Use Button instead", category: "actions", status: "deprecated" },
   }),
-  Link: makeSegment({
+  Link: makeFragment({
     meta: { name: "Link", description: "Navigation link", category: "navigation", status: "stable" },
     usage: {
       when: ["User needs to navigate"],
@@ -74,25 +74,25 @@ const baseSegments: Record<string, CompiledSegment> = {
 describe("analyzeComposition", () => {
   describe("name validation", () => {
     it("should split components into found and unknown", () => {
-      const result = analyzeComposition(baseSegments, ["Button", "NonExistent", "TextField", "AlsoFake"]);
+      const result = analyzeComposition(baseFragments, ["Button", "NonExistent", "TextField", "AlsoFake"]);
       expect(result.components).toEqual(["Button", "TextField"]);
       expect(result.unknown).toEqual(["NonExistent", "AlsoFake"]);
     });
 
     it("should handle all valid names", () => {
-      const result = analyzeComposition(baseSegments, ["Button", "TextField"]);
+      const result = analyzeComposition(baseFragments, ["Button", "TextField"]);
       expect(result.components).toEqual(["Button", "TextField"]);
       expect(result.unknown).toEqual([]);
     });
 
     it("should handle all unknown names", () => {
-      const result = analyzeComposition(baseSegments, ["Foo", "Bar"]);
+      const result = analyzeComposition(baseFragments, ["Foo", "Bar"]);
       expect(result.components).toEqual([]);
       expect(result.unknown).toEqual(["Foo", "Bar"]);
     });
 
     it("should handle empty input", () => {
-      const result = analyzeComposition(baseSegments, []);
+      const result = analyzeComposition(baseFragments, []);
       expect(result.components).toEqual([]);
       expect(result.unknown).toEqual([]);
       expect(result.warnings).toEqual([]);
@@ -103,7 +103,7 @@ describe("analyzeComposition", () => {
 
   describe("relation checks", () => {
     it("should warn about missing parent", () => {
-      const result = analyzeComposition(baseSegments, ["TextField"]);
+      const result = analyzeComposition(baseFragments, ["TextField"]);
       const parentWarning = result.warnings.find((w) => w.type === "missing_parent");
       expect(parentWarning).toBeDefined();
       expect(parentWarning!.component).toBe("TextField");
@@ -111,13 +111,13 @@ describe("analyzeComposition", () => {
     });
 
     it("should not warn about parent when parent is selected", () => {
-      const result = analyzeComposition(baseSegments, ["TextField", "Form"]);
+      const result = analyzeComposition(baseFragments, ["TextField", "Form"]);
       const parentWarning = result.warnings.find((w) => w.type === "missing_parent");
       expect(parentWarning).toBeUndefined();
     });
 
     it("should suggest missing children", () => {
-      const result = analyzeComposition(baseSegments, ["ButtonGroup"]);
+      const result = analyzeComposition(baseFragments, ["ButtonGroup"]);
       const childSuggestion = result.suggestions.find(
         (s) => s.component === "Button" && s.relationship === "child"
       );
@@ -126,7 +126,7 @@ describe("analyzeComposition", () => {
     });
 
     it("should warn about missing composition peers", () => {
-      const result = analyzeComposition(baseSegments, ["Button"]);
+      const result = analyzeComposition(baseFragments, ["Button"]);
       const compWarning = result.warnings.find((w) => w.type === "missing_composition");
       expect(compWarning).toBeDefined();
       expect(compWarning!.component).toBe("Button");
@@ -134,13 +134,13 @@ describe("analyzeComposition", () => {
     });
 
     it("should not warn when composition peer is selected", () => {
-      const result = analyzeComposition(baseSegments, ["Button", "ButtonGroup"]);
+      const result = analyzeComposition(baseFragments, ["Button", "ButtonGroup"]);
       const compWarning = result.warnings.find((w) => w.type === "missing_composition");
       expect(compWarning).toBeUndefined();
     });
 
     it("should suggest missing siblings", () => {
-      const result = analyzeComposition(baseSegments, ["TextField", "Form"]);
+      const result = analyzeComposition(baseFragments, ["TextField", "Form"]);
       const siblingSuggestion = result.suggestions.find(
         (s) => s.component === "Label" && s.relationship === "sibling"
       );
@@ -149,7 +149,7 @@ describe("analyzeComposition", () => {
     });
 
     it("should warn about redundant alternatives", () => {
-      const result = analyzeComposition(baseSegments, ["Button", "IconButton"]);
+      const result = analyzeComposition(baseFragments, ["Button", "IconButton"]);
       const altWarning = result.warnings.find((w) => w.type === "redundant_alternative");
       expect(altWarning).toBeDefined();
       expect(altWarning!.component).toBe("Button");
@@ -157,7 +157,7 @@ describe("analyzeComposition", () => {
     });
 
     it("should not warn when only one alternative is selected", () => {
-      const result = analyzeComposition(baseSegments, ["Button"]);
+      const result = analyzeComposition(baseFragments, ["Button"]);
       const altWarning = result.warnings.find((w) => w.type === "redundant_alternative");
       expect(altWarning).toBeUndefined();
     });
@@ -165,7 +165,7 @@ describe("analyzeComposition", () => {
 
   describe("usage conflict checks", () => {
     it("should emit guideline when whenNot mentions another selected component", () => {
-      const result = analyzeComposition(baseSegments, ["Button", "Link"]);
+      const result = analyzeComposition(baseFragments, ["Button", "Link"]);
       const conflict = result.guidelines.find(
         (g) => g.component === "Link" && g.guideline.includes("Button")
       );
@@ -173,14 +173,14 @@ describe("analyzeComposition", () => {
     });
 
     it("should not emit guideline when no conflict exists", () => {
-      const result = analyzeComposition(baseSegments, ["Button", "Alert"]);
+      const result = analyzeComposition(baseFragments, ["Button", "Alert"]);
       expect(result.guidelines).toEqual([]);
     });
   });
 
   describe("status warnings", () => {
     it("should warn about deprecated components", () => {
-      const result = analyzeComposition(baseSegments, ["OldButton"]);
+      const result = analyzeComposition(baseFragments, ["OldButton"]);
       const depWarning = result.warnings.find((w) => w.type === "deprecated");
       expect(depWarning).toBeDefined();
       expect(depWarning!.component).toBe("OldButton");
@@ -188,7 +188,7 @@ describe("analyzeComposition", () => {
     });
 
     it("should warn about experimental components", () => {
-      const result = analyzeComposition(baseSegments, ["Toast"]);
+      const result = analyzeComposition(baseFragments, ["Toast"]);
       const expWarning = result.warnings.find((w) => w.type === "experimental");
       expect(expWarning).toBeDefined();
       expect(expWarning!.component).toBe("Toast");
@@ -196,7 +196,7 @@ describe("analyzeComposition", () => {
     });
 
     it("should not warn about stable components", () => {
-      const result = analyzeComposition(baseSegments, ["Button"]);
+      const result = analyzeComposition(baseFragments, ["Button"]);
       const statusWarnings = result.warnings.filter(
         (w) => w.type === "deprecated" || w.type === "experimental"
       );
@@ -206,7 +206,7 @@ describe("analyzeComposition", () => {
 
   describe("category gap analysis", () => {
     it("should suggest feedback component when forms are selected without feedback", () => {
-      const result = analyzeComposition(baseSegments, ["TextField", "Form"]);
+      const result = analyzeComposition(baseFragments, ["TextField", "Form"]);
       const gapSuggestion = result.suggestions.find(
         (s) => s.relationship === "category_gap"
       );
@@ -216,7 +216,7 @@ describe("analyzeComposition", () => {
     });
 
     it("should suggest feedback component when actions are selected without feedback", () => {
-      const result = analyzeComposition(baseSegments, ["Button", "ButtonGroup"]);
+      const result = analyzeComposition(baseFragments, ["Button", "ButtonGroup"]);
       const gapSuggestion = result.suggestions.find(
         (s) => s.relationship === "category_gap"
       );
@@ -225,7 +225,7 @@ describe("analyzeComposition", () => {
     });
 
     it("should not suggest category gap when feedback is already present", () => {
-      const result = analyzeComposition(baseSegments, ["Button", "ButtonGroup", "Alert"]);
+      const result = analyzeComposition(baseFragments, ["Button", "ButtonGroup", "Alert"]);
       const gapSuggestion = result.suggestions.find(
         (s) => s.relationship === "category_gap"
       );
@@ -234,7 +234,7 @@ describe("analyzeComposition", () => {
 
     it("should prefer stable components over experimental in category gap suggestions", () => {
       // Alert is stable, Toast is experimental — should pick Alert
-      const result = analyzeComposition(baseSegments, ["TextField", "Form"]);
+      const result = analyzeComposition(baseFragments, ["TextField", "Form"]);
       const gapSuggestion = result.suggestions.find(
         (s) => s.relationship === "category_gap"
       );
@@ -244,7 +244,7 @@ describe("analyzeComposition", () => {
 
   describe("deduplication", () => {
     it("should not suggest the same component twice", () => {
-      const result = analyzeComposition(baseSegments, ["ButtonGroup", "Button"]);
+      const result = analyzeComposition(baseFragments, ["ButtonGroup", "Button"]);
       const buttonSuggestions = result.suggestions.filter(
         (s) => s.component === "Button"
       );
@@ -255,7 +255,7 @@ describe("analyzeComposition", () => {
 
   describe("context parameter", () => {
     it("should accept optional context without error", () => {
-      const result = analyzeComposition(baseSegments, ["Button"], "building a form page");
+      const result = analyzeComposition(baseFragments, ["Button"], "building a form page");
       expect(result.components).toEqual(["Button"]);
     });
   });

package/src/core/composition.ts

@@ -1,4 +1,4 @@
-import type { CompiledSegment, RelationshipType } from "./types.js";
+import type { CompiledFragment, RelationshipType } from "./types.js";
 import type { ComponentGraph } from "@fragments-sdk/context/graph";
 import { ComponentGraphEngine } from "@fragments-sdk/context/graph";
 
@@ -66,12 +66,12 @@ const CATEGORY_AFFINITIES: Record<string, string[]> = {
  * Browser-safe: no Node.js APIs used.
  */
 export function analyzeComposition(
-  segments: Record<string, CompiledSegment>,
+  fragments: Record<string, CompiledFragment>,
   componentNames: string[],
   _context?: string,
   options?: { graph?: ComponentGraph },
 ): CompositionAnalysis {
-  const allNames = new Set(Object.keys(segments));
+  const allNames = new Set(Object.keys(fragments));
 
   // 1. Validate names
   const components: string[] = [];
@@ -93,11 +93,11 @@ export function analyzeComposition(
   const suggestedSet = new Set<string>();
 
   for (const name of components) {
-    const segment = segments[name];
+    const fragment = fragments[name];
 
     // 2. Relation checks
-    if (segment.relations) {
-      for (const rel of segment.relations) {
+    if (fragment.relations) {
+      for (const rel of fragment.relations) {
         switch (rel.relationship) {
           case "parent":
             if (!selectedSet.has(rel.component)) {
@@ -160,8 +160,8 @@ export function analyzeComposition(
     }
 
     // 3. Usage conflict checks (whenNot)
-    if (segment.usage?.whenNot) {
-      for (const whenNotEntry of segment.usage.whenNot) {
+    if (fragment.usage?.whenNot) {
+      for (const whenNotEntry of fragment.usage.whenNot) {
         const lower = whenNotEntry.toLowerCase();
         for (const other of components) {
           if (other !== name && lower.includes(other.toLowerCase())) {
@@ -175,15 +175,15 @@ export function analyzeComposition(
     }
 
     // 4. Status warnings
-    if (segment.meta.status === "deprecated") {
+    if (fragment.meta.status === "deprecated") {
       warnings.push({
         type: "deprecated",
         component: name,
-        message: segment.meta.description
-          ? `"${name}" is deprecated: ${segment.meta.description}`
+        message: fragment.meta.description
+          ? `"${name}" is deprecated: ${fragment.meta.description}`
           : `"${name}" is deprecated`,
       });
-    } else if (segment.meta.status === "experimental") {
+    } else if (fragment.meta.status === "experimental") {
       warnings.push({
         type: "experimental",
         component: name,
@@ -194,7 +194,7 @@ export function analyzeComposition(
 
   // 5. Category gap analysis
   const selectedCategories = new Set(
-    components.map((name) => segments[name].meta.category)
+    components.map((name) => fragments[name].meta.category)
   );
 
   for (const [category, affinities] of Object.entries(CATEGORY_AFFINITIES)) {
@@ -205,7 +205,7 @@ export function analyzeComposition(
 
       // Find the best component from the needed category
       const candidate = findBestCategoryCandidate(
-        segments,
+        fragments,
         neededCategory,
         selectedSet,
         suggestedSet
@@ -216,7 +216,7 @@ export function analyzeComposition(
           reason: `Compositions using "${category}" components often benefit from a "${neededCategory}" component`,
           relationship: "category_gap",
           sourceComponent: components.find(
-            (n) => segments[n].meta.category === category
+            (n) => fragments[n].meta.category === category
           )!,
         });
         suggestedSet.add(candidate);
@@ -289,7 +289,7 @@ export function analyzeComposition(
  * Prefers stable components and avoids already-selected or already-suggested ones.
  */
 function findBestCategoryCandidate(
-  segments: Record<string, CompiledSegment>,
+  fragments: Record<string, CompiledFragment>,
   category: string,
   selectedSet: Set<string>,
   suggestedSet: Set<string>
@@ -297,11 +297,11 @@ function findBestCategoryCandidate(
   let best: string | null = null;
   let bestScore = -1;
 
-  for (const [name, segment] of Object.entries(segments)) {
-    if (segment.meta.category !== category) continue;
+  for (const [name, fragment] of Object.entries(fragments)) {
+    if (fragment.meta.category !== category) continue;
     if (selectedSet.has(name) || suggestedSet.has(name)) continue;
 
-    const status = segment.meta.status ?? "stable";
+    const status = fragment.meta.status ?? "stable";
     let score = 0;
     if (status === "stable") score = 3;
     else if (status === "beta") score = 2;

package/src/core/config.ts

@@ -2,12 +2,12 @@ import { existsSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { createJiti } from 'jiti';
 import { BRAND } from './constants.js';
-import type { SegmentsConfig } from './types.js';
-import { segmentsConfigSchema } from './schema.js';
+import type { FragmentsConfig } from './types.js';
+import { fragmentsConfigSchema } from './schema.js';
 
-const DEFAULT_CONFIG: SegmentsConfig = {
+const DEFAULT_CONFIG: FragmentsConfig = {
   include: [
-    `src/**/*${BRAND.fileExtension}`,  // *.segment.tsx files
+    `src/**/*${BRAND.fileExtension}`,  // *.fragment.tsx files
     'src/**/*.stories.tsx',             // Storybook stories (auto-converted)
   ],
   exclude: ['**/node_modules/**'],
@@ -43,7 +43,7 @@ export function findConfigFile(startDir: string = process.cwd()): string | null
  * Load and validate the config file
  */
 export async function loadConfig(configPath?: string): Promise<{
-  config: SegmentsConfig;
+  config: FragmentsConfig;
   configDir: string;
 }> {
   const resolvedPath = configPath ?? findConfigFile();
@@ -62,7 +62,7 @@ export async function loadConfig(configPath?: string): Promise<{
     });
     const rawConfig = await jiti.import(resolvedPath);
 
-    const result = segmentsConfigSchema.safeParse(rawConfig);
+    const result = fragmentsConfigSchema.safeParse(rawConfig);
 
     if (!result.success) {
       const errors = result.error.errors

package/src/core/{defineSegment.ts → defineFragment.ts}

@@ -1,18 +1,18 @@
-import type { SegmentDefinition, CompiledSegment, SegmentComponent, BlockDefinition, CompiledBlock } from './types.js';
-import { segmentDefinitionSchema, blockDefinitionSchema } from './schema.js';
+import type { FragmentDefinition, CompiledFragment, FragmentComponent, BlockDefinition, CompiledBlock } from './types.js';
+import { fragmentDefinitionSchema, blockDefinitionSchema } from './schema.js';
 
 /**
- * Define a segment for a component.
+ * Define a fragment for a component.
  *
- * This is the main API for creating segment documentation.
+ * This is the main API for creating fragment documentation.
  * It provides runtime validation and type safety.
  *
  * @example
  * ```tsx
- * import { defineSegment } from '@fragments/core';
+ * import { defineFragment } from '@fragments/core';
  * import { Button } from './Button';
  *
- * export default defineSegment({
+ * export default defineFragment({
  *   component: Button,
  *   meta: {
  *     name: 'Button',
@@ -41,18 +41,18 @@ import { segmentDefinitionSchema, blockDefinitionSchema } from './schema.js';
  * });
  * ```
  */
-export function defineSegment<TProps>(
-  definition: SegmentDefinition<TProps>
-): SegmentDefinition<TProps> {
+export function defineFragment<TProps>(
+  definition: FragmentDefinition<TProps>
+): FragmentDefinition<TProps> {
   // Validate at runtime in development
   if (process.env.NODE_ENV !== 'production') {
-    const result = segmentDefinitionSchema.safeParse(definition);
+    const result = fragmentDefinitionSchema.safeParse(definition);
     if (!result.success) {
       const errors = result.error.errors
         .map((e) => `  - ${e.path.join('.')}: ${e.message}`)
         .join('\n');
       throw new Error(
-        `Invalid segment definition for "${definition.meta?.name || 'unknown'}":\n${errors}`
+        `Invalid fragment definition for "${definition.meta?.name || 'unknown'}":\n${errors}`
       );
     }
   }
@@ -61,19 +61,13 @@ export function defineSegment<TProps>(
 }
 
 /**
- * Alias for defineSegment - use this for new projects.
- * @see defineSegment
- */
-export const defineFragment = defineSegment;
-
-/**
- * Compile a segment definition to JSON-serializable format.
+ * Compile a fragment definition to JSON-serializable format.
  * Used for generating fragments.json for AI consumption.
  */
-export function compileSegment(
-  definition: SegmentDefinition,
+export function compileFragment(
+  definition: FragmentDefinition,
   filePath: string
-): CompiledSegment {
+): CompiledFragment {
   return {
     filePath,
     meta: definition.meta,
@@ -144,4 +138,4 @@ export const compileRecipe = compileBlock;
 /**
  * Type helper for extracting props type from a component
  */
-export type InferProps<T> = T extends SegmentComponent<infer P> ? P : never;
+export type InferProps<T> = T extends FragmentComponent<infer P> ? P : never;

package/src/core/discovery.ts

@@ -2,7 +2,7 @@ import { resolve, dirname, basename } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import fg from 'fast-glob';
-import type { SegmentsConfig } from './types.js';
+import type { FragmentsConfig } from './types.js';
 import { BRAND } from './constants.js';
 
 export interface DiscoveredFile {
@@ -56,10 +56,10 @@ export async function discoverBlockFiles(
 export const discoverRecipeFiles = discoverBlockFiles;
 
 /**
- * Discover segment files matching the config patterns
+ * Discover fragment files matching the config patterns
  */
-export async function discoverSegmentFiles(
-  config: SegmentsConfig,
+export async function discoverFragmentFiles(
+  config: FragmentsConfig,
   configDir: string
 ): Promise<DiscoveredFile[]> {
   const files = await fg(config.include, {
@@ -78,7 +78,7 @@ export async function discoverSegmentFiles(
  * Discover component files for coverage validation
  */
 export async function discoverComponentFiles(
-  config: SegmentsConfig,
+  config: FragmentsConfig,
   configDir: string
 ): Promise<DiscoveredFile[]> {
   if (!config.components || config.components.length === 0) {
@@ -89,7 +89,7 @@ export async function discoverComponentFiles(
     cwd: configDir,
     ignore: [
       ...(config.exclude ?? []),
-      // Exclude segment files themselves
+      // Exclude fragment files themselves
       ...config.include,
       // Exclude test files
       '**/*.test.*',

package/src/core/figma.ts

@@ -6,9 +6,9 @@
  *
  * @example
  * ```tsx
- * import { defineSegment, figma } from '@fragments/core';
+ * import { defineFragment, figma } from '@fragments/core';
  *
- * export default defineSegment({
+ * export default defineFragment({
  *   component: Button,
  *   meta: {
  *     name: 'Button',