@fragments-sdk/cli 0.11.1 → 0.12.1

package/src/core/discovery.ts

@@ -5,6 +5,60 @@ import fg from 'fast-glob';
 import { BRAND } from '@fragments-sdk/core';
 import type { FragmentsConfig } from '@fragments-sdk/core';
 
+/**
+ * Convert a lowercase file name to PascalCase component name.
+ * e.g., "button" → "Button", "date-picker" → "DatePicker"
+ */
+function toPascalCase(name: string): string {
+  return name
+    .split(/[-_]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+/**
+ * Extract PascalCase named exports from a source file using regex.
+ * Finds patterns like:
+ * - `export function Button`
+ * - `export const Button`
+ * - `export { Button, CardHeader }` (from export blocks)
+ * - `function Button` + later `export { Button }` (shadcn pattern)
+ */
+async function extractPascalCaseExports(filePath: string): Promise<string[]> {
+  try {
+    const content = await readFile(filePath, 'utf-8');
+    const exports = new Set<string>();
+
+    // Pattern 1: export function ComponentName
+    const exportFuncRegex = /export\s+function\s+([A-Z][a-zA-Z0-9]*)/g;
+    let match;
+    while ((match = exportFuncRegex.exec(content)) !== null) {
+      exports.add(match[1]);
+    }
+
+    // Pattern 2: export const ComponentName
+    const exportConstRegex = /export\s+const\s+([A-Z][a-zA-Z0-9]*)/g;
+    while ((match = exportConstRegex.exec(content)) !== null) {
+      exports.add(match[1]);
+    }
+
+    // Pattern 3: export { Name1, Name2, ... }
+    const exportBlockRegex = /export\s*\{([^}]+)\}/g;
+    while ((match = exportBlockRegex.exec(content)) !== null) {
+      const names = match[1].split(',').map((n) => n.trim().split(/\s+as\s+/)[0].trim());
+      for (const name of names) {
+        if (/^[A-Z]/.test(name)) {
+          exports.add(name);
+        }
+      }
+    }
+
+    return Array.from(exports);
+  } catch {
+    return [];
+  }
+}
+
 export interface DiscoveredFile {
   /** Absolute path to the file */
   absolutePath: string;
@@ -180,11 +234,18 @@ export async function discoverComponentsFromSource(
     absolute: false,
   });
 
-  // Filter to only component-like files (start with uppercase)
-  const componentFiles = files.filter((file) => {
+  // Separate files into PascalCase (existing behavior) and lowercase (new: parse exports)
+  const pascalCaseFiles: string[] = [];
+  const lowercaseFiles: string[] = [];
+
+  for (const file of files) {
     const name = extractComponentName(file);
-    return /^[A-Z]/.test(name);
-  });
+    if (/^[A-Z]/.test(name)) {
+      pascalCaseFiles.push(file);
+    } else if (/^[a-z]/.test(name)) {
+      lowercaseFiles.push(file);
+    }
+  }
 
   // Find associated story files
   const storyPatterns = [
@@ -209,11 +270,10 @@ export async function discoverComponentsFromSource(
   // Build discovered components
   const components: DiscoveredComponent[] = [];
 
-  for (const file of componentFiles) {
+  // Add PascalCase-named files directly (existing behavior)
+  for (const file of pascalCaseFiles) {
     const name = extractComponentName(file);
     const absolutePath = resolve(configDir, file);
-
-    // Look for story file
     const storyFile = storyMap.get(name);
 
     components.push({
@@ -224,6 +284,32 @@ export async function discoverComponentsFromSource(
     });
   }
 
+  // For lowercase files (e.g., shadcn's button.tsx, card.tsx), extract the
+  // primary PascalCase export as the component name. This discovers components
+  // from libraries that use lowercase file names.
+  for (const file of lowercaseFiles) {
+    const absolutePath = resolve(configDir, file);
+    const fileName = extractComponentName(file);
+    const pascalName = toPascalCase(fileName);
+
+    // Parse exports from the file to find PascalCase component names
+    const exports = await extractPascalCaseExports(absolutePath);
+
+    // Use the primary component: prefer the PascalCase version of the file name,
+    // otherwise take the first PascalCase export
+    const primaryExport = exports.find((e) => e === pascalName) || exports[0];
+    if (primaryExport) {
+      const storyFile = storyMap.get(primaryExport) || storyMap.get(fileName);
+
+      components.push({
+        name: primaryExport,
+        sourcePath: absolutePath,
+        relativePath: file,
+        storyPath: storyFile ? resolve(configDir, storyFile) : undefined,
+      });
+    }
+  }
+
   // Sort by name
   components.sort((a, b) => a.name.localeCompare(b.name));
 

package/src/service/enhance/props-extractor.ts

@@ -68,6 +68,8 @@ export interface PropsExtractionOptions {
   propsTypeName?: string;
   /** Include inherited props from extended interfaces */
   includeInherited?: boolean;
+  /** Explicit component name (for lowercase file names like shadcn's button.tsx → "Button") */
+  componentName?: string;
 }
 
 /**
@@ -103,7 +105,7 @@ export function extractPropsFromSource(
 ): PropsExtractionResult {
   const { propsTypeName } = options;
 
-  const componentName = inferComponentName(filePath);
+  const componentName = options.componentName || inferComponentName(filePath);
   const result: PropsExtractionResult = {
     filePath,
     componentName,
@@ -156,23 +158,34 @@ export function extractPropsFromSource(
     );
   }
 
-  if (!propsDecl) {
-    result.warnings.push(
-      `No props type found for ${componentName}. Looked for: ${targetName}`
-    );
+  if (propsDecl) {
+    result.propsTypeName = propsDecl.name;
+
+    // Extract props from the declaration
+    if (ts.isInterfaceDeclaration(propsDecl.node)) {
+      extractPropsFromInterface(propsDecl.node, sourceFile, result);
+    } else if (ts.isTypeAliasDeclaration(propsDecl.node)) {
+      extractPropsFromTypeAlias(propsDecl.node, sourceFile, result);
+    }
+
+    result.success = result.props.length > 0;
     return result;
   }
 
-  result.propsTypeName = propsDecl.name;
-
-  // Extract props from the declaration
-  if (ts.isInterfaceDeclaration(propsDecl.node)) {
-    extractPropsFromInterface(propsDecl.node, sourceFile, result);
-  } else if (ts.isTypeAliasDeclaration(propsDecl.node)) {
-    extractPropsFromTypeAlias(propsDecl.node, sourceFile, result);
+  // Fallback: extract props from inline function parameter types.
+  // This handles libraries like shadcn/ui that use inline types:
+  //   function Button({ variant = "default", ...props }: React.ComponentProps<"button"> & { asChild?: boolean })
+  const inlineProps = extractPropsFromInlineParams(componentName, sourceFile);
+  if (inlineProps.length > 0) {
+    result.props = inlineProps;
+    result.propsTypeName = `${componentName}(inline)`;
+    result.success = true;
+    return result;
   }
 
-  result.success = result.props.length > 0;
+  result.warnings.push(
+    `No props type found for ${componentName}. Looked for: ${targetName}`
+  );
   return result;
 }
 
@@ -544,6 +557,215 @@ function parseTypeNode(
   };
 }
 
+/**
+ * Extract props from inline function parameter types.
+ *
+ * Handles the pattern common in shadcn/ui and similar libraries:
+ *   function Button({ variant = "default", size, ...props }: SomeType & { asChild?: boolean })
+ *
+ * Extracts:
+ * 1. Destructured parameter names with default values
+ * 2. Properties from inline type literal members in intersection types
+ * 3. Variant enum values from cva() definitions in the same file
+ */
+function extractPropsFromInlineParams(
+  componentName: string,
+  sourceFile: ts.SourceFile
+): ExtractedProp[] {
+  const props: ExtractedProp[] = [];
+  const seen = new Set<string>();
+
+  // Find the main component function declaration
+  let targetFunc: ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression | undefined;
+
+  ts.forEachChild(sourceFile, (node) => {
+    // function ComponentName(...)
+    if (ts.isFunctionDeclaration(node) && node.name?.text === componentName) {
+      targetFunc = node;
+    }
+    // const ComponentName = (...) => ...
+    if (ts.isVariableStatement(node)) {
+      for (const decl of node.declarationList.declarations) {
+        if (
+          ts.isIdentifier(decl.name) &&
+          decl.name.text === componentName &&
+          decl.initializer &&
+          (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer))
+        ) {
+          targetFunc = decl.initializer;
+        }
+      }
+    }
+  });
+
+  if (!targetFunc || targetFunc.parameters.length === 0) return props;
+
+  const firstParam = targetFunc.parameters[0];
+
+  // Extract destructured parameter names and defaults
+  if (ts.isObjectBindingPattern(firstParam.name)) {
+    for (const element of firstParam.name.elements) {
+      if (ts.isBindingElement(element) && ts.isIdentifier(element.name)) {
+        const name = element.name.text;
+        if (name === 'props' || name === 'rest' || name.startsWith('_')) continue;
+
+        // Skip common passthrough props
+        if (name === 'className' || name === 'children' || name === 'ref') continue;
+
+        if (seen.has(name)) continue;
+        seen.add(name);
+
+        const hasDefault = element.initializer !== undefined;
+        let defaultValue: unknown = undefined;
+        let enumValues: string[] | undefined;
+        let propType: PropType = { type: 'string' };
+
+        if (element.initializer) {
+          if (ts.isStringLiteral(element.initializer)) {
+            defaultValue = element.initializer.text;
+          } else if (element.initializer.kind === ts.SyntaxKind.TrueKeyword) {
+            defaultValue = true;
+            propType = { type: 'boolean' };
+          } else if (element.initializer.kind === ts.SyntaxKind.FalseKeyword) {
+            defaultValue = false;
+            propType = { type: 'boolean' };
+          } else if (ts.isNumericLiteral(element.initializer)) {
+            defaultValue = Number(element.initializer.text);
+            propType = { type: 'number' };
+          }
+        }
+
+        const prop: ExtractedProp = {
+          name,
+          type: propType.type,
+          propType,
+          description: '',
+          required: !hasDefault && !element.dotDotDotToken,
+        };
+
+        if (defaultValue !== undefined) prop.defaultValue = defaultValue;
+        if (enumValues) prop.enumValues = enumValues;
+
+        props.push(prop);
+      }
+    }
+  }
+
+  // Extract from inline type literal in intersection types
+  // e.g., React.ComponentProps<"button"> & { asChild?: boolean }
+  if (firstParam.type) {
+    extractFromInlineType(firstParam.type, sourceFile, props, seen);
+  }
+
+  // Look for cva() definitions to extract variant enum values
+  extractCvaVariants(sourceFile, props);
+
+  return props;
+}
+
+/**
+ * Extract properties from inline type annotations (intersection types, type literals)
+ */
+function extractFromInlineType(
+  typeNode: ts.TypeNode,
+  sourceFile: ts.SourceFile,
+  props: ExtractedProp[],
+  seen: Set<string>
+): void {
+  if (ts.isIntersectionTypeNode(typeNode)) {
+    for (const type of typeNode.types) {
+      extractFromInlineType(type, sourceFile, props, seen);
+    }
+  } else if (ts.isTypeLiteralNode(typeNode)) {
+    for (const member of typeNode.members) {
+      if (ts.isPropertySignature(member) && ts.isIdentifier(member.name)) {
+        const name = member.name.text;
+        if (seen.has(name) || name === 'className' || name === 'children') continue;
+        seen.add(name);
+
+        const prop = extractPropFromSignature(member, sourceFile);
+        if (prop) props.push(prop);
+      }
+    }
+  }
+}
+
+/**
+ * Extract variant enum values from cva() definitions in the file.
+ * shadcn uses class-variance-authority (cva) to define variants.
+ * This enriches discovered props with the actual enum values.
+ */
+function extractCvaVariants(
+  sourceFile: ts.SourceFile,
+  props: ExtractedProp[]
+): void {
+  const cvaVariants = new Map<string, string[]>();
+
+  function visitCva(node: ts.Node): void {
+    // Look for cva(..., { variants: { variant: { ... }, size: { ... } } })
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === 'cva' &&
+      node.arguments.length >= 2
+    ) {
+      const configArg = node.arguments[1];
+      if (ts.isObjectLiteralExpression(configArg)) {
+        for (const prop of configArg.properties) {
+          if (
+            ts.isPropertyAssignment(prop) &&
+            ts.isIdentifier(prop.name) &&
+            prop.name.text === 'variants' &&
+            ts.isObjectLiteralExpression(prop.initializer)
+          ) {
+            for (const variantProp of prop.initializer.properties) {
+              if (
+                ts.isPropertyAssignment(variantProp) &&
+                ts.isIdentifier(variantProp.name) &&
+                ts.isObjectLiteralExpression(variantProp.initializer)
+              ) {
+                const variantName = variantProp.name.text;
+                const values: string[] = [];
+                for (const valueProp of variantProp.initializer.properties) {
+                  if (ts.isPropertyAssignment(valueProp)) {
+                    const key = valueProp.name;
+                    if (ts.isIdentifier(key)) {
+                      values.push(key.text);
+                    } else if (ts.isStringLiteral(key)) {
+                      values.push(key.text);
+                    } else if (ts.isComputedPropertyName(key)) {
+                      const expr = key.expression;
+                      if (ts.isStringLiteral(expr)) {
+                        values.push(expr.text);
+                      }
+                    }
+                  }
+                }
+                if (values.length > 0) {
+                  cvaVariants.set(variantName, values);
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visitCva);
+  }
+
+  ts.forEachChild(sourceFile, visitCva);
+
+  // Enrich existing props with cva variant values
+  for (const prop of props) {
+    const values = cvaVariants.get(prop.name);
+    if (values && values.length > 0) {
+      prop.enumValues = values;
+      prop.propType = { type: 'enum', values };
+      prop.type = values.map((v) => `"${v}"`).join(' | ');
+    }
+  }
+}
+
 /**
  * Infer component name from file path
  */

package/src/validators.ts

@@ -6,6 +6,10 @@ import {
   loadFragmentFile,
 } from './core/node.js';
 import { validateSnippetPolicy, type SnippetValidationOptions } from './service/snippet-validation.js';
+import { createComponentExtractor, type ComponentMeta, type PropMeta } from './core/component-extractor.js';
+import { resolveComponentSourcePath } from './core/auto-props.js';
+import { parseFragmentFile } from './core/parser.js';
+import { readFile } from 'node:fs/promises';
 
 export interface ValidationResult {
   valid: boolean;
@@ -198,3 +202,235 @@ export async function validateSnippets(
     warnings: snippetResult.warnings,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Drift Detection
+// ---------------------------------------------------------------------------
+
+/** A single prop drift finding */
+export interface DriftItem {
+  prop: string;
+  kind: 'added' | 'removed' | 'type_changed' | 'required_changed' | 'values_changed' | 'default_changed';
+  source: string;
+  fragment: string;
+}
+
+/** Drift result for a single component */
+export interface DriftReport {
+  component: string;
+  file: string;
+  drifts: DriftItem[];
+  compositionDrift: string | null;
+}
+
+/** Full drift validation result */
+export interface DriftValidationResult extends ValidationResult {
+  reports: DriftReport[];
+}
+
+/**
+ * Validate drift — detect metadata discrepancies between component source and fragment files.
+ *
+ * Compares auto-extracted props/composition from the component source against what's
+ * documented in the fragment file. Reports:
+ * - Props in source but missing from fragment (added)
+ * - Props in fragment but removed from source (removed)
+ * - Type/required/values/default changes
+ * - Composition pattern changes
+ */
+export async function validateDrift(
+  config: FragmentsConfig,
+  configDir: string,
+  options: { tsconfig?: string } = {}
+): Promise<DriftValidationResult> {
+  const fragmentFiles = await discoverFragmentFiles(config, configDir);
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+  const reports: DriftReport[] = [];
+
+  if (fragmentFiles.length === 0) {
+    return { valid: true, errors, warnings, reports };
+  }
+
+  const extractor = createComponentExtractor(options.tsconfig);
+
+  try {
+    for (const file of fragmentFiles) {
+      try {
+        // Load the fragment to get documented props
+        const fragment = await loadFragmentFile(file.absolutePath);
+        if (!fragment?.meta?.name) continue;
+
+        // Parse the fragment file to find the component import path
+        const fileContent = await readFile(file.absolutePath, 'utf-8');
+        const parsed = parseFragmentFile(fileContent, file.absolutePath);
+        if (!parsed.componentImport) continue;
+
+        // Resolve the component source path
+        const sourcePath = resolveComponentSourcePath(file.absolutePath, parsed.componentImport);
+        if (!sourcePath) continue;
+
+        // Extract current state from source
+        const meta = extractor.extract(sourcePath, fragment.meta.name);
+        if (!meta) continue;
+
+        // Compare props
+        const drifts = diffProps(fragment.props, meta.props);
+
+        // Compare composition
+        let compositionDrift: string | null = null;
+        const fragmentAi = fragment.ai;
+        if (meta.composition && !fragmentAi?.compositionPattern) {
+          compositionDrift = `Source has "${meta.composition.pattern}" composition but fragment has no ai.compositionPattern`;
+        } else if (!meta.composition && fragmentAi?.compositionPattern) {
+          compositionDrift = `Fragment declares "${fragmentAi.compositionPattern}" but source has no compound pattern`;
+        } else if (meta.composition && fragmentAi?.compositionPattern &&
+          meta.composition.pattern !== fragmentAi.compositionPattern) {
+          compositionDrift = `Composition pattern changed: fragment="${fragmentAi.compositionPattern}" source="${meta.composition.pattern}"`;
+        }
+
+        if (drifts.length > 0 || compositionDrift) {
+          const report: DriftReport = {
+            component: fragment.meta.name,
+            file: file.relativePath,
+            drifts,
+            compositionDrift,
+          };
+          reports.push(report);
+
+          // Classify drift items as errors (removed props) or warnings (added/changed props)
+          for (const drift of drifts) {
+            if (drift.kind === 'removed') {
+              errors.push({
+                file: file.relativePath,
+                message: `Prop "${drift.prop}" documented in fragment but removed from source`,
+                details: `Fragment: ${drift.fragment} | Source: (not found)`,
+              });
+            } else if (drift.kind === 'added') {
+              warnings.push({
+                file: file.relativePath,
+                message: `Prop "${drift.prop}" exists in source but not documented in fragment`,
+              });
+            } else {
+              warnings.push({
+                file: file.relativePath,
+                message: `Prop "${drift.prop}" ${drift.kind.replace('_', ' ')}: fragment=${drift.fragment} source=${drift.source}`,
+              });
+            }
+          }
+
+          if (compositionDrift) {
+            warnings.push({
+              file: file.relativePath,
+              message: compositionDrift,
+            });
+          }
+        }
+      } catch {
+        // Skip fragments that can't be analyzed — schema/coverage validators handle those
+      }
+    }
+  } finally {
+    extractor.dispose();
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    reports,
+  };
+}
+
+/**
+ * Compare documented props (from fragment) against extracted props (from source).
+ * Only compares local (non-inherited) props from the source.
+ */
+export function diffProps(
+  fragmentProps: Record<string, { type?: string; required?: boolean; values?: readonly string[]; default?: unknown }>,
+  sourceProps: Record<string, PropMeta>
+): DriftItem[] {
+  const drifts: DriftItem[] = [];
+
+  // Filter source to local props only
+  const localSourceProps = Object.fromEntries(
+    Object.entries(sourceProps).filter(([_, p]) => p.source === 'local')
+  );
+
+  // Check for props in source but not in fragment
+  for (const [name, sourceProp] of Object.entries(localSourceProps)) {
+    if (!(name in fragmentProps)) {
+      drifts.push({
+        prop: name,
+        kind: 'added',
+        source: sourceProp.type,
+        fragment: '(not documented)',
+      });
+    }
+  }
+
+  // Check for props in fragment but not in source
+  for (const [name, fragProp] of Object.entries(fragmentProps)) {
+    if (!(name in localSourceProps)) {
+      drifts.push({
+        prop: name,
+        kind: 'removed',
+        source: '(not found)',
+        fragment: String(fragProp.type ?? 'unknown'),
+      });
+      continue;
+    }
+
+    const sourceProp = localSourceProps[name];
+
+    // Type changed
+    if (fragProp.type && fragProp.type !== sourceProp.typeKind) {
+      drifts.push({
+        prop: name,
+        kind: 'type_changed',
+        source: sourceProp.typeKind,
+        fragment: String(fragProp.type),
+      });
+    }
+
+    // Required changed
+    if (fragProp.required !== undefined && fragProp.required !== sourceProp.required) {
+      drifts.push({
+        prop: name,
+        kind: 'required_changed',
+        source: String(sourceProp.required),
+        fragment: String(fragProp.required),
+      });
+    }
+
+    // Enum values changed
+    if (fragProp.values && sourceProp.values) {
+      const fragSet = new Set(fragProp.values);
+      const srcSet = new Set(sourceProp.values);
+      const added = sourceProp.values.filter(v => !fragSet.has(v));
+      const removed = Array.from(fragProp.values).filter(v => !srcSet.has(v));
+      if (added.length > 0 || removed.length > 0) {
+        drifts.push({
+          prop: name,
+          kind: 'values_changed',
+          source: sourceProp.values.join(', '),
+          fragment: Array.from(fragProp.values).join(', '),
+        });
+      }
+    }
+
+    // Default changed
+    if (fragProp.default !== undefined && sourceProp.default !== undefined) {
+      if (String(fragProp.default) !== sourceProp.default) {
+        drifts.push({
+          prop: name,
+          kind: 'default_changed',
+          source: sourceProp.default,
+          fragment: String(fragProp.default),
+        });
+      }
+    }
+  }
+
+  return drifts;
+}