@fragments-sdk/cli 0.10.1 → 0.12.1

package/src/commands/scan-generate.ts

@@ -6,10 +6,9 @@
  *
  * Combines:
  * - Component discovery (core/discovery.ts)
- * - Props extraction (service/enhance/props-extractor.ts)
- * - JSDoc extraction (new: TypeScript AST)
- * - Compound component detection (new: Object.assign pattern)
+ * - ComponentExtractor: persistent LanguageService-based prop + compound extraction
  * - Confidence scoring with TODO markers
+ * - Composition-aware code generation
  */
 
 import { readFile, writeFile, access, mkdir } from "node:fs/promises";
@@ -22,11 +21,12 @@ import {
   type DiscoveredComponent,
 } from "../core/node.js";
 import {
-  extractPropsFromFile,
-  convertToFragmentProps,
-  type PropsExtractionResult,
-  type ExtractedProp,
-} from "../service/index.js";
+  createComponentExtractor,
+  type ComponentExtractor,
+  type ComponentMeta,
+  type PropMeta,
+  type CompositionMeta,
+} from "../core/component-extractor.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -45,6 +45,18 @@ export interface ScanGenerateOptions {
   skipStorybook?: boolean;
   /** Verbose logging */
   verbose?: boolean;
+  /** Path to tsconfig.json for accurate type resolution */
+  tsconfig?: string;
+  /** Enable LLM enrichment of knowledge fields */
+  enrich?: boolean;
+  /** Show what would be enriched without calling API */
+  dryRun?: boolean;
+  /** AI provider override: anthropic or openai */
+  provider?: 'anthropic' | 'openai';
+  /** Explicit API key for enrichment */
+  apiKey?: string;
+  /** Override default AI model for enrichment */
+  model?: string;
 }
 
 export interface ScanGenerateResult {
@@ -54,17 +66,18 @@ export interface ScanGenerateResult {
     path: string;
     confidence: number;
     todoCount: number;
+    enriched?: boolean;
   }>;
   skipped: Array<{ name: string; reason: string }>;
   errors: Array<{ name: string; error: string }>;
   averageConfidence: number;
+  enrichmentCost?: number;
 }
 
 interface ComponentData {
   component: DiscoveredComponent;
-  props: PropsExtractionResult | null;
-  jsDoc: string | null;
-  compoundChildren: string[];
+  /** Full metadata from ComponentExtractor (props, composition, description) */
+  meta: ComponentMeta | null;
   storyVariants: StoryVariant[];
 }
 
@@ -78,6 +91,15 @@ interface FieldConfidence {
   todoFields: string[];
 }
 
+export interface EnrichmentResult {
+  when: string[];
+  whenNot: string[];
+  guidelines: string[];
+  a11yRules: string[];
+  scenarioTags: string[];
+  tags: string[];
+}
+
 // ---------------------------------------------------------------------------
 // Main orchestrator
 // ---------------------------------------------------------------------------
@@ -133,33 +155,42 @@ export async function scanGenerate(
 
   console.log(pc.green(`  Found ${components.length} components`));
 
-  // Phase 2: Extract data for each component
+  // Phase 2: Extract data for each component (persistent LanguageService)
   console.log(pc.dim("\nPhase 2: Extracting component metadata..."));
 
+  // Create a single extractor that reuses its LanguageService across all components
+  const extractor = createComponentExtractor(options.tsconfig);
   const componentDataList: ComponentData[] = [];
 
-  for (const comp of components) {
-    let propsResult: PropsExtractionResult | null = null;
-    try {
-      propsResult = await extractPropsFromFile(comp.sourcePath, {
-        propsTypeName: `${comp.name}Props`,
-      });
-    } catch {
-      // Props extraction can fail for complex types — continue gracefully
-    }
+  const extractionStart = performance.now();
 
-    let jsDoc: string | null = null;
+  for (const comp of components) {
+    let meta: ComponentMeta | null = null;
     try {
-      jsDoc = await extractComponentJSDoc(comp.sourcePath, comp.name);
+      meta = extractor.extract(comp.sourcePath, comp.name);
     } catch {
-      // JSDoc extraction failure is non-fatal
+      // Extraction can fail for complex types — continue gracefully
     }
 
-    let compoundChildren: string[] = [];
-    try {
-      compoundChildren = await detectCompoundComponents(comp.sourcePath);
-    } catch {
-      // Compound detection failure is non-fatal
+    // Fallback compound detection for prefix-based patterns (e.g., shadcn-style
+    // components that export CardHeader, CardFooter etc. as separate named exports
+    // rather than using Object.assign)
+    if (meta && !meta.composition) {
+      try {
+        const subComponents = await detectCompoundComponents(comp.sourcePath, comp.name);
+        if (subComponents.length > 0) {
+          meta = {
+            ...meta,
+            composition: {
+              pattern: 'compound',
+              parts: subComponents.map(name => ({ name, props: {} })),
+              required: [],
+            },
+          };
+        }
+      } catch {
+        // Non-fatal
+      }
     }
 
     let storyVariants: StoryVariant[] = [];
@@ -173,20 +204,53 @@ export async function scanGenerate(
 
     componentDataList.push({
       component: comp,
-      props: propsResult,
-      jsDoc,
-      compoundChildren,
+      meta,
       storyVariants,
     });
   }
 
+  extractor.dispose();
+
+  const extractionMs = (performance.now() - extractionStart).toFixed(0);
   const propsExtracted = componentDataList.filter(
-    (d) => d.props?.success && d.props.props.length > 0
+    (d) => d.meta && Object.keys(d.meta.props).length > 0
+  ).length;
+  const compoundCount = componentDataList.filter(
+    (d) => d.meta?.composition !== null
   ).length;
-  console.log(pc.green(`  Extracted props for ${propsExtracted} components`));
+  console.log(pc.green(`  Extracted props for ${propsExtracted} components (${extractionMs}ms)`));
+  if (compoundCount > 0) {
+    console.log(pc.green(`  Detected ${compoundCount} compound component(s) with sub-component props`));
+  }
+
+  // Phase 3: Enrich with LLM (if --enrich)
+  let enrichments = new Map<string, EnrichmentResult>();
+  let enrichmentCost: number | undefined;
+
+  if (options.enrich) {
+    console.log(pc.dim("\nPhase 3: Enriching with AI..."));
+
+    const enrichResult = await enrichComponents(componentDataList, {
+      dryRun: options.dryRun,
+      provider: options.provider,
+      apiKey: options.apiKey,
+      model: options.model,
+    });
 
-  // Phase 3: Generate fragment files
-  console.log(pc.dim("\nPhase 3: Generating fragment files..."));
+    enrichments = enrichResult.enrichments;
+
+    if (enrichResult.model && enrichResult.totalInputTokens > 0) {
+      const { calculateCost } = await import('../ai-client.js');
+      enrichmentCost = calculateCost(
+        enrichResult.model,
+        enrichResult.totalInputTokens,
+        enrichResult.totalOutputTokens
+      );
+    }
+  }
+
+  // Phase 4: Generate fragment files
+  console.log(pc.dim(`\nPhase ${options.enrich ? '4' : '3'}: Generating fragment files...`));
 
   for (const data of componentDataList) {
     const comp = data.component;
@@ -225,8 +289,11 @@ export async function scanGenerate(
     }
 
     try {
-      // Calculate confidence
-      const confidence = calculateFieldConfidence(data);
+      // Look up enrichment for this component
+      const enrichment = enrichments.get(comp.name);
+
+      // Calculate confidence (enrichment boosts score)
+      const confidence = calculateFieldConfidence(data, enrichment);
 
       // Compute import path
       const importPath = computeImportPath(
@@ -240,7 +307,8 @@ export async function scanGenerate(
         comp.name,
         importPath,
         data,
-        confidence
+        confidence,
+        enrichment
       );
 
       await writeFile(fragmentPath, content, "utf-8");
@@ -251,6 +319,7 @@ export async function scanGenerate(
         path: relPath,
         confidence: confidence.score,
         todoCount: confidence.todoFields.length,
+        enriched: !!enrichment,
       });
 
       const confColor =
@@ -297,6 +366,14 @@ export async function scanGenerate(
 
   console.log(pc.dim(`  Average confidence: ${avgConfidence}/100`));
 
+  if (options.enrich) {
+    const enrichedCount = generated.filter(g => g.enriched).length;
+    console.log(pc.dim(`  Enriched: ${enrichedCount}/${generated.length} components`));
+    if (enrichmentCost !== undefined && enrichmentCost > 0) {
+      console.log(pc.dim(`  Estimated cost: $${enrichmentCost.toFixed(4)}`));
+    }
+  }
+
   const totalTodos = generated.reduce((sum, g) => sum + g.todoCount, 0);
   if (totalTodos > 0) {
     console.log(
@@ -313,6 +390,7 @@ export async function scanGenerate(
     skipped,
     errors,
     averageConfidence: avgConfidence,
+    enrichmentCost,
   };
 }
 
@@ -453,15 +531,17 @@ function getLeadingJSDoc(
  * Returns the names of sub-components found.
  */
 export async function detectCompoundComponents(
-  filePath: string
+  filePath: string,
+  primaryComponentName?: string
 ): Promise<string[]> {
   const content = await readFile(filePath, "utf-8");
-  return detectCompoundComponentsFromSource(content, filePath);
+  return detectCompoundComponentsFromSource(content, filePath, primaryComponentName);
 }
 
 export function detectCompoundComponentsFromSource(
   source: string,
-  filePath: string
+  filePath: string,
+  primaryComponentName?: string
 ): string[] {
   const sourceFile = ts.createSourceFile(
     filePath,
@@ -502,6 +582,58 @@ export function detectCompoundComponentsFromSource(
   }
 
   ts.forEachChild(sourceFile, visit);
+
+  // Fallback: detect shadcn-style compound exports.
+  // Libraries like shadcn/ui export compound sub-components as separate named exports
+  // that share a prefix: export { Card, CardHeader, CardContent, CardFooter }
+  // Detect these by finding PascalCase exports that start with the primary component name.
+  if (subComponents.length === 0 && primaryComponentName) {
+    const exportedNames: string[] = [];
+
+    // Find export { Name1, Name2, ... } blocks
+    for (const statement of sourceFile.statements) {
+      if (ts.isExportDeclaration(statement) && statement.exportClause) {
+        if (ts.isNamedExports(statement.exportClause)) {
+          for (const element of statement.exportClause.elements) {
+            exportedNames.push(element.name.text);
+          }
+        }
+      }
+      // Also catch `export function CardHeader` / `export const CardHeader`
+      if (ts.isFunctionDeclaration(statement) && statement.name) {
+        const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
+        if (modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+          exportedNames.push(statement.name.text);
+        }
+      }
+      if (ts.isVariableStatement(statement)) {
+        const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
+        if (modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+          for (const decl of statement.declarationList.declarations) {
+            if (ts.isIdentifier(decl.name)) {
+              exportedNames.push(decl.name.text);
+            }
+          }
+        }
+      }
+    }
+
+    // Find exports that start with primaryComponentName but aren't the primary itself
+    // e.g., "Card" → ["CardHeader", "CardFooter", "CardContent", "CardTitle"]
+    const prefix = primaryComponentName;
+    for (const name of exportedNames) {
+      if (
+        name !== prefix &&
+        name.startsWith(prefix) &&
+        /^[A-Z]/.test(name.slice(prefix.length))
+      ) {
+        // Strip the prefix to get the sub-component name
+        const subName = name.slice(prefix.length);
+        subComponents.push(subName);
+      }
+    }
+  }
+
   return subComponents;
 }
 
@@ -587,33 +719,271 @@ function parseArgsBlock(argsBlock: string): Record<string, unknown> {
   return args;
 }
 
+// ---------------------------------------------------------------------------
+// Enrichment: LLM-powered knowledge field generation
+// ---------------------------------------------------------------------------
+
+export function buildEnrichmentSystemPrompt(): string {
+  return `You are a senior frontend architect and design system expert.
+Given a component's metadata (name, description, props, composition), generate knowledge fields that help AI models use the component correctly.
+
+Respond ONLY with a JSON object. No explanation, no markdown outside the JSON.
+
+The JSON must have exactly these fields:
+{
+  "when": ["..."],      // 3-5 scenarios when this component should be used
+  "whenNot": ["..."],   // 2-4 scenarios when NOT to use this component (suggest alternatives)
+  "guidelines": ["..."], // 2-3 usage guidelines or best practices
+  "a11yRules": ["..."], // 2-4 accessibility rules or requirements
+  "scenarioTags": ["..."], // 3-5 dot-notation scenario tags (e.g., "form.input.text", "layout.container.card")
+  "tags": ["..."]       // 3-5 search keywords for component discovery
+}
+
+Rules:
+- "when" items should describe concrete UI scenarios (e.g., "Displaying grouped content with a header, body, and footer")
+- "whenNot" items should name a better alternative (e.g., "Simple text grouping without visual separation — use a div or Stack instead")
+- "guidelines" should be actionable best practices
+- "a11yRules" should reference WCAG or ARIA patterns where relevant
+- "scenarioTags" use dot notation: category.subcategory.detail
+- "tags" should be lowercase single words or short phrases for search
+- Keep each item to 1 sentence. Be specific, not generic.`;
+}
+
+export function buildEnrichmentUserPrompt(
+  name: string,
+  data: ComponentData
+): string {
+  const props = data.meta?.props ?? {};
+  const localProps = Object.entries(props).filter(([_, p]) => p.source === 'local');
+  const composition = data.meta?.composition ?? null;
+  const description = data.meta?.description || '';
+  const category = inferCategoryFromMeta(
+    name,
+    Object.fromEntries(localProps)
+  );
+
+  const lines: string[] = [
+    `Component: ${name}`,
+    `Category: ${category}`,
+  ];
+
+  if (description) {
+    lines.push(`Description: ${description}`);
+  }
+
+  if (localProps.length > 0) {
+    lines.push('');
+    lines.push('Props:');
+    for (const [propName, prop] of localProps) {
+      let propLine = `  - ${propName}: ${prop.typeKind}`;
+      if (prop.values && prop.values.length > 0) {
+        propLine += ` (${prop.values.join(' | ')})`;
+      }
+      if (prop.required) propLine += ' [required]';
+      if (prop.description) propLine += ` — ${prop.description}`;
+      lines.push(propLine);
+    }
+  }
+
+  if (composition && composition.parts.length > 0) {
+    lines.push('');
+    lines.push(`Composition: ${composition.pattern} pattern`);
+    lines.push(`Sub-components: ${composition.parts.map(p => p.name).join(', ')}`);
+  }
+
+  if (data.storyVariants.length > 0) {
+    lines.push('');
+    lines.push(`Known variants: ${data.storyVariants.map(v => v.name).join(', ')}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function parseEnrichmentResponse(text: string): EnrichmentResult {
+  const empty: EnrichmentResult = {
+    when: [],
+    whenNot: [],
+    guidelines: [],
+    a11yRules: [],
+    scenarioTags: [],
+    tags: [],
+  };
+
+  try {
+    // Parse JSON from response, handling ```json fences
+    const jsonMatch = text.match(/```json\n?([\s\S]*?)\n?```/) || text.match(/\{[\s\S]*\}/);
+    const jsonStr = jsonMatch ? (jsonMatch[1] || jsonMatch[0]) : text;
+    const parsed = JSON.parse(jsonStr) as Record<string, unknown>;
+
+    const getArray = (key: string, maxLen: number): string[] => {
+      const val = parsed[key];
+      if (!Array.isArray(val)) return [];
+      return val
+        .filter((item): item is string => typeof item === 'string')
+        .slice(0, maxLen);
+    };
+
+    return {
+      when: getArray('when', 5),
+      whenNot: getArray('whenNot', 4),
+      guidelines: getArray('guidelines', 3),
+      a11yRules: getArray('a11yRules', 4),
+      scenarioTags: getArray('scenarioTags', 5),
+      tags: getArray('tags', 5),
+    };
+  } catch {
+    return empty;
+  }
+}
+
+async function enrichComponents(
+  componentDataList: ComponentData[],
+  options: Pick<ScanGenerateOptions, 'dryRun' | 'provider' | 'apiKey' | 'model'>
+): Promise<{
+  enrichments: Map<string, EnrichmentResult>;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  model: string;
+}> {
+  const enrichments = new Map<string, EnrichmentResult>();
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+
+  const {
+    detectProvider,
+    getApiKey,
+    createAIClient,
+    generateCompletion,
+    ENRICHMENT_MODELS,
+  } = await import('../ai-client.js');
+
+  const provider = detectProvider({ provider: options.provider, apiKey: options.apiKey });
+  if (provider === 'none') {
+    console.log(pc.yellow('  No API key found. Set ANTHROPIC_API_KEY or OPENAI_API_KEY, or use --api-key'));
+    console.log(pc.yellow('  Skipping enrichment — fragment files will have TODO markers instead.\n'));
+    return { enrichments, totalInputTokens: 0, totalOutputTokens: 0, model: '' };
+  }
+
+  const apiKey = getApiKey(provider, options.apiKey);
+  if (!apiKey) {
+    console.log(pc.yellow('  API key not found for provider: ' + provider));
+    console.log(pc.yellow('  Skipping enrichment.\n'));
+    return { enrichments, totalInputTokens: 0, totalOutputTokens: 0, model: '' };
+  }
+
+  const model = options.model || ENRICHMENT_MODELS[provider];
+
+  if (options.dryRun) {
+    for (const data of componentDataList) {
+      console.log(pc.dim(`  Would enrich: ${data.component.name}`));
+    }
+    return { enrichments, totalInputTokens: 0, totalOutputTokens: 0, model };
+  }
+
+  const client = await createAIClient(provider, apiKey);
+  const systemPrompt = buildEnrichmentSystemPrompt();
+
+  for (const data of componentDataList) {
+    const name = data.component.name;
+    process.stdout.write(pc.dim(`  Enriching ${name}...`));
+
+    try {
+      const userPrompt = buildEnrichmentUserPrompt(name, data);
+      const result = await generateCompletion(client, provider, model, systemPrompt, userPrompt, 512);
+
+      totalInputTokens += result.inputTokens;
+      totalOutputTokens += result.outputTokens;
+
+      const enrichment = parseEnrichmentResponse(result.text);
+      const fieldCount =
+        enrichment.when.length +
+        enrichment.whenNot.length +
+        enrichment.guidelines.length +
+        enrichment.a11yRules.length +
+        enrichment.scenarioTags.length +
+        enrichment.tags.length;
+
+      enrichments.set(name, enrichment);
+      process.stdout.write(`\r  ${pc.green('✓')} ${name} (${fieldCount} fields)\n`);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      process.stdout.write(`\r  ${pc.yellow('!')} ${name}: ${msg}\n`);
+    }
+  }
+
+  return { enrichments, totalInputTokens, totalOutputTokens, model };
+}
+
+export function buildEnrichedUsageBlock(enrichment: EnrichmentResult): string {
+  const lines: string[] = [];
+  lines.push('  usage: {');
+
+  if (enrichment.when.length > 0) {
+    lines.push('    when: [');
+    for (const item of enrichment.when) {
+      lines.push(`      '${escapeQuotes(item)}',`);
+    }
+    lines.push('    ],');
+  } else {
+    lines.push('    when: [],');
+  }
+
+  if (enrichment.whenNot.length > 0) {
+    lines.push('    whenNot: [');
+    for (const item of enrichment.whenNot) {
+      lines.push(`      '${escapeQuotes(item)}',`);
+    }
+    lines.push('    ],');
+  } else {
+    lines.push('    whenNot: [],');
+  }
+
+  if (enrichment.guidelines.length > 0) {
+    lines.push('    guidelines: [');
+    for (const item of enrichment.guidelines) {
+      lines.push(`      '${escapeQuotes(item)}',`);
+    }
+    lines.push('    ],');
+  }
+
+  lines.push('  },');
+  return lines.join('\n');
+}
+
 // ---------------------------------------------------------------------------
 // Confidence Scoring
 // ---------------------------------------------------------------------------
 
-export function calculateFieldConfidence(data: ComponentData): FieldConfidence {
+export function calculateFieldConfidence(
+  data: ComponentData,
+  enrichment?: EnrichmentResult
+): FieldConfidence {
   let score = 0;
   const todoFields: string[] = [];
 
+  const props = data.meta?.props ?? {};
+  // Use only local props — inherited HTML/React props inflate confidence
+  // without adding value to the generated fragment output
+  const localEntries = Object.values(props).filter(p => p.source === 'local');
+  const hasProps = localEntries.length > 0;
+
   // Props extracted: +30
-  const hasProps =
-    data.props?.success && data.props.props.length > 0;
   if (hasProps) {
     score += 30;
   }
 
   // JSDoc description found: +15
-  if (data.jsDoc) {
+  if (data.meta?.description) {
     score += 15;
   } else {
     todoFields.push("meta.description");
   }
 
   // Category inferred from path/name (not fallback): +10
-  const category = inferCategory(
-    data.component.name,
-    data.props?.success ? data.props.props : []
+  const localProps = Object.fromEntries(
+    Object.entries(props).filter(([_, p]) => p.source === 'local')
   );
+  const category = inferCategoryFromMeta(data.component.name, localProps);
   if (category !== "Components") {
     score += 10;
   } else {
@@ -627,32 +997,45 @@ export function calculateFieldConfidence(data: ComponentData): FieldConfidence {
 
   // All prop types resolved (no "custom"): +10
   if (hasProps) {
-    const allResolved = data.props!.props.every(
-      (p) => p.propType.type !== "custom"
-    );
+    const allResolved = localEntries.every((p) => p.typeKind !== "custom");
     if (allResolved) {
       score += 10;
     }
   }
 
-  // Compound component detected: +5
-  if (data.compoundChildren.length > 0) {
-    score += 5;
+  // Compound component detected with sub-component props: +10
+  if (data.meta?.composition && data.meta.composition.parts.length > 0) {
+    score += 10;
   }
 
   // Has default values: +5
   if (hasProps) {
-    const hasDefaults = data.props!.props.some(
-      (p) => p.defaultValue !== undefined
-    );
+    const hasDefaults = localEntries.some((p) => p.default !== undefined);
     if (hasDefaults) {
       score += 5;
     }
   }
 
-  // usage.when and usage.whenNot always get TODOs (human knowledge needed)
-  todoFields.push("usage.when");
-  todoFields.push("usage.whenNot");
+  // Enrichment bonuses — if LLM filled these, they're no longer TODOs
+  if (enrichment && enrichment.when.length > 0) {
+    score += 10;
+  } else {
+    todoFields.push("usage.when");
+  }
+
+  if (enrichment && enrichment.whenNot.length > 0) {
+    score += 5;
+  } else {
+    todoFields.push("usage.whenNot");
+  }
+
+  if (enrichment && enrichment.guidelines.length > 0) {
+    score += 5;
+  }
+
+  if (enrichment && enrichment.tags.length > 0) {
+    score += 5;
+  }
 
   return { score: Math.min(score, 100), todoFields };
 }
@@ -691,9 +1074,9 @@ const CATEGORY_PATTERNS: Record<string, string[]> = {
   Media: ["image", "video", "icon", "carousel"],
 };
 
-function inferCategory(
+function inferCategoryFromMeta(
   componentName: string,
-  props: ExtractedProp[]
+  props: Record<string, PropMeta>
 ): string {
   const lower = componentName.toLowerCase();
 
@@ -706,7 +1089,7 @@ function inferCategory(
   }
 
   // Prop-based fallbacks
-  const propNames = new Set(props.map((p) => p.name));
+  const propNames = new Set(Object.keys(props));
   if (propNames.has("onClick") || propNames.has("onPress")) return "Actions";
   if (propNames.has("value") || propNames.has("defaultValue")) return "Forms";
   if (propNames.has("children")) return "Layout";
@@ -728,16 +1111,16 @@ function inferStatus(
   return "stable";
 }
 
-function inferDescription(
+function inferDescriptionFromMeta(
   componentName: string,
-  props: ExtractedProp[]
+  props: Record<string, PropMeta>
 ): string {
   const words = componentName
     .replace(/([A-Z])/g, " $1")
     .trim()
     .toLowerCase();
 
-  const propNames = new Set(props.map((p) => p.name));
+  const propNames = new Set(Object.keys(props));
   const hasOnClick =
     propNames.has("onClick") || propNames.has("onPress");
   const hasValue =
@@ -751,11 +1134,11 @@ function inferDescription(
   return `${words.charAt(0).toUpperCase() + words.slice(1)} component`;
 }
 
-function inferAccessibility(props: ExtractedProp[]): {
+function inferAccessibilityFromMeta(props: Record<string, PropMeta>): {
   role?: string;
   requirements?: string[];
 } {
-  const propNames = new Set(props.map((p) => p.name));
+  const propNames = new Set(Object.keys(props));
   const accessibility: { role?: string; requirements?: string[] } = {};
 
   const hasOnClick =
@@ -780,6 +1163,152 @@ function inferAccessibility(props: ExtractedProp[]): {
   return accessibility;
 }
 
+// ---------------------------------------------------------------------------
+// Contract Block Generation
+// ---------------------------------------------------------------------------
+
+interface ContractBlock {
+  propsSummary: string[];
+  compoundChildren?: Record<string, {
+    required?: boolean;
+    accepts?: string[];
+    description?: string;
+  }>;
+  canonicalUsage?: string[];
+  a11yRules?: string[];
+  scenarioTags?: string[];
+}
+
+function buildContractBlock(
+  componentName: string,
+  props: Record<string, PropMeta>,
+  composition: CompositionMeta | null,
+  accessibility: { role?: string; requirements?: string[] }
+): ContractBlock | null {
+  const localEntries = Object.entries(props).filter(([_, p]) => p.source === 'local');
+  if (localEntries.length === 0 && !composition && !accessibility.requirements?.length) {
+    return null;
+  }
+
+  const contract: ContractBlock = { propsSummary: [] };
+
+  // propsSummary: "propName: value1 | value2 | value3" for enums, "propName: type" otherwise
+  for (const [name, prop] of localEntries) {
+    let summary = name + ': ';
+    if (prop.typeKind === 'enum' && prop.values && prop.values.length > 0) {
+      summary += prop.values.join(' | ');
+    } else {
+      summary += prop.typeKind;
+    }
+    if (prop.required) summary += ' (required)';
+    if (prop.default !== undefined) summary += ` (default: ${prop.default})`;
+    contract.propsSummary.push(summary);
+  }
+
+  // compoundChildren: built from CompositionMeta.parts[]
+  if (composition && composition.parts.length > 0) {
+    const children: Record<string, { required?: boolean; accepts?: string[]; description?: string }> = {};
+    for (const part of composition.parts) {
+      const childEntry: { required?: boolean; accepts?: string[]; description?: string } = {};
+      if (composition.required.includes(part.name)) {
+        childEntry.required = true;
+      }
+      // Infer accepts from ReactNode-type props on the sub-component
+      const nodeProps = Object.entries(part.props)
+        .filter(([_, p]) => p.typeKind === 'node' || p.typeKind === 'element')
+        .map(([n]) => n);
+      if (nodeProps.length > 0) {
+        childEntry.accepts = nodeProps;
+      }
+      children[part.name] = childEntry;
+    }
+    contract.compoundChildren = children;
+  }
+
+  // canonicalUsage: generate 1 JSX snippet using actual component + sub-component names
+  if (composition && composition.parts.length > 0) {
+    const innerLines = composition.parts
+      .map(part => `  <${componentName}.${part.name}>...</${componentName}.${part.name}>`)
+      .join('\n');
+    contract.canonicalUsage = [
+      `<${componentName}>\n${innerLines}\n</${componentName}>`,
+    ];
+  }
+
+  // a11yRules: from accessibility inference
+  const rules: string[] = [];
+  if (accessibility.role) {
+    rules.push(`Role: ${accessibility.role}`);
+  }
+  if (accessibility.requirements) {
+    rules.push(...accessibility.requirements);
+  }
+  if (rules.length > 0) {
+    contract.a11yRules = rules;
+  }
+
+  return contract;
+}
+
+function emitContractBlock(contract: ContractBlock): string {
+  const lines: string[] = [];
+  lines.push('\n  contract: {');
+
+  // propsSummary
+  if (contract.propsSummary.length > 0) {
+    lines.push('    propsSummary: [');
+    for (const s of contract.propsSummary) {
+      lines.push(`      '${escapeQuotes(s)}',`);
+    }
+    lines.push('    ],');
+  }
+
+  // compoundChildren
+  if (contract.compoundChildren && Object.keys(contract.compoundChildren).length > 0) {
+    lines.push('    compoundChildren: {');
+    for (const [name, meta] of Object.entries(contract.compoundChildren)) {
+      const fields: string[] = [];
+      if (meta.required) fields.push(`required: true`);
+      if (meta.accepts && meta.accepts.length > 0) {
+        fields.push(`accepts: [${meta.accepts.map(a => `'${a}'`).join(', ')}]`);
+      }
+      if (meta.description) fields.push(`description: '${escapeQuotes(meta.description)}'`);
+      lines.push(`      ${name}: { ${fields.join(', ')} },`);
+    }
+    lines.push('    },');
+  }
+
+  // canonicalUsage
+  if (contract.canonicalUsage && contract.canonicalUsage.length > 0) {
+    lines.push('    canonicalUsage: [');
+    for (const usage of contract.canonicalUsage) {
+      lines.push(`      \`${usage}\`,`);
+    }
+    lines.push('    ],');
+  }
+
+  // a11yRules
+  if (contract.a11yRules && contract.a11yRules.length > 0) {
+    lines.push('    a11yRules: [');
+    for (const rule of contract.a11yRules) {
+      lines.push(`      '${escapeQuotes(rule)}',`);
+    }
+    lines.push('    ],');
+  }
+
+  // scenarioTags
+  if (contract.scenarioTags && contract.scenarioTags.length > 0) {
+    lines.push('    scenarioTags: [');
+    for (const tag of contract.scenarioTags) {
+      lines.push(`      '${escapeQuotes(tag)}',`);
+    }
+    lines.push('    ],');
+  }
+
+  lines.push('  },');
+  return lines.join('\n');
+}
+
 // ---------------------------------------------------------------------------
 // Import path computation
 // ---------------------------------------------------------------------------
@@ -821,77 +1350,111 @@ function generateFragmentWithTodos(
   componentName: string,
   importPath: string,
   data: ComponentData,
-  confidence: FieldConfidence
+  confidence: FieldConfidence,
+  enrichment?: EnrichmentResult
 ): string {
-  const props = data.props?.success ? data.props.props : [];
-  const isDefaultExport = data.props?.success
-    ? !data.props.propsTypeName // heuristic: if no explicit props type, might be default export
-    : false;
-  // For scan-generated files we always use named import
-  const description = data.jsDoc || inferDescription(componentName, props);
-  const descriptionTodo = data.jsDoc ? "" : " // TODO: Review description";
-  const category = inferCategory(componentName, props);
+  const props = data.meta?.props ?? {};
+  // Use only local props for inference — inherited HTML/React props cause
+  // wrong descriptions (e.g., Card getting "Form card for user input" from
+  // inherited defaultValue) and wrong roles (e.g., Card getting role: 'button'
+  // from inherited onClick)
+  const localProps = Object.fromEntries(
+    Object.entries(props).filter(([_, p]) => p.source === 'local')
+  );
+  const composition = data.meta?.composition ?? null;
+  const description = data.meta?.description || inferDescriptionFromMeta(componentName, localProps);
+  const descriptionTodo = data.meta?.description ? "" : " // TODO: Review description";
+  const category = inferCategoryFromMeta(componentName, localProps);
   const categoryTodo = category === "Components" ? " // TODO: Set correct category" : "";
   const status = inferStatus(data.component.sourcePath);
-  const accessibility = inferAccessibility(props);
+  const accessibility = inferAccessibilityFromMeta(localProps);
+
+  // Build props block from PropMeta
+  const propsBlock = buildPropsBlockFromMeta(props);
+
+  // Build contract block — enrichment can replace/augment a11yRules and add scenarioTags
+  const contract = buildContractBlock(componentName, props, composition, accessibility);
+  if (contract && enrichment) {
+    if (enrichment.a11yRules.length > 0) {
+      contract.a11yRules = enrichment.a11yRules;
+    }
+    if (enrichment.scenarioTags.length > 0) {
+      contract.scenarioTags = enrichment.scenarioTags;
+    }
+  }
+  const contractBlock = contract ? emitContractBlock(contract) : '';
 
-  // Build props block
-  const propsBlock = buildPropsBlock(props);
+  // Build usage block — enriched or TODO markers
+  let usageBlock: string;
+  if (enrichment && (enrichment.when.length > 0 || enrichment.whenNot.length > 0)) {
+    usageBlock = buildEnrichedUsageBlock(enrichment);
+  } else {
+    usageBlock = `  usage: {
+    when: [
+      // TODO: Describe when to use ${componentName}
+    ],
+    whenNot: [
+      // TODO: Describe when NOT to use ${componentName}
+    ],
+  },`;
+  }
 
-  // Build accessibility block
-  const accessibilityBlock = buildAccessibilityBlock(accessibility);
+  // Build meta.tags from enrichment
+  const tagsLine = enrichment && enrichment.tags.length > 0
+    ? `\n    tags: [${enrichment.tags.map(t => `'${escapeQuotes(t)}'`).join(', ')}],`
+    : '';
 
-  // Build variants
+  // Build variants (compound-aware)
   const variantsBlock = buildVariantsBlock(
     componentName,
-    data.storyVariants
+    data.storyVariants,
+    composition
   );
 
-  // Build compound children comment
-  const compoundComment =
-    data.compoundChildren.length > 0
-      ? `\n  // Compound sub-components detected: ${data.compoundChildren.join(", ")}`
-      : "";
+  // Build AI metadata block with composition info
+  const aiBlock = buildAIBlock(composition);
+
+  // Build provenance block
+  const provenanceBlock = buildProvenanceBlock(confidence, props);
+
+  // Build compound sub-components comment
+  const compoundComment = composition && composition.parts.length > 0
+    ? `\n// Compound sub-components detected: ${composition.parts.map(p => p.name).join(', ')}`
+    : '';
 
   return `// Auto-generated by fragments init --scan | Confidence: ${confidence.score}/100
-// ${confidence.todoFields.length} TODO(s) — search for "TODO:" and fill in human knowledge
+// ${confidence.todoFields.length} TODO(s) — search for "TODO:" and fill in human knowledge${compoundComment}
 import React from 'react';
 import { defineFragment } from '@fragments-sdk/core';
 import { ${componentName} } from '${importPath}';
 
 export default defineFragment({
   component: ${componentName},
-${compoundComment}
+
   meta: {
     name: '${escapeQuotes(componentName)}',
     description: '${escapeQuotes(description)}',${descriptionTodo}
     category: '${escapeQuotes(category)}',${categoryTodo}
-    status: '${status}',
+    status: '${status}',${tagsLine}
   },
 
-  usage: {
-    when: [
-      // TODO: Describe when to use ${componentName}
-    ],
-    whenNot: [
-      // TODO: Describe when NOT to use ${componentName}
-    ],
-  },
+${usageBlock}
 
-  props: ${propsBlock},${accessibilityBlock}
+  props: ${propsBlock},${contractBlock}${aiBlock}
 
   variants: [
 ${variantsBlock}
   ],
-});
+${provenanceBlock}});
 `;
 }
 
-function buildPropsBlock(props: ExtractedProp[]): string {
-  if (props.length === 0) return "{}";
+function buildPropsBlockFromMeta(props: Record<string, PropMeta>): string {
+  const entries = Object.entries(props).filter(([_, p]) => p.source === 'local');
+  if (entries.length === 0) return "{}";
 
-  const lines = props.map((prop) => {
-    const type = prop.propType.type;
+  const lines = entries.map(([name, prop]) => {
+    const type = prop.typeKind;
     const parts: string[] = [`      type: '${type}'`];
 
     if (prop.description) {
@@ -902,58 +1465,39 @@ function buildPropsBlock(props: ExtractedProp[]): string {
 
     parts.push(`      required: ${prop.required}`);
 
-    if (prop.defaultValue !== undefined) {
-      parts.push(`      default: ${JSON.stringify(prop.defaultValue)}`);
+    if (prop.default !== undefined) {
+      parts.push(`      default: ${JSON.stringify(prop.default)}`);
     }
 
-    if (prop.enumValues && prop.enumValues.length > 0) {
-      parts.push(`      values: ${JSON.stringify(prop.enumValues)}`);
+    if (prop.values && prop.values.length > 0) {
+      parts.push(`      values: ${JSON.stringify(prop.values)}`);
     }
 
     const todoComment =
       type === "custom" ? " // TODO: Review type" : "";
 
-    return `    ${prop.name}: {\n${parts.join(",\n")},\n    },${todoComment}`;
+    return `    ${name}: {\n${parts.join(",\n")},\n    },${todoComment}`;
   });
 
   return `{\n${lines.join("\n")}\n  }`;
 }
 
-function buildAccessibilityBlock(accessibility: {
-  role?: string;
-  requirements?: string[];
-}): string {
-  if (
-    !accessibility.role &&
-    (!accessibility.requirements || accessibility.requirements.length === 0)
-  ) {
-    return "";
-  }
-
-  const parts: string[] = [];
-  if (accessibility.role) {
-    parts.push(`    role: '${accessibility.role}'`);
-  }
-  if (accessibility.requirements && accessibility.requirements.length > 0) {
-    const reqs = accessibility.requirements
-      .map((r) => `'${escapeQuotes(r)}'`)
-      .join(", ");
-    parts.push(`    requirements: [${reqs}]`);
-  }
-
-  return `\n\n  accessibility: {\n${parts.join(",\n")},\n  },`;
-}
-
 function buildVariantsBlock(
   componentName: string,
-  storyVariants: StoryVariant[]
+  storyVariants: StoryVariant[],
+  composition?: CompositionMeta | null
 ): string {
   const entries: string[] = [];
 
   // Always include a Default variant
   const hasDefault = storyVariants.some((v) => v.name === "Default");
   if (!hasDefault) {
-    entries.push(formatVariantEntry(componentName, "Default", `Default ${componentName}`, {}));
+    if (composition && composition.pattern === 'compound' && composition.parts.length > 0) {
+      // Generate a compound-aware default variant
+      entries.push(formatCompoundVariantEntry(componentName, composition));
+    } else {
+      entries.push(formatVariantEntry(componentName, "Default", `Default ${componentName}`, {}));
+    }
   }
 
   for (const variant of storyVariants) {
@@ -986,6 +1530,63 @@ function formatVariantEntry(
     },`;
 }
 
+/**
+ * Generate a compound-aware default variant showing sub-component usage.
+ */
+function formatCompoundVariantEntry(
+  componentName: string,
+  composition: CompositionMeta
+): string {
+  const parts = composition.parts;
+  const innerJsx = parts
+    .map((part) => `    <${componentName}.${part.name}>...</${componentName}.${part.name}>`)
+    .join('\n');
+
+  const jsxCode = `<${componentName}>\n${innerJsx}\n  </${componentName}>`;
+
+  return `    {
+      name: 'Default',
+      description: 'Default ${componentName} with sub-components',
+      code: \`${jsxCode}\`,
+      render: () => (\n        ${jsxCode}\n      ),
+    },`;
+}
+
+/**
+ * Build the ai block with composition metadata.
+ */
+function buildAIBlock(composition: CompositionMeta | null): string {
+  if (!composition || composition.parts.length === 0) return "";
+
+  const subComponents = composition.parts.map((p) => `'${p.name}'`).join(', ');
+  const pattern = `\n      <Component>\n${composition.parts.map((p) => `        <Component.${p.name}>...</Component.${p.name}>`).join('\n')}\n      </Component>`;
+
+  return `
+
+  ai: {
+    compositionPattern: '${composition.pattern}',
+    subComponents: [${subComponents}],
+    commonPatterns: [\`${pattern}\n    \`],
+  },`;
+}
+
+/**
+ * Build _generated provenance block.
+ */
+function buildProvenanceBlock(
+  confidence: FieldConfidence,
+  props: Record<string, PropMeta>
+): string {
+  const autoFields = Object.keys(props).filter((name) => props[name].source === 'local');
+  return `
+  _generated: {
+    source: 'ai',
+    confidence: ${(confidence.score / 100).toFixed(2)},
+    timestamp: '${new Date().toISOString()}',
+  },
+`;
+}
+
 function buildJsxString(
   componentName: string,
   args: Record<string, unknown>