@fragments-sdk/cli 0.2.2

package/src/core/fragment-types.ts

@@ -0,0 +1,214 @@
+/**
+ * TypeScript types for Fragment JSON files.
+ * These types correspond to the JSON schemas in ./schema/
+ */
+
+/**
+ * Figma design links and mappings
+ */
+export interface FragmentFigma {
+  /** Figma file URL */
+  file?: string;
+  /** Default Figma node ID for this component */
+  nodeId?: string;
+  /** Mapping of variant names to Figma node IDs */
+  variants?: Record<string, string>;
+}
+
+/**
+ * Anti-pattern with optional alternative
+ */
+export interface FragmentDoNotItem {
+  /** What not to do */
+  text: string;
+  /** Component name to use instead */
+  instead?: string;
+}
+
+/**
+ * Usage pattern with code example
+ */
+export interface FragmentPattern {
+  /** Pattern name */
+  name: string;
+  /** Code example */
+  code: string;
+  /** When to use this pattern */
+  description?: string;
+}
+
+/**
+ * Usage guidelines for AI agents and developers
+ */
+export interface FragmentUsage {
+  /** Scenarios when this component should be used */
+  when?: string[];
+  /** Anti-patterns and what to use instead */
+  doNot?: (string | FragmentDoNotItem)[];
+  /** Common usage patterns with code examples */
+  patterns?: FragmentPattern[];
+}
+
+/**
+ * Accessibility requirements and guidelines
+ */
+export interface FragmentAccessibility {
+  /** ARIA role this component implements */
+  role?: string;
+  /** Accessibility requirements */
+  requirements?: string[];
+  /** Keyboard interaction patterns (key -> description) */
+  keyboard?: Record<string, string>;
+}
+
+/**
+ * Relationships to other components
+ */
+export interface FragmentRelated {
+  /** Similar components that might be alternatives */
+  similar?: string[];
+  /** Components commonly used together with this one */
+  composedWith?: string[];
+  /** Parent components or patterns where this is commonly used */
+  usedIn?: string[];
+}
+
+/**
+ * Administrative metadata
+ */
+export interface FragmentMeta {
+  /** Team or person responsible for this component */
+  owner?: string;
+  /** Component lifecycle status */
+  status?: "draft" | "experimental" | "beta" | "stable" | "deprecated";
+  /** Version when this component was introduced */
+  since?: string;
+  /** Version when this component was deprecated */
+  deprecatedSince?: string;
+  /** Why this component was deprecated and what to use instead */
+  deprecatedReason?: string;
+  /** Tags for categorization and search */
+  tags?: string[];
+}
+
+/**
+ * Fragment JSON file structure (.fragment.json)
+ * Contains enrichment metadata for a component
+ */
+export interface Fragment {
+  /** JSON Schema reference */
+  $schema?: string;
+  /** Component name (must match the component export name) */
+  name: string;
+  /** Brief description of the component's purpose */
+  description?: string;
+  /** Figma design links and mappings */
+  figma?: FragmentFigma;
+  /** Usage guidelines for AI agents and developers */
+  usage?: FragmentUsage;
+  /** Accessibility requirements and guidelines */
+  accessibility?: FragmentAccessibility;
+  /** Relationships to other components */
+  related?: FragmentRelated;
+  /** Administrative metadata */
+  meta?: FragmentMeta;
+}
+
+/**
+ * Prop entry in the registry
+ */
+export interface RegistryPropEntry {
+  /** TypeScript type (e.g., 'string', 'boolean', enum values) */
+  type?: string;
+  /** Simplified type category */
+  typeKind?: "string" | "number" | "boolean" | "enum" | "object" | "array" | "function" | "node" | "element" | "union" | "unknown";
+  /** For enum types, the allowed values */
+  options?: string[];
+  /** Default value if specified */
+  default?: unknown;
+  /** Whether this prop is required */
+  required?: boolean;
+  /** Prop description from JSDoc or TypeScript */
+  description?: string;
+}
+
+/**
+ * Component entry in the registry (simplified - focuses on paths and enrichment)
+ */
+export interface RegistryComponentEntry {
+  /** Relative path to the component source file */
+  path: string;
+  /** Relative path to the .fragment.json file (if exists) */
+  fragmentPath?: string;
+  /** Relative path to the .stories.tsx file (if exists) */
+  storyPath?: string;
+  /** Component category (inferred from directory or fragment) */
+  category?: string;
+  /** Component lifecycle status (from fragment) */
+  status?: "draft" | "experimental" | "beta" | "stable" | "deprecated";
+  /** Component description (from fragment or JSDoc) */
+  description?: string;
+  /** Has human-authored enrichment (fragment file exists with content beyond skeleton) */
+  hasEnrichment?: boolean;
+  /** Extracted prop definitions - only included if config.registry.includeProps is true */
+  props?: Record<string, RegistryPropEntry>;
+  /** Named exports from the component file */
+  exports?: string[];
+  /** Component dependencies (other components used) */
+  dependencies?: string[];
+  /** Merged fragment enrichment data - only included if config.registry.embedFragments is true */
+  fragment?: Fragment;
+}
+
+/**
+ * Minimal component index (.fragments/index.json)
+ * Ultra-light name → path mapping for quick lookups
+ */
+export interface FragmentIndex {
+  /** Schema version */
+  version: string;
+  /** When this index was generated */
+  generatedAt: string;
+  /** Simple name → path mapping */
+  components: Record<string, string>;
+  /** Categories for grouping */
+  categories?: Record<string, string[]>;
+}
+
+/**
+ * Registry file structure (.fragments/registry.json)
+ * Component index with resolved paths and optional metadata
+ */
+export interface FragmentRegistry {
+  /** JSON Schema reference */
+  $schema?: string;
+  /** Schema version */
+  version: string;
+  /** When this registry was generated */
+  generatedAt: string;
+  /** Component count for quick reference */
+  componentCount: number;
+  /** Component index keyed by component name */
+  components: Record<string, RegistryComponentEntry>;
+  /** Components grouped by category */
+  categories?: Record<string, string[]>;
+}
+
+/**
+ * Context file options for generation
+ */
+export interface FragmentContextOptions {
+  /** Output format */
+  format?: "markdown" | "json";
+  /** Compact mode - minimal output for token efficiency */
+  compact?: boolean;
+  /** What to include in the output */
+  include?: {
+    /** Include prop details (default: true) */
+    props?: boolean;
+    /** Include code examples (default: false) */
+    code?: boolean;
+    /** Include related components (default: true) */
+    relations?: boolean;
+  };
+}

package/src/core/generators/context.ts

@@ -0,0 +1,389 @@
+/**
+ * Context.md Generator
+ * Generates a consolidated AI-ready context file from the fragment registry
+ *
+ * Philosophy: Focus on human-authored semantic knowledge that AI can't get from source.
+ * - Usage guidelines: When to use, when not to use
+ * - Relationships: Similar components, alternatives
+ * - Accessibility: Requirements and keyboard patterns
+ * - DO NOT: Duplicate prop types (AI can read TypeScript directly)
+ */
+
+import type {
+  FragmentRegistry,
+  RegistryComponentEntry,
+  RegistryPropEntry,
+  FragmentDoNotItem,
+  FragmentContextOptions,
+} from "../fragment-types.js";
+
+/**
+ * Result of context generation
+ */
+export interface ContextGeneratorResult {
+  /** Generated markdown content */
+  content: string;
+  /** Estimated token count */
+  tokenEstimate: number;
+  /** Component count */
+  componentCount: number;
+}
+
+/**
+ * Generate context.md from a fragment registry
+ */
+export function generateContextMd(
+  registry: FragmentRegistry,
+  options: FragmentContextOptions = {}
+): ContextGeneratorResult {
+  const {
+    format = "markdown",
+    compact = false,
+    include = { props: true, relations: true, code: false },
+  } = options;
+
+  if (format === "json") {
+    return generateJsonContext(registry, include, compact);
+  }
+
+  return generateMarkdownContext(registry, include, compact);
+}
+
+/**
+ * Generate markdown context
+ */
+function generateMarkdownContext(
+  registry: FragmentRegistry,
+  include: { props?: boolean; relations?: boolean; code?: boolean },
+  compact: boolean
+): ContextGeneratorResult {
+  const lines: string[] = [];
+  const componentNames = Object.keys(registry.components).sort();
+  const componentCount = componentNames.length;
+
+  // Header
+  lines.push("# Component Library Context");
+  lines.push(`Generated: ${new Date().toISOString().split("T")[0]} | Components: ${componentCount}`);
+  lines.push("");
+
+  // Quick reference table
+  lines.push("## Quick Reference");
+  lines.push("");
+  lines.push("| Component | Path | Category | Status |");
+  lines.push("|-----------|------|----------|--------|");
+
+  for (const name of componentNames) {
+    const entry = registry.components[name];
+    const status = entry.status || "stable";
+    const category = entry.category || "-";
+    lines.push(`| ${name} | ${entry.path} | ${category} | ${status} |`);
+  }
+
+  lines.push("");
+
+  // In compact mode, stop here
+  if (compact) {
+    const content = lines.join("\n");
+    return {
+      content,
+      tokenEstimate: estimateTokens(content),
+      componentCount,
+    };
+  }
+
+  // Full documentation for each component
+  lines.push("---");
+  lines.push("");
+
+  for (const name of componentNames) {
+    const entry = registry.components[name];
+    const fragment = entry.fragment;
+
+    lines.push(`## ${name}`);
+    lines.push(`**Path:** \`${entry.path}\``);
+
+    if (entry.category) {
+      lines.push(`**Category:** ${entry.category} | **Status:** ${entry.status || "stable"}`);
+    }
+    lines.push("");
+
+    // Description
+    if (entry.description || fragment?.description) {
+      lines.push("### Description");
+      lines.push(entry.description || fragment?.description || "");
+      lines.push("");
+    }
+
+    // Usage guidelines
+    if (fragment?.usage) {
+      if (fragment.usage.when && fragment.usage.when.length > 0) {
+        lines.push("### When to Use");
+        for (const when of fragment.usage.when) {
+          lines.push(`- ${when}`);
+        }
+        lines.push("");
+      }
+
+      if (fragment.usage.doNot && fragment.usage.doNot.length > 0) {
+        lines.push("### Do Not");
+        for (const doNotItem of fragment.usage.doNot) {
+          if (typeof doNotItem === "string") {
+            lines.push(`- ${doNotItem}`);
+          } else {
+            const item = doNotItem as FragmentDoNotItem;
+            if (item.instead) {
+              // Resolve component path
+              const alternativePath = resolveComponentPath(item.instead, registry);
+              if (alternativePath) {
+                lines.push(`- ${item.text} → use **${item.instead}** (\`${alternativePath}\`)`);
+              } else {
+                lines.push(`- ${item.text} → use **${item.instead}**`);
+              }
+            } else {
+              lines.push(`- ${item.text}`);
+            }
+          }
+        }
+        lines.push("");
+      }
+
+      if (include.code && fragment.usage.patterns && fragment.usage.patterns.length > 0) {
+        lines.push("### Patterns");
+        for (const pattern of fragment.usage.patterns) {
+          lines.push(`**${pattern.name}**`);
+          if (pattern.description) {
+            lines.push(pattern.description);
+          }
+          lines.push("```tsx");
+          lines.push(pattern.code);
+          lines.push("```");
+          lines.push("");
+        }
+      }
+    }
+
+    // Props
+    if (include.props && entry.props && Object.keys(entry.props).length > 0) {
+      lines.push("### Props");
+      lines.push("| Prop | Type | Default | Description |");
+      lines.push("|------|------|---------|-------------|");
+
+      for (const [propName, prop] of Object.entries(entry.props)) {
+        const type = formatPropType(prop);
+        const defaultVal = prop.default !== undefined ? `\`${JSON.stringify(prop.default)}\`` : "-";
+        const desc = prop.description || "-";
+        const required = prop.required ? " (required)" : "";
+        lines.push(`| ${propName}${required} | ${type} | ${defaultVal} | ${desc} |`);
+      }
+      lines.push("");
+    }
+
+    // Accessibility
+    if (fragment?.accessibility) {
+      lines.push("### Accessibility");
+      if (fragment.accessibility.role) {
+        lines.push(`**Role:** ${fragment.accessibility.role}`);
+      }
+      if (fragment.accessibility.requirements && fragment.accessibility.requirements.length > 0) {
+        for (const req of fragment.accessibility.requirements) {
+          lines.push(`- ${req}`);
+        }
+      }
+      if (fragment.accessibility.keyboard) {
+        lines.push("");
+        lines.push("**Keyboard:**");
+        for (const [key, action] of Object.entries(fragment.accessibility.keyboard)) {
+          lines.push(`- \`${key}\`: ${action}`);
+        }
+      }
+      lines.push("");
+    }
+
+    // Related components
+    if (include.relations && fragment?.related) {
+      lines.push("### Related");
+      if (fragment.related.similar && fragment.related.similar.length > 0) {
+        const resolved = fragment.related.similar.map((comp) => {
+          const path = resolveComponentPath(comp, registry);
+          return path ? `${comp} (\`${path}\`)` : comp;
+        });
+        lines.push(`- **Similar:** ${resolved.join(", ")}`);
+      }
+      if (fragment.related.composedWith && fragment.related.composedWith.length > 0) {
+        const resolved = fragment.related.composedWith.map((comp) => {
+          const path = resolveComponentPath(comp, registry);
+          return path ? `${comp} (\`${path}\`)` : comp;
+        });
+        lines.push(`- **Composed with:** ${resolved.join(", ")}`);
+      }
+      if (fragment.related.usedIn && fragment.related.usedIn.length > 0) {
+        const resolved = fragment.related.usedIn.map((comp) => {
+          const path = resolveComponentPath(comp, registry);
+          return path ? `${comp} (\`${path}\`)` : comp;
+        });
+        lines.push(`- **Used in:** ${resolved.join(", ")}`);
+      }
+      lines.push("");
+    }
+
+    lines.push("---");
+    lines.push("");
+  }
+
+  const content = lines.join("\n");
+  return {
+    content,
+    tokenEstimate: estimateTokens(content),
+    componentCount,
+  };
+}
+
+/**
+ * Generate JSON context
+ */
+function generateJsonContext(
+  registry: FragmentRegistry,
+  include: { props?: boolean; relations?: boolean; code?: boolean },
+  compact: boolean
+): ContextGeneratorResult {
+  const componentNames = Object.keys(registry.components).sort();
+  const componentCount = componentNames.length;
+
+  interface JsonComponent {
+    path: string;
+    category?: string;
+    status?: string;
+    description?: string;
+    whenToUse?: string[];
+    doNot?: Array<{ text: string; instead?: string; insteadPath?: string }>;
+    props?: Record<string, {
+      type: string;
+      required?: boolean;
+      default?: unknown;
+      description?: string;
+    }>;
+    related?: {
+      similar?: Array<{ name: string; path?: string }>;
+      composedWith?: Array<{ name: string; path?: string }>;
+      usedIn?: Array<{ name: string; path?: string }>;
+    };
+  }
+
+  const components: Record<string, JsonComponent> = {};
+
+  for (const name of componentNames) {
+    const entry = registry.components[name];
+    const fragment = entry.fragment;
+
+    const component: JsonComponent = {
+      path: entry.path,
+    };
+
+    if (entry.category) component.category = entry.category;
+    if (entry.status) component.status = entry.status;
+    if (entry.description || fragment?.description) {
+      component.description = entry.description || fragment?.description;
+    }
+
+    if (!compact && fragment?.usage) {
+      if (fragment.usage.when && fragment.usage.when.length > 0) {
+        component.whenToUse = fragment.usage.when;
+      }
+
+      if (fragment.usage.doNot && fragment.usage.doNot.length > 0) {
+        component.doNot = fragment.usage.doNot.map((item) => {
+          if (typeof item === "string") {
+            return { text: item };
+          }
+          const doNotItem = item as FragmentDoNotItem;
+          const result: { text: string; instead?: string; insteadPath?: string } = {
+            text: doNotItem.text,
+          };
+          if (doNotItem.instead) {
+            result.instead = doNotItem.instead;
+            result.insteadPath = resolveComponentPath(doNotItem.instead, registry);
+          }
+          return result;
+        });
+      }
+    }
+
+    if (!compact && include.props && entry.props) {
+      component.props = {};
+      for (const [propName, prop] of Object.entries(entry.props)) {
+        component.props[propName] = {
+          type: formatPropType(prop),
+        };
+        if (prop.required) component.props[propName].required = true;
+        if (prop.default !== undefined) component.props[propName].default = prop.default;
+        if (prop.description) component.props[propName].description = prop.description;
+      }
+    }
+
+    if (!compact && include.relations && fragment?.related) {
+      component.related = {};
+      if (fragment.related.similar) {
+        component.related.similar = fragment.related.similar.map((name) => ({
+          name,
+          path: resolveComponentPath(name, registry),
+        }));
+      }
+      if (fragment.related.composedWith) {
+        component.related.composedWith = fragment.related.composedWith.map((name) => ({
+          name,
+          path: resolveComponentPath(name, registry),
+        }));
+      }
+      if (fragment.related.usedIn) {
+        component.related.usedIn = fragment.related.usedIn.map((name) => ({
+          name,
+          path: resolveComponentPath(name, registry),
+        }));
+      }
+    }
+
+    components[name] = component;
+  }
+
+  const output = {
+    version: "1.0",
+    generatedAt: registry.generatedAt,
+    componentCount,
+    categories: registry.categories,
+    components,
+  };
+
+  const content = JSON.stringify(output, null, 2);
+  return {
+    content,
+    tokenEstimate: estimateTokens(content),
+    componentCount,
+  };
+}
+
+/**
+ * Resolve component name to path
+ */
+function resolveComponentPath(
+  componentName: string,
+  registry: FragmentRegistry
+): string | undefined {
+  return registry.components[componentName]?.path;
+}
+
+/**
+ * Format prop type for display
+ */
+function formatPropType(prop: RegistryPropEntry): string {
+  if (prop.options && prop.options.length > 0) {
+    return prop.options.map((o) => `"${o}"`).join(" \\| ");
+  }
+  return prop.type || "unknown";
+}
+
+/**
+ * Estimate token count (rough: ~4 chars per token)
+ */
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}

package/src/core/generators/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Generator utilities for Fragments
+ * These are Node.js-only APIs for generating registry and context files
+ */
+
+export {
+  extractPropsFromFile,
+  extractPropsFromSource,
+  type ExtractedProps,
+} from "./typescript-extractor.js";
+
+export {
+  generateRegistry,
+  resolveComponentPath,
+  getComponentsByCategory,
+  type RegistryGeneratorOptions,
+  type RegistryGeneratorResult,
+} from "./registry.js";
+
+export {
+  generateContextMd,
+  type ContextGeneratorResult,
+} from "./context.js";