@fragments-sdk/cli 0.14.3 → 0.15.0

package/src/core/extractor-adapter.ts

@@ -0,0 +1,80 @@
+/**
+ * Extractor Adapter — framework-aware prop extraction interface.
+ *
+ * V1 ships a React/TS adapter wrapping the existing createComponentExtractor().
+ * Non-React frameworks return a no-op adapter with verificationLevel: 'none'.
+ */
+
+import { createComponentExtractor, type ComponentExtractor, type ComponentMeta } from './component-extractor.js';
+
+export interface ExtractorAdapter {
+  /** Whether this adapter can handle the given framework */
+  canHandle(framework: string): boolean;
+
+  /** Extract component metadata from source */
+  extract(sourcePath: string, exportName: string): ComponentMeta | null;
+
+  /** Clean up resources */
+  dispose(): void;
+
+  /** How thoroughly this adapter can verify contracts */
+  readonly verificationLevel: 'full' | 'partial' | 'none';
+}
+
+/**
+ * React/TypeScript extractor adapter.
+ * Wraps the existing LanguageService-based component extractor.
+ */
+class ReactExtractorAdapter implements ExtractorAdapter {
+  private extractor: ComponentExtractor;
+  readonly verificationLevel = 'full' as const;
+
+  constructor(tsconfigPath?: string) {
+    this.extractor = createComponentExtractor(tsconfigPath);
+  }
+
+  canHandle(framework: string): boolean {
+    return framework === 'react';
+  }
+
+  extract(sourcePath: string, exportName: string): ComponentMeta | null {
+    return this.extractor.extract(sourcePath, exportName);
+  }
+
+  dispose(): void {
+    this.extractor.dispose();
+  }
+}
+
+/**
+ * No-op adapter for unsupported frameworks.
+ * Returns null for all extractions, allowing build to proceed with manual props.
+ */
+class NoopExtractorAdapter implements ExtractorAdapter {
+  readonly verificationLevel = 'none' as const;
+
+  canHandle(): boolean {
+    return true;
+  }
+
+  extract(): ComponentMeta | null {
+    return null;
+  }
+
+  dispose(): void {
+    // Nothing to clean up
+  }
+}
+
+/**
+ * Create an extractor adapter for the given framework.
+ */
+export function createExtractorAdapter(
+  framework: string,
+  tsconfigPath?: string,
+): ExtractorAdapter {
+  if (framework === 'react') {
+    return new ReactExtractorAdapter(tsconfigPath);
+  }
+  return new NoopExtractorAdapter();
+}

package/src/mcp/__tests__/projectFields.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { projectFields } from "../utils.js";
+import { projectFields } from "../../shared/project-fields.js";
 
 describe("projectFields", () => {
   describe("basic field extraction", () => {

package/src/mcp/utils.ts

@@ -2,53 +2,4 @@
  * Utility functions for the MCP server
  */
 
-/**
- * Extract specific fields from an object using dot notation paths.
- * E.g., projectFields(obj, ['meta.name', 'usage.when']) returns { meta: { name: ... }, usage: { when: ... } }
- *
- * @param obj - The source object to extract fields from
- * @param fields - Array of field paths (supports dot notation for nested fields)
- * @returns A new object containing only the requested fields
- */
-export function projectFields<T extends Record<string, unknown>>(
-  obj: T,
-  fields: string[]
-): Partial<T> {
-  if (!fields || fields.length === 0) {
-    return obj;
-  }
-
-  const result: Record<string, unknown> = {};
-
-  for (const field of fields) {
-    const parts = field.split('.');
-    let source: unknown = obj;
-    let target = result;
-
-    for (let i = 0; i < parts.length; i++) {
-      const part = parts[i];
-      const isLast = i === parts.length - 1;
-
-      if (source === null || source === undefined || typeof source !== 'object') {
-        break;
-      }
-
-      const sourceObj = source as Record<string, unknown>;
-      const value = sourceObj[part];
-
-      if (isLast) {
-        // Set the final value
-        target[part] = value;
-      } else {
-        // Create nested object if needed
-        if (!(part in target)) {
-          target[part] = {};
-        }
-        target = target[part] as Record<string, unknown>;
-        source = value;
-      }
-    }
-  }
-
-  return result as Partial<T>;
-}
+export { projectFields } from '../shared/project-fields.js';

package/src/migrate/converter.ts

@@ -39,7 +39,7 @@ export function convertToFragment(parsed: ParsedStoryFile): ConversionResult {
 
     // Determine output file path for the error result
     const outputFile = parsed.filePath
-      .replace(/\.stories\.(tsx?|jsx?|mdx)$/, ".fragment.tsx");
+      .replace(/\.stories\.(tsx?|jsx?|mdx)$/, ".contract.json");
 
     return {
       sourceFile: parsed.filePath,
@@ -103,9 +103,9 @@ export function convertToFragment(parsed: ParsedStoryFile): ConversionResult {
     },
   });
 
-  // Determine output file path
+  // Determine output file path — prefer .contract.json over legacy .fragment.tsx
   const outputFile = parsed.filePath
-    .replace(/\.stories\.(tsx?|jsx?|mdx)$/, ".fragment.tsx");
+    .replace(/\.stories\.(tsx?|jsx?|mdx)$/, ".contract.json");
 
   return {
     sourceFile: parsed.filePath,

package/src/migrate/fragment-to-contract.ts

@@ -0,0 +1,253 @@
+/**
+ * Fragment-to-Contract Migration
+ *
+ * Converts .fragment.tsx files to .contract.json files.
+ * The contract.json format is framework-agnostic, token-efficient,
+ * and agent-first — the canonical V2 authoring format.
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve, dirname, relative, basename } from 'node:path';
+import { parseFragmentFile } from '../core/parser.js';
+import { createComponentExtractor, type ComponentMeta } from '../core/component-extractor.js';
+import { resolveComponentSourcePath } from '../core/auto-props.js';
+import type { ComponentContract } from '@fragments-sdk/core';
+
+export interface MigrateOptions {
+  dryRun?: boolean;
+  tsconfigPath?: string;
+}
+
+export interface MigrateResult {
+  contractPath: string;
+  contract: ComponentContract;
+  warnings: string[];
+}
+
+/**
+ * Compile a propsSummary array from extracted props.
+ * Format: "variant: primary|secondary (required)"
+ */
+function compilePropsSummaryFromExtracted(
+  props: Record<string, { typeKind: string; values?: string[]; default?: string; required: boolean; source: string }>
+): string[] {
+  return Object.entries(props)
+    .filter(([, p]) => p.source === 'local')
+    .map(([name, prop]) => {
+      let summary = name + ': ';
+      if (prop.values && prop.values.length > 0) {
+        summary += prop.values.join('|');
+      } else {
+        summary += prop.typeKind;
+      }
+      if (prop.default !== undefined) {
+        summary += ` (default: ${prop.default})`;
+      }
+      if (prop.required) {
+        summary += ' (required)';
+      }
+      return summary;
+    });
+}
+
+/**
+ * Compile a propsSummary from documented props (fallback when extraction fails).
+ */
+function compilePropsSummaryFromDocs(
+  props: Record<string, { type?: string; values?: readonly string[]; default?: unknown; required?: boolean }>
+): string[] {
+  return Object.entries(props).map(([name, prop]) => {
+    let summary = name + ': ';
+    if (prop.values && prop.values.length > 0) {
+      summary += [...prop.values].join('|');
+    } else {
+      summary += prop.type ?? 'custom';
+    }
+    if (prop.default !== undefined) {
+      summary += ` (default: ${String(prop.default)})`;
+    }
+    if (prop.required) {
+      summary += ' (required)';
+    }
+    return summary;
+  });
+}
+
+/**
+ * Migrate a .fragment.tsx file to .contract.json.
+ */
+export async function migrateFragmentToContract(
+  fragmentPath: string,
+  configDir: string,
+  options?: MigrateOptions,
+): Promise<MigrateResult> {
+  const warnings: string[] = [];
+  const absFragmentPath = resolve(fragmentPath);
+
+  // 1. Read and parse the .fragment.tsx file
+  const content = await readFile(absFragmentPath, 'utf-8');
+  const parsed = parseFragmentFile(content, fragmentPath);
+  warnings.push(...parsed.warnings);
+
+  if (!parsed.meta.name) {
+    throw new Error(`Fragment file ${fragmentPath} has no meta.name`);
+  }
+
+  // 2. Try to extract live props from component source
+  let extractedMeta: ComponentMeta | null = null;
+  const extractor = createComponentExtractor(options?.tsconfigPath);
+
+  try {
+    const componentExportName = parsed.componentName ?? parsed.meta.name;
+    const componentSourcePath = resolveComponentSourcePath(
+      absFragmentPath,
+      parsed.componentImport,
+    );
+
+    if (componentExportName && componentSourcePath) {
+      try {
+        extractedMeta = extractor.extract(componentSourcePath, componentExportName);
+      } catch {
+        warnings.push('Auto-props extraction failed; falling back to documented props');
+      }
+    }
+  } finally {
+    extractor.dispose();
+  }
+
+  // 3. Resolve sourcePath relative to config root
+  let sourcePath: string;
+  if (parsed.componentImport) {
+    const absSource = resolveComponentSourcePath(absFragmentPath, parsed.componentImport);
+    if (absSource) {
+      sourcePath = relative(configDir, absSource);
+    } else {
+      sourcePath = parsed.componentImport;
+      warnings.push(`Could not resolve component source path: ${parsed.componentImport}`);
+    }
+  } else {
+    // Fallback: assume component is adjacent
+    const fragDir = dirname(absFragmentPath);
+    sourcePath = relative(configDir, resolve(fragDir, 'index.tsx'));
+    warnings.push('No component import found; assuming ./index.tsx');
+  }
+
+  const exportName = parsed.componentName ?? parsed.meta.name;
+
+  // 4. Compile propsSummary
+  let propsSummary: string[];
+  if (extractedMeta) {
+    propsSummary = compilePropsSummaryFromExtracted(extractedMeta.props);
+  } else {
+    propsSummary = compilePropsSummaryFromDocs(parsed.props);
+  }
+
+  // 5. Merge props
+  let mergedProps: Record<string, {
+    type: string;
+    description: string;
+    default?: unknown;
+    required?: boolean;
+    values?: string[];
+    constraints?: string[];
+  }>;
+
+  if (extractedMeta && Object.keys(extractedMeta.props).length > 0) {
+    mergedProps = {};
+    for (const [name, auto] of Object.entries(extractedMeta.props)) {
+      if (auto.source !== 'local' && !(name in parsed.props)) continue;
+      const documented = parsed.props[name];
+      mergedProps[name] = {
+        type: auto.typeKind,
+        description: documented?.description ?? auto.description ?? '',
+        default: auto.default !== undefined ? auto.default : documented?.default,
+        required: auto.required,
+        values: auto.values ?? (documented?.values ? [...documented.values] : undefined),
+        constraints: documented?.constraints ? [...documented.constraints] : undefined,
+      };
+    }
+  } else {
+    mergedProps = {};
+    for (const [name, prop] of Object.entries(parsed.props)) {
+      mergedProps[name] = {
+        type: prop.type ?? 'custom',
+        description: prop.description ?? '',
+        default: prop.default,
+        required: prop.required,
+        values: prop.values ? [...prop.values] : undefined,
+        constraints: prop.constraints ? [...prop.constraints] : undefined,
+      };
+    }
+  }
+
+  // 6. Determine verification status
+  const verified = false; // Default to false; only true after full extraction + clean drift pass
+
+  // 7. Build AI metadata
+  let ai: ComponentContract['ai'] | undefined;
+  if (parsed.ai) {
+    ai = { ...parsed.ai };
+  }
+  if (extractedMeta?.composition) {
+    const comp = extractedMeta.composition;
+    ai = {
+      compositionPattern: comp.pattern,
+      subComponents: comp.parts.map((p) => p.name),
+      ...ai,
+    };
+  }
+
+  // 8. Assemble the contract
+  const contract: ComponentContract = {
+    $schema: 'https://usefragments.com/schemas/contract.v1.json',
+    name: parsed.meta.name,
+    description: parsed.meta.description ?? `${parsed.meta.name} component`,
+    category: parsed.meta.category ?? 'Uncategorized',
+    ...(parsed.meta.tags && { tags: parsed.meta.tags }),
+    ...(parsed.meta.status && { status: parsed.meta.status }),
+    sourcePath,
+    exportName,
+    propsSummary,
+    props: mergedProps,
+    usage: {
+      when: parsed.usage.when ?? [],
+      whenNot: parsed.usage.whenNot ?? [],
+      ...(parsed.usage.guidelines && { guidelines: parsed.usage.guidelines }),
+      ...(parsed.usage.accessibility && { accessibility: parsed.usage.accessibility }),
+    },
+    ...(parsed.variants.length > 0 && {
+      examples: parsed.variants.map((v) => ({
+        name: v.name,
+        description: v.description,
+        code: v.code ?? '',
+        ...(v.args && { args: v.args }),
+      })),
+    }),
+    ...(parsed.relations.length > 0 && {
+      relations: parsed.relations.map((r) => ({
+        component: r.component,
+        relationship: r.relationship as 'alternative' | 'parent' | 'child' | 'sibling',
+        note: r.note,
+      })),
+    }),
+    ...(parsed.contract && { contract: parsed.contract }),
+    ...(ai && { ai }),
+    provenance: {
+      source: 'migrated',
+      verified,
+      frameworkSupport: 'native',
+      extractedAt: new Date().toISOString(),
+    },
+  };
+
+  // 9. Determine output path
+  const contractPath = absFragmentPath
+    .replace(/\.fragment\.tsx?$/, '.contract.json');
+
+  // 10. Write output (unless dry run)
+  if (!options?.dryRun) {
+    await writeFile(contractPath, JSON.stringify(contract, null, 2) + '\n');
+  }
+
+  return { contractPath, contract, warnings };
+}

package/src/migrate/report.ts

@@ -618,7 +618,7 @@ function renderFooter(): string {
   return `
     <footer class="footer">
       <p>Generated by <a href="#">${BRAND.name}</a> Migration Tool</p>
-      <p style="margin-top: 8px">Run <code>fragments dev</code> to view your new design system documentation</p>
+      <p style="margin-top: 8px">Run <code>fragments build</code> to compile your design system documentation</p>
     </footer>
   `;
 }

package/src/scripts/token-benchmark.ts

@@ -0,0 +1,121 @@
+#!/usr/bin/env tsx
+/**
+ * Token Budget Benchmark
+ *
+ * Compares token counts between .fragment.tsx and .contract.json corpora.
+ * Run: pnpm --filter @fragments-sdk/cli tsx src/scripts/token-benchmark.ts
+ *
+ * Uses character-based estimation (4 chars ≈ 1 token) as a stable proxy.
+ * The compact payload size gets a threshold assertion for regression guarding.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { glob } from 'glob';
+import { resolve } from 'node:path';
+
+interface CorpusStats {
+  fileCount: number;
+  totalChars: number;
+  estimatedTokens: number;
+  avgTokensPerFile: number;
+}
+
+function estimateTokens(text: string): number {
+  // GPT/Claude tokenizer approximation: ~4 chars per token for code/JSON
+  return Math.ceil(text.length / 4);
+}
+
+async function measureCorpus(pattern: string, cwd: string): Promise<CorpusStats> {
+  const files = await glob(pattern, { cwd, absolute: true });
+  let totalChars = 0;
+
+  for (const file of files) {
+    const content = await readFile(file, 'utf-8');
+    totalChars += content.length;
+  }
+
+  const estimatedTokens = estimateTokens(' '.repeat(totalChars));
+  return {
+    fileCount: files.length,
+    totalChars,
+    estimatedTokens,
+    avgTokensPerFile: files.length > 0 ? Math.round(estimatedTokens / files.length) : 0,
+  };
+}
+
+async function measureCompactPayload(pattern: string, cwd: string): Promise<CorpusStats> {
+  const files = await glob(pattern, { cwd, absolute: true });
+  let totalChars = 0;
+
+  for (const file of files) {
+    try {
+      const content = await readFile(file, 'utf-8');
+      const contract = JSON.parse(content);
+      // Compact payload = name + category + propsSummary only
+      const compact = JSON.stringify({
+        name: contract.name,
+        category: contract.category,
+        propsSummary: contract.propsSummary ?? [],
+      });
+      totalChars += compact.length;
+    } catch {
+      // Skip non-JSON or malformed files
+    }
+  }
+
+  const estimatedTokens = estimateTokens(' '.repeat(totalChars));
+  return {
+    fileCount: files.length,
+    totalChars,
+    estimatedTokens,
+    avgTokensPerFile: files.length > 0 ? Math.round(estimatedTokens / files.length) : 0,
+  };
+}
+
+function formatRow(label: string, stats: CorpusStats): string {
+  return `| ${label.padEnd(25)} | ${String(stats.fileCount).padStart(5)} | ${String(stats.totalChars).padStart(10)} | ${String(stats.estimatedTokens).padStart(10)} | ${String(stats.avgTokensPerFile).padStart(10)} |`;
+}
+
+async function main() {
+  // Default to the UI lib where the components live
+  const projectRoot = resolve(process.cwd(), '..', '..');
+  const uiDir = resolve(projectRoot, 'libs', 'ui');
+
+  console.log('# Token Budget Benchmark Report\n');
+  console.log(`Date: ${new Date().toISOString()}`);
+  console.log(`Project root: ${projectRoot}\n`);
+
+  const tsxCorpus = await measureCorpus('src/**/*.fragment.tsx', uiDir);
+  const jsonCorpus = await measureCorpus('src/**/*.contract.json', uiDir);
+  const compactPayload = await measureCompactPayload('src/**/*.contract.json', uiDir);
+
+  console.log('| Corpus                    | Files |     Chars  |    Tokens  |   Avg/File |');
+  console.log('|---------------------------|------:|-----------:|-----------:|-----------:|');
+  console.log(formatRow('.fragment.tsx', tsxCorpus));
+  console.log(formatRow('.contract.json', jsonCorpus));
+  console.log(formatRow('Compact (propsSummary)', compactPayload));
+
+  // Calculate savings
+  if (tsxCorpus.estimatedTokens > 0 && jsonCorpus.estimatedTokens > 0) {
+    const savings = ((1 - jsonCorpus.estimatedTokens / tsxCorpus.estimatedTokens) * 100).toFixed(1);
+    console.log(`\n## Token Savings: ${savings}% (JSON vs TSX)\n`);
+  }
+
+  if (jsonCorpus.estimatedTokens > 0 && compactPayload.estimatedTokens > 0) {
+    const compactRatio = ((compactPayload.estimatedTokens / jsonCorpus.estimatedTokens) * 100).toFixed(1);
+    console.log(`## Compact Payload: ${compactRatio}% of full JSON\n`);
+  }
+
+  // Regression guard: compact payload should average < 50 tokens per component
+  if (compactPayload.fileCount > 0 && compactPayload.avgTokensPerFile > 50) {
+    console.error('WARN: Compact payload exceeds 50 tokens/component average');
+    process.exit(1);
+  }
+
+  console.log('Benchmark complete.');
+}
+
+main().catch((err) => {
+  console.error('Benchmark failed:', err);
+  process.exit(1);
+});

package/src/service/__tests__/props-extractor.test.ts

@@ -274,6 +274,79 @@ export function Component(props: MyCustomProps) {
     expect(result.props).toHaveLength(1);
     expect(result.propsTypeName).toBe("MyCustomProps");
   });
+
+  it("should extract shadcn-style inline props and cva variants", () => {
+    const source = `
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Slot } from "radix-ui";
+
+const buttonVariants = cva("", {
+  variants: {
+    variant: {
+      default: "",
+      outline: "",
+      secondary: "",
+      ghost: "",
+    },
+    size: {
+      default: "",
+      sm: "",
+      lg: "",
+      icon: "",
+    },
+  },
+});
+
+export function Button({
+  className,
+  variant = "default",
+  size = "default",
+  asChild = false,
+  ...props
+}: React.ComponentProps<"button"> &
+  VariantProps<typeof buttonVariants> & {
+    asChild?: boolean
+  }) {
+  const Comp = asChild ? Slot.Root : "button";
+  return <Comp data-variant={variant} data-size={size} className={className} {...props} />;
+}
+`;
+
+    const result = extractPropsFromSource(source, "Button.tsx");
+
+    expect(result.success).toBe(true);
+
+    const variantProp = result.props.find((p) => p.name === "variant");
+    const sizeProp = result.props.find((p) => p.name === "size");
+    const asChildProp = result.props.find((p) => p.name === "asChild");
+
+    expect(variantProp?.enumValues).toEqual(["default", "outline", "secondary", "ghost"]);
+    expect(sizeProp?.enumValues).toEqual(["default", "sm", "lg", "icon"]);
+    expect(asChildProp?.propType.type).toBe("boolean");
+    expect(asChildProp?.defaultValue).toBe(false);
+  });
+
+  it("should infer PascalCase component names from lowercase shadcn file names", () => {
+    const source = `
+import * as React from "react";
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return <input className={className} type={type} {...props} />;
+}
+
+export { Input };
+`;
+
+    const result = extractPropsFromSource(source, "input.tsx");
+
+    expect(result.success).toBe(true);
+    expect(result.componentName).toBe("Input");
+
+    const typeProp = result.props.find((p) => p.name === "type");
+    expect(typeProp?.propType.type).toBe("string");
+    expect(typeProp?.required).toBe(true);
+  });
 });
 
 describe("extractPropsFromFile", () => {
@@ -329,6 +402,27 @@ export function MyComponent(props: MyComponentProps) {
 
     expect(result.componentName).toBe("MyComponent");
   });
+
+  it("should extract inline props from lowercase shadcn-style file names", async () => {
+    const filePath = await writeTestFile(
+      "input.tsx",
+      `
+import * as React from "react";
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return <input className={className} type={type} {...props} />;
+}
+
+export { Input };
+`
+    );
+
+    const result = await extractPropsFromFile(filePath);
+
+    expect(result.success).toBe(true);
+    expect(result.componentName).toBe("Input");
+    expect(result.props.some((prop) => prop.name === "type")).toBe(true);
+  });
 });
 
 describe("convertToFragmentProps", () => {