@fragments-sdk/cli 0.2.2

package/src/commands/generate.ts

@@ -0,0 +1,391 @@
+/**
+ * fragments generate - AI-assisted fragment generation
+ *
+ * Analyzes component source code and generates fragment files with:
+ * - Extracted props from TypeScript
+ * - Inferred usage patterns from story names
+ * - Generated description
+ */
+
+import { readFile, writeFile, mkdir, access } from "node:fs/promises";
+import { resolve, join, basename, dirname, relative } from "node:path";
+import pc from "picocolors";
+import fg from "fast-glob";
+import { BRAND, type Fragment } from "../core/index.js";
+import { extractPropsFromFile } from "../core/node.js";
+
+export interface GenerateOptions {
+  /** Project root directory */
+  projectRoot?: string;
+  /** Specific component name to generate (optional) */
+  component?: string;
+  /** Overwrite existing fragment files */
+  force?: boolean;
+  /** Pattern for component files */
+  componentPattern?: string;
+}
+
+export interface GenerateResult {
+  success: boolean;
+  generated: Array<{ name: string; path: string }>;
+  skipped: Array<{ name: string; reason: string }>;
+  errors: Array<{ name: string; error: string }>;
+}
+
+/**
+ * Generate fragment files from component source code
+ */
+export async function generate(options: GenerateOptions = {}): Promise<GenerateResult> {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const generated: Array<{ name: string; path: string }> = [];
+  const skipped: Array<{ name: string; reason: string }> = [];
+  const errors: Array<{ name: string; error: string }> = [];
+
+  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 ||
+    "src/components/**/*.tsx";
+
+  const componentFiles = await fg(componentPattern, {
+    cwd: projectRoot,
+    ignore: [
+      "**/node_modules/**",
+      "**/*.stories.*",
+      "**/*.segment.*",
+      "**/*.test.*",
+      "**/*.spec.*",
+      "**/*.d.ts",
+      "**/index.tsx", // Often just re-exports
+    ],
+    absolute: true,
+  });
+
+  // Find story files for pattern inference
+  const storyFiles = await fg(["src/**/*.stories.tsx", "src/**/*.stories.ts"], {
+    cwd: projectRoot,
+    ignore: ["**/node_modules/**"],
+    absolute: true,
+  });
+
+  // Build story map for pattern inference
+  const storyMap = new Map<string, string[]>();
+  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);
+      }
+    } catch {
+      // Ignore parsing errors
+    }
+  }
+
+  console.log(pc.dim(`Found ${componentFiles.length} component files\n`));
+
+  // Process each component file
+  for (const filePath of componentFiles) {
+    try {
+      const extracted = extractPropsFromFile(filePath);
+
+      if (!extracted || !extracted.componentName) {
+        continue;
+      }
+
+      const componentName = extracted.componentName;
+
+      // Filter by component name if specified
+      if (options.component && componentName !== options.component) {
+        continue;
+      }
+
+      // Check if fragment already exists
+      const fragmentPath = join(fragmentsDir, `${componentName}${BRAND.fileExtension}`);
+      let fragmentExists = false;
+      try {
+        await access(fragmentPath);
+        fragmentExists = true;
+      } catch {
+        // Fragment doesn't exist
+      }
+
+      if (fragmentExists && !options.force) {
+        skipped.push({ name: componentName, reason: "Fragment already exists" });
+        console.log(pc.dim(`  Skipping ${componentName} (fragment exists)`));
+        continue;
+      }
+
+      // Generate fragment from analysis
+      const fragment = generateFragmentFromComponent(
+        componentName,
+        extracted,
+        filePath,
+        storyMap.get(componentName) || []
+      );
+
+      // Write fragment file
+      await writeFile(fragmentPath, JSON.stringify(fragment, null, 2), "utf-8");
+      generated.push({ name: componentName, path: relative(projectRoot, fragmentPath) });
+      console.log(pc.green(`  ✓ Generated ${componentName}${BRAND.fileExtension}`));
+    } catch (e) {
+      const fileName = basename(filePath);
+      errors.push({
+        name: fileName,
+        error: e instanceof Error ? e.message : String(e),
+      });
+      console.log(pc.red(`  ✗ Failed: ${fileName}`));
+    }
+  }
+
+  // Summary
+  console.log();
+  if (generated.length > 0) {
+    console.log(pc.green(`✓ Generated ${generated.length} fragment(s)`));
+  }
+  if (skipped.length > 0) {
+    console.log(pc.dim(`  Skipped ${skipped.length} (use --force to overwrite)`));
+  }
+  if (errors.length > 0) {
+    console.log(pc.yellow(`  ${errors.length} error(s)`));
+  }
+  console.log();
+
+  return {
+    success: errors.length === 0,
+    generated,
+    skipped,
+    errors,
+  };
+}
+
+/**
+ * Generate a Fragment from extracted component data
+ */
+function generateFragmentFromComponent(
+  componentName: string,
+  extracted: ReturnType<typeof extractPropsFromFile> & { componentName: string },
+  filePath: string,
+  storyNames: string[]
+): Fragment {
+  // Infer usage from story names
+  const whenToUse = inferUsageFromStories(storyNames);
+
+  // Generate description from component name
+  const description = generateDescription(componentName, extracted.props);
+
+  // Infer accessibility from props
+  const accessibility = inferAccessibility(extracted.props);
+
+  // Infer status from file path
+  const status = inferStatus(filePath);
+
+  const fragment: Fragment = {
+    $schema: "https://fragments.dev/schema/v1.json",
+    name: componentName,
+    description,
+    usage: {
+      when: whenToUse,
+      doNot: [],
+    },
+    meta: {
+      status,
+    },
+  };
+
+  // Add accessibility if any was inferred
+  if (accessibility.role || (accessibility.requirements && accessibility.requirements.length > 0)) {
+    fragment.accessibility = accessibility;
+  }
+
+  return fragment;
+}
+
+/**
+ * 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)) {
+    return componentName;
+  }
+
+  return null;
+}
+
+/**
+ * Extract story names from story file content
+ */
+function extractStoryNames(content: string): string[] {
+  const names: string[] = [];
+
+  // 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);
+    }
+  }
+
+  return names;
+}
+
+/**
+ * Infer usage scenarios from story names
+ */
+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()
+      )
+    ) {
+      continue;
+    }
+
+    // Generate usage from story name
+    if (sentence.includes("loading")) {
+      usage.push("Showing loading states");
+    } else if (sentence.includes("disabled")) {
+      usage.push("Preventing user interaction");
+    } else if (sentence.includes("error")) {
+      usage.push("Displaying error states");
+    } else if (sentence.includes("success")) {
+      usage.push("Showing success feedback");
+    } 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}`);
+    }
+  }
+
+  return usage;
+}
+
+/**
+ * Generate description from component name and props
+ */
+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;
+
+  if (hasOnClick && !hasValue) {
+    return `Interactive ${words} element for triggering actions`;
+  }
+
+  if (hasValue) {
+    return `Form ${words} for user input`;
+  }
+
+  if (hasChildren) {
+    return `Container ${words} for grouping content`;
+  }
+
+  return `${words.charAt(0).toUpperCase() + words.slice(1)} component`;
+}
+
+/**
+ * Infer accessibility from props
+ */
+function inferAccessibility(props: Record<string, unknown>): {
+  role?: string;
+  requirements?: string[];
+} {
+  const accessibility: { role?: string; requirements?: string[] } = {};
+
+  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) {
+    requirements.push("Should have visible text or aria-label");
+  }
+
+  if (hasDisabled) {
+    requirements.push("Disabled state should be conveyed to assistive technology");
+  }
+
+  if (requirements.length > 0) {
+    accessibility.requirements = requirements;
+  }
+
+  return accessibility;
+}
+
+/**
+ * Infer status from file path
+ */
+function inferStatus(
+  filePath: string
+): "draft" | "experimental" | "beta" | "stable" | "deprecated" {
+  const lowerPath = filePath.toLowerCase();
+
+  if (lowerPath.includes("/experimental/") || lowerPath.includes("/labs/")) {
+    return "experimental";
+  }
+  if (lowerPath.includes("/beta/")) {
+    return "beta";
+  }
+  if (lowerPath.includes("/deprecated/") || lowerPath.includes("/legacy/")) {
+    return "deprecated";
+  }
+  if (lowerPath.includes("/draft/") || lowerPath.includes("/wip/")) {
+    return "draft";
+  }
+
+  return "stable";
+}