@fragments-sdk/cli 0.2.2

package/src/service/enhance/props-extractor.ts

@@ -0,0 +1,665 @@
+/**
+ * TypeScript Props Extractor
+ *
+ * Uses TypeScript AST to extract complete prop definitions
+ * from component TypeScript interfaces and types.
+ *
+ * This extracts:
+ * - Interface and type alias definitions
+ * - Property names, types, and optionality
+ * - JSDoc comments and descriptions
+ * - Union types (for enum-like values)
+ * - Default values from JSDoc tags
+ */
+
+import * as ts from "typescript";
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import type { PropDefinition, PropType } from "../../core/index.js";
+
+/**
+ * Extracted prop with full type information
+ */
+export interface ExtractedProp {
+  /** Prop name */
+  name: string;
+  /** Type string for display */
+  type: string;
+  /** Structured type information */
+  propType: PropType;
+  /** JSDoc description */
+  description: string;
+  /** Whether the prop is required */
+  required: boolean;
+  /** Default value if detected */
+  defaultValue?: unknown;
+  /** For enum/union types, the specific values */
+  enumValues?: string[];
+  /** Deprecation notice if present */
+  deprecated?: string;
+  /** Additional JSDoc tags */
+  tags?: Record<string, string>;
+}
+
+/**
+ * Result of props extraction from a component file
+ */
+export interface PropsExtractionResult {
+  /** Path to the source file */
+  filePath: string;
+  /** Component name */
+  componentName: string;
+  /** All extracted props */
+  props: ExtractedProp[];
+  /** Name of the props interface/type found */
+  propsTypeName?: string;
+  /** Whether extraction was successful */
+  success: boolean;
+  /** Any warnings or errors encountered */
+  warnings: string[];
+}
+
+/**
+ * Options for props extraction
+ */
+export interface PropsExtractionOptions {
+  /** Look for a specific props type name (e.g., "ButtonProps") */
+  propsTypeName?: string;
+  /** Include inherited props from extended interfaces */
+  includeInherited?: boolean;
+}
+
+/**
+ * Extract props from a TypeScript/TSX component file
+ */
+export async function extractPropsFromFile(
+  filePath: string,
+  options: PropsExtractionOptions = {}
+): Promise<PropsExtractionResult> {
+  const absPath = resolve(filePath);
+
+  if (!existsSync(absPath)) {
+    return {
+      filePath: absPath,
+      componentName: inferComponentName(absPath),
+      props: [],
+      success: false,
+      warnings: [`File not found: ${absPath}`],
+    };
+  }
+
+  const content = await readFile(absPath, "utf-8");
+  return extractPropsFromSource(content, absPath, options);
+}
+
+/**
+ * Extract props from TypeScript source code
+ */
+export function extractPropsFromSource(
+  source: string,
+  filePath: string,
+  options: PropsExtractionOptions = {}
+): PropsExtractionResult {
+  const { propsTypeName } = options;
+
+  const componentName = inferComponentName(filePath);
+  const result: PropsExtractionResult = {
+    filePath,
+    componentName,
+    props: [],
+    success: false,
+    warnings: [],
+  };
+
+  // Create a source file
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    source,
+    ts.ScriptTarget.ESNext,
+    true,
+    filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS
+  );
+
+  // Find all interfaces and type aliases that could be props
+  const propsDeclarations: Array<{
+    name: string;
+    node: ts.InterfaceDeclaration | ts.TypeAliasDeclaration;
+  }> = [];
+
+  ts.forEachChild(sourceFile, (node) => {
+    if (ts.isInterfaceDeclaration(node)) {
+      propsDeclarations.push({ name: node.name.text, node });
+    }
+    if (ts.isTypeAliasDeclaration(node)) {
+      propsDeclarations.push({ name: node.name.text, node });
+    }
+  });
+
+  // Find the best matching props type
+  const targetName = propsTypeName || `${componentName}Props`;
+  let propsDecl = propsDeclarations.find((d) => d.name === targetName);
+
+  // Fallback to common names
+  if (!propsDecl) {
+    const fallbackNames = ["Props", `${componentName}Properties`];
+    for (const name of fallbackNames) {
+      propsDecl = propsDeclarations.find((d) => d.name === name);
+      if (propsDecl) break;
+    }
+  }
+
+  // Fallback to any *Props or *Properties
+  if (!propsDecl) {
+    propsDecl = propsDeclarations.find(
+      (d) => d.name.endsWith("Props") || d.name.endsWith("Properties")
+    );
+  }
+
+  if (!propsDecl) {
+    result.warnings.push(
+      `No props type found for ${componentName}. Looked for: ${targetName}`
+    );
+    return result;
+  }
+
+  result.propsTypeName = propsDecl.name;
+
+  // Extract props from the declaration
+  if (ts.isInterfaceDeclaration(propsDecl.node)) {
+    extractPropsFromInterface(propsDecl.node, sourceFile, result);
+  } else if (ts.isTypeAliasDeclaration(propsDecl.node)) {
+    extractPropsFromTypeAlias(propsDecl.node, sourceFile, result);
+  }
+
+  result.success = result.props.length > 0;
+  return result;
+}
+
+/**
+ * Extract props from an interface declaration
+ */
+function extractPropsFromInterface(
+  node: ts.InterfaceDeclaration,
+  sourceFile: ts.SourceFile,
+  result: PropsExtractionResult
+): void {
+  for (const member of node.members) {
+    if (ts.isPropertySignature(member)) {
+      const prop = extractPropFromSignature(member, sourceFile);
+      if (prop) {
+        result.props.push(prop);
+      }
+    }
+  }
+}
+
+/**
+ * Extract props from a type alias declaration
+ */
+function extractPropsFromTypeAlias(
+  node: ts.TypeAliasDeclaration,
+  sourceFile: ts.SourceFile,
+  result: PropsExtractionResult
+): void {
+  if (ts.isTypeLiteralNode(node.type)) {
+    for (const member of node.type.members) {
+      if (ts.isPropertySignature(member)) {
+        const prop = extractPropFromSignature(member, sourceFile);
+        if (prop) {
+          result.props.push(prop);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Extract a single prop from a property signature
+ */
+function extractPropFromSignature(
+  member: ts.PropertySignature,
+  sourceFile: ts.SourceFile
+): ExtractedProp | null {
+  // Get prop name
+  const name = ts.isIdentifier(member.name)
+    ? member.name.text
+    : member.name.getText(sourceFile);
+
+  // Skip internal props
+  if (name.startsWith("_") || name.startsWith("$")) {
+    return null;
+  }
+
+  // Get type
+  const typeNode = member.type;
+  const typeString = typeNode ? typeNode.getText(sourceFile) : "unknown";
+
+  // Determine if optional
+  const isOptional = member.questionToken !== undefined;
+
+  // Get JSDoc information
+  const jsDoc = getJSDocInfo(member, sourceFile);
+
+  // Parse the type into our PropType structure
+  const typeInfo = typeNode
+    ? parseTypeNode(typeNode, sourceFile)
+    : { propType: { type: "custom" as const, typescript: "unknown" } };
+
+  const prop: ExtractedProp = {
+    name,
+    type: typeString,
+    propType: typeInfo.propType,
+    description: jsDoc.description,
+    required: !isOptional,
+  };
+
+  // Add enum values if available
+  if (typeInfo.enumValues && typeInfo.enumValues.length > 0) {
+    prop.enumValues = typeInfo.enumValues;
+  }
+
+  // Add default value if detected from JSDoc
+  if (jsDoc.defaultValue !== undefined) {
+    prop.defaultValue = jsDoc.defaultValue;
+  }
+
+  // Add deprecation notice
+  if (jsDoc.deprecated) {
+    prop.deprecated = jsDoc.deprecated;
+  }
+
+  // Add other tags
+  if (Object.keys(jsDoc.tags).length > 0) {
+    prop.tags = jsDoc.tags;
+  }
+
+  return prop;
+}
+
+/**
+ * Get JSDoc information from a node
+ */
+function getJSDocInfo(
+  node: ts.Node,
+  sourceFile: ts.SourceFile
+): {
+  description: string;
+  defaultValue?: unknown;
+  deprecated?: string;
+  tags: Record<string, string>;
+} {
+  const result = {
+    description: "",
+    defaultValue: undefined as unknown,
+    deprecated: undefined as string | undefined,
+    tags: {} as Record<string, string>,
+  };
+
+  // Get full text including comments
+  const fullText = sourceFile.getFullText();
+  const nodeStart = node.getFullStart();
+  const nodePos = node.getStart(sourceFile);
+  const leadingText = fullText.slice(nodeStart, nodePos);
+
+  // Find JSDoc comments (/** ... */)
+  const jsDocMatch = leadingText.match(/\/\*\*([\s\S]*?)\*\//);
+  if (jsDocMatch) {
+    const content = jsDocMatch[1];
+    parseJSDocContent(content, result);
+  }
+
+  // Also check line comment above (// ...)
+  const lineCommentMatch = leadingText.match(/\/\/\s*(.+)$/m);
+  if (lineCommentMatch && !result.description) {
+    result.description = lineCommentMatch[1].trim();
+  }
+
+  return result;
+}
+
+/**
+ * Parse JSDoc content into structured data
+ */
+function parseJSDocContent(
+  content: string,
+  result: {
+    description: string;
+    defaultValue?: unknown;
+    deprecated?: string;
+    tags: Record<string, string>;
+  }
+): void {
+  const lines = content.split("\n");
+  let currentDescription: string[] = [];
+  let currentTag: string | null = null;
+  let currentTagContent: string[] = [];
+
+  for (const line of lines) {
+    // Remove leading * and whitespace
+    const trimmed = line.replace(/^\s*\*?\s?/, "").trim();
+
+    // Check for JSDoc tag
+    const tagMatch = trimmed.match(/^@(\w+)(?:\s+(.*))?$/);
+
+    if (tagMatch) {
+      // Save previous tag if exists
+      if (currentTag) {
+        processJSDocTag(result, currentTag, currentTagContent.join("\n").trim());
+      } else if (currentDescription.length > 0) {
+        result.description = currentDescription.join(" ").trim();
+      }
+
+      currentTag = tagMatch[1];
+      currentTagContent = tagMatch[2] ? [tagMatch[2]] : [];
+    } else if (currentTag) {
+      if (trimmed) {
+        currentTagContent.push(trimmed);
+      }
+    } else if (trimmed) {
+      currentDescription.push(trimmed);
+    }
+  }
+
+  // Process final tag
+  if (currentTag) {
+    processJSDocTag(result, currentTag, currentTagContent.join("\n").trim());
+  } else if (currentDescription.length > 0 && !result.description) {
+    result.description = currentDescription.join(" ").trim();
+  }
+}
+
+/**
+ * Process a single JSDoc tag
+ */
+function processJSDocTag(
+  result: {
+    description: string;
+    defaultValue?: unknown;
+    deprecated?: string;
+    tags: Record<string, string>;
+  },
+  tag: string,
+  content: string
+): void {
+  switch (tag) {
+    case "default":
+    case "defaultValue":
+      result.defaultValue = parseDefaultValue(content);
+      break;
+    case "deprecated":
+      result.deprecated = content || "This prop is deprecated";
+      break;
+    case "description":
+      result.description = content;
+      break;
+    default:
+      if (content) {
+        result.tags[tag] = content;
+      }
+  }
+}
+
+/**
+ * Parse a default value from JSDoc string
+ */
+function parseDefaultValue(value: string): unknown {
+  const trimmed = value.trim();
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "null") return null;
+  if (trimmed === "undefined") return undefined;
+  if (/^-?\d+$/.test(trimmed)) return parseInt(trimmed, 10);
+  if (/^-?\d+\.\d+$/.test(trimmed)) return parseFloat(trimmed);
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    return trimmed.slice(1, -1);
+  }
+  if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+/**
+ * Parse a type node into our PropType structure
+ */
+function parseTypeNode(
+  node: ts.TypeNode,
+  sourceFile: ts.SourceFile
+): { propType: PropType; enumValues?: string[] } {
+  // Boolean keyword
+  if (node.kind === ts.SyntaxKind.BooleanKeyword) {
+    return { propType: { type: "boolean" } };
+  }
+
+  // String keyword
+  if (node.kind === ts.SyntaxKind.StringKeyword) {
+    return { propType: { type: "string" } };
+  }
+
+  // Number keyword
+  if (node.kind === ts.SyntaxKind.NumberKeyword) {
+    return { propType: { type: "number" } };
+  }
+
+  // Union type (including string literal unions -> enum)
+  if (ts.isUnionTypeNode(node)) {
+    const stringLiterals: string[] = [];
+    const otherTypes: PropType[] = [];
+
+    for (const type of node.types) {
+      if (ts.isLiteralTypeNode(type) && ts.isStringLiteral(type.literal)) {
+        stringLiterals.push(type.literal.text);
+      } else if (
+        type.kind !== ts.SyntaxKind.NullKeyword &&
+        type.kind !== ts.SyntaxKind.UndefinedKeyword
+      ) {
+        const parsed = parseTypeNode(type, sourceFile);
+        otherTypes.push(parsed.propType);
+      }
+    }
+
+    // If all non-null types are string literals, it's an enum
+    if (stringLiterals.length > 0 && otherTypes.length === 0) {
+      return {
+        propType: { type: "enum", values: stringLiterals },
+        enumValues: stringLiterals,
+      };
+    }
+
+    // If we have string literals plus other types, still treat as enum for the values
+    if (stringLiterals.length > 0) {
+      return {
+        propType: { type: "enum", values: stringLiterals },
+        enumValues: stringLiterals,
+      };
+    }
+
+    // Generic union
+    if (otherTypes.length > 0) {
+      return {
+        propType: { type: "union", types: otherTypes },
+      };
+    }
+  }
+
+  // Array type
+  if (ts.isArrayTypeNode(node)) {
+    const elementType = parseTypeNode(node.elementType, sourceFile);
+    return {
+      propType: { type: "array", items: elementType.propType },
+    };
+  }
+
+  // Function type
+  if (ts.isFunctionTypeNode(node)) {
+    const params = node.parameters
+      .map((p) => {
+        const name = p.name.getText(sourceFile);
+        const type = p.type ? p.type.getText(sourceFile) : "any";
+        return `${name}: ${type}`;
+      })
+      .join(", ");
+    const returnType = node.type ? node.type.getText(sourceFile) : "void";
+    return {
+      propType: { type: "function", signature: `(${params}) => ${returnType}` },
+    };
+  }
+
+  // Type reference (like ReactNode, ReactElement, etc.)
+  if (ts.isTypeReferenceNode(node)) {
+    const typeName = node.typeName.getText(sourceFile);
+
+    // Check for React node types
+    if (
+      typeName === "ReactNode" ||
+      typeName === "React.ReactNode" ||
+      typeName.endsWith(".ReactNode")
+    ) {
+      return { propType: { type: "node" } };
+    }
+
+    if (
+      typeName === "ReactElement" ||
+      typeName === "React.ReactElement" ||
+      typeName === "JSX.Element"
+    ) {
+      return { propType: { type: "element" } };
+    }
+
+    // Generic type reference
+    return {
+      propType: { type: "custom", typescript: node.getText(sourceFile) },
+    };
+  }
+
+  // Type literal (inline object type)
+  if (ts.isTypeLiteralNode(node)) {
+    return { propType: { type: "object" } };
+  }
+
+  // Default: custom type
+  return {
+    propType: { type: "custom", typescript: node.getText(sourceFile) },
+  };
+}
+
+/**
+ * Infer component name from file path
+ */
+function inferComponentName(filePath: string): string {
+  const fileName = basename(filePath);
+  // Remove extension
+  let name = fileName.replace(/\.(tsx?|jsx?)$/, "");
+  // Handle index files
+  if (name === "index") {
+    name = basename(dirname(filePath));
+  }
+  return name;
+}
+
+/**
+ * Convert extracted props to PropDefinition format for segments.json
+ */
+export function convertToSegmentProps(
+  props: ExtractedProp[]
+): Record<string, PropDefinition> {
+  const result: Record<string, PropDefinition> = {};
+
+  for (const prop of props) {
+    const definition: PropDefinition = {
+      type: prop.propType.type,
+      description: prop.description,
+      required: prop.required,
+    };
+
+    // Add values for enum types
+    if (prop.enumValues && prop.enumValues.length > 0) {
+      definition.values = prop.enumValues;
+    }
+
+    // Add default value
+    if (prop.defaultValue !== undefined) {
+      definition.default = prop.defaultValue;
+    }
+
+    // Add type details for complex types
+    if (prop.propType.type === "object" && "shape" in prop.propType) {
+      definition.typeDetails = { shape: prop.propType.shape };
+    }
+    if (prop.propType.type === "array" && "items" in prop.propType) {
+      definition.typeDetails = { items: prop.propType.items };
+    }
+    if (prop.propType.type === "function" && "signature" in prop.propType) {
+      definition.typeDetails = { signature: prop.propType.signature };
+    }
+    if (prop.propType.type === "union" && "types" in prop.propType) {
+      definition.typeDetails = { types: prop.propType.types };
+    }
+    if (prop.propType.type === "custom" && "typescript" in prop.propType) {
+      definition.typeDetails = { typescript: prop.propType.typescript };
+    }
+
+    result[prop.name] = definition;
+  }
+
+  return result;
+}
+
+/**
+ * Find component source file and extract props
+ */
+export async function extractPropsForComponent(
+  componentName: string,
+  searchDirs: string[]
+): Promise<PropsExtractionResult | null> {
+  const patterns = [
+    `${componentName}.tsx`,
+    `${componentName}.ts`,
+    `${componentName}/index.tsx`,
+    `${componentName}/index.ts`,
+    `${componentName}/${componentName}.tsx`,
+    `${componentName}/${componentName}.ts`,
+  ];
+
+  for (const dir of searchDirs) {
+    for (const pattern of patterns) {
+      const fullPath = join(dir, pattern);
+      if (existsSync(fullPath)) {
+        return extractPropsFromFile(fullPath, {
+          propsTypeName: `${componentName}Props`,
+        });
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extract props from multiple component files
+ */
+export async function extractAllComponentProps(
+  componentFiles: Map<string, string>
+): Promise<Map<string, PropsExtractionResult>> {
+  const results = new Map<string, PropsExtractionResult>();
+
+  for (const [componentName, filePath] of componentFiles) {
+    try {
+      const extraction = await extractPropsFromFile(filePath, {
+        propsTypeName: `${componentName}Props`,
+      });
+      results.set(componentName, extraction);
+    } catch (error) {
+      results.set(componentName, {
+        filePath,
+        componentName,
+        props: [],
+        success: false,
+        warnings: [`Extraction failed: ${(error as Error).message}`],
+      });
+    }
+  }
+
+  return results;
+}