@fragments-sdk/cli 0.11.1 → 0.12.1

package/src/bin.ts

@@ -39,6 +39,7 @@ import { graph } from './commands/graph.js';
 import { perf } from './commands/perf.js';
 import { doctor } from './commands/doctor.js';
 import { setup } from './commands/setup.js';
+import { sync } from './commands/sync.js';
 
 // Import existing commands that were already extracted
 import { runScreenshotCommand } from './screenshot.js';
@@ -62,6 +63,8 @@ program
   .option('--schema', 'Validate fragment schema only')
   .option('--coverage', 'Validate coverage only')
   .option('--snippets', 'Validate snippet/render policy only')
+  .option('--drift', 'Detect metadata drift between source and fragments')
+  .option('--tsconfig <path>', 'Path to tsconfig.json (for drift detection)')
   .option('--snippet-mode <mode>', 'Override snippet policy mode (warn|error)')
   .option('--component-start <name>', 'Start component name for alphabetical snippet batch validation')
   .option('--component-limit <n>', 'Component count for alphabetical snippet batch validation', (value) => Number.parseInt(value, 10))
@@ -77,6 +80,33 @@ program
     }
   });
 
+// ============================================================================
+// SYNC COMMAND
+// ============================================================================
+program
+  .command('sync')
+  .description('Auto-update fragment files from component source')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--tsconfig <path>', 'Path to tsconfig.json')
+  .option('--dry-run', 'Preview changes without writing')
+  .option('--component <name>', 'Sync specific component only')
+  .action(async (options) => {
+    try {
+      const result = await sync({
+        config: options.config,
+        tsconfig: options.tsconfig,
+        dryRun: options.dryRun,
+        component: options.component,
+      });
+      if (!result.success) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
 // ============================================================================
 // BUILD COMMAND
 // ============================================================================
@@ -794,10 +824,16 @@ program
 // ============================================================================
 program
   .command('init')
-  .description('Initialize fragments in a project (interactive by default)')
+  .description('Initialize fragments in a project (zero-config by default)')
   .option('--force', 'Overwrite existing config')
-  .option('-y, --yes', 'Non-interactive mode - auto-detect and use defaults')
+  .option('-y, --yes', 'Non-interactive mode (now the default)')
+  .option('--configure', 'Interactive mode for theme seeds, snapshots, etc.')
   .option('--scan <path>', 'Scan a TypeScript component directory and generate fragment files')
+  .option('--enrich', 'Use AI to fill knowledge fields during --scan (requires API key)')
+  .option('--dry-run', 'Show what --enrich would generate without calling API')
+  .option('--provider <provider>', 'AI provider for enrichment: anthropic or openai')
+  .option('--api-key <key>', 'API key for AI enrichment')
+  .option('--model <model>', 'Override AI model for enrichment')
   .action(async (options) => {
     try {
       const { init } = await import('./commands/init.js');
@@ -806,6 +842,12 @@ program
         force: options.force,
         yes: options.scan ? true : options.yes,
         scan: options.scan,
+        configure: options.configure,
+        enrich: options.enrich,
+        dryRun: options.dryRun,
+        provider: options.provider,
+        apiKey: options.apiKey,
+        model: options.model,
       });
 
       if (!result.success) {

package/src/build.ts

@@ -21,10 +21,13 @@ import {
   generateContextMd,
 } from "./core/node.js";
 import {
-  extractCustomPropsFromComponentFile,
   resolveComponentSourcePath,
-  type AutoDetectedPropDefinition,
 } from "./core/auto-props.js";
+import {
+  createComponentExtractor,
+  type PropMeta,
+  type ComponentMeta,
+} from "./core/component-extractor.js";
 import { buildComponentGraph } from "./core/graph-extractor.js";
 import { serializeGraph } from "@fragments-sdk/context/graph";
 import { resolvePerformanceConfig } from "./core/index.js";
@@ -53,17 +56,21 @@ function normalizeParsedProps(
 
 function mergeDocumentedAndAutoProps(
   documentedProps: Record<string, CompiledProp>,
-  autoProps: Record<string, AutoDetectedPropDefinition>
+  autoProps: Record<string, PropMeta>
 ): Record<string, CompiledProp> {
   return Object.fromEntries(
-    Object.keys(autoProps).map((name) => {
+    Object.keys(autoProps)
+      // Strip inherited HTML/React props — they're identical across all components
+      // and bloat fragments.json. MCP consumers know these exist implicitly.
+      .filter((name) => autoProps[name].source === 'local' || name in documentedProps)
+      .map((name) => {
       const documented = documentedProps[name];
       const auto = autoProps[name];
 
       return [
         name,
         {
-          type: auto.type,
+          type: auto.typeKind,
           description: documented?.description ?? auto.description ?? "",
           default: auto.default !== undefined ? auto.default : documented?.default,
           required: auto.required,
@@ -75,6 +82,30 @@ function mergeDocumentedAndAutoProps(
   );
 }
 
+/**
+ * Auto-compile a propsSummary for the contract from extracted props.
+ * Format: "variant: primary|secondary|ghost (required)"
+ */
+function compilePropsSummary(props: Record<string, PropMeta>): 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;
+    });
+}
+
 export interface BuildResult {
   success: boolean;
   outputPath: string;
@@ -98,6 +129,15 @@ export async function buildFragments(
   const warnings: Array<{ file: string; warning: string }> = [];
   const fragments: CompiledFragmentsFile["fragments"] = {};
 
+  // Create a persistent extractor — shared LanguageService across all fragments
+  // Try to find a tsconfig.json in the config directory
+  const tsconfigCandidates = [
+    resolve(configDir, 'tsconfig.json'),
+    resolve(configDir, '..', 'tsconfig.json'),
+  ];
+  const tsconfigPath = tsconfigCandidates.find((p) => existsSync(p));
+  const extractor = createComponentExtractor(tsconfigPath);
+
   for (const file of files) {
     try {
       // Read file content as text
@@ -139,38 +179,38 @@ export async function buildFragments(
         parsed.componentImport
       );
 
+      // Extract full component metadata using persistent LanguageService
+      let extractedMeta: ComponentMeta | null = null;
       if (componentExportName && componentSourcePath) {
-        const autoPropsResult = extractCustomPropsFromComponentFile(
-          componentSourcePath,
-          componentExportName
-        );
-
-        for (const warning of autoPropsResult.warnings) {
-          warnings.push({ file: file.relativePath, warning });
+        try {
+          extractedMeta = extractor.extract(componentSourcePath, componentExportName);
+        } catch {
+          // Extraction failure is non-fatal — fall back to documented props
         }
 
-        const hasAutoProps = Object.keys(autoPropsResult.props).length > 0;
-        if (autoPropsResult.resolved && hasAutoProps) {
-          const removedDocumentedProps = Object.keys(documentedProps).filter(
-            (propName) => !(propName in autoPropsResult.props)
-          );
+        if (extractedMeta) {
+          const autoProps = extractedMeta.props;
+          const hasAutoProps = Object.keys(autoProps).length > 0;
 
-          if (removedDocumentedProps.length > 0) {
+          if (hasAutoProps) {
+            const removedDocumentedProps = Object.keys(documentedProps).filter(
+              (propName) => !(propName in autoProps)
+            );
+
+            if (removedDocumentedProps.length > 0) {
+              warnings.push({
+                file: file.relativePath,
+                warning: `Removed ${removedDocumentedProps.length} documented props not present in source API: ${removedDocumentedProps.join(", ")}`,
+              });
+            }
+
+            mergedProps = mergeDocumentedAndAutoProps(documentedProps, autoProps);
+          } else if (Object.keys(documentedProps).length > 0) {
             warnings.push({
               file: file.relativePath,
-              warning: `Removed ${removedDocumentedProps.length} documented props not present in source API: ${removedDocumentedProps.join(", ")}`,
+              warning: "Auto-props extraction returned no props; falling back to documented props",
             });
           }
-
-          mergedProps = mergeDocumentedAndAutoProps(
-            documentedProps,
-            autoPropsResult.props
-          );
-        } else if (autoPropsResult.resolved && !hasAutoProps && Object.keys(documentedProps).length > 0) {
-          warnings.push({
-            file: file.relativePath,
-            warning: "Auto-props extraction returned no custom props; falling back to documented props",
-          });
         }
       } else if (!componentExportName) {
         warnings.push({
@@ -184,6 +224,26 @@ export async function buildFragments(
         });
       }
 
+      // Auto-compile contract if not manually authored
+      let contract = parsed.contract;
+      if (!contract?.propsSummary && extractedMeta) {
+        const summary = compilePropsSummary(extractedMeta.props);
+        if (summary.length > 0) {
+          contract = { ...contract, propsSummary: summary };
+        }
+      }
+
+      // Auto-enrich AI metadata from extractor's composition data
+      let ai = parsed.ai;
+      if (extractedMeta?.composition) {
+        const comp = extractedMeta.composition;
+        ai = {
+          compositionPattern: comp.pattern,
+          subComponents: comp.parts.map((p) => p.name),
+          ...ai, // Manually authored ai fields take precedence
+        };
+      }
+
       // Build compiled fragment from parsed metadata
       const compiled: CompiledFragment = {
         filePath: file.relativePath,
@@ -221,10 +281,10 @@ export async function buildFragments(
           ...(v.figma && { figma: v.figma }),
           ...(v.args && { args: v.args }),
         })),
-        // Include AI metadata if present
-        ...(parsed.ai && { ai: parsed.ai }),
-        // Include contract metadata if present
-        ...(parsed.contract && { contract: parsed.contract }),
+        // Include AI metadata (auto-enriched or manual)
+        ...(ai && { ai }),
+        // Include contract metadata (auto-compiled or manual)
+        ...(contract && { contract }),
       };
 
       fragments[parsed.meta.name] = compiled;
@@ -236,6 +296,8 @@ export async function buildFragments(
     }
   }
 
+  extractor.dispose();
+
   // Discover and compile block files
   const blocks: Record<string, CompiledBlock> = {};
   try {

package/src/commands/__tests__/drift-sync.test.ts

@@ -0,0 +1,252 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtemp, writeFile, mkdir, rm, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { diffProps, validateDrift, type DriftItem } from '../../validators.js';
+import type { PropMeta } from '../../core/component-extractor.js';
+import type { FragmentsConfig } from '@fragments-sdk/core';
+
+// ---------------------------------------------------------------------------
+// Helper: build a PropMeta for tests
+// ---------------------------------------------------------------------------
+
+function makeProp(overrides: Partial<PropMeta> & { name: string }): PropMeta {
+  return {
+    type: overrides.type ?? 'string',
+    typeKind: overrides.typeKind ?? 'string',
+    required: overrides.required ?? false,
+    source: overrides.source ?? 'local',
+    name: overrides.name,
+    ...(overrides.values && { values: overrides.values }),
+    ...(overrides.default !== undefined && { default: overrides.default }),
+    ...(overrides.description && { description: overrides.description }),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Unit tests: diffProps
+// ---------------------------------------------------------------------------
+
+describe('diffProps', () => {
+  it('detects added props (in source but not in fragment)', () => {
+    const fragmentProps = {
+      children: { type: 'node', required: true },
+    };
+    const sourceProps: Record<string, PropMeta> = {
+      children: makeProp({ name: 'children', typeKind: 'node', required: true }),
+      variant: makeProp({ name: 'variant', typeKind: 'enum', values: ['primary', 'secondary'] }),
+    };
+
+    const drifts = diffProps(fragmentProps, sourceProps);
+    const added = drifts.filter(d => d.kind === 'added');
+    expect(added.length).toBe(1);
+    expect(added[0].prop).toBe('variant');
+  });
+
+  it('detects removed props (in fragment but not in source)', () => {
+    const fragmentProps = {
+      children: { type: 'node', required: true },
+      loading: { type: 'boolean', description: 'Show loading' },
+    };
+    const sourceProps: Record<string, PropMeta> = {
+      children: makeProp({ name: 'children', typeKind: 'node', required: true }),
+    };
+
+    const drifts = diffProps(fragmentProps, sourceProps);
+    const removed = drifts.filter(d => d.kind === 'removed');
+    expect(removed.length).toBe(1);
+    expect(removed[0].prop).toBe('loading');
+  });
+
+  it('detects type changes', () => {
+    const fragmentProps = {
+      value: { type: 'string', required: false },
+    };
+    const sourceProps: Record<string, PropMeta> = {
+      value: makeProp({ name: 'value', typeKind: 'number' }),
+    };
+
+    const drifts = diffProps(fragmentProps, sourceProps);
+    const typeChanged = drifts.filter(d => d.kind === 'type_changed');
+    expect(typeChanged.length).toBe(1);
+    expect(typeChanged[0].source).toBe('number');
+    expect(typeChanged[0].fragment).toBe('string');
+  });
+
+  it('detects required status changes', () => {
+    const fragmentProps = {
+      name: { type: 'string', required: false },
+    };
+    const sourceProps: Record<string, PropMeta> = {
+      name: makeProp({ name: 'name', typeKind: 'string', required: true }),
+    };
+
+    const drifts = diffProps(fragmentProps, sourceProps);
+    const reqChanged = drifts.filter(d => d.kind === 'required_changed');
+    expect(reqChanged.length).toBe(1);
+    expect(reqChanged[0].source).toBe('true');
+    expect(reqChanged[0].fragment).toBe('false');
+  });
+
+  it('detects enum value changes', () => {
+    const fragmentProps = {
+      variant: { type: 'enum', values: ['primary', 'secondary'] as const },
+    };
+    const sourceProps: Record<string, PropMeta> = {
+      variant: makeProp({
+        name: 'variant',
+        typeKind: 'enum',
+        values: ['primary', 'secondary', 'ghost'],
+      }),
+    };
+
+    const drifts = diffProps(fragmentProps, sourceProps);
+    const valChanged = drifts.filter(d => d.kind === 'values_changed');
+    expect(valChanged.length).toBe(1);
+    expect(valChanged[0].source).toContain('ghost');
+  });
+
+  it('detects default value changes', () => {
+    const fragmentProps = {
+      size: { type: 'enum', default: 'md' },
+    };
+    const sourceProps: Record<string, PropMeta> = {
+      size: makeProp({ name: 'size', typeKind: 'enum', default: 'lg' }),
+    };
+
+    const drifts = diffProps(fragmentProps, sourceProps);
+    const defChanged = drifts.filter(d => d.kind === 'default_changed');
+    expect(defChanged.length).toBe(1);
+    expect(defChanged[0].source).toBe('lg');
+    expect(defChanged[0].fragment).toBe('md');
+  });
+
+  it('filters out inherited source props', () => {
+    const fragmentProps = {};
+    const sourceProps: Record<string, PropMeta> = {
+      className: makeProp({ name: 'className', typeKind: 'string', source: 'inherited' }),
+      style: makeProp({ name: 'style', typeKind: 'object', source: 'inherited' }),
+    };
+
+    const drifts = diffProps(fragmentProps, sourceProps);
+    expect(drifts.length).toBe(0);
+  });
+
+  it('returns empty array when in sync', () => {
+    const fragmentProps = {
+      children: { type: 'node', required: true },
+      variant: { type: 'enum', values: ['a', 'b'] as const },
+    };
+    const sourceProps: Record<string, PropMeta> = {
+      children: makeProp({ name: 'children', typeKind: 'node', required: true }),
+      variant: makeProp({ name: 'variant', typeKind: 'enum', values: ['a', 'b'] }),
+    };
+
+    const drifts = diffProps(fragmentProps, sourceProps);
+    expect(drifts.length).toBe(0);
+  });
+
+  it('detects multiple drift types simultaneously', () => {
+    const fragmentProps = {
+      children: { type: 'node', required: true },
+      loading: { type: 'boolean' },
+      variant: { type: 'enum', values: ['a'] as const },
+    };
+    const sourceProps: Record<string, PropMeta> = {
+      children: makeProp({ name: 'children', typeKind: 'node', required: true }),
+      size: makeProp({ name: 'size', typeKind: 'enum', values: ['sm', 'md'] }),
+      variant: makeProp({ name: 'variant', typeKind: 'enum', values: ['a', 'b'] }),
+    };
+
+    const drifts = diffProps(fragmentProps, sourceProps);
+    expect(drifts.length).toBe(3);
+
+    const kinds = drifts.map(d => d.kind);
+    expect(kinds).toContain('added');      // size
+    expect(kinds).toContain('removed');     // loading
+    expect(kinds).toContain('values_changed'); // variant
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Integration: validateDrift with real files
+// ---------------------------------------------------------------------------
+
+describe('validateDrift integration', () => {
+  let tmpDir: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'drift-int-'));
+
+    const compDir = join(tmpDir, 'components', 'Tag');
+    await mkdir(compDir, { recursive: true });
+
+    // Simple component — no JSX to avoid esbuild issues
+    await writeFile(
+      join(compDir, 'index.tsx'),
+      `export interface TagProps {
+  /** Tag label text */
+  label: string;
+  /** Color variant */
+  color?: 'blue' | 'green' | 'red';
+}
+
+export function Tag({ label, color = 'blue' }: TagProps) {
+  return label;
+}
+`,
+      'utf-8'
+    );
+
+    // Fragment with missing 'color' prop and stale 'icon' prop
+    await writeFile(
+      join(compDir, 'Tag.fragment.tsx'),
+      `import { defineFragment } from '@fragments-sdk/core';
+import { Tag } from './index';
+
+export default defineFragment({
+  component: Tag,
+  meta: { name: 'Tag', description: 'A tag component', category: 'Display', status: 'stable' },
+  usage: { when: ['Label items'], whenNot: ['Navigation'] },
+  props: {
+    label: { type: 'string', description: 'Tag label text', required: true },
+    icon: { type: 'node', description: 'Leading icon' },
+  },
+  variants: [],
+});
+`,
+      'utf-8'
+    );
+  });
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('detects drift in real fragment files', async () => {
+    const config: FragmentsConfig = {
+      include: ['components/**/*.fragment.tsx'],
+      exclude: [],
+      components: ['components/**/index.tsx'],
+      outFile: 'fragments.json',
+      dataDir: '.fragments',
+    } as FragmentsConfig;
+
+    const result = await validateDrift(config, tmpDir);
+
+    // Should find drift: 'color' added (in source, not in fragment), 'icon' removed (in fragment, not in source)
+    expect(result.reports.length).toBe(1);
+    expect(result.reports[0].component).toBe('Tag');
+
+    const driftKinds = result.reports[0].drifts.map(d => d.kind);
+    expect(driftKinds).toContain('added');
+    expect(driftKinds).toContain('removed');
+
+    // 'icon' removal should be an error (breaks existing code)
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.message.includes('icon'))).toBe(true);
+
+    // 'color' addition should be a warning (new undocumented prop)
+    expect(result.warnings.some(w => w.message.includes('color'))).toBe(true);
+  });
+});