@fragments-sdk/cli 0.2.2

package/src/core/context.ts

@@ -0,0 +1,380 @@
+import type { CompiledSegment, CompiledRecipe, PropDefinition } from "./types.js";
+
+/**
+ * Placeholder patterns to filter out from usage text.
+ * These are generated by the migrate tool and provide no value.
+ */
+const PLACEHOLDER_PATTERNS = [
+  /^\w+ component is needed$/i,
+  /^Alternative component is more appropriate$/i,
+  /^Use \w+ when you need/i,
+];
+
+/**
+ * Filter out placeholder text from usage arrays
+ */
+function filterPlaceholders(items: string[]): string[] {
+  return items.filter(item =>
+    !PLACEHOLDER_PATTERNS.some(pattern => pattern.test(item.trim()))
+  );
+}
+
+/**
+ * Options for context generation
+ */
+export interface ContextOptions {
+  /** Output format */
+  format?: "markdown" | "json";
+
+  /** What to include in the output */
+  include?: {
+    /** Include prop details (default: true) */
+    props?: boolean;
+    /** Include variant list (default: true) */
+    variants?: boolean;
+    /** Include usage guidelines (default: true) */
+    usage?: boolean;
+    /** Include related components (default: false) */
+    relations?: boolean;
+    /** Include code examples (default: false) */
+    code?: boolean;
+  };
+
+  /** Compact mode - minimal output for token efficiency */
+  compact?: boolean;
+}
+
+/**
+ * Result of context generation
+ */
+export interface ContextResult {
+  /** The generated context content */
+  content: string;
+  /** Estimated token count */
+  tokenEstimate: number;
+}
+
+/**
+ * Generate AI-ready context from compiled segments and optional recipes
+ */
+export function generateContext(
+  segments: CompiledSegment[],
+  options: ContextOptions = {},
+  recipes?: CompiledRecipe[]
+): ContextResult {
+  const format = options.format ?? "markdown";
+  const compact = options.compact ?? false;
+
+  const include = {
+    props: options.include?.props ?? true,
+    variants: options.include?.variants ?? true,
+    usage: options.include?.usage ?? true,
+    relations: options.include?.relations ?? false,
+    code: options.include?.code ?? false,
+  };
+
+  // Sort segments by category, then name
+  const sorted = [...segments].sort((a, b) => {
+    const catCompare = a.meta.category.localeCompare(b.meta.category);
+    if (catCompare !== 0) return catCompare;
+    return a.meta.name.localeCompare(b.meta.name);
+  });
+
+  if (format === "json") {
+    return generateJsonContext(sorted, include, compact, recipes);
+  }
+
+  return generateMarkdownContext(sorted, include, compact, recipes);
+}
+
+/**
+ * Generate markdown context
+ */
+function generateMarkdownContext(
+  segments: CompiledSegment[],
+  include: Required<NonNullable<ContextOptions["include"]>>,
+  compact: boolean,
+  recipes?: CompiledRecipe[]
+): ContextResult {
+  const lines: string[] = [];
+
+  lines.push("# Design System Reference");
+  lines.push("");
+
+  // Quick reference table
+  lines.push("## Quick Reference");
+  lines.push("");
+  lines.push("| Component | Category | Use For |");
+  lines.push("|-----------|----------|---------|");
+
+  for (const segment of segments) {
+    const filteredWhen = filterPlaceholders(segment.usage.when);
+    const useFor = filteredWhen.slice(0, 2).join(", ") || segment.meta.description;
+    lines.push(`| ${segment.meta.name} | ${segment.meta.category} | ${truncate(useFor, 50)} |`);
+  }
+
+  lines.push("");
+
+  // If compact mode, stop here
+  if (compact) {
+    const content = lines.join("\n");
+    return {
+      content,
+      tokenEstimate: estimateTokens(content),
+    };
+  }
+
+  // Full component documentation
+  lines.push("## Components");
+  lines.push("");
+
+  for (const segment of segments) {
+    lines.push(`### ${segment.meta.name}`);
+    lines.push("");
+
+    // Status line
+    const statusParts = [`**Category:** ${segment.meta.category}`];
+    if (segment.meta.status) {
+      statusParts.push(`**Status:** ${segment.meta.status}`);
+    }
+    lines.push(statusParts.join(" | "));
+    lines.push("");
+
+    if (segment.meta.description) {
+      lines.push(segment.meta.description);
+      lines.push("");
+    }
+
+    // Usage guidelines (filter out placeholder text)
+    const whenFiltered = filterPlaceholders(segment.usage.when);
+    const whenNotFiltered = filterPlaceholders(segment.usage.whenNot);
+
+    if (include.usage && (whenFiltered.length > 0 || whenNotFiltered.length > 0)) {
+      if (whenFiltered.length > 0) {
+        lines.push("**When to use:**");
+        for (const when of whenFiltered) {
+          lines.push(`- ${when}`);
+        }
+        lines.push("");
+      }
+
+      if (whenNotFiltered.length > 0) {
+        lines.push("**When NOT to use:**");
+        for (const whenNot of whenNotFiltered) {
+          lines.push(`- ${whenNot}`);
+        }
+        lines.push("");
+      }
+    }
+
+    // Props
+    if (include.props && Object.keys(segment.props).length > 0) {
+      lines.push("**Props:**");
+      for (const [name, prop] of Object.entries(segment.props)) {
+        lines.push(`- \`${name}\`: ${formatPropType(prop)}${prop.required ? " (required)" : ""}`);
+      }
+      lines.push("");
+    }
+
+    // Variants
+    if (include.variants && segment.variants.length > 0) {
+      const variantNames = segment.variants.map((v) => v.name).join(", ");
+      lines.push(`**Variants:** ${variantNames}`);
+      lines.push("");
+
+      // Code examples
+      if (include.code) {
+        for (const variant of segment.variants) {
+          if (variant.code) {
+            lines.push(`*${variant.name}:*`);
+            lines.push("```tsx");
+            lines.push(variant.code);
+            lines.push("```");
+            lines.push("");
+          }
+        }
+      }
+    }
+
+    // Relations
+    if (include.relations && segment.relations && segment.relations.length > 0) {
+      lines.push("**Related:**");
+      for (const relation of segment.relations) {
+        lines.push(`- ${relation.component} (${relation.relationship}): ${relation.note}`);
+      }
+      lines.push("");
+    }
+
+    lines.push("---");
+    lines.push("");
+  }
+
+  // Recipes section
+  if (recipes && recipes.length > 0) {
+    lines.push("## Recipes");
+    lines.push("");
+    lines.push("Composition patterns showing how components wire together.");
+    lines.push("");
+
+    for (const recipe of recipes) {
+      lines.push(`### ${recipe.name}`);
+      lines.push("");
+      lines.push(recipe.description);
+      lines.push("");
+      lines.push(`**Category:** ${recipe.category}`);
+      lines.push(`**Components:** ${recipe.components.join(", ")}`);
+      if (recipe.tags && recipe.tags.length > 0) {
+        lines.push(`**Tags:** ${recipe.tags.join(", ")}`);
+      }
+      lines.push("");
+      lines.push("```tsx");
+      lines.push(recipe.code);
+      lines.push("```");
+      lines.push("");
+      lines.push("---");
+      lines.push("");
+    }
+  }
+
+  const content = lines.join("\n");
+  return {
+    content,
+    tokenEstimate: estimateTokens(content),
+  };
+}
+
+/**
+ * Generate JSON context
+ */
+function generateJsonContext(
+  segments: CompiledSegment[],
+  include: Required<NonNullable<ContextOptions["include"]>>,
+  compact: boolean,
+  recipes?: CompiledRecipe[]
+): ContextResult {
+  const categories = [...new Set(segments.map((s) => s.meta.category))].sort();
+
+  interface JsonComponent {
+    category: string;
+    description: string;
+    status?: string;
+    whenToUse?: string[];
+    whenNotToUse?: string[];
+    props?: Record<string, { type: string; required?: boolean; default?: unknown; description: string }>;
+    variants?: string[];
+    relations?: Array<{ component: string; relationship: string; note: string }>;
+  }
+
+  const components: Record<string, JsonComponent> = {};
+
+  for (const segment of segments) {
+    const component: JsonComponent = {
+      category: segment.meta.category,
+      description: segment.meta.description,
+    };
+
+    if (segment.meta.status) {
+      component.status = segment.meta.status;
+    }
+
+    if (!compact) {
+      if (include.usage) {
+        const whenFiltered = filterPlaceholders(segment.usage.when);
+        const whenNotFiltered = filterPlaceholders(segment.usage.whenNot);
+        if (whenFiltered.length > 0) {
+          component.whenToUse = whenFiltered;
+        }
+        if (whenNotFiltered.length > 0) {
+          component.whenNotToUse = whenNotFiltered;
+        }
+      }
+
+      if (include.props && Object.keys(segment.props).length > 0) {
+        component.props = {};
+        for (const [name, prop] of Object.entries(segment.props)) {
+          component.props[name] = {
+            type: formatPropType(prop),
+            description: prop.description,
+          };
+          if (prop.required) {
+            component.props[name].required = true;
+          }
+          if (prop.default !== undefined) {
+            component.props[name].default = prop.default;
+          }
+        }
+      }
+
+      if (include.variants && segment.variants.length > 0) {
+        component.variants = segment.variants.map((v) => v.name);
+      }
+
+      if (include.relations && segment.relations && segment.relations.length > 0) {
+        component.relations = segment.relations.map((r) => ({
+          component: r.component,
+          relationship: r.relationship,
+          note: r.note,
+        }));
+      }
+    }
+
+    components[segment.meta.name] = component;
+  }
+
+  // Build recipes map
+  const recipesMap = recipes && recipes.length > 0
+    ? Object.fromEntries(recipes.map(r => [r.name, {
+        description: r.description,
+        category: r.category,
+        components: r.components,
+        code: r.code,
+        tags: r.tags,
+      }]))
+    : undefined;
+
+  const output = {
+    version: "1.0",
+    generatedAt: new Date().toISOString(),
+    summary: {
+      totalComponents: segments.length,
+      categories,
+      ...(recipesMap && { totalRecipes: recipes!.length }),
+    },
+    components,
+    ...(recipesMap && { recipes: recipesMap }),
+  };
+
+  const content = JSON.stringify(output, null, 2);
+  return {
+    content,
+    tokenEstimate: estimateTokens(content),
+  };
+}
+
+/**
+ * Format a prop type for display
+ */
+function formatPropType(prop: PropDefinition): string {
+  if (prop.type === "enum" && prop.values) {
+    return prop.values.map((v) => `"${v}"`).join(" | ");
+  }
+  if (prop.default !== undefined) {
+    return `${prop.type} (default: ${JSON.stringify(prop.default)})`;
+  }
+  return prop.type;
+}
+
+/**
+ * Truncate string to max length
+ */
+function truncate(str: string, maxLength: number): string {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - 3) + "...";
+}
+
+/**
+ * Estimate token count (rough approximation: ~4 chars per token)
+ */
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}

package/src/core/defineSegment.ts

@@ -0,0 +1,137 @@
+import type { SegmentDefinition, CompiledSegment, SegmentComponent, RecipeDefinition, CompiledRecipe } from './types.js';
+import { segmentDefinitionSchema, recipeDefinitionSchema } from './schema.js';
+
+/**
+ * Define a segment for a component.
+ *
+ * This is the main API for creating segment documentation.
+ * It provides runtime validation and type safety.
+ *
+ * @example
+ * ```tsx
+ * import { defineSegment } from '@fragments/core';
+ * import { Button } from './Button';
+ *
+ * export default defineSegment({
+ *   component: Button,
+ *   meta: {
+ *     name: 'Button',
+ *     description: 'Primary action trigger',
+ *     category: 'actions',
+ *   },
+ *   usage: {
+ *     when: ['User needs to trigger an action'],
+ *     whenNot: ['Navigation without side effects'],
+ *   },
+ *   props: {
+ *     variant: {
+ *       type: 'enum',
+ *       values: ['primary', 'secondary'],
+ *       default: 'primary',
+ *       description: 'Visual style',
+ *     },
+ *   },
+ *   variants: [
+ *     {
+ *       name: 'Default',
+ *       description: 'Default button',
+ *       render: () => <Button>Click me</Button>,
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export function defineSegment<TProps>(
+  definition: SegmentDefinition<TProps>
+): SegmentDefinition<TProps> {
+  // Validate at runtime in development
+  if (process.env.NODE_ENV !== 'production') {
+    const result = segmentDefinitionSchema.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}`
+      );
+    }
+  }
+
+  return definition;
+}
+
+/**
+ * Alias for defineSegment - use this for new projects.
+ * @see defineSegment
+ */
+export const defineFragment = defineSegment;
+
+/**
+ * Compile a segment definition to JSON-serializable format.
+ * Used for generating fragments.json for AI consumption.
+ */
+export function compileSegment(
+  definition: SegmentDefinition,
+  filePath: string
+): CompiledSegment {
+  return {
+    filePath,
+    meta: definition.meta,
+    usage: definition.usage,
+    props: definition.props,
+    relations: definition.relations,
+    variants: definition.variants.map((v) => ({
+      name: v.name,
+      description: v.description,
+      code: v.code,
+      figma: v.figma,
+    })),
+    contract: definition.contract,
+    _generated: definition._generated,
+  };
+}
+
+/**
+ * Define a composition recipe.
+ *
+ * Recipes are pure data describing how design system components
+ * wire together for common use cases.
+ */
+export function defineRecipe(definition: RecipeDefinition): RecipeDefinition {
+  if (process.env.NODE_ENV !== 'production') {
+    const result = recipeDefinitionSchema.safeParse(definition);
+    if (!result.success) {
+      const errors = result.error.errors
+        .map((e) => `  - ${e.path.join('.')}: ${e.message}`)
+        .join('\n');
+      throw new Error(
+        `Invalid recipe definition for "${definition.name || 'unknown'}":\n${errors}`
+      );
+    }
+  }
+
+  return definition;
+}
+
+/**
+ * Compile a recipe definition to JSON-serializable format.
+ */
+export function compileRecipe(
+  definition: RecipeDefinition,
+  filePath: string
+): CompiledRecipe {
+  return {
+    filePath,
+    name: definition.name,
+    description: definition.description,
+    category: definition.category,
+    components: definition.components,
+    code: definition.code,
+    tags: definition.tags,
+  };
+}
+
+/**
+ * Type helper for extracting props type from a component
+ */
+export type InferProps<T> = T extends SegmentComponent<infer P> ? P : never;