@fragments-sdk/cli 0.2.2

package/src/migrate/converter.ts

@@ -0,0 +1,658 @@
+/**
+ * Storybook to Segments Converter
+ *
+ * Transforms parsed Storybook data into Segment definitions.
+ */
+
+import type { ParsedStoryFile, ParsedArgType, ConversionResult } from "./types.js";
+import { storyNameToTitle, extractCategory } from "./parser.js";
+
+/**
+ * Sanitize a component name to be a valid JavaScript identifier.
+ * "No recent searches" -> "NoRecentSearches"
+ * "My-Component" -> "MyComponent"
+ */
+function sanitizeComponentName(name: string): string {
+  // Convert to PascalCase: remove spaces/hyphens, capitalize each word
+  return name
+    .split(/[\s-_]+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join("")
+    .replace(/[^a-zA-Z0-9]/g, ""); // Remove any remaining invalid chars
+}
+
+/**
+ * Convert a parsed story file into a segment definition.
+ */
+export function convertToSegment(parsed: ParsedStoryFile): ConversionResult {
+  const warnings: string[] = [...parsed.warnings];
+  const todos: string[] = [];
+
+  // Extract category and name from title
+  const category = extractCategory(parsed.meta.title);
+  const componentName = sanitizeComponentName(parsed.meta.componentName);
+
+  // Check if we have a valid component import path
+  // If not, the story likely defines the component locally or uses a pattern we can't parse
+  if (!parsed.meta.componentImport) {
+    warnings.push(`No importable component found - story may define component locally`);
+
+    // Determine output file path for the error result
+    const outputFile = parsed.filePath
+      .replace(/\.stories\.(tsx?|jsx?|mdx)$/, ".segment.tsx");
+
+    return {
+      sourceFile: parsed.filePath,
+      outputFile,
+      code: "",
+      componentName,
+      category,
+      variantCount: 0,
+      propCount: 0,
+      confidence: 0,
+      todos: [],
+      warnings,
+      success: false,
+    };
+  }
+
+  // Convert argTypes to props
+  const props = convertArgTypesToProps(parsed.argTypes);
+
+  // Convert stories to variants
+  const variants = convertStoriesToVariants(parsed, componentName);
+
+  // Track what's missing (needs human input)
+  todos.push("Add usage.when - scenarios where this component is appropriate");
+  todos.push("Add usage.whenNot - scenarios where alternatives should be used");
+  todos.push("Add usage.guidelines - best practices");
+  todos.push("Add relations - related components");
+
+  if (Object.keys(props).length > 0) {
+    const propsWithoutConstraints = Object.entries(props)
+      .filter(([, p]) => !p.constraints?.length)
+      .map(([name]) => name);
+
+    if (propsWithoutConstraints.length > 0) {
+      todos.push(`Add constraints for props: ${propsWithoutConstraints.slice(0, 3).join(", ")}${propsWithoutConstraints.length > 3 ? "..." : ""}`);
+    }
+  }
+
+  // Extract skipped variants info
+  const skippedVariants = variants
+    .filter(v => v.needsManualReview && v.skipReason)
+    .map(v => ({ name: v.name, reason: v.skipReason! }));
+
+  // Generate the segment code with _generated metadata
+  const code = generateSegmentCode({
+    componentName,
+    componentImport: parsed.meta.componentImport,
+    description: parsed.meta.description,
+    category,
+    tags: parsed.meta.tags,
+    props,
+    variants,
+    todos,
+    generated: {
+      source: "storybook",
+      sourceFile: parsed.filePath,
+      confidence: parsed.confidence,
+      timestamp: new Date().toISOString(),
+      skippedVariants: skippedVariants.length > 0 ? skippedVariants : undefined,
+    },
+  });
+
+  // Determine output file path
+  const outputFile = parsed.filePath
+    .replace(/\.stories\.(tsx?|jsx?|mdx)$/, ".segment.tsx");
+
+  return {
+    sourceFile: parsed.filePath,
+    outputFile,
+    code,
+    componentName,
+    category,
+    variantCount: variants.length,
+    propCount: Object.keys(props).length,
+    confidence: parsed.confidence,
+    todos,
+    warnings,
+    success: true,
+  };
+}
+
+/**
+ * Convert Storybook argTypes to Segments props.
+ */
+function convertArgTypesToProps(
+  argTypes: Record<string, ParsedArgType>
+): Record<string, PropDef> {
+  const props: Record<string, PropDef> = {};
+
+  for (const [name, argType] of Object.entries(argTypes)) {
+    props[name] = convertArgType(name, argType);
+  }
+
+  return props;
+}
+
+interface PropDef {
+  type: string;
+  description?: string;
+  default?: unknown;
+  required?: boolean;
+  values?: string[];
+  constraints?: string[];
+}
+
+/**
+ * Convert a single argType to a prop definition.
+ */
+function convertArgType(name: string, argType: ParsedArgType): PropDef {
+  const prop: PropDef = {
+    type: inferPropType(argType),
+  };
+
+  if (argType.description) {
+    prop.description = argType.description;
+  }
+
+  if (argType.defaultValue !== undefined) {
+    prop.default = argType.defaultValue;
+  }
+
+  if (argType.required) {
+    prop.required = true;
+  }
+
+  // Add enum values if present
+  if (argType.options && argType.options.length > 0) {
+    prop.type = "enum";
+    prop.values = argType.options;
+  }
+
+  return prop;
+}
+
+/**
+ * Infer prop type from Storybook control type.
+ */
+function inferPropType(argType: ParsedArgType): string {
+  // If explicit type is provided
+  if (argType.type) {
+    const typeMap: Record<string, string> = {
+      string: "string",
+      number: "number",
+      boolean: "boolean",
+      object: "object",
+      array: "array",
+      function: "function",
+    };
+    return typeMap[argType.type.toLowerCase()] ?? "custom";
+  }
+
+  // Infer from control type
+  if (argType.control) {
+    const controlMap: Record<string, string> = {
+      text: "string",
+      number: "number",
+      boolean: "boolean",
+      select: "enum",
+      radio: "enum",
+      "inline-radio": "enum",
+      check: "boolean",
+      "inline-check": "boolean",
+      range: "number",
+      object: "object",
+      array: "array",
+      date: "string",
+      color: "string",
+    };
+    return controlMap[argType.control] ?? "custom";
+  }
+
+  // If has options, it's an enum
+  if (argType.options && argType.options.length > 0) {
+    return "enum";
+  }
+
+  return "custom";
+}
+
+interface VariantDef {
+  name: string;
+  description: string;
+  renderCode: string;
+  needsManualReview: boolean;
+  skipReason?: string;
+}
+
+/**
+ * Convert stories to variant definitions.
+ *
+ * Stories with custom render functions or unrenderable args are marked
+ * as needing manual review since we can't reliably extract complex JSX.
+ * For these, use the viewer's native story support instead of migration.
+ */
+function convertStoriesToVariants(
+  parsed: ParsedStoryFile,
+  componentName: string
+): VariantDef[] {
+  return parsed.stories.map((story) => {
+    // Check if story has custom render or args we can't statically render
+    const hasCustomRender = story.hasCustomRender === true;
+    const unrenderableReason = getUnrenderableReason(story.args);
+    const needsManualReview = hasCustomRender || unrenderableReason !== null;
+
+    // Determine skip reason
+    let skipReason: string | undefined;
+    if (hasCustomRender) {
+      skipReason = "uses custom render function";
+    } else if (unrenderableReason) {
+      skipReason = unrenderableReason;
+    }
+
+    // Generate render code - will include comments for unrenderable values
+    const renderCode = hasCustomRender
+      ? `<${componentName} />` // Placeholder for custom render
+      : generateRenderCode(componentName, story.args);
+
+    const description = story.description ??
+      `${storyNameToTitle(story.name)} variant`;
+
+    return {
+      name: storyNameToTitle(story.name),
+      description,
+      renderCode,
+      needsManualReview,
+      skipReason,
+    };
+  });
+}
+
+/**
+ * Check if args contain values that can't be statically rendered.
+ * Returns the reason string if unrenderable, null if renderable.
+ */
+function getUnrenderableReason(args: Record<string, unknown>, path: string = ""): string | null {
+  for (const [key, value] of Object.entries(args)) {
+    const currentPath = path ? `${path}.${key}` : key;
+    if (typeof value === "string") {
+      // JSX, expressions, and variable references can't be rendered statically
+      if (value === "__JSX__") {
+        return `JSX element in prop "${currentPath}"`;
+      }
+      if (value === "__EXPR__") {
+        return `expression in prop "${currentPath}"`;
+      }
+      if (value.startsWith("__REF__")) {
+        const ref = value.slice(7);
+        return `variable reference "${ref}" in prop "${currentPath}"`;
+      }
+      if (value === "__SPREAD__" || key === "__SPREAD__") {
+        return `spread syntax in args`;
+      }
+    }
+    if (typeof value === "object" && value !== null) {
+      const nestedReason = getUnrenderableReason(value as Record<string, unknown>, currentPath);
+      if (nestedReason) {
+        return nestedReason;
+      }
+    }
+  }
+  return null;
+}
+
+// Backward compatibility wrapper
+function hasUnrenderableArgs(args: Record<string, unknown>): boolean {
+  return getUnrenderableReason(args) !== null;
+}
+
+/**
+ * Generate render code from component name and args.
+ */
+function generateRenderCode(
+  componentName: string,
+  args: Record<string, unknown>
+): string {
+  const entries = Object.entries(args);
+
+  if (entries.length === 0) {
+    return `<${componentName} />`;
+  }
+
+  // Check for children
+  const children = args.children;
+  const otherArgs = Object.entries(args).filter(([k]) => k !== "children");
+
+  // Build props string
+  const propsString = otherArgs
+    .map(([key, value]) => formatPropValue(key, value))
+    .filter(Boolean)
+    .join(" ");
+
+  if (children !== undefined) {
+    const childrenStr = formatChildrenValue(children);
+    return propsString
+      ? `<${componentName} ${propsString}>${childrenStr}</${componentName}>`
+      : `<${componentName}>${childrenStr}</${componentName}>`;
+  }
+
+  return propsString
+    ? `<${componentName} ${propsString} />`
+    : `<${componentName} />`;
+}
+
+/**
+ * Format children value for JSX.
+ */
+function formatChildrenValue(value: unknown): string {
+  if (typeof value === "string") {
+    // Handle special markers
+    if (value === "__JSX__") return "{null /* JSX children */}";
+    if (value === "__EXPR__") return "{null /* expression */}";
+    if (value.startsWith("__REF__")) return `{${value.slice(7)}}`;
+    return value;
+  }
+  return String(value);
+}
+
+/**
+ * Format a prop value for JSX.
+ */
+function formatPropValue(key: string, value: unknown): string {
+  if (value === undefined || value === null) {
+    return "";
+  }
+
+  if (typeof value === "string") {
+    // Handle special markers from parser
+    if (value === "__JSX__") {
+      // Use undefined as placeholder - JSX comments can't be prop values
+      return `${key}={undefined /* JSX */}`;
+    }
+    if (value === "__EXPR__") {
+      return `${key}={undefined /* expression */}`;
+    }
+    if (value.startsWith("__REF__")) {
+      // Variable reference - output as expression
+      return `${key}={${value.slice(7)}}`;
+    }
+    // For strings with special characters (quotes, backslashes, newlines),
+    // use JSX expression syntax {""} instead of attribute syntax ""
+    // This ensures proper JavaScript string escaping
+    if (value.includes('"') || value.includes("\\") || value.includes("\n")) {
+      return `${key}={"${escapeString(value)}"}`;
+    }
+    return `${key}="${value}"`;
+  }
+
+  if (typeof value === "boolean") {
+    return value ? key : `${key}={false}`;
+  }
+
+  if (typeof value === "number") {
+    return `${key}={${value}}`;
+  }
+
+  if (Array.isArray(value)) {
+    // Format array value
+    const formatted = formatArrayValue(value);
+    return `${key}={${formatted}}`;
+  }
+
+  if (typeof value === "object" && value !== null) {
+    // Format nested object
+    const formatted = formatObjectValue(value as Record<string, unknown>);
+    return `${key}={${formatted}}`;
+  }
+
+  // For other complex values, use JSON
+  return `${key}={${JSON.stringify(value)}}`;
+}
+
+/**
+ * Format a nested object value for JSX.
+ */
+function formatObjectValue(obj: Record<string, unknown>): string {
+  const entries = Object.entries(obj);
+  if (entries.length === 0) return "{}";
+
+  const props = entries
+    .map(([k, v]) => {
+      const formatted = formatValueForObject(v);
+      return `${k}: ${formatted}`;
+    })
+    .join(", ");
+
+  return `{ ${props} }`;
+}
+
+/**
+ * Format an array value for JSX.
+ */
+function formatArrayValue(arr: unknown[]): string {
+  if (arr.length === 0) return "[]";
+
+  const items = arr.map((item) => formatValueForObject(item));
+  return `[${items.join(", ")}]`;
+}
+
+/**
+ * Format a value for use inside an object/array literal.
+ */
+function formatValueForObject(value: unknown): string {
+  if (value === undefined) return "undefined";
+  if (value === null) return "null";
+
+  if (typeof value === "string") {
+    // Handle special markers - use valid JS values with comments
+    if (value === "__JSX__") return "undefined /* JSX */";
+    if (value === "__EXPR__") return "undefined /* expression */";
+    if (value.startsWith("__REF__")) return value.slice(7);
+    return `"${escapeString(value)}"`;
+  }
+
+  if (typeof value === "boolean" || typeof value === "number") {
+    return String(value);
+  }
+
+  if (Array.isArray(value)) {
+    return formatArrayValue(value);
+  }
+
+  if (typeof value === "object") {
+    return formatObjectValue(value as Record<string, unknown>);
+  }
+
+  return JSON.stringify(value);
+}
+
+interface SkippedVariant {
+  name: string;
+  reason: string;
+}
+
+interface GeneratedMetadata {
+  source: "storybook" | "manual" | "ai";
+  sourceFile: string;
+  confidence: number;
+  timestamp: string;
+  skippedVariants?: SkippedVariant[];
+}
+
+interface GenerateOptions {
+  componentName: string;
+  componentImport: string;
+  description?: string;
+  category: string;
+  tags?: string[];
+  props: Record<string, PropDef>;
+  variants: VariantDef[];
+  todos: string[];
+  generated?: GeneratedMetadata;
+}
+
+/**
+ * Generate the full segment file code.
+ *
+ * Note: We use a placeholder component instead of importing the real component.
+ * This allows the segment build to work without needing all component dependencies.
+ * The viewer will load the actual component at runtime.
+ */
+function generateSegmentCode(options: GenerateOptions): string {
+  const {
+    componentName,
+    componentImport,
+    description,
+    category,
+    tags,
+    props,
+    variants,
+    todos,
+    generated,
+  } = options;
+
+  // Format props
+  const propsCode = formatPropsCode(props);
+
+  // Format variants - stories with custom renders get TODO comments
+  const variantsCode = formatVariantsCode(componentName, variants);
+
+  // Format tags
+  const tagsCode = tags && tags.length > 0
+    ? `tags: [${tags.map((t) => `"${t}"`).join(", ")}],`
+    : "";
+
+  // Format TODOs as comments
+  const todosComments = todos.length > 0
+    ? todos.map((t) => `      // TODO: ${t}`).join("\n") + "\n"
+    : "";
+
+  // Format _generated metadata
+  let generatedCode = "";
+  if (generated) {
+    const skippedCode = generated.skippedVariants && generated.skippedVariants.length > 0
+      ? `
+    skippedVariants: [
+${generated.skippedVariants.map(sv => `      { name: "${escapeString(sv.name)}", reason: "${escapeString(sv.reason)}" },`).join("\n")}
+    ],`
+      : "";
+
+    generatedCode = `
+  _generated: {
+    source: "${generated.source}",
+    sourceFile: "${escapeString(generated.sourceFile)}",
+    confidence: ${generated.confidence.toFixed(2)},
+    timestamp: "${generated.timestamp}",${skippedCode}
+  },
+`;
+  }
+
+  // Import the actual component - this makes the segment immediately usable
+  return `import { defineSegment } from "@fragments/core";
+import { ${componentName} } from "${componentImport}";
+
+export default defineSegment({
+  component: ${componentName},
+
+  meta: {
+    name: "${componentName}",
+    description: "${escapeString(description ?? `${componentName} component`)}",
+    category: "${category}",
+    ${tagsCode}
+    // status: undefined, // TODO: Set to stable/beta/deprecated/experimental
+  },
+
+  usage: {
+    // TODO: Add specific use cases - when should developers use this component?
+    when: [
+${todosComments}    ],
+    // TODO: Add anti-patterns - when should developers NOT use this component?
+    whenNot: [],
+  },
+
+${propsCode}
+
+  relations: [
+    // TODO: Add related components
+  ],
+
+${variantsCode}
+${generatedCode}});
+`;
+}
+
+/**
+ * Format props object for code generation.
+ */
+function formatPropsCode(props: Record<string, PropDef>): string {
+  if (Object.keys(props).length === 0) {
+    return "  props: {},";
+  }
+
+  const entries = Object.entries(props).map(([name, prop]) => {
+    const lines: string[] = [];
+    lines.push(`    ${name}: {`);
+    lines.push(`      type: "${prop.type}",`);
+
+    if (prop.values && prop.values.length > 0) {
+      lines.push(`      values: [${prop.values.map((v) => `"${v}"`).join(", ")}],`);
+    }
+
+    if (prop.default !== undefined) {
+      const defaultVal = typeof prop.default === "string"
+        ? `"${prop.default}"`
+        : String(prop.default);
+      lines.push(`      default: ${defaultVal},`);
+    }
+
+    if (prop.required) {
+      lines.push(`      required: true,`);
+    }
+
+    if (prop.description) {
+      lines.push(`      description: "${escapeString(prop.description)}",`);
+    }
+
+    lines.push(`    },`);
+    return lines.join("\n");
+  });
+
+  return `  props: {\n${entries.join("\n")}\n  },`;
+}
+
+/**
+ * Format variants array for code generation.
+ *
+ * Variants needing manual review get a placeholder render that won't crash.
+ * This makes the segment file a starting point that humans can enhance.
+ */
+function formatVariantsCode(componentName: string, variants: VariantDef[]): string {
+  // Filter out variants that can't be rendered - they would cause runtime errors
+  const renderableVariants = variants.filter((v) => !v.needsManualReview);
+
+  if (renderableVariants.length === 0) {
+    return "  variants: [],";
+  }
+
+  const entries = renderableVariants.map((variant) => {
+    return `    {
+      name: "${variant.name}",
+      description: "${escapeString(variant.description)}",
+      render: () => ${variant.renderCode},
+    },`;
+  });
+
+  return `  variants: [\n${entries.join("\n")}\n  ],`;
+}
+
+/**
+ * Escape special characters in strings for code generation.
+ */
+function escapeString(str: string): string {
+  return str
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n");
+}