@fragments-sdk/cli 0.14.2 → 0.15.0

package/src/core/__tests__/contract-parity.test.ts

@@ -0,0 +1,316 @@
+/**
+ * Contract Parity Tests
+ *
+ * Verifies that building from .contract.json produces structurally identical
+ * CompiledFragment output to building from .fragment.tsx (via the parser).
+ *
+ * These are "golden" tests — if both paths produce the same CompiledFragment,
+ * the migration from TSX to JSON is lossless.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseComponentContract } from '@fragments-sdk/core';
+
+// ---------------------------------------------------------------------------
+// Fixture: Button contract (simple component)
+// ---------------------------------------------------------------------------
+
+const buttonContract = JSON.stringify({
+  $schema: 'https://usefragments.com/schemas/contract.v1.json',
+  name: 'Button',
+  description: 'A clickable button component',
+  category: 'actions',
+  tags: ['interactive', 'form'],
+  status: 'stable',
+  sourcePath: 'src/components/Button/index.tsx',
+  exportName: 'Button',
+  propsSummary: [
+    'variant: primary|secondary|ghost (default: primary)',
+    'size: sm|md|lg (default: md)',
+    'disabled: boolean (default: false)',
+  ],
+  props: {
+    variant: {
+      type: 'enum',
+      values: ['primary', 'secondary', 'ghost'],
+      default: 'primary',
+      description: 'Visual style variant',
+    },
+    size: {
+      type: 'enum',
+      values: ['sm', 'md', 'lg'],
+      default: 'md',
+      description: 'Button size',
+    },
+    disabled: {
+      type: 'boolean',
+      default: false,
+      description: 'Whether the button is disabled',
+    },
+  },
+  usage: {
+    when: ['User needs to trigger an action', 'Form submissions'],
+    whenNot: ['Navigation — use Link instead'],
+    guidelines: ['Always provide visible text or aria-label'],
+    accessibility: ['Must have accessible name via text content or aria-label'],
+  },
+  examples: [
+    {
+      name: 'Primary',
+      description: 'Default primary button',
+      code: '<Button variant="primary">Click me</Button>',
+    },
+    {
+      name: 'Disabled',
+      description: 'Disabled state',
+      code: '<Button disabled>Cannot click</Button>',
+      args: { disabled: true },
+    },
+  ],
+  relations: [
+    { component: 'Link', relationship: 'alternative', note: 'Use Link for navigation' },
+    { component: 'IconButton', relationship: 'sibling', note: 'Icon-only variant' },
+  ],
+  contract: {
+    scenarioTags: ['form.submit', 'action.primary'],
+    a11yRules: ['A11Y_BTN_LABEL'],
+    bans: [{ pattern: '<Button onClick> without type', message: 'Always specify type="button" or type="submit"' }],
+  },
+  provenance: {
+    source: 'migrated',
+    verified: false,
+    frameworkSupport: 'native',
+    extractedAt: '2026-03-13T00:00:00Z',
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Fixture: Card contract (compound component)
+// ---------------------------------------------------------------------------
+
+const cardContract = JSON.stringify({
+  $schema: 'https://usefragments.com/schemas/contract.v1.json',
+  name: 'Card',
+  description: 'A container with header, body, and footer slots',
+  category: 'layout',
+  tags: ['container', 'surface'],
+  status: 'stable',
+  sourcePath: 'src/components/Card/index.tsx',
+  exportName: 'Card',
+  propsSummary: [
+    'variant: elevated|outlined|flat (default: elevated)',
+    'padding: boolean (default: true)',
+  ],
+  props: {
+    variant: {
+      type: 'enum',
+      values: ['elevated', 'outlined', 'flat'],
+      default: 'elevated',
+      description: 'Card visual style',
+    },
+    padding: {
+      type: 'boolean',
+      default: true,
+      description: 'Whether card has internal padding',
+    },
+  },
+  usage: {
+    when: ['Grouping related content with a visual boundary'],
+    whenNot: ['Simple text blocks without visual separation'],
+  },
+  examples: [
+    {
+      name: 'With header and body',
+      description: 'Common card layout',
+      code: '<Card><Card.Header>Title</Card.Header><Card.Body>Content</Card.Body></Card>',
+    },
+  ],
+  ai: {
+    compositionPattern: 'compound',
+    subComponents: ['Header', 'Body', 'Footer'],
+    requiredChildren: ['Body'],
+    commonPatterns: ['<Card><Card.Header /><Card.Body /></Card>'],
+  },
+  contract: {
+    compoundChildren: {
+      Header: { required: false, description: 'Card title area' },
+      Body: { required: true, description: 'Main card content' },
+      Footer: { required: false, accepts: ['Button'], description: 'Card action area' },
+    },
+    canonicalUsage: [
+      '<Card variant="elevated"><Card.Header>Title</Card.Header><Card.Body>Content</Card.Body></Card>',
+    ],
+  },
+  provenance: {
+    source: 'migrated',
+    verified: false,
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Fixture: Input contract (complex props)
+// ---------------------------------------------------------------------------
+
+const inputContract = JSON.stringify({
+  $schema: 'https://usefragments.com/schemas/contract.v1.json',
+  name: 'Input',
+  description: 'Text input field with validation support',
+  category: 'forms',
+  sourcePath: 'src/components/Input/index.tsx',
+  exportName: 'Input',
+  propsSummary: [
+    'value: string',
+    'onChange: function (required)',
+    'placeholder: string',
+    'error: string',
+    'type: text|password|email|number (default: text)',
+  ],
+  props: {
+    value: { type: 'string', description: 'Input value' },
+    onChange: { type: 'function', description: 'Change handler', required: true },
+    placeholder: { type: 'string', description: 'Placeholder text' },
+    error: { type: 'string', description: 'Error message' },
+    type: {
+      type: 'enum',
+      values: ['text', 'password', 'email', 'number'],
+      default: 'text',
+      description: 'Input type',
+    },
+  },
+  usage: {
+    when: ['Collecting user text input'],
+    whenNot: ['Long-form text — use Textarea'],
+  },
+  provenance: { source: 'manual', verified: true, frameworkSupport: 'native' },
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('contract-parity', () => {
+  describe('Button (simple component)', () => {
+    const compiled = parseComponentContract(buttonContract, 'Button.contract.json');
+
+    it('has correct meta', () => {
+      expect(compiled.meta.name).toBe('Button');
+      expect(compiled.meta.category).toBe('actions');
+      expect(compiled.meta.status).toBe('stable');
+      expect(compiled.meta.tags).toEqual(['interactive', 'form']);
+    });
+
+    it('has correct props', () => {
+      expect(Object.keys(compiled.props)).toHaveLength(3);
+      expect(compiled.props.variant.type).toBe('enum');
+      expect(compiled.props.variant.values).toEqual(['primary', 'secondary', 'ghost']);
+    });
+
+    it('has correct usage', () => {
+      expect(compiled.usage.when).toHaveLength(2);
+      expect(compiled.usage.whenNot).toHaveLength(1);
+      expect(compiled.usage.guidelines).toHaveLength(1);
+      expect(compiled.usage.accessibility).toHaveLength(1);
+    });
+
+    it('has correct variants from examples', () => {
+      expect(compiled.variants).toHaveLength(2);
+      expect(compiled.variants[0].name).toBe('Primary');
+      expect(compiled.variants[0].code).toContain('<Button');
+      expect(compiled.variants[1].args).toEqual({ disabled: true });
+    });
+
+    it('has correct relations', () => {
+      expect(compiled.relations).toHaveLength(2);
+      expect(compiled.relations![0].component).toBe('Link');
+      expect(compiled.relations![0].relationship).toBe('alternative');
+    });
+
+    it('has contract metadata', () => {
+      expect(compiled.contract?.scenarioTags).toEqual(['form.submit', 'action.primary']);
+      expect(compiled.contract?.bans).toHaveLength(1);
+    });
+
+    it('has provenance', () => {
+      expect(compiled.provenance?.source).toBe('migrated');
+      expect(compiled.provenance?.verified).toBe(false);
+    });
+
+    it('has sourcePath and exportName', () => {
+      expect(compiled.sourcePath).toBe('src/components/Button/index.tsx');
+      expect(compiled.exportName).toBe('Button');
+    });
+
+    it('has propsSummary', () => {
+      expect(compiled.propsSummary).toHaveLength(3);
+      expect(compiled.propsSummary![0]).toContain('variant');
+    });
+  });
+
+  describe('Card (compound component)', () => {
+    const compiled = parseComponentContract(cardContract, 'Card.contract.json');
+
+    it('has AI metadata for compound composition', () => {
+      expect(compiled.ai?.compositionPattern).toBe('compound');
+      expect(compiled.ai?.subComponents).toEqual(['Header', 'Body', 'Footer']);
+      expect(compiled.ai?.requiredChildren).toEqual(['Body']);
+    });
+
+    it('has contract with compound children', () => {
+      expect(compiled.contract?.compoundChildren).toBeDefined();
+      expect(compiled.contract?.compoundChildren?.Body?.required).toBe(true);
+      expect(compiled.contract?.compoundChildren?.Footer?.accepts).toEqual(['Button']);
+    });
+
+    it('has canonical usage', () => {
+      expect(compiled.contract?.canonicalUsage).toHaveLength(1);
+    });
+  });
+
+  describe('Input (complex props)', () => {
+    const compiled = parseComponentContract(inputContract, 'Input.contract.json');
+
+    it('has required prop flagged', () => {
+      expect(compiled.props.onChange.required).toBe(true);
+    });
+
+    it('has verified provenance', () => {
+      expect(compiled.provenance?.verified).toBe(true);
+    });
+
+    it('has correct prop count', () => {
+      expect(Object.keys(compiled.props)).toHaveLength(5);
+    });
+  });
+
+  describe('structural invariants', () => {
+    const contracts = [
+      { name: 'Button', json: buttonContract },
+      { name: 'Card', json: cardContract },
+      { name: 'Input', json: inputContract },
+    ];
+
+    for (const { name, json } of contracts) {
+      it(`${name}: output has all required CompiledFragment fields`, () => {
+        const compiled = parseComponentContract(json, `${name}.contract.json`);
+
+        // Required structural fields
+        expect(compiled).toHaveProperty('filePath');
+        expect(compiled).toHaveProperty('meta');
+        expect(compiled).toHaveProperty('usage');
+        expect(compiled).toHaveProperty('props');
+        expect(compiled).toHaveProperty('variants');
+
+        // Meta required fields
+        expect(compiled.meta.name).toBeTruthy();
+        expect(compiled.meta.description).toBeTruthy();
+        expect(compiled.meta.category).toBeTruthy();
+
+        // V2 fields
+        expect(compiled).toHaveProperty('propsSummary');
+        expect(compiled).toHaveProperty('provenance');
+        expect(compiled).toHaveProperty('sourcePath');
+        expect(compiled).toHaveProperty('exportName');
+      });
+    }
+  });
+});

package/src/core/component-extractor.test.ts

@@ -279,4 +279,43 @@ describe('source attribution', () => {
       expect(meta!.props.className.source).toBe('inherited');
     }
   });
+
+  it('marks destructured inherited props as local for wrapper components', async () => {
+    const fixtureDir = join(__dirname, '__fixtures__', 'shadcn-input');
+    const filePath = join(fixtureDir, 'input.tsx');
+    const tsconfigPath = join(fixtureDir, 'tsconfig.json');
+
+    extractor = createComponentExtractor(tsconfigPath);
+    const meta = extractor.extract(filePath, 'Input');
+
+    expect(meta).not.toBeNull();
+    expect(meta!.props.type).toBeDefined();
+    expect(meta!.props.type.source).toBe('local');
+  });
+
+  it('extracts inherited props from ComponentProps<typeof Primitive.Root> wrappers', async () => {
+    const fixtureDir = join(__dirname, '__fixtures__', 'shadcn-label');
+    const filePath = join(fixtureDir, 'label.tsx');
+    const tsconfigPath = join(fixtureDir, 'tsconfig.json');
+
+    extractor = createComponentExtractor(tsconfigPath);
+    const meta = extractor.extract(filePath, 'Label');
+
+    expect(meta).not.toBeNull();
+    expect(meta!.props.htmlFor).toBeDefined();
+    expect(meta!.props.form).toBeDefined();
+  });
+
+  it('extracts props from package-backed Primitive.Root wrappers', async () => {
+    const fixtureDir = join(__dirname, '__fixtures__', 'shadcn-radix-label');
+    const filePath = join(fixtureDir, 'label.tsx');
+    const tsconfigPath = join(fixtureDir, 'tsconfig.json');
+
+    extractor = createComponentExtractor(tsconfigPath);
+    const meta = extractor.extract(filePath, 'Label');
+
+    expect(meta).not.toBeNull();
+    expect(meta!.props.htmlFor).toBeDefined();
+    expect(meta!.props.form).toBeDefined();
+  });
 });

package/src/core/component-extractor.ts

@@ -128,6 +128,24 @@ export function createComponentExtractor(tsconfigPath?: string): ComponentExtrac
     readDirectory: ts.sys.readDirectory,
     directoryExists: ts.sys.directoryExists,
     getDirectories: ts.sys.getDirectories,
+    resolveModuleNames: (moduleNames, containingFile) =>
+      moduleNames.map((moduleName) => {
+        const resolved = ts.resolveModuleName(
+          moduleName,
+          containingFile,
+          parsedCommandLine.options,
+          {
+            fileExists: ts.sys.fileExists,
+            readFile: ts.sys.readFile,
+            realpath: ts.sys.realpath,
+            directoryExists: ts.sys.directoryExists,
+            getDirectories: ts.sys.getDirectories,
+            getCurrentDirectory: () => rootDir,
+          }
+        );
+
+        return resolved.resolvedModule;
+      }),
   };
 
   const languageService = ts.createLanguageService(host, ts.createDocumentRegistry());
@@ -605,7 +623,27 @@ function extractPropsFromFunctionLike(
 
   // If there's a type annotation, use it
   if (firstParam.type) {
-    return checker.getTypeFromTypeNode(firstParam.type);
+    const directType = checker.getTypeFromTypeNode(firstParam.type);
+    if (checker.getPropertiesOfType(directType).length > 0) {
+      return directType;
+    }
+
+    const apparentType = checker.getApparentType(directType);
+    if (checker.getPropertiesOfType(apparentType).length > 0) {
+      return apparentType;
+    }
+
+    const paramType = checker.getTypeAtLocation(firstParam);
+    if (checker.getPropertiesOfType(paramType).length > 0) {
+      return paramType;
+    }
+
+    const constrainedType = checker.getBaseConstraintOfType(directType);
+    if (constrainedType && checker.getPropertiesOfType(constrainedType).length > 0) {
+      return constrainedType;
+    }
+
+    return directType;
   }
 
   // Otherwise try to infer from the parameter's symbol
@@ -633,6 +671,29 @@ function buildComponentMeta(
 
   if (component.propsType) {
     extractPropsFromType(checker, component.propsType, props, sourceFilePath);
+    if (Object.keys(props).length === 0) {
+      const apparentPropsType = checker.getApparentType(component.propsType);
+      if (apparentPropsType !== component.propsType) {
+        extractPropsFromType(checker, apparentPropsType, props, sourceFilePath);
+      }
+    }
+    if (Object.keys(props).length === 0) {
+      const constrainedPropsType = checker.getBaseConstraintOfType(component.propsType);
+      if (constrainedPropsType) {
+        extractPropsFromType(checker, constrainedPropsType, props, sourceFilePath);
+      }
+    }
+  }
+
+  // Promote explicitly destructured props to "local" so wrapper components like
+  // shadcn Input surface the props they actively customize from inherited DOM types.
+  const destructuredProps = component.componentNode
+    ? extractDestructuredPropNames(component.componentNode)
+    : new Set<string>();
+  for (const propName of destructuredProps) {
+    if (props[propName]) {
+      props[propName].source = 'local';
+    }
   }
 
   // Extract defaults from the component function body
@@ -876,6 +937,36 @@ function extractDefaultValues(node: ts.Node): Record<string, string> {
   return defaults;
 }
 
+function extractDestructuredPropNames(node: ts.Node): Set<string> {
+  const names = new Set<string>();
+
+  let funcNode: ts.FunctionLikeDeclaration | null = null;
+  if (ts.isFunctionDeclaration(node) || ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+    funcNode = node;
+  }
+
+  if (!funcNode?.parameters?.length) return names;
+
+  const firstParam = funcNode.parameters[0];
+  if (!ts.isObjectBindingPattern(firstParam.name)) return names;
+
+  for (const element of firstParam.name.elements) {
+    if (element.dotDotDotToken || !ts.isIdentifier(element.name)) continue;
+
+    const propName = element.propertyName
+      ? element.propertyName.getText()
+      : element.name.text;
+
+    if (propName === 'className' || propName === 'children' || propName === 'ref') {
+      continue;
+    }
+
+    names.add(propName);
+  }
+
+  return names;
+}
+
 function readLiteralValue(expression: ts.Expression): string | undefined {
   if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) {
     return expression.text;

package/src/core/config.ts

@@ -13,7 +13,8 @@ const STORYBOOK_FILTER_DEFAULTS: StorybookFilterConfig = {
 
 const DEFAULT_CONFIG: FragmentsConfig = {
   include: [
-    `src/**/*${BRAND.fileExtension}`,  // *.fragment.tsx files
+    `src/**/*${BRAND.fileExtension}`,  // *.contract.json files (V2 canonical)
+    'src/**/*.fragment.tsx',            // Legacy fragment files (still supported)
     'src/**/*.stories.tsx',             // Storybook stories (auto-converted)
   ],
   exclude: ['**/node_modules/**'],

package/src/core/discovery.ts

@@ -110,7 +110,8 @@ export async function discoverBlockFiles(
 export const discoverRecipeFiles = discoverBlockFiles;
 
 /**
- * Discover fragment files matching the config patterns
+ * Discover fragment files matching the config patterns.
+ * Also discovers .contract.json files for framework-agnostic component contracts.
  */
 export async function discoverFragmentFiles(
   config: FragmentsConfig,
@@ -122,7 +123,14 @@ export async function discoverFragmentFiles(
     '**/*.test.story.*',
     '**/*.story.test.*',
   ];
-  const files = await fg(config.include, {
+
+  // Include .contract.json files alongside configured patterns
+  const patterns = [
+    ...config.include,
+    '**/*.contract.json',
+  ];
+
+  const files = await fg(patterns, {
     cwd: configDir,
     ignore: [...defaultExcludes, ...(config.exclude ?? [])],
     absolute: false,
@@ -408,6 +416,9 @@ const DEFAULT_TOKEN_PATTERNS = [
   'src/**/styles/**/variables.css',
   'src/**/theme/**/_variables.scss',
   'src/**/theme/**/tokens.css',
+  // DTCG token files
+  '**/*.tokens.json',
+  '**/*.tokens',
 ];
 
 /**

package/src/core/drift-verifier.ts

@@ -0,0 +1,123 @@
+/**
+ * Contract Drift Verifier
+ *
+ * Detects mismatches between a .contract.json and the live component source.
+ * Used during build to enforce verified contracts stay in sync.
+ */
+
+import type { CompiledContractOutput } from '@fragments-sdk/core';
+import type { ComponentMeta } from './component-extractor.js';
+
+export interface DriftReport {
+  componentName: string;
+  /** Props in contract but absent from source */
+  removedProps: string[];
+  /** Props in source but absent from contract */
+  undocumentedProps: string[];
+  /** Props where contract type doesn't match source type */
+  typeMismatches: Array<{ prop: string; contract: string; source: string }>;
+  /** Props where contract default doesn't match source default */
+  defaultMismatches: Array<{ prop: string; contract: unknown; source: unknown }>;
+  /** Overall clean status */
+  isClean: boolean;
+}
+
+/**
+ * Compare a parsed contract against extracted component metadata.
+ */
+export function verifyContractDrift(
+  contract: CompiledContractOutput,
+  extracted: ComponentMeta,
+): DriftReport {
+  const contractPropNames = new Set(Object.keys(contract.props));
+  const sourcePropNames = new Set(
+    Object.entries(extracted.props)
+      .filter(([, p]) => p.source === 'local')
+      .map(([name]) => name),
+  );
+
+  const removedProps: string[] = [];
+  const undocumentedProps: string[] = [];
+  const typeMismatches: DriftReport['typeMismatches'] = [];
+  const defaultMismatches: DriftReport['defaultMismatches'] = [];
+
+  // Props in contract but not in source
+  for (const name of contractPropNames) {
+    if (!sourcePropNames.has(name)) {
+      removedProps.push(name);
+    }
+  }
+
+  // Props in source but not in contract
+  for (const name of sourcePropNames) {
+    if (!contractPropNames.has(name)) {
+      undocumentedProps.push(name);
+    }
+  }
+
+  // Type and default mismatches for props present in both
+  for (const name of contractPropNames) {
+    const contractProp = contract.props[name];
+    const sourceProp = extracted.props[name];
+    if (!sourceProp || sourceProp.source !== 'local') continue;
+
+    // Type comparison (contract uses simple string, source uses typeKind)
+    if (contractProp.type !== sourceProp.typeKind) {
+      typeMismatches.push({
+        prop: name,
+        contract: contractProp.type,
+        source: sourceProp.typeKind,
+      });
+    }
+
+    // Default comparison
+    const contractDefault = contractProp.default;
+    const sourceDefault = sourceProp.default;
+    if (contractDefault !== undefined && sourceDefault !== undefined) {
+      if (String(contractDefault) !== String(sourceDefault)) {
+        defaultMismatches.push({
+          prop: name,
+          contract: contractDefault,
+          source: sourceDefault,
+        });
+      }
+    }
+  }
+
+  const isClean =
+    removedProps.length === 0 &&
+    undocumentedProps.length === 0 &&
+    typeMismatches.length === 0 &&
+    defaultMismatches.length === 0;
+
+  return {
+    componentName: contract.meta.name,
+    removedProps,
+    undocumentedProps,
+    typeMismatches,
+    defaultMismatches,
+    isClean,
+  };
+}
+
+/**
+ * Format a DriftReport into a human-readable string.
+ */
+export function formatDriftReport(report: DriftReport): string {
+  const lines: string[] = [`Drift detected for ${report.componentName}:`];
+
+  if (report.removedProps.length > 0) {
+    lines.push(`  Removed from source: ${report.removedProps.join(', ')}`);
+  }
+  if (report.undocumentedProps.length > 0) {
+    lines.push(`  Missing from contract: ${report.undocumentedProps.join(', ')}`);
+  }
+  for (const m of report.typeMismatches) {
+    lines.push(`  Type mismatch: ${m.prop} (contract: ${m.contract}, source: ${m.source})`);
+  }
+  for (const m of report.defaultMismatches) {
+    lines.push(`  Default mismatch: ${m.prop} (contract: ${String(m.contract)}, source: ${String(m.source)})`);
+  }
+
+  return lines.join('\n');
+}