@fragments-sdk/cli 0.2.2

package/src/service/enhance/storybook-parser.ts

@@ -0,0 +1,552 @@
+/**
+ * Storybook Parser
+ *
+ * Extracts examples and documentation from Storybook story files.
+ */
+
+import { parse } from "@babel/parser";
+import _traverse from "@babel/traverse";
+import * as t from "@babel/types";
+
+// Handle CommonJS/ESM interop
+const traverse = (_traverse as unknown as { default: typeof _traverse }).default || _traverse;
+import { readFile } from "node:fs/promises";
+import fg from "fast-glob";
+import { basename, dirname, join, relative } from "node:path";
+
+export interface StoryExample {
+  name: string;
+  displayName: string;
+  description?: string;
+  args: Record<string, unknown>;
+  code: string;
+  isDefault: boolean;
+}
+
+export interface StorybookMeta {
+  componentName: string;
+  title?: string;
+  description?: string;
+  argTypes?: Record<string, ArgType>;
+  parameters?: Record<string, unknown>;
+}
+
+export interface ArgType {
+  description?: string;
+  defaultValue?: unknown;
+  control?: string;
+  options?: string[];
+  table?: {
+    category?: string;
+    type?: { summary: string };
+  };
+}
+
+export interface ParsedStoryFile {
+  filePath: string;
+  meta: StorybookMeta;
+  stories: StoryExample[];
+}
+
+/**
+ * Parse a Storybook story file
+ */
+export async function parseStoryFile(
+  filePath: string
+): Promise<ParsedStoryFile> {
+  const content = await readFile(filePath, "utf-8");
+  return parseStorySource(content, filePath);
+}
+
+/**
+ * Parse Storybook story source code
+ */
+export function parseStorySource(
+  source: string,
+  filePath: string
+): ParsedStoryFile {
+  const isTypeScript = filePath.endsWith(".ts") || filePath.endsWith(".tsx");
+  const isJSX = filePath.endsWith(".tsx") || filePath.endsWith(".jsx");
+
+  const ast = parse(source, {
+    sourceType: "module",
+    plugins: [
+      ...(isTypeScript ? (["typescript"] as const) : []),
+      ...(isJSX ? (["jsx"] as const) : []),
+      "decorators-legacy",
+    ],
+  });
+
+  const result: ParsedStoryFile = {
+    filePath,
+    meta: {
+      componentName: inferComponentFromPath(filePath),
+    },
+    stories: [],
+  };
+
+  // Track what's been exported as default (the meta)
+  let defaultExportNode: t.Node | null = null;
+
+  // First pass: find default export (meta)
+  traverse(ast, {
+    ExportDefaultDeclaration(path) {
+      defaultExportNode = path.node.declaration;
+    },
+  });
+
+  // Parse the meta object
+  if (defaultExportNode) {
+    const metaObject = extractMetaObject(defaultExportNode, ast);
+    if (metaObject) {
+      result.meta = parseMetaObject(metaObject, result.meta.componentName);
+    }
+  }
+
+  // Second pass: find named exports (stories)
+  traverse(ast, {
+    ExportNamedDeclaration(path) {
+      const declaration = path.node.declaration;
+
+      if (t.isVariableDeclaration(declaration)) {
+        for (const declarator of declaration.declarations) {
+          if (!t.isIdentifier(declarator.id)) continue;
+
+          const storyName = declarator.id.name;
+          // Skip non-story exports (usually lowercase)
+          if (!/^[A-Z]/.test(storyName)) continue;
+
+          const story = parseStoryDeclarator(
+            storyName,
+            declarator,
+            source,
+            result.meta.componentName
+          );
+          if (story) {
+            result.stories.push(story);
+          }
+        }
+      }
+    },
+  });
+
+  // Mark Default story
+  const defaultStory = result.stories.find(
+    (s) => s.name === "Default" || s.name === "Primary"
+  );
+  if (defaultStory) {
+    defaultStory.isDefault = true;
+  }
+
+  return result;
+}
+
+/**
+ * Extract meta object from default export node
+ */
+function extractMetaObject(
+  node: t.Node,
+  ast: ReturnType<typeof parse>
+): t.ObjectExpression | null {
+  // Direct object expression: export default { ... }
+  if (t.isObjectExpression(node)) {
+    return node;
+  }
+
+  // Reference to variable: export default meta
+  if (t.isIdentifier(node)) {
+    const metaName = node.name;
+    let foundObject: t.ObjectExpression | null = null;
+    traverse(ast, {
+      VariableDeclarator(path) {
+        if (
+          t.isIdentifier(path.node.id) &&
+          path.node.id.name === metaName &&
+          t.isObjectExpression(path.node.init)
+        ) {
+          foundObject = path.node.init;
+        }
+      },
+    });
+    return foundObject;
+  }
+
+  // Type assertion: export default { ... } as Meta<typeof Button>
+  if (t.isTSAsExpression(node) && t.isObjectExpression(node.expression)) {
+    return node.expression;
+  }
+
+  // Satisfies expression: export default { ... } satisfies Meta<typeof Button>
+  if (
+    t.isTSSatisfiesExpression &&
+    t.isTSSatisfiesExpression(node) &&
+    t.isObjectExpression(node.expression)
+  ) {
+    return node.expression;
+  }
+
+  return null;
+}
+
+/**
+ * Parse the meta (default export) object
+ */
+function parseMetaObject(
+  obj: t.ObjectExpression,
+  fallbackName: string
+): StorybookMeta {
+  const meta: StorybookMeta = {
+    componentName: fallbackName,
+  };
+
+  for (const prop of obj.properties) {
+    if (!t.isObjectProperty(prop) || !t.isIdentifier(prop.key)) continue;
+
+    const key = prop.key.name;
+
+    switch (key) {
+      case "title":
+        if (t.isStringLiteral(prop.value)) {
+          meta.title = prop.value.value;
+          // Extract component name from title (e.g., "Components/Button" -> "Button")
+          const parts = meta.title.split("/");
+          meta.componentName = parts[parts.length - 1];
+        }
+        break;
+
+      case "component":
+        if (t.isIdentifier(prop.value)) {
+          meta.componentName = prop.value.name;
+        }
+        break;
+
+      case "parameters":
+        if (t.isObjectExpression(prop.value)) {
+          meta.parameters = extractObjectLiteral(prop.value);
+          // Extract description from parameters.docs.description.component
+          const docs = meta.parameters?.docs as Record<string, unknown>;
+          if (docs?.description) {
+            const desc = docs.description as Record<string, string>;
+            if (desc.component) {
+              meta.description = desc.component;
+            }
+          }
+        }
+        break;
+
+      case "argTypes":
+        if (t.isObjectExpression(prop.value)) {
+          meta.argTypes = parseArgTypes(prop.value);
+        }
+        break;
+    }
+  }
+
+  return meta;
+}
+
+/**
+ * Parse argTypes object
+ */
+function parseArgTypes(obj: t.ObjectExpression): Record<string, ArgType> {
+  const argTypes: Record<string, ArgType> = {};
+
+  for (const prop of obj.properties) {
+    if (!t.isObjectProperty(prop) || !t.isIdentifier(prop.key)) continue;
+
+    const propName = prop.key.name;
+    const argType: ArgType = {};
+
+    if (t.isObjectExpression(prop.value)) {
+      for (const inner of prop.value.properties) {
+        if (!t.isObjectProperty(inner) || !t.isIdentifier(inner.key)) continue;
+
+        const innerKey = inner.key.name;
+
+        if (innerKey === "description" && t.isStringLiteral(inner.value)) {
+          argType.description = inner.value.value;
+        }
+
+        if (innerKey === "defaultValue") {
+          argType.defaultValue = extractLiteralValue(inner.value);
+        }
+
+        if (innerKey === "control") {
+          if (t.isStringLiteral(inner.value)) {
+            argType.control = inner.value.value;
+          } else if (t.isObjectExpression(inner.value)) {
+            const controlObj = extractObjectLiteral(inner.value);
+            argType.control = controlObj?.type as string;
+          }
+        }
+
+        if (innerKey === "options" && t.isArrayExpression(inner.value)) {
+          argType.options = inner.value.elements
+            .filter((el): el is t.StringLiteral => t.isStringLiteral(el))
+            .map((el) => el.value);
+        }
+      }
+    }
+
+    argTypes[propName] = argType;
+  }
+
+  return argTypes;
+}
+
+/**
+ * Parse a story variable declarator
+ */
+function parseStoryDeclarator(
+  name: string,
+  declarator: t.VariableDeclarator,
+  source: string,
+  componentName: string
+): StoryExample | null {
+  const init = declarator.init;
+  if (!init) return null;
+
+  const story: StoryExample = {
+    name,
+    displayName: camelToTitle(name),
+    args: {},
+    code: "",
+    isDefault: false,
+  };
+
+  // Handle object-style story: export const Primary = { args: { ... } }
+  if (t.isObjectExpression(init)) {
+    parseStoryObject(init, story);
+    story.code = generateStoryCode(componentName, story.args);
+    return story;
+  }
+
+  // Handle: export const Primary: Story = { ... }
+  if (
+    t.isTSAsExpression(init) &&
+    t.isObjectExpression(init.expression)
+  ) {
+    parseStoryObject(init.expression, story);
+    story.code = generateStoryCode(componentName, story.args);
+    return story;
+  }
+
+  // Handle render function style: export const Primary = () => <Button />
+  if (t.isArrowFunctionExpression(init) || t.isFunctionExpression(init)) {
+    // Extract the code from source
+    if (init.start != null && init.end != null) {
+      const fnCode = source.slice(init.start, init.end);
+      story.code = fnCode;
+    }
+    return story;
+  }
+
+  // Handle satisfies expression: export const Primary = { ... } satisfies Story
+  if (t.isTSSatisfiesExpression && t.isTSSatisfiesExpression(init)) {
+    if (t.isObjectExpression(init.expression)) {
+      parseStoryObject(init.expression, story);
+      story.code = generateStoryCode(componentName, story.args);
+      return story;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse story object properties
+ */
+function parseStoryObject(obj: t.ObjectExpression, story: StoryExample): void {
+  for (const prop of obj.properties) {
+    if (!t.isObjectProperty(prop) || !t.isIdentifier(prop.key)) continue;
+
+    const key = prop.key.name;
+
+    switch (key) {
+      case "name":
+        if (t.isStringLiteral(prop.value)) {
+          story.displayName = prop.value.value;
+        }
+        break;
+
+      case "args":
+        if (t.isObjectExpression(prop.value)) {
+          story.args = extractObjectLiteral(prop.value);
+        }
+        break;
+
+      case "parameters":
+        if (t.isObjectExpression(prop.value)) {
+          const params = extractObjectLiteral(prop.value);
+          const docs = params?.docs as Record<string, unknown>;
+          if (docs?.description) {
+            const desc = docs.description as Record<string, string>;
+            if (desc.story) {
+              story.description = desc.story;
+            }
+          }
+        }
+        break;
+    }
+  }
+}
+
+/**
+ * Extract a literal value from an AST node
+ */
+function extractLiteralValue(node: t.Node): unknown {
+  if (t.isStringLiteral(node)) return node.value;
+  if (t.isNumericLiteral(node)) return node.value;
+  if (t.isBooleanLiteral(node)) return node.value;
+  if (t.isNullLiteral(node)) return null;
+  if (t.isIdentifier(node) && node.name === "undefined") return undefined;
+
+  if (t.isArrayExpression(node)) {
+    return node.elements
+      .filter((el): el is t.Expression => el !== null && t.isExpression(el))
+      .map(extractLiteralValue);
+  }
+
+  if (t.isObjectExpression(node)) {
+    return extractObjectLiteral(node);
+  }
+
+  // Can't extract complex expressions
+  return undefined;
+}
+
+/**
+ * Extract an object literal into a plain object
+ */
+function extractObjectLiteral(
+  node: t.ObjectExpression
+): Record<string, unknown> {
+  const obj: Record<string, unknown> = {};
+
+  for (const prop of node.properties) {
+    if (t.isSpreadElement(prop)) continue;
+    if (!t.isObjectProperty(prop)) continue;
+
+    let key: string;
+    if (t.isIdentifier(prop.key)) {
+      key = prop.key.name;
+    } else if (t.isStringLiteral(prop.key)) {
+      key = prop.key.value;
+    } else {
+      continue;
+    }
+
+    obj[key] = extractLiteralValue(prop.value);
+  }
+
+  return obj;
+}
+
+/**
+ * Generate example code from component name and args
+ */
+function generateStoryCode(
+  componentName: string,
+  args: Record<string, unknown>
+): string {
+  const props = Object.entries(args)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => {
+      if (typeof value === "string") {
+        return `${key}="${value}"`;
+      }
+      if (typeof value === "boolean" && value) {
+        return key;
+      }
+      return `${key}={${JSON.stringify(value)}}`;
+    })
+    .join(" ");
+
+  if (props) {
+    return `<${componentName} ${props} />`;
+  }
+  return `<${componentName} />`;
+}
+
+/**
+ * Convert camelCase to Title Case
+ */
+function camelToTitle(str: string): string {
+  return str
+    .replace(/([A-Z])/g, " $1")
+    .replace(/^./, (s) => s.toUpperCase())
+    .trim();
+}
+
+/**
+ * Infer component name from story file path
+ */
+function inferComponentFromPath(filePath: string): string {
+  const fileName = basename(filePath);
+  // Remove .stories.tsx etc
+  let name = fileName.replace(/\.stories\.(tsx?|jsx?|mdx?)$/, "");
+  // Handle patterns like Button.stories.tsx
+  return name;
+}
+
+/**
+ * Find all story files in a directory
+ */
+export async function findStoryFiles(
+  rootDir: string,
+  include: string[] = ["**/*.stories.{tsx,ts,jsx,js}"],
+  exclude: string[] = ["**/node_modules/**", "**/dist/**"]
+): Promise<string[]> {
+  return fg(include, {
+    cwd: rootDir,
+    ignore: exclude,
+    absolute: true,
+    onlyFiles: true,
+  });
+}
+
+/**
+ * Parse all story files and group by component
+ */
+export async function parseAllStories(
+  rootDir: string
+): Promise<Map<string, ParsedStoryFile>> {
+  const storyFiles = await findStoryFiles(rootDir);
+  const results = new Map<string, ParsedStoryFile>();
+
+  for (const filePath of storyFiles) {
+    try {
+      const parsed = await parseStoryFile(filePath);
+      results.set(parsed.meta.componentName, parsed);
+    } catch (error) {
+      console.warn(
+        `Failed to parse story file ${relative(rootDir, filePath)}:`,
+        (error as Error).message
+      );
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Merge Storybook data into extracted docs
+ */
+export function mergeStorybookIntoDoc(
+  storyFile: ParsedStoryFile,
+  existingExamples: string[] = []
+): string[] {
+  const examples = [...existingExamples];
+
+  for (const story of storyFile.stories) {
+    if (story.code && !examples.includes(story.code)) {
+      // Add with story name as comment
+      const example = story.description
+        ? `// ${story.displayName}: ${story.description}\n${story.code}`
+        : `// ${story.displayName}\n${story.code}`;
+      examples.push(example);
+    }
+  }
+
+  return examples;
+}