@fragments-sdk/cli 0.2.2

package/src/core/parser.ts

@@ -0,0 +1,551 @@
+/**
+ * AST-Based Segment Parser
+ *
+ * Extracts segment metadata from .segment.tsx files WITHOUT executing them.
+ * This allows `segments build` to work without any project dependencies.
+ *
+ * Uses TypeScript's compiler API to parse and analyze the AST.
+ */
+
+import ts from "typescript";
+import type { SegmentMeta, SegmentUsage, PropDefinition } from "./types.js";
+
+/**
+ * Parsed segment metadata (extracted statically from AST)
+ */
+export interface ParsedSegmentMetadata {
+  /** Component import path (e.g., "./Button" or "@/components/Button") */
+  componentImport: string | null;
+
+  /** Component name as used in the file */
+  componentName: string | null;
+
+  /** Component metadata */
+  meta: Partial<SegmentMeta>;
+
+  /** Usage guidelines */
+  usage: Partial<SegmentUsage>;
+
+  /** Props documentation */
+  props: Record<string, Partial<PropDefinition>>;
+
+  /** Variant definitions */
+  variants: Array<{
+    name: string;
+    description: string;
+    code?: string;
+    figma?: string;
+    args?: Record<string, unknown>;
+  }>;
+
+  /** Related components */
+  relations: Array<{
+    component: string;
+    relationship: string;
+    note: string;
+  }>;
+
+  /** Parse warnings */
+  warnings: string[];
+}
+
+/**
+ * Parse a segment file and extract metadata without executing it.
+ */
+export function parseSegmentFile(
+  fileContent: string,
+  filePath?: string
+): ParsedSegmentMetadata {
+  const warnings: string[] = [];
+
+  // Parse the file
+  const sourceFile = ts.createSourceFile(
+    filePath ?? "segment.tsx",
+    fileContent,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX
+  );
+
+  // Find imports
+  const imports = extractImports(sourceFile);
+
+  // Find the defineSegment call
+  const defineSegmentCall = findDefineSegmentCall(sourceFile);
+
+  if (!defineSegmentCall) {
+    warnings.push("No defineSegment() call found");
+    return {
+      componentImport: null,
+      componentName: null,
+      meta: {},
+      usage: { when: [], whenNot: [] },
+      props: {},
+      variants: [],
+      relations: [],
+      warnings,
+    };
+  }
+
+  // Extract the argument (object literal)
+  const arg = defineSegmentCall.arguments[0];
+  if (!arg || !ts.isObjectLiteralExpression(arg)) {
+    warnings.push("defineSegment() argument is not an object literal");
+    return {
+      componentImport: null,
+      componentName: null,
+      meta: {},
+      usage: { when: [], whenNot: [] },
+      props: {},
+      variants: [],
+      relations: [],
+      warnings,
+    };
+  }
+
+  // Extract component reference
+  const componentProp = findProperty(arg, "component");
+  let componentName: string | null = null;
+  let componentImport: string | null = null;
+
+  if (componentProp && ts.isIdentifier(componentProp)) {
+    componentName = componentProp.text;
+    // Find the import for this component
+    componentImport = imports.get(componentName) ?? null;
+  }
+
+  // Extract meta
+  const meta = extractMeta(arg, warnings);
+
+  // Extract usage
+  const usage = extractUsage(arg, warnings);
+
+  // Extract props
+  const props = extractProps(arg, warnings);
+
+  // Extract variants
+  const variants = extractVariants(arg, sourceFile, warnings);
+
+  // Extract relations
+  const relations = extractRelations(arg, warnings);
+
+  return {
+    componentImport,
+    componentName,
+    meta,
+    usage,
+    props,
+    variants,
+    relations,
+    warnings,
+  };
+}
+
+/**
+ * Extract all imports from the source file.
+ * Returns a map of imported name -> module path
+ */
+function extractImports(sourceFile: ts.SourceFile): Map<string, string> {
+  const imports = new Map<string, string>();
+
+  ts.forEachChild(sourceFile, (node) => {
+    if (ts.isImportDeclaration(node)) {
+      const moduleSpecifier = node.moduleSpecifier;
+      if (ts.isStringLiteral(moduleSpecifier)) {
+        const modulePath = moduleSpecifier.text;
+
+        // Handle named imports
+        const importClause = node.importClause;
+        if (importClause) {
+          // Default import
+          if (importClause.name) {
+            imports.set(importClause.name.text, modulePath);
+          }
+
+          // Named imports
+          const namedBindings = importClause.namedBindings;
+          if (namedBindings && ts.isNamedImports(namedBindings)) {
+            for (const element of namedBindings.elements) {
+              imports.set(element.name.text, modulePath);
+            }
+          }
+        }
+      }
+    }
+  });
+
+  return imports;
+}
+
+/**
+ * Find the defineSegment() call in the source file.
+ */
+function findDefineSegmentCall(
+  sourceFile: ts.SourceFile
+): ts.CallExpression | null {
+  let result: ts.CallExpression | null = null;
+
+  function visit(node: ts.Node): void {
+    if (ts.isCallExpression(node)) {
+      const expression = node.expression;
+      if (ts.isIdentifier(expression) && expression.text === "defineSegment") {
+        result = node;
+        return;
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return result;
+}
+
+/**
+ * Find a property in an object literal by name.
+ */
+function findProperty(
+  obj: ts.ObjectLiteralExpression,
+  name: string
+): ts.Expression | null {
+  for (const prop of obj.properties) {
+    if (ts.isPropertyAssignment(prop)) {
+      const propName = prop.name;
+      if (ts.isIdentifier(propName) && propName.text === name) {
+        return prop.initializer;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract meta object from defineSegment call.
+ */
+function extractMeta(
+  arg: ts.ObjectLiteralExpression,
+  warnings: string[]
+): Partial<SegmentMeta> {
+  const metaProp = findProperty(arg, "meta");
+  if (!metaProp || !ts.isObjectLiteralExpression(metaProp)) {
+    warnings.push("No meta object found");
+    return {};
+  }
+
+  const meta: Partial<SegmentMeta> = {};
+
+  // Extract string properties
+  const name = extractStringProperty(metaProp, "name");
+  if (name) meta.name = name;
+
+  const description = extractStringProperty(metaProp, "description");
+  if (description) meta.description = description;
+
+  const category = extractStringProperty(metaProp, "category");
+  if (category) meta.category = category;
+
+  const status = extractStringProperty(metaProp, "status") as SegmentMeta["status"];
+  if (status) meta.status = status;
+
+  const since = extractStringProperty(metaProp, "since");
+  if (since) meta.since = since;
+
+  // Extract figma URL
+  const figma = extractStringProperty(metaProp, "figma");
+  if (figma) meta.figma = figma;
+
+  // Extract tags array
+  const tags = extractStringArray(metaProp, "tags");
+  if (tags.length > 0) meta.tags = tags;
+
+  return meta;
+}
+
+/**
+ * Extract usage object from defineSegment call.
+ */
+function extractUsage(
+  arg: ts.ObjectLiteralExpression,
+  warnings: string[]
+): Partial<SegmentUsage> {
+  const usageProp = findProperty(arg, "usage");
+  if (!usageProp || !ts.isObjectLiteralExpression(usageProp)) {
+    return { when: [], whenNot: [] };
+  }
+
+  return {
+    when: extractStringArray(usageProp, "when"),
+    whenNot: extractStringArray(usageProp, "whenNot"),
+    guidelines: extractStringArray(usageProp, "guidelines"),
+    accessibility: extractStringArray(usageProp, "accessibility"),
+  };
+}
+
+/**
+ * Extract props object from defineSegment call.
+ */
+function extractProps(
+  arg: ts.ObjectLiteralExpression,
+  warnings: string[]
+): Record<string, Partial<PropDefinition>> {
+  const propsProp = findProperty(arg, "props");
+  if (!propsProp || !ts.isObjectLiteralExpression(propsProp)) {
+    return {};
+  }
+
+  const props: Record<string, Partial<PropDefinition>> = {};
+
+  for (const prop of propsProp.properties) {
+    if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+      const propName = prop.name.text;
+      const propValue = prop.initializer;
+
+      if (ts.isObjectLiteralExpression(propValue)) {
+        props[propName] = extractPropDefinition(propValue);
+      }
+    }
+  }
+
+  return props;
+}
+
+/**
+ * Extract a single prop definition.
+ */
+function extractPropDefinition(
+  obj: ts.ObjectLiteralExpression
+): Partial<PropDefinition> {
+  const def: Partial<PropDefinition> = {};
+
+  const type = extractStringProperty(obj, "type");
+  if (type) def.type = type as PropDefinition["type"];
+
+  const description = extractStringProperty(obj, "description");
+  if (description) def.description = description;
+
+  const values = extractStringArray(obj, "values");
+  if (values.length > 0) def.values = values;
+
+  const required = extractBooleanProperty(obj, "required");
+  if (required !== null) def.required = required;
+
+  // Default value - try to extract as literal
+  const defaultProp = findProperty(obj, "default");
+  if (defaultProp) {
+    def.default = extractLiteralValue(defaultProp);
+  }
+
+  const constraints = extractStringArray(obj, "constraints");
+  if (constraints.length > 0) def.constraints = constraints;
+
+  return def;
+}
+
+/**
+ * Extract variants array from defineSegment call.
+ */
+function extractVariants(
+  arg: ts.ObjectLiteralExpression,
+  sourceFile: ts.SourceFile,
+  warnings: string[]
+): Array<{ name: string; description: string; code?: string; figma?: string; args?: Record<string, unknown> }> {
+  const variantsProp = findProperty(arg, "variants");
+  if (!variantsProp || !ts.isArrayLiteralExpression(variantsProp)) {
+    return [];
+  }
+
+  const variants: Array<{ name: string; description: string; code?: string; figma?: string; args?: Record<string, unknown> }> = [];
+
+  for (const element of variantsProp.elements) {
+    if (ts.isObjectLiteralExpression(element)) {
+      const name = extractStringProperty(element, "name");
+      const description = extractStringProperty(element, "description");
+
+      if (name) {
+        const variant: { name: string; description: string; code?: string; figma?: string; args?: Record<string, unknown> } = {
+          name,
+          description: description ?? "",
+        };
+
+        // Try to extract code property if present
+        const codeProp = findProperty(element, "code");
+        if (codeProp && ts.isStringLiteral(codeProp)) {
+          variant.code = codeProp.text;
+        }
+
+        // Try to extract render function and convert to code string
+        const renderProp = findProperty(element, "render");
+        if (renderProp && !variant.code) {
+          variant.code = extractRenderCode(renderProp, sourceFile);
+        }
+
+        // Extract figma URL for variant
+        const figma = extractStringProperty(element, "figma");
+        if (figma) {
+          variant.figma = figma;
+        }
+
+        // Extract args object for code generation
+        const argsProp = findProperty(element, "args");
+        if (argsProp && ts.isObjectLiteralExpression(argsProp)) {
+          const argsValue = extractLiteralValue(argsProp);
+          if (argsValue && typeof argsValue === 'object' && !Array.isArray(argsValue)) {
+            variant.args = argsValue as Record<string, unknown>;
+          }
+        }
+
+        variants.push(variant);
+      }
+    }
+  }
+
+  return variants;
+}
+
+/**
+ * Extract the code from a render function.
+ */
+function extractRenderCode(
+  renderProp: ts.Expression,
+  sourceFile: ts.SourceFile
+): string | undefined {
+  // Handle arrow function: () => <Component />
+  if (ts.isArrowFunction(renderProp)) {
+    const body = renderProp.body;
+    // Get the source text of the body
+    const start = body.getStart(sourceFile);
+    const end = body.getEnd();
+    let code = sourceFile.text.substring(start, end).trim();
+
+    // Remove parentheses if present
+    if (code.startsWith("(") && code.endsWith(")")) {
+      code = code.slice(1, -1).trim();
+    }
+
+    return code;
+  }
+
+  return undefined;
+}
+
+/**
+ * Extract relations array from defineSegment call.
+ */
+function extractRelations(
+  arg: ts.ObjectLiteralExpression,
+  warnings: string[]
+): Array<{ component: string; relationship: string; note: string }> {
+  const relationsProp = findProperty(arg, "relations");
+  if (!relationsProp || !ts.isArrayLiteralExpression(relationsProp)) {
+    return [];
+  }
+
+  const relations: Array<{ component: string; relationship: string; note: string }> = [];
+
+  for (const element of relationsProp.elements) {
+    if (ts.isObjectLiteralExpression(element)) {
+      const component = extractStringProperty(element, "component");
+      const relationship = extractStringProperty(element, "relationship");
+      const note = extractStringProperty(element, "note");
+
+      if (component && relationship) {
+        relations.push({
+          component,
+          relationship,
+          note: note ?? "",
+        });
+      }
+    }
+  }
+
+  return relations;
+}
+
+/**
+ * Extract a string property from an object literal.
+ */
+function extractStringProperty(
+  obj: ts.ObjectLiteralExpression,
+  name: string
+): string | null {
+  const prop = findProperty(obj, name);
+  if (prop && ts.isStringLiteral(prop)) {
+    return prop.text;
+  }
+  // Handle template literals without expressions
+  if (prop && ts.isNoSubstitutionTemplateLiteral(prop)) {
+    return prop.text;
+  }
+  return null;
+}
+
+/**
+ * Extract a boolean property from an object literal.
+ */
+function extractBooleanProperty(
+  obj: ts.ObjectLiteralExpression,
+  name: string
+): boolean | null {
+  const prop = findProperty(obj, name);
+  if (prop) {
+    if (prop.kind === ts.SyntaxKind.TrueKeyword) return true;
+    if (prop.kind === ts.SyntaxKind.FalseKeyword) return false;
+  }
+  return null;
+}
+
+/**
+ * Extract a string array from an object literal.
+ */
+function extractStringArray(
+  obj: ts.ObjectLiteralExpression,
+  name: string
+): string[] {
+  const prop = findProperty(obj, name);
+  if (!prop || !ts.isArrayLiteralExpression(prop)) {
+    return [];
+  }
+
+  const result: string[] = [];
+  for (const element of prop.elements) {
+    if (ts.isStringLiteral(element)) {
+      result.push(element.text);
+    } else if (ts.isNoSubstitutionTemplateLiteral(element)) {
+      result.push(element.text);
+    }
+  }
+  return result;
+}
+
+/**
+ * Extract a literal value from an expression.
+ */
+function extractLiteralValue(expr: ts.Expression): unknown {
+  if (ts.isStringLiteral(expr)) {
+    return expr.text;
+  }
+  if (ts.isNumericLiteral(expr)) {
+    return Number(expr.text);
+  }
+  if (expr.kind === ts.SyntaxKind.TrueKeyword) {
+    return true;
+  }
+  if (expr.kind === ts.SyntaxKind.FalseKeyword) {
+    return false;
+  }
+  if (expr.kind === ts.SyntaxKind.NullKeyword) {
+    return null;
+  }
+  if (ts.isArrayLiteralExpression(expr)) {
+    return expr.elements.map(extractLiteralValue);
+  }
+  if (ts.isObjectLiteralExpression(expr)) {
+    const obj: Record<string, unknown> = {};
+    for (const prop of expr.properties) {
+      if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+        obj[prop.name.text] = extractLiteralValue(prop.initializer);
+      }
+    }
+    return obj;
+  }
+  return undefined;
+}

package/src/core/previewLoader.ts

@@ -0,0 +1,172 @@
+/**
+ * Loader for Storybook .storybook/preview.{tsx,ts,jsx,js} configuration.
+ *
+ * This module detects and loads Storybook preview configuration to extract:
+ * - decorators: Global decorators applied to all stories
+ * - parameters: Global parameters for all stories
+ * - globalTypes: Global type definitions (e.g., for toolbar controls)
+ * - args: Default args for all stories
+ * - argTypes: Default argTypes for all stories
+ * - loaders: Global loaders for all stories
+ */
+
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { PreviewConfig } from "./storyAdapter.js";
+
+/**
+ * Possible file extensions and names for preview config
+ */
+const PREVIEW_FILES = [
+  "preview.tsx",
+  "preview.ts",
+  "preview.jsx",
+  "preview.js",
+];
+
+/**
+ * Find the preview config file in a .storybook directory
+ *
+ * @param storybookDir - Path to the .storybook directory
+ * @returns The full path to the preview file, or null if not found
+ */
+export function findPreviewConfigPath(storybookDir: string): string | null {
+  for (const fileName of PREVIEW_FILES) {
+    const filePath = join(storybookDir, fileName);
+    if (existsSync(filePath)) {
+      return filePath;
+    }
+  }
+  return null;
+}
+
+/**
+ * Find the .storybook directory starting from a project root.
+ * Checks common locations.
+ *
+ * @param projectRoot - The project root directory
+ * @returns The path to the .storybook directory, or null if not found
+ */
+export function findStorybookDir(projectRoot: string): string | null {
+  const possiblePaths = [
+    join(projectRoot, ".storybook"),
+    join(projectRoot, "storybook"),
+  ];
+
+  for (const dir of possiblePaths) {
+    if (existsSync(dir)) {
+      return dir;
+    }
+  }
+  return null;
+}
+
+/**
+ * Load and parse the Storybook preview configuration.
+ *
+ * This function dynamically imports the preview file and extracts
+ * the relevant configuration exports.
+ *
+ * @param previewPath - Full path to the preview config file
+ * @returns The parsed preview configuration
+ */
+export async function loadPreviewConfig(
+  previewPath: string
+): Promise<PreviewConfig> {
+  try {
+    // Dynamic import with file:// URL for ESM compatibility
+    const fileUrl = new URL(`file://${resolve(previewPath)}`);
+    const module = await import(fileUrl.href);
+
+    // Extract configuration from the module
+    const config: PreviewConfig = {
+      decorators: module.decorators ?? module.default?.decorators ?? [],
+      parameters: module.parameters ?? module.default?.parameters ?? {},
+      globalTypes: module.globalTypes ?? module.default?.globalTypes ?? {},
+      args: module.args ?? module.default?.args ?? {},
+      argTypes: module.argTypes ?? module.default?.argTypes ?? {},
+      loaders: module.loaders ?? module.default?.loaders ?? [],
+    };
+
+    return config;
+  } catch (error) {
+    console.warn(
+      `[Segments] Failed to load preview config from ${previewPath}:`,
+      error instanceof Error ? error.message : error
+    );
+    return {};
+  }
+}
+
+/**
+ * Auto-detect and load preview configuration from a project.
+ *
+ * @param projectRoot - The project root directory
+ * @returns The preview configuration, or empty config if not found
+ */
+export async function autoLoadPreviewConfig(
+  projectRoot: string
+): Promise<PreviewConfig> {
+  const storybookDir = findStorybookDir(projectRoot);
+  if (!storybookDir) {
+    return {};
+  }
+
+  const previewPath = findPreviewConfigPath(storybookDir);
+  if (!previewPath) {
+    return {};
+  }
+
+  return loadPreviewConfig(previewPath);
+}
+
+/**
+ * Generate a virtual module that imports and re-exports preview config.
+ * This is used in the Vite plugin to make preview config available at runtime.
+ *
+ * @param previewPath - Full path to the preview config file, or null
+ * @returns JavaScript code for the virtual module
+ */
+export function generatePreviewModule(previewPath: string | null): string {
+  if (!previewPath) {
+    // No preview config found - export empty defaults
+    return `
+export const decorators = [];
+export const parameters = {};
+export const globalTypes = {};
+export const args = {};
+export const argTypes = {};
+export const loaders = [];
+
+export default {
+  decorators,
+  parameters,
+  globalTypes,
+  args,
+  argTypes,
+  loaders,
+};
+`;
+  }
+
+  // Import from the actual preview file and re-export
+  return `
+import * as preview from "${previewPath}";
+
+export const decorators = preview.decorators ?? preview.default?.decorators ?? [];
+export const parameters = preview.parameters ?? preview.default?.parameters ?? {};
+export const globalTypes = preview.globalTypes ?? preview.default?.globalTypes ?? {};
+export const args = preview.args ?? preview.default?.args ?? {};
+export const argTypes = preview.argTypes ?? preview.default?.argTypes ?? {};
+export const loaders = preview.loaders ?? preview.default?.loaders ?? [];
+
+export default {
+  decorators,
+  parameters,
+  globalTypes,
+  args,
+  argTypes,
+  loaders,
+};
+`;
+}