@fragments-sdk/cli 0.9.0 → 0.10.0

package/src/commands/generate.ts

@@ -1,17 +1,16 @@
 /**
- * fragments generate - AI-assisted fragment generation
+ * fragments generate - Generate fragment files from component source code
  *
- * Analyzes component source code and generates fragment files with:
- * - Extracted props from TypeScript
- * - Inferred usage patterns from story names
- * - Generated description
+ * Analyzes component source code and generates proper defineFragment() TSX files
+ * colocated next to the component source. These files are parseable by the
+ * build command and renderable by the dev viewer.
  */
 
-import { readFile, writeFile, mkdir, access } from "node:fs/promises";
-import { resolve, join, basename, dirname, relative } from "node:path";
+import { readFile, writeFile, access } from "node:fs/promises";
+import { resolve, basename, dirname, relative, join } from "node:path";
 import pc from "picocolors";
 import fg from "fast-glob";
-import { BRAND, type Fragment } from "../core/index.js";
+import { BRAND } from "../core/index.js";
 import { extractPropsFromFile } from "../core/node.js";
 
 export interface GenerateOptions {
@@ -43,10 +42,6 @@ export async function generate(options: GenerateOptions = {}): Promise<GenerateR
 
   console.log(pc.cyan(`\n${BRAND.name} Generate\n`));
 
-  // Ensure .fragments/components directory exists
-  const fragmentsDir = join(projectRoot, BRAND.dataDir, BRAND.componentsDir);
-  await mkdir(fragmentsDir, { recursive: true });
-
   // Find component files
   const componentPattern =
     options.componentPattern ||
@@ -73,15 +68,15 @@ export async function generate(options: GenerateOptions = {}): Promise<GenerateR
     absolute: true,
   });
 
-  // Build story map for pattern inference
-  const storyMap = new Map<string, string[]>();
+  // Build story map for pattern inference (names + args)
+  const storyMap = new Map<string, StoryVariant[]>();
   for (const storyFile of storyFiles) {
     try {
       const content = await readFile(storyFile, "utf-8");
       const componentName = extractComponentNameFromStory(content, storyFile);
       if (componentName) {
-        const storyNames = extractStoryNames(content);
-        storyMap.set(componentName, storyNames);
+        const variants = extractStoryVariants(content);
+        storyMap.set(componentName, variants);
       }
     } catch {
       // Ignore parsing errors
@@ -106,8 +101,11 @@ export async function generate(options: GenerateOptions = {}): Promise<GenerateR
         continue;
       }
 
-      // Check if fragment already exists
-      const fragmentPath = join(fragmentsDir, `${componentName}${BRAND.fileExtension}`);
+      // Write fragment file colocated next to the component source
+      const componentDir = dirname(filePath);
+      const componentBaseName = basename(filePath, ".tsx");
+      const fragmentPath = join(componentDir, `${componentBaseName}${BRAND.fileExtension}`);
+
       let fragmentExists = false;
       try {
         await access(fragmentPath);
@@ -122,16 +120,18 @@ export async function generate(options: GenerateOptions = {}): Promise<GenerateR
         continue;
       }
 
-      // Generate fragment from analysis
-      const fragment = generateFragmentFromComponent(
+      // Generate proper defineFragment() TSX content
+      const storyVariants = storyMap.get(componentName) || [];
+      const fragmentContent = generateFragmentTsx(
         componentName,
+        componentBaseName,
         extracted,
         filePath,
-        storyMap.get(componentName) || []
+        storyVariants
       );
 
       // Write fragment file
-      await writeFile(fragmentPath, JSON.stringify(fragment, null, 2), "utf-8");
+      await writeFile(fragmentPath, fragmentContent, "utf-8");
       generated.push({ name: componentName, path: relative(projectRoot, fragmentPath) });
       console.log(pc.green(`  ✓ Generated ${componentName}${BRAND.fileExtension}`));
     } catch (e) {
@@ -166,59 +166,235 @@ export async function generate(options: GenerateOptions = {}): Promise<GenerateR
 }
 
 /**
- * Generate a Fragment from extracted component data
+ * Generate proper defineFragment() TSX file content
  */
-function generateFragmentFromComponent(
+function generateFragmentTsx(
   componentName: string,
+  componentBaseName: string,
   extracted: ReturnType<typeof extractPropsFromFile> & { componentName: string },
   filePath: string,
-  storyNames: string[]
-): Fragment {
-  // Infer usage from story names
+  storyVariants: StoryVariant[]
+): string {
+  const storyNames = storyVariants.map((v) => v.name);
   const whenToUse = inferUsageFromStories(storyNames);
-
-  // Generate description from component name
   const description = generateDescription(componentName, extracted.props);
-
-  // Infer accessibility from props
+  const status = inferStatus(filePath);
   const accessibility = inferAccessibility(extracted.props);
 
-  // Infer status from file path
-  const status = inferStatus(filePath);
+  // Build props object for defineFragment
+  const propsEntries = Object.entries(extracted.props || {});
+
+  // Format when array
+  const whenLines = whenToUse.length > 0
+    ? whenToUse.map((w) => `      '${escapeQuotes(w)}',`).join("\n")
+    : `      'TODO: describe when to use ${componentName}',`;
+
+  // Format props
+  let propsBlock = "{}";
+  if (propsEntries.length > 0) {
+    const propLines = propsEntries.map(([name, info]) => {
+      const propInfo = info as Record<string, unknown>;
+      const rawType = propInfo.type ? String(propInfo.type) : "";
+      const classified = classifyPropType(rawType);
+      const desc = propInfo.description ? String(propInfo.description).replace(/\n/g, " ") : "";
+      const required = propInfo.required ? "true" : "false";
+      const parts = [`      type: '${classified.type}'`];
+      if (desc) parts.push(`      description: '${escapeQuotes(desc)}'`);
+      parts.push(`      required: ${required}`);
+      if (propInfo.default !== undefined) {
+        parts.push(`      default: ${JSON.stringify(propInfo.default)}`);
+      }
+      // Use classified values (from string literal unions) or existing values
+      const values = classified.values || (propInfo.values && Array.isArray(propInfo.values) ? propInfo.values : null);
+      if (values && values.length > 0) {
+        parts.push(`      values: ${JSON.stringify(values)}`);
+      }
+      return `    ${name}: {\n${parts.join(",\n")},\n    }`;
+    });
+    propsBlock = `{\n${propLines.join(",\n")},\n  }`;
+  }
+
+  // Build accessibility section
+  let accessibilityBlock = "";
+  if (accessibility.role || (accessibility.requirements && accessibility.requirements.length > 0)) {
+    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}]`);
+    }
+    accessibilityBlock = `
+
+  accessibility: {
+${parts.join(",\n")},
+  },`;
+  }
+
+  // Build variants from story args or fallback to bare render
+  const variants = buildVariants(componentName, storyVariants);
+
+  // Use default import when the source component uses export default
+  const componentImportStatement = extracted.isDefaultExport
+    ? `import ${componentName} from './${componentBaseName}';`
+    : `import { ${componentName} } from './${componentBaseName}';`;
+
+  return `import React from 'react';
+import { defineFragment } from '@fragments-sdk/cli/core';
+${componentImportStatement}
+
+export default defineFragment({
+  component: ${componentName},
+
+  meta: {
+    name: '${escapeQuotes(componentName)}',
+    description: '${escapeQuotes(description)}',
+    category: '${inferCategory(componentName, extracted.props)}',
+    status: '${status}',
+  },
+
+  usage: {
+    when: [
+${whenLines}
+    ],
+    whenNot: [],
+  },
+
+  props: ${propsBlock},${accessibilityBlock}
+
+  variants: [
+${variants}
+  ],
+});
+`;
+}
+
+/**
+ * Escape single quotes in strings
+ */
+function escapeQuotes(str: string): string {
+  return str.replace(/'/g, "\\'");
+}
+
+/**
+ * Classify a raw TypeScript type string into a valid fragment prop type enum value.
+ * Returns the classified type and optionally extracted enum values.
+ */
+function classifyPropType(rawType: string): { type: string; values?: string[] } {
+  const t = rawType.replace(/\s+/g, " ").trim();
+  const lower = t.toLowerCase();
+
+  // Direct primitive matches
+  if (lower === "string") return { type: "string" };
+  if (lower === "number") return { type: "number" };
+  if (lower === "boolean" || lower === "bool") return { type: "boolean" };
+
+  // String/number literal unions → enum with values
+  // e.g., '"primary" | "secondary"' or "'default' | 'modal'"
+  if (/^["'][^"']*["'](\s*\|\s*["'][^"']*["'])*$/.test(t)) {
+    const values = [...t.matchAll(/["']([^"']+)["']/g)].map((m) => m[1]);
+    if (values.length > 0) return { type: "enum", values };
+  }
+
+  // Function types — arrow functions, callbacks, handlers, dispatchers
+  if (
+    lower.includes("=>") ||
+    lower.includes("handler") ||
+    lower.includes("callback") ||
+    lower.includes("dispatch") ||
+    lower.includes("listener") ||
+    /^\(/.test(t)
+  ) {
+    return { type: "function" };
+  }
+
+  // React node types
+  if (
+    lower.includes("reactnode") ||
+    lower.includes("react.reactnode") ||
+    lower === "node"
+  ) {
+    return { type: "node" };
+  }
 
-  const fragment: Fragment = {
-    $schema: "https://fragments.dev/schema/v1.json",
-    name: componentName,
-    description,
-    usage: {
-      when: whenToUse,
-      doNot: [],
-    },
-    meta: {
-      status,
-    },
+  // React element types
+  if (
+    lower.includes("reactelement") ||
+    lower.includes("react.reactelement") ||
+    lower.includes("jsx.element")
+  ) {
+    return { type: "element" };
+  }
+
+  // Array types
+  if (lower.includes("[]") || lower.startsWith("array<") || lower.startsWith("readonly ")) {
+    return { type: "array" };
+  }
+
+  // Object types (must come after array check since objects can contain [])
+  if (lower.startsWith("{") || lower.includes("record<") || lower === "object") {
+    return { type: "object" };
+  }
+
+  // Union types (mixed types with |)
+  if (lower.includes("|")) {
+    // Check if it's a union of just string literals (enum)
+    const parts = t.split("|").map((p) => p.trim());
+    const allStringLiterals = parts.every((p) => /^["'].*["']$/.test(p));
+    if (allStringLiterals) {
+      const values = parts.map((p) => p.replace(/^["']|["']$/g, ""));
+      return { type: "enum", values };
+    }
+    return { type: "union" };
+  }
+
+  // Anything else
+  return { type: "custom" };
+}
+
+/**
+ * Infer category from component name and props
+ */
+function inferCategory(componentName: string, props: Record<string, unknown>): string {
+  const lower = componentName.toLowerCase();
+
+  const categoryPatterns: Record<string, string[]> = {
+    "Actions": ["button", "action", "cta", "fab", "floatingaction"],
+    "Forms": ["form", "input", "select", "checkbox", "radio", "textarea", "field", "textfield", "datepicker", "switch", "slider", "segmented"],
+    "Layout": ["layout", "container", "grid", "flex", "stack", "box", "divider", "spacer", "sidebar"],
+    "Navigation": ["nav", "menu", "breadcrumb", "tab", "link", "pagination", "stepper", "topbar"],
+    "Feedback": ["alert", "toast", "notification", "message", "badge", "indicator", "progress", "spinner", "loading", "loader", "lozenge", "chip"],
+    "Data Display": ["table", "list", "card", "avatar", "stat", "timeline", "tree", "datalist", "datacard"],
+    "Overlays": ["modal", "dialog", "drawer", "popover", "tooltip", "dropdown", "slidepanel"],
+    "Typography": ["text", "heading", "title", "label", "paragraph"],
+    "Media": ["image", "video", "icon", "carousel"],
   };
 
-  // Add accessibility if any was inferred
-  if (accessibility.role || (accessibility.requirements && accessibility.requirements.length > 0)) {
-    fragment.accessibility = accessibility;
+  for (const [category, patterns] of Object.entries(categoryPatterns)) {
+    for (const pattern of patterns) {
+      if (lower.includes(pattern)) {
+        return category;
+      }
+    }
   }
 
-  return fragment;
+  if ("onClick" in props || "onPress" in props) return "Actions";
+  if ("value" in props || "defaultValue" in props) return "Forms";
+  if ("children" in props) return "Layout";
+
+  return "Components";
 }
 
 /**
  * Extract component name from story file
  */
 function extractComponentNameFromStory(content: string, filePath: string): string | null {
-  // Try to extract from title in default export
-  // e.g., export default { title: 'Components/Button' }
   const titleMatch = content.match(/title:\s*['"](?:[^'"]+\/)?([^'"]+)['"]/);
   if (titleMatch) {
     return titleMatch[1];
   }
 
-  // Try to extract from file name
   const fileName = basename(filePath);
   const componentName = fileName.replace(/\.stories\.(tsx?|jsx?)$/, "");
   if (/^[A-Z]/.test(componentName)) {
@@ -228,26 +404,174 @@ function extractComponentNameFromStory(content: string, filePath: string): strin
   return null;
 }
 
+interface StoryVariant {
+  name: string;
+  args: Record<string, unknown>;
+}
+
 /**
- * Extract story names from story file content
+ * Extract story names and their args from story file content (CSF3 format).
+ * Parses patterns like:
+ *   export const Primary: Story = { args: { variant: 'primary', children: 'Click me' } }
  */
-function extractStoryNames(content: string): string[] {
-  const names: string[] = [];
+function extractStoryVariants(content: string): StoryVariant[] {
+  const variants: StoryVariant[] = [];
 
-  // Match named exports that look like stories
-  // e.g., export const Primary = ...
   const exportMatches = content.matchAll(
     /export\s+const\s+([A-Z][a-zA-Z0-9]*)\s*[=:]/g
   );
 
   for (const match of exportMatches) {
     const name = match[1];
-    if (name !== "default" && !name.endsWith("Args") && !name.endsWith("Meta")) {
-      names.push(name);
+    if (name === "default" || name.endsWith("Args") || name.endsWith("Meta")) {
+      continue;
+    }
+
+    const args = extractStoryArgs(content, name);
+    variants.push({ name, args });
+  }
+
+  return variants;
+}
+
+/**
+ * Extract the `args` object from a named story export.
+ * Uses balanced-brace matching to handle nested objects.
+ */
+function extractStoryArgs(content: string, storyName: string): Record<string, unknown> {
+  // Find the story export and look for an args block
+  const storyPattern = new RegExp(
+    `export\\s+const\\s+${storyName}[^=]*=\\s*\\{([\\s\\S]*?)\\n\\};`,
+  );
+  const storyMatch = content.match(storyPattern);
+  if (!storyMatch) return {};
+
+  const storyBody = storyMatch[1];
+
+  // Find the args block within the story body
+  const argsStart = storyBody.indexOf('args:');
+  if (argsStart === -1) return {};
+
+  // Find the opening brace after "args:"
+  const braceStart = storyBody.indexOf('{', argsStart);
+  if (braceStart === -1) return {};
+
+  // Balanced brace matching to find the full args object
+  let depth = 0;
+  let braceEnd = -1;
+  for (let i = braceStart; i < storyBody.length; i++) {
+    if (storyBody[i] === '{') depth++;
+    else if (storyBody[i] === '}') {
+      depth--;
+      if (depth === 0) {
+        braceEnd = i;
+        break;
+      }
+    }
+  }
+  if (braceEnd === -1) return {};
+
+  const argsBlock = storyBody.slice(braceStart + 1, braceEnd).trim();
+  return parseArgsBlock(argsBlock);
+}
+
+/**
+ * Parse a simplified args block into key-value pairs.
+ * Handles string literals, numbers, booleans, and simple expressions.
+ */
+function parseArgsBlock(argsBlock: string): Record<string, unknown> {
+  const args: Record<string, unknown> = {};
+
+  // Match key: value pairs (handles string, number, boolean values)
+  const pairPattern = /(\w+)\s*:\s*(?:['"]([^'"]*?)['"]|(true|false)|(\d+(?:\.\d+)?))/g;
+  let pairMatch: RegExpExecArray | null;
+
+  while ((pairMatch = pairPattern.exec(argsBlock)) !== null) {
+    const key = pairMatch[1];
+    if (pairMatch[2] !== undefined) {
+      // String value
+      args[key] = pairMatch[2];
+    } else if (pairMatch[3] !== undefined) {
+      // Boolean
+      args[key] = pairMatch[3] === 'true';
+    } else if (pairMatch[4] !== undefined) {
+      // Number
+      args[key] = Number(pairMatch[4]);
     }
   }
 
-  return names;
+  return args;
+}
+
+/**
+ * Build variant entries from story args.
+ * If stories have args, generates JSX with those props.
+ * Falls back to a bare `<Component />` for the Default variant.
+ */
+function buildVariants(componentName: string, storyVariants: StoryVariant[]): string {
+  // Filter to variants with args, plus always include a Default
+  const hasDefault = storyVariants.some((v) => v.name === 'Default');
+  const entries: string[] = [];
+
+  if (!hasDefault) {
+    entries.push(formatVariantEntry(componentName, 'Default', `Default ${componentName}`, {}));
+  }
+
+  for (const variant of storyVariants) {
+    const description = variant.name
+      .replace(/([A-Z])/g, ' $1')
+      .trim();
+    entries.push(formatVariantEntry(componentName, variant.name, `${description} ${componentName}`, variant.args));
+  }
+
+  // Deduplicate: if stories provided a Default, don't double-add
+  return entries.join('\n');
+}
+
+/**
+ * Format a single variant entry with JSX code and render function.
+ * Handles `children` as JSX children, all other args as props.
+ */
+function formatVariantEntry(
+  componentName: string,
+  name: string,
+  description: string,
+  args: Record<string, unknown>
+): string {
+  const jsxCode = buildJsxString(componentName, args);
+  return `    {
+      name: '${escapeQuotes(name)}',
+      description: '${escapeQuotes(description)}',
+      code: \`${jsxCode}\`,
+      render: () => ${jsxCode},
+    },`;
+}
+
+/**
+ * Build a JSX string from component name and args.
+ * `children` string args become JSX children, others become props.
+ */
+function buildJsxString(componentName: string, args: Record<string, unknown>): string {
+  const { children, ...restArgs } = args;
+  const propParts: string[] = [];
+
+  for (const [key, value] of Object.entries(restArgs)) {
+    if (typeof value === 'string') {
+      propParts.push(`${key}="${escapeQuotes(value)}"`);
+    } else if (typeof value === 'boolean') {
+      propParts.push(value ? key : `${key}={false}`);
+    } else if (typeof value === 'number') {
+      propParts.push(`${key}={${value}}`);
+    }
+  }
+
+  const propsStr = propParts.length > 0 ? ' ' + propParts.join(' ') : '';
+
+  if (typeof children === 'string') {
+    return `<${componentName}${propsStr}>${children}</${componentName}>`;
+  }
+
+  return `<${componentName}${propsStr} />`;
 }
 
 /**
@@ -257,13 +581,11 @@ function inferUsageFromStories(storyNames: string[]): string[] {
   const usage: string[] = [];
 
   for (const name of storyNames) {
-    // Convert PascalCase to sentence
     const sentence = name
       .replace(/([A-Z])/g, " $1")
       .trim()
       .toLowerCase();
 
-    // Skip generic names
     if (
       ["default", "primary", "basic", "example", "playground"].includes(
         sentence.toLowerCase()
@@ -272,7 +594,6 @@ function inferUsageFromStories(storyNames: string[]): string[] {
       continue;
     }
 
-    // Generate usage from story name
     if (sentence.includes("loading")) {
       usage.push("Showing loading states");
     } else if (sentence.includes("disabled")) {
@@ -284,7 +605,6 @@ function inferUsageFromStories(storyNames: string[]): string[] {
     } else if (sentence.includes("empty")) {
       usage.push("Handling empty states");
     } else if (sentence.includes("with")) {
-      // "WithIcon" -> "Adding icons"
       const withPart = sentence.replace("with ", "");
       usage.push(`Displaying with ${withPart}`);
     }
@@ -300,13 +620,11 @@ function generateDescription(
   componentName: string,
   props: Record<string, unknown>
 ): string {
-  // Convert PascalCase to words
   const words = componentName
     .replace(/([A-Z])/g, " $1")
     .trim()
     .toLowerCase();
 
-  // Detect component type from name or props
   const hasOnClick = "onClick" in props || "onPress" in props;
   const hasValue = "value" in props || "defaultValue" in props;
   const hasChildren = "children" in props;
@@ -337,18 +655,15 @@ function inferAccessibility(props: Record<string, unknown>): {
 
   const hasOnClick = "onClick" in props || "onPress" in props;
   const hasAriaLabel = "ariaLabel" in props || "aria-label" in props;
-  const hasRole = "role" in props;
   const hasDisabled = "disabled" in props;
   const hasHref = "href" in props;
 
-  // Infer role
   if (hasOnClick && !hasHref) {
     accessibility.role = "button";
   } else if (hasHref) {
     accessibility.role = "link";
   }
 
-  // Infer requirements
   const requirements: string[] = [];
 
   if (hasOnClick && !hasAriaLabel) {