@fragments-sdk/cli 0.2.2

package/src/migrate/detect.ts

@@ -0,0 +1,196 @@
+/**
+ * Storybook Configuration Detection
+ *
+ * Auto-detects Storybook configuration files and extracts
+ * story patterns for migration.
+ */
+
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import fg from "fast-glob";
+import type { StorybookConfig } from "./types.js";
+
+/**
+ * Common Storybook config file names in order of preference
+ */
+const CONFIG_FILES = [
+  ".storybook/main.ts",
+  ".storybook/main.mts",
+  ".storybook/main.js",
+  ".storybook/main.mjs",
+  ".storybook/main.cjs",
+];
+
+/**
+ * Default story patterns if none found in config
+ */
+const DEFAULT_PATTERNS = [
+  "**/*.stories.@(ts|tsx|js|jsx|mdx)",
+  "**/*.story.@(ts|tsx|js|jsx|mdx)",
+];
+
+/**
+ * Detect Storybook configuration in a project directory.
+ */
+export async function detectStorybookConfig(
+  projectRoot: string
+): Promise<StorybookConfig | null> {
+  // Try each config file
+  for (const configFile of CONFIG_FILES) {
+    const configPath = join(projectRoot, configFile);
+    if (existsSync(configPath)) {
+      return parseStorybookConfig(configPath);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse a Storybook configuration file.
+ */
+async function parseStorybookConfig(
+  configPath: string
+): Promise<StorybookConfig> {
+  const errors: string[] = [];
+  let storyPatterns: string[] = [];
+  let framework: string | undefined;
+  let builder: string | undefined;
+
+  try {
+    const content = await readFile(configPath, "utf-8");
+
+    // Extract stories array/patterns
+    // Pattern: stories: ['../src/**/*.stories.@(ts|tsx)']
+    const storiesMatch = content.match(
+      /stories:\s*\[([^\]]+)\]/s
+    );
+
+    if (storiesMatch) {
+      // Parse the array content
+      const storiesContent = storiesMatch[1];
+      const patterns = storiesContent
+        .split(",")
+        .map((p) => p.trim())
+        .map((p) => {
+          // Remove quotes and template literals
+          const cleaned = p.replace(/^['"`]|['"`]$/g, "").trim();
+          return cleaned;
+        })
+        .filter((p) => p && !p.startsWith("//") && !p.startsWith("{"));
+
+      if (patterns.length > 0) {
+        storyPatterns = patterns;
+      }
+    }
+
+    // Extract framework
+    // Pattern: framework: '@storybook/react-vite' or framework: { name: '...' }
+    const frameworkMatch = content.match(
+      /framework:\s*['"`]([^'"`]+)['"`]/
+    );
+    if (frameworkMatch) {
+      framework = frameworkMatch[1];
+    } else {
+      const frameworkNameMatch = content.match(
+        /framework:\s*\{[^}]*name:\s*['"`]([^'"`]+)['"`]/
+      );
+      if (frameworkNameMatch) {
+        framework = frameworkNameMatch[1];
+      }
+    }
+
+    // Extract builder if specified
+    // Pattern: builder: 'vite' or core: { builder: 'vite' }
+    const builderMatch = content.match(
+      /builder:\s*['"`]([^'"`]+)['"`]/
+    );
+    if (builderMatch) {
+      builder = builderMatch[1];
+    }
+  } catch (error) {
+    errors.push(
+      `Failed to parse config: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+
+  // Use defaults if no patterns found
+  if (storyPatterns.length === 0) {
+    storyPatterns = DEFAULT_PATTERNS;
+    errors.push("No story patterns found in config, using defaults");
+  }
+
+  return {
+    configPath,
+    storyPatterns,
+    framework,
+    builder,
+    valid: errors.length === 0 || storyPatterns.length > 0,
+    errors: errors.length > 0 ? errors : undefined,
+  };
+}
+
+/**
+ * Discover story files using detected or provided patterns.
+ */
+export async function discoverStoryFiles(
+  projectRoot: string,
+  patterns?: string[]
+): Promise<string[]> {
+  // If no patterns provided, try to detect from config
+  if (!patterns || patterns.length === 0) {
+    const config = await detectStorybookConfig(projectRoot);
+    patterns = config?.storyPatterns ?? DEFAULT_PATTERNS;
+  }
+
+  // Resolve patterns relative to project root
+  const configDir = join(projectRoot, ".storybook");
+  const resolvedPatterns = patterns.map((p) => {
+    // If pattern starts with ../, resolve from .storybook dir
+    if (p.startsWith("../")) {
+      return join(configDir, p);
+    }
+    // Otherwise resolve from project root
+    return join(projectRoot, p);
+  });
+
+  // Find matching files
+  const files = await fg(resolvedPatterns, {
+    cwd: projectRoot,
+    absolute: true,
+    ignore: [
+      "**/node_modules/**",
+      "**/dist/**",
+      "**/build/**",
+      "**/.storybook/**",
+    ],
+  });
+
+  return files.sort();
+}
+
+/**
+ * Get a summary of detected Storybook setup.
+ */
+export async function getStorybookSummary(
+  projectRoot: string
+): Promise<{
+  detected: boolean;
+  config?: StorybookConfig;
+  storyCount: number;
+  storyFiles: string[];
+}> {
+  const config = await detectStorybookConfig(projectRoot);
+  const storyFiles = await discoverStoryFiles(
+    projectRoot,
+    config?.storyPatterns
+  );
+
+  return {
+    detected: config !== null,
+    config: config ?? undefined,
+    storyCount: storyFiles.length,
+    storyFiles,
+  };
+}

package/src/migrate/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @fragments/migrate
+ *
+ * Storybook to Segments migration tool.
+ *
+ * Provides automated conversion of Storybook CSF files to Segments format,
+ * preserving component documentation while adding AI-first capabilities.
+ */
+
+// Migration engine
+export { migrate } from "./migrate.js";
+
+// Parser
+export {
+  parseStoryFile,
+  parseStoryContent,
+  storyNameToTitle,
+  extractCategory,
+  __testing,
+} from "./parser.js";
+
+// Converter
+export { convertToSegment } from "./converter.js";
+
+// Report generator
+export { generateMigrationReport } from "./report.js";
+
+// Storybook detection
+export {
+  detectStorybookConfig,
+  discoverStoryFiles,
+  getStorybookSummary,
+} from "./detect.js";
+
+// Types
+export type {
+  ParsedMeta,
+  ParsedArgType,
+  ParsedStory,
+  ParsedStoryFile,
+  ConversionResult,
+  MigrationReport,
+  MigrateOptions,
+  StorybookConfig,
+} from "./types.js";

package/src/migrate/migrate.ts

@@ -0,0 +1,163 @@
+/**
+ * Migration Engine
+ *
+ * Orchestrates the full migration pipeline:
+ * 1. Discover Storybook files
+ * 2. Parse CSF format
+ * 3. Convert to Segments
+ * 4. Write output files
+ * 5. Generate report
+ */
+
+import { readdir, writeFile, mkdir, access, stat } from "node:fs/promises";
+import { join, dirname, relative } from "node:path";
+import fg from "fast-glob";
+import type {
+  MigrateOptions,
+  MigrationReport,
+  ConversionResult,
+} from "./types.js";
+import { parseStoryFile } from "./parser.js";
+import { convertToSegment } from "./converter.js";
+import { generateMigrationReport } from "./report.js";
+
+/**
+ * Run the migration process.
+ */
+export async function migrate(options: MigrateOptions): Promise<MigrationReport> {
+  const startTime = Date.now();
+
+  // Discover story files
+  const storyFiles = await discoverStoryFiles(options.from);
+
+  const results: ConversionResult[] = [];
+  const categories = new Set<string>();
+  let totalTodos = 0;
+  let totalVariants = 0;
+
+  // Process each story file
+  for (const storyFile of storyFiles) {
+    try {
+      // Parse
+      const parsed = await parseStoryFile(storyFile);
+
+      // Convert
+      const result = convertToSegment(parsed);
+
+      // Determine output path
+      const outputDir = options.to ?? dirname(storyFile);
+      const outputFile = join(outputDir, relative(dirname(storyFile), result.outputFile));
+      result.outputFile = outputFile;
+
+      // Check if file exists
+      if (!options.overwrite) {
+        try {
+          await access(outputFile);
+          result.warnings.push(`Output file already exists: ${outputFile}`);
+          if (!options.dryRun) {
+            result.success = false;
+            results.push(result);
+            continue;
+          }
+        } catch {
+          // File doesn't exist, proceed
+        }
+      }
+
+      // Write file (unless dry run)
+      if (!options.dryRun) {
+        await mkdir(dirname(outputFile), { recursive: true });
+        await writeFile(outputFile, result.code);
+      }
+
+      // Track stats
+      categories.add(result.category);
+      totalTodos += result.todos.length;
+      totalVariants += result.variantCount;
+
+      results.push(result);
+    } catch (error) {
+      results.push({
+        sourceFile: storyFile,
+        outputFile: "",
+        code: "",
+        componentName: "",
+        category: "",
+        variantCount: 0,
+        propCount: 0,
+        confidence: 0,
+        todos: [],
+        warnings: [error instanceof Error ? error.message : String(error)],
+        success: false,
+      });
+    }
+  }
+
+  // Calculate stats
+  const successfulConversions = results.filter((r) => r.success).length;
+  const failedConversions = results.filter((r) => !r.success).length;
+
+  // Build report
+  const report: MigrationReport = {
+    timestamp: new Date(),
+    sourceDir: options.from,
+    outputDir: options.to ?? options.from,
+    totalStoryFiles: storyFiles.length,
+    successfulConversions,
+    failedConversions,
+    totalVariants,
+    totalTodos,
+    results,
+    categories: Array.from(categories).sort(),
+  };
+
+  // Generate HTML report if requested
+  if (options.report) {
+    const reportHtml = generateMigrationReport(report);
+    const reportPath = options.reportPath ?? join(options.from, "migration-report.html");
+    await mkdir(dirname(reportPath), { recursive: true });
+    await writeFile(reportPath, reportHtml);
+  }
+
+  return report;
+}
+
+/**
+ * Discover Storybook story files in a directory.
+ */
+async function discoverStoryFiles(fromPath: string): Promise<string[]> {
+  // Support both file and directory paths
+  const stats = await stat(fromPath);
+
+  if (stats.isFile()) {
+    // Single file
+    if (isStoryFile(fromPath)) {
+      return [fromPath];
+    }
+    return [];
+  }
+
+  // Directory - find all story files
+  const patterns = [
+    "**/*.stories.tsx",
+    "**/*.stories.ts",
+    "**/*.stories.jsx",
+    "**/*.stories.js",
+  ];
+
+  const files = await fg(patterns, {
+    cwd: fromPath,
+    ignore: ["**/node_modules/**", "**/.storybook/**"],
+    absolute: false,
+  });
+
+  // Return absolute paths, sorted
+  return files.map((f) => join(fromPath, f)).sort();
+}
+
+/**
+ * Check if a file is a Storybook story file.
+ */
+function isStoryFile(filePath: string): boolean {
+  return /\.stories\.(tsx?|jsx?)$/.test(filePath);
+}