@fragments-sdk/cli 0.2.2

package/src/core/discovery.ts

@@ -0,0 +1,337 @@
+import { resolve, dirname, basename } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import fg from 'fast-glob';
+import type { SegmentsConfig } from './types.js';
+import { BRAND } from './constants.js';
+
+export interface DiscoveredFile {
+  /** Absolute path to the file */
+  absolutePath: string;
+  /** Path relative to config directory */
+  relativePath: string;
+}
+
+/**
+ * Discovered component with source file information
+ */
+export interface DiscoveredComponent {
+  /** Component name (e.g., "Button") */
+  name: string;
+  /** Absolute path to the component source file */
+  sourcePath: string;
+  /** Path relative to config directory */
+  relativePath: string;
+  /** Path to storybook file if found */
+  storyPath?: string;
+}
+
+/**
+ * Discover recipe files (*.recipe.ts) under the config directory
+ */
+export async function discoverRecipeFiles(
+  configDir: string,
+  exclude?: string[]
+): Promise<DiscoveredFile[]> {
+  const pattern = `**/*${BRAND.recipeFileExtension}`;
+  const files = await fg(pattern, {
+    cwd: configDir,
+    ignore: exclude ?? ['**/node_modules/**', '**/dist/**'],
+    absolute: false,
+  });
+
+  return files.map((relativePath) => ({
+    relativePath,
+    absolutePath: resolve(configDir, relativePath),
+  }));
+}
+
+/**
+ * Discover segment files matching the config patterns
+ */
+export async function discoverSegmentFiles(
+  config: SegmentsConfig,
+  configDir: string
+): Promise<DiscoveredFile[]> {
+  const files = await fg(config.include, {
+    cwd: configDir,
+    ignore: config.exclude ?? [],
+    absolute: false,
+  });
+
+  return files.map((relativePath) => ({
+    relativePath,
+    absolutePath: resolve(configDir, relativePath),
+  }));
+}
+
+/**
+ * Discover component files for coverage validation
+ */
+export async function discoverComponentFiles(
+  config: SegmentsConfig,
+  configDir: string
+): Promise<DiscoveredFile[]> {
+  if (!config.components || config.components.length === 0) {
+    return [];
+  }
+
+  const files = await fg(config.components, {
+    cwd: configDir,
+    ignore: [
+      ...(config.exclude ?? []),
+      // Exclude segment files themselves
+      ...config.include,
+      // Exclude test files
+      '**/*.test.*',
+      '**/*.spec.*',
+      '**/__tests__/**',
+    ],
+    absolute: false,
+  });
+
+  return files.map((relativePath) => ({
+    relativePath,
+    absolutePath: resolve(configDir, relativePath),
+  }));
+}
+
+/**
+ * Extract component name from file path
+ */
+export function extractComponentName(filePath: string): string {
+  // Handle index.tsx files - use parent directory name
+  const parts = filePath.replace(/\\/g, '/').split('/');
+  const fileName = parts[parts.length - 1];
+
+  if (fileName === 'index.tsx' || fileName === 'index.ts') {
+    return parts[parts.length - 2] ?? 'Unknown';
+  }
+
+  // Remove extension
+  return fileName.replace(/\.(tsx?|jsx?)$/, '');
+}
+
+/**
+ * Default patterns for component discovery
+ */
+const DEFAULT_COMPONENT_PATTERNS = [
+  'src/components/**/*.tsx',
+  'src/components/**/index.tsx',
+  'components/**/*.tsx',
+  'lib/components/**/*.tsx',
+  'packages/*/src/components/**/*.tsx',
+];
+
+/**
+ * Patterns to exclude from component discovery
+ */
+const DEFAULT_EXCLUDE_PATTERNS = [
+  '**/*.test.*',
+  '**/*.spec.*',
+  '**/*.stories.*',
+  '**/*.story.*',
+  '**/__tests__/**',
+  '**/__mocks__/**',
+  '**/node_modules/**',
+  '**/dist/**',
+];
+
+/**
+ * Discover components from source files
+ *
+ * This function finds React components by:
+ * 1. Looking for TypeScript/TSX files in common component directories
+ * 2. Filtering out test files, stories, and internal files
+ * 3. Extracting component names from file names or directories
+ */
+export async function discoverComponentsFromSource(
+  configDir: string,
+  patterns?: string[],
+  exclude?: string[]
+): Promise<DiscoveredComponent[]> {
+  const searchPatterns = patterns && patterns.length > 0
+    ? patterns
+    : DEFAULT_COMPONENT_PATTERNS;
+
+  const excludePatterns = [
+    ...DEFAULT_EXCLUDE_PATTERNS,
+    ...(exclude ?? []),
+  ];
+
+  const files = await fg(searchPatterns, {
+    cwd: configDir,
+    ignore: excludePatterns,
+    absolute: false,
+  });
+
+  // Filter to only component-like files (start with uppercase)
+  const componentFiles = files.filter((file) => {
+    const name = extractComponentName(file);
+    return /^[A-Z]/.test(name);
+  });
+
+  // Find associated story files
+  const storyPatterns = [
+    '**/*.stories.tsx',
+    '**/*.stories.ts',
+    '**/*.story.tsx',
+    '**/*.story.ts',
+  ];
+
+  const storyFiles = await fg(storyPatterns, {
+    cwd: configDir,
+    ignore: ['**/node_modules/**', '**/dist/**'],
+    absolute: false,
+  });
+
+  const storyMap = new Map<string, string>();
+  for (const storyFile of storyFiles) {
+    const name = extractComponentName(storyFile.replace(/\.stories?\.(tsx?|jsx?)$/, '.tsx'));
+    storyMap.set(name, storyFile);
+  }
+
+  // Build discovered components
+  const components: DiscoveredComponent[] = [];
+
+  for (const file of componentFiles) {
+    const name = extractComponentName(file);
+    const absolutePath = resolve(configDir, file);
+
+    // Look for story file
+    const storyFile = storyMap.get(name);
+
+    components.push({
+      name,
+      sourcePath: absolutePath,
+      relativePath: file,
+      storyPath: storyFile ? resolve(configDir, storyFile) : undefined,
+    });
+  }
+
+  // Sort by name
+  components.sort((a, b) => a.name.localeCompare(b.name));
+
+  return components;
+}
+
+/**
+ * Discover components from a barrel export file (index.ts)
+ *
+ * Parses the barrel file to find exported components.
+ * This is useful for libraries that expose components through a single entry point.
+ */
+export async function discoverComponentsFromBarrel(
+  barrelPath: string,
+  configDir: string
+): Promise<DiscoveredComponent[]> {
+  const absoluteBarrelPath = resolve(configDir, barrelPath);
+
+  if (!existsSync(absoluteBarrelPath)) {
+    return [];
+  }
+
+  const content = await readFile(absoluteBarrelPath, 'utf-8');
+  const components: DiscoveredComponent[] = [];
+
+  // Match export statements like:
+  // export { Button } from './Button'
+  // export { Card, CardHeader } from './Card'
+  // export * from './Modal'
+  const exportRegex = /export\s+(?:\*|{([^}]+)})\s+from\s+['"]([^'"]+)['"]/g;
+
+  let match;
+  while ((match = exportRegex.exec(content)) !== null) {
+    const exportedNames = match[1];
+    const importPath = match[2];
+
+    // Resolve the import path
+    const barrelDir = dirname(absoluteBarrelPath);
+    let resolvedPath = resolve(barrelDir, importPath);
+
+    // Add extension if needed
+    if (!resolvedPath.endsWith('.tsx') && !resolvedPath.endsWith('.ts')) {
+      if (existsSync(`${resolvedPath}.tsx`)) {
+        resolvedPath = `${resolvedPath}.tsx`;
+      } else if (existsSync(`${resolvedPath}.ts`)) {
+        resolvedPath = `${resolvedPath}.ts`;
+      } else if (existsSync(`${resolvedPath}/index.tsx`)) {
+        resolvedPath = `${resolvedPath}/index.tsx`;
+      } else if (existsSync(`${resolvedPath}/index.ts`)) {
+        resolvedPath = `${resolvedPath}/index.ts`;
+      }
+    }
+
+    if (!existsSync(resolvedPath)) {
+      continue;
+    }
+
+    if (exportedNames) {
+      // Named exports: { Button, Card }
+      const names = exportedNames.split(',').map((n) => n.trim().split(/\s+as\s+/)[0].trim());
+      for (const name of names) {
+        if (/^[A-Z]/.test(name)) {
+          const relativePath = resolvedPath.replace(configDir + '/', '');
+          components.push({
+            name,
+            sourcePath: resolvedPath,
+            relativePath,
+          });
+        }
+      }
+    } else {
+      // Star export: export * from './Component'
+      const name = extractComponentName(importPath);
+      if (/^[A-Z]/.test(name)) {
+        const relativePath = resolvedPath.replace(configDir + '/', '');
+        components.push({
+          name,
+          sourcePath: resolvedPath,
+          relativePath,
+        });
+      }
+    }
+  }
+
+  return components;
+}
+
+/**
+ * Discover all components using multiple strategies
+ */
+export async function discoverAllComponents(
+  configDir: string,
+  options: {
+    patterns?: string[];
+    exclude?: string[];
+    barrelFiles?: string[];
+  } = {}
+): Promise<DiscoveredComponent[]> {
+  const componentsMap = new Map<string, DiscoveredComponent>();
+
+  // Discover from source files
+  const sourceComponents = await discoverComponentsFromSource(
+    configDir,
+    options.patterns,
+    options.exclude
+  );
+
+  for (const comp of sourceComponents) {
+    componentsMap.set(comp.name, comp);
+  }
+
+  // Discover from barrel files if specified
+  if (options.barrelFiles && options.barrelFiles.length > 0) {
+    for (const barrelFile of options.barrelFiles) {
+      const barrelComponents = await discoverComponentsFromBarrel(barrelFile, configDir);
+      for (const comp of barrelComponents) {
+        // Only add if not already found
+        if (!componentsMap.has(comp.name)) {
+          componentsMap.set(comp.name, comp);
+        }
+      }
+    }
+  }
+
+  return Array.from(componentsMap.values()).sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/core/figma.ts

@@ -0,0 +1,263 @@
+/**
+ * Figma property mapping DSL
+ *
+ * Provides helpers for mapping Figma component properties to code props.
+ * Inspired by Figma Code Connect's API.
+ *
+ * @example
+ * ```tsx
+ * import { defineSegment, figma } from '@fragments/core';
+ *
+ * export default defineSegment({
+ *   component: Button,
+ *   meta: {
+ *     name: 'Button',
+ *     description: 'Primary action trigger',
+ *     category: 'actions',
+ *     figma: 'https://figma.com/file/abc/Design?node-id=1-2',
+ *     figmaProps: {
+ *       children: figma.string('Label'),
+ *       disabled: figma.boolean('Disabled'),
+ *       variant: figma.enum('Type', {
+ *         'Primary': 'primary',
+ *         'Secondary': 'secondary',
+ *       }),
+ *     },
+ *   },
+ *   // ...
+ * });
+ * ```
+ */
+
+import type {
+  FigmaStringMapping,
+  FigmaBooleanMapping,
+  FigmaEnumMapping,
+  FigmaInstanceMapping,
+  FigmaChildrenMapping,
+  FigmaTextContentMapping,
+} from './types.js';
+
+/**
+ * Map a Figma text property to a string prop.
+ *
+ * @param figmaProperty - The name of the text property in Figma
+ * @returns A string mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   label: figma.string('Button Text'),
+ *   placeholder: figma.string('Placeholder'),
+ * }
+ * ```
+ */
+function string(figmaProperty: string): FigmaStringMapping {
+  return {
+    __type: 'figma-string',
+    figmaProperty,
+  };
+}
+
+/**
+ * Map a Figma boolean property to a boolean prop.
+ * Optionally map true/false to different values.
+ *
+ * @param figmaProperty - The name of the boolean property in Figma
+ * @param valueMapping - Optional mapping of true/false to other values
+ * @returns A boolean mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   disabled: figma.boolean('Disabled'),
+ *   // Map boolean to string values
+ *   size: figma.boolean('Large', { true: 'lg', false: 'md' }),
+ * }
+ * ```
+ */
+function boolean(
+  figmaProperty: string,
+  valueMapping?: { true: unknown; false: unknown }
+): FigmaBooleanMapping {
+  return {
+    __type: 'figma-boolean',
+    figmaProperty,
+    valueMapping,
+  };
+}
+
+/**
+ * Map a Figma variant property to an enum prop.
+ *
+ * @param figmaProperty - The name of the variant property in Figma
+ * @param valueMapping - Mapping of Figma values to code values
+ * @returns An enum mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   variant: figma.enum('Type', {
+ *     'Primary': 'primary',
+ *     'Secondary': 'secondary',
+ *     'Outline': 'outline',
+ *   }),
+ *   size: figma.enum('Size', {
+ *     'Small': 'sm',
+ *     'Medium': 'md',
+ *     'Large': 'lg',
+ *   }),
+ * }
+ * ```
+ */
+function enumValue<T extends Record<string, unknown>>(
+  figmaProperty: string,
+  valueMapping: T
+): FigmaEnumMapping {
+  return {
+    __type: 'figma-enum',
+    figmaProperty,
+    valueMapping,
+  };
+}
+
+/**
+ * Reference a nested Figma component instance.
+ * Use this when a prop accepts a component that's represented
+ * as an instance swap in Figma.
+ *
+ * @param figmaProperty - The name of the instance property in Figma
+ * @returns An instance mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   icon: figma.instance('Icon'),
+ *   avatar: figma.instance('Avatar'),
+ * }
+ * ```
+ */
+function instance(figmaProperty: string): FigmaInstanceMapping {
+  return {
+    __type: 'figma-instance',
+    figmaProperty,
+  };
+}
+
+/**
+ * Render children from specific Figma layers.
+ * Use this when children are represented as named layers in Figma.
+ *
+ * @param layers - Array of layer names to include as children
+ * @returns A children mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   children: figma.children(['Title', 'Description', 'Actions']),
+ * }
+ * ```
+ */
+function children(layers: string[]): FigmaChildrenMapping {
+  return {
+    __type: 'figma-children',
+    layers,
+  };
+}
+
+/**
+ * Extract text content from a Figma text layer.
+ * Use this when a prop should be the actual text from a layer.
+ *
+ * @param layer - The name of the text layer in Figma
+ * @returns A text content mapping descriptor
+ *
+ * @example
+ * ```tsx
+ * figmaProps: {
+ *   title: figma.textContent('Header Text'),
+ *   description: figma.textContent('Body Text'),
+ * }
+ * ```
+ */
+function textContent(layer: string): FigmaTextContentMapping {
+  return {
+    __type: 'figma-text-content',
+    layer,
+  };
+}
+
+/**
+ * Figma property mapping helpers.
+ *
+ * Use these to define how Figma properties map to your component props.
+ * The mappings are used for:
+ * - Generating accurate code snippets in Figma Dev Mode
+ * - AI agents understanding the design-to-code relationship
+ * - Automated design verification
+ */
+export const figma = {
+  string,
+  boolean,
+  enum: enumValue,
+  instance,
+  children,
+  textContent,
+} as const;
+
+/**
+ * Helper type to check if a value is a Figma prop mapping
+ */
+export function isFigmaPropMapping(
+  value: unknown
+): value is FigmaStringMapping | FigmaBooleanMapping | FigmaEnumMapping | FigmaInstanceMapping | FigmaChildrenMapping | FigmaTextContentMapping {
+  if (typeof value !== 'object' || value === null || !('__type' in value)) {
+    return false;
+  }
+  const typeValue = (value as Record<string, unknown>).__type;
+  return typeof typeValue === 'string' && typeValue.startsWith('figma-');
+}
+
+/**
+ * Resolve a Figma prop mapping to an actual value given Figma property values.
+ *
+ * @param mapping - The Figma prop mapping
+ * @param figmaValues - Object containing Figma property values
+ * @returns The resolved value for the code prop
+ */
+export function resolveFigmaMapping(
+  mapping: FigmaStringMapping | FigmaBooleanMapping | FigmaEnumMapping | FigmaInstanceMapping | FigmaChildrenMapping | FigmaTextContentMapping,
+  figmaValues: Record<string, unknown>
+): unknown {
+  switch (mapping.__type) {
+    case 'figma-string':
+      return figmaValues[mapping.figmaProperty] ?? '';
+
+    case 'figma-boolean': {
+      const boolValue = figmaValues[mapping.figmaProperty] as boolean;
+      if (mapping.valueMapping) {
+        return boolValue ? mapping.valueMapping.true : mapping.valueMapping.false;
+      }
+      return boolValue;
+    }
+
+    case 'figma-enum': {
+      const enumKey = figmaValues[mapping.figmaProperty] as string;
+      return mapping.valueMapping[enumKey] ?? enumKey;
+    }
+
+    case 'figma-instance':
+      // Instance mappings return the instance reference
+      return figmaValues[mapping.figmaProperty];
+
+    case 'figma-children':
+      // Children mappings return array of layer contents
+      return mapping.layers.map((layer) => figmaValues[layer]);
+
+    case 'figma-text-content':
+      return figmaValues[mapping.layer] ?? '';
+
+    default:
+      return undefined;
+  }
+}