@fragments-sdk/cli 0.2.2

package/src/core/generators/typescript-extractor.ts

@@ -0,0 +1,374 @@
+/**
+ * TypeScript Props Extractor
+ * Extracts prop types, default values, and JSDoc comments from React component files
+ */
+
+import ts from "typescript";
+import { readFileSync } from "node:fs";
+import type { RegistryPropEntry } from "../fragment-types.js";
+
+/**
+ * Result of extracting props from a component file
+ */
+export interface ExtractedProps {
+  /** Component name */
+  componentName: string;
+  /** Props interface name (e.g., "ButtonProps") */
+  propsInterfaceName?: string;
+  /** Extracted props */
+  props: Record<string, RegistryPropEntry>;
+  /** Named exports from the file */
+  exports: string[];
+  /** Import statements (for dependency tracking) */
+  imports: string[];
+}
+
+/**
+ * Extract props from a TypeScript/TSX component file
+ */
+export function extractPropsFromFile(filePath: string): ExtractedProps | null {
+  const sourceText = readFileSync(filePath, "utf-8");
+  return extractPropsFromSource(sourceText, filePath);
+}
+
+/**
+ * Extract props from TypeScript source code
+ */
+export function extractPropsFromSource(
+  sourceText: string,
+  fileName = "component.tsx"
+): ExtractedProps | null {
+  const sourceFile = ts.createSourceFile(
+    fileName,
+    sourceText,
+    ts.ScriptTarget.Latest,
+    true,
+    fileName.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS
+  );
+
+  const result: ExtractedProps = {
+    componentName: "",
+    props: {},
+    exports: [],
+    imports: [],
+  };
+
+  // Find all exports and props interfaces
+  const propsInterfaces = new Map<string, ts.InterfaceDeclaration | ts.TypeAliasDeclaration>();
+  const componentExports: string[] = [];
+  const importedModules: string[] = [];
+
+  ts.forEachChild(sourceFile, (node) => {
+    // Track imports
+    if (ts.isImportDeclaration(node)) {
+      const moduleSpecifier = node.moduleSpecifier;
+      if (ts.isStringLiteral(moduleSpecifier)) {
+        importedModules.push(moduleSpecifier.text);
+      }
+    }
+
+    // Find interface declarations (e.g., interface ButtonProps { ... })
+    if (ts.isInterfaceDeclaration(node)) {
+      const name = node.name.text;
+      if (name.endsWith("Props")) {
+        propsInterfaces.set(name, node);
+      }
+    }
+
+    // Find type alias declarations (e.g., type ButtonProps = { ... })
+    if (ts.isTypeAliasDeclaration(node)) {
+      const name = node.name.text;
+      if (name.endsWith("Props")) {
+        propsInterfaces.set(name, node);
+      }
+    }
+
+    // Find exported functions/components
+    if (ts.isFunctionDeclaration(node) && node.name) {
+      const hasExport = node.modifiers?.some(
+        (m) => m.kind === ts.SyntaxKind.ExportKeyword
+      );
+      if (hasExport) {
+        componentExports.push(node.name.text);
+      }
+    }
+
+    // Find exported variable declarations (e.g., export const Button = ...)
+    if (ts.isVariableStatement(node)) {
+      const hasExport = node.modifiers?.some(
+        (m) => m.kind === ts.SyntaxKind.ExportKeyword
+      );
+      if (hasExport) {
+        for (const decl of node.declarationList.declarations) {
+          if (ts.isIdentifier(decl.name)) {
+            componentExports.push(decl.name.text);
+          }
+        }
+      }
+    }
+
+    // Find export declarations (e.g., export { Button })
+    if (ts.isExportDeclaration(node) && node.exportClause) {
+      if (ts.isNamedExports(node.exportClause)) {
+        for (const element of node.exportClause.elements) {
+          componentExports.push(element.name.text);
+        }
+      }
+    }
+  });
+
+  result.exports = componentExports;
+  result.imports = importedModules;
+
+  // Find the main component (first PascalCase export)
+  const mainComponent = componentExports.find(
+    (name) => /^[A-Z]/.test(name) && !name.endsWith("Props")
+  );
+
+  if (!mainComponent) {
+    return null;
+  }
+
+  result.componentName = mainComponent;
+
+  // Find matching props interface
+  const propsInterfaceName = `${mainComponent}Props`;
+  const propsInterface = propsInterfaces.get(propsInterfaceName);
+
+  if (propsInterface) {
+    result.propsInterfaceName = propsInterfaceName;
+    result.props = extractPropsFromInterface(propsInterface, sourceFile);
+  }
+
+  return result;
+}
+
+/**
+ * Extract props from an interface or type alias declaration
+ */
+function extractPropsFromInterface(
+  node: ts.InterfaceDeclaration | ts.TypeAliasDeclaration,
+  sourceFile: ts.SourceFile
+): Record<string, RegistryPropEntry> {
+  const props: Record<string, RegistryPropEntry> = {};
+
+  // Handle interface declaration
+  if (ts.isInterfaceDeclaration(node)) {
+    for (const member of node.members) {
+      if (ts.isPropertySignature(member) && member.name) {
+        const propName = member.name.getText(sourceFile);
+        const prop = extractPropFromMember(member, sourceFile);
+        if (prop) {
+          props[propName] = prop;
+        }
+      }
+    }
+  }
+
+  // Handle type alias declaration
+  if (ts.isTypeAliasDeclaration(node)) {
+    const typeNode = node.type;
+    if (ts.isTypeLiteralNode(typeNode)) {
+      for (const member of typeNode.members) {
+        if (ts.isPropertySignature(member) && member.name) {
+          const propName = member.name.getText(sourceFile);
+          const prop = extractPropFromMember(member, sourceFile);
+          if (prop) {
+            props[propName] = prop;
+          }
+        }
+      }
+    }
+  }
+
+  return props;
+}
+
+/**
+ * Extract prop info from a property signature
+ */
+function extractPropFromMember(
+  member: ts.PropertySignature,
+  sourceFile: ts.SourceFile
+): RegistryPropEntry | null {
+  const entry: RegistryPropEntry = {};
+
+  // Check if required
+  entry.required = !member.questionToken;
+
+  // Get type
+  if (member.type) {
+    const typeInfo = parseTypeNode(member.type, sourceFile);
+    entry.type = typeInfo.type;
+    entry.typeKind = typeInfo.typeKind;
+    if (typeInfo.options) {
+      entry.options = typeInfo.options;
+    }
+  }
+
+  // Get JSDoc comment
+  const jsDocComment = getJSDocComment(member);
+  if (jsDocComment) {
+    entry.description = jsDocComment;
+  }
+
+  // Get default value from JSDoc @default tag
+  const defaultValue = getJSDocDefault(member);
+  if (defaultValue !== undefined) {
+    entry.default = defaultValue;
+  }
+
+  return entry;
+}
+
+/**
+ * Parse a TypeScript type node into a simplified representation
+ */
+function parseTypeNode(
+  typeNode: ts.TypeNode,
+  sourceFile: ts.SourceFile
+): { type: string; typeKind: RegistryPropEntry["typeKind"]; options?: string[] } {
+  // String
+  if (typeNode.kind === ts.SyntaxKind.StringKeyword) {
+    return { type: "string", typeKind: "string" };
+  }
+
+  // Number
+  if (typeNode.kind === ts.SyntaxKind.NumberKeyword) {
+    return { type: "number", typeKind: "number" };
+  }
+
+  // Boolean
+  if (typeNode.kind === ts.SyntaxKind.BooleanKeyword) {
+    return { type: "boolean", typeKind: "boolean" };
+  }
+
+  // Union type (string literal union for enums)
+  if (ts.isUnionTypeNode(typeNode)) {
+    const options: string[] = [];
+    let allLiterals = true;
+
+    for (const subType of typeNode.types) {
+      if (ts.isLiteralTypeNode(subType)) {
+        if (ts.isStringLiteral(subType.literal)) {
+          options.push(subType.literal.text);
+        } else if (subType.literal.kind === ts.SyntaxKind.TrueKeyword) {
+          options.push("true");
+        } else if (subType.literal.kind === ts.SyntaxKind.FalseKeyword) {
+          options.push("false");
+        } else {
+          allLiterals = false;
+        }
+      } else {
+        allLiterals = false;
+      }
+    }
+
+    if (allLiterals && options.length > 0) {
+      return {
+        type: options.map((o) => `"${o}"`).join(" | "),
+        typeKind: "enum",
+        options,
+      };
+    }
+
+    return {
+      type: typeNode.getText(sourceFile),
+      typeKind: "union",
+    };
+  }
+
+  // Function type
+  if (ts.isFunctionTypeNode(typeNode)) {
+    return {
+      type: typeNode.getText(sourceFile),
+      typeKind: "function",
+    };
+  }
+
+  // Array type
+  if (ts.isArrayTypeNode(typeNode)) {
+    return {
+      type: typeNode.getText(sourceFile),
+      typeKind: "array",
+    };
+  }
+
+  // Type reference (e.g., ReactNode, React.ReactElement)
+  if (ts.isTypeReferenceNode(typeNode)) {
+    const typeName = typeNode.typeName.getText(sourceFile);
+
+    // React types
+    if (typeName === "ReactNode" || typeName === "React.ReactNode") {
+      return { type: "ReactNode", typeKind: "node" };
+    }
+    if (typeName === "ReactElement" || typeName === "React.ReactElement") {
+      return { type: "ReactElement", typeKind: "element" };
+    }
+    if (typeName === "JSX.Element") {
+      return { type: "JSX.Element", typeKind: "element" };
+    }
+
+    return {
+      type: typeNode.getText(sourceFile),
+      typeKind: "object",
+    };
+  }
+
+  // Object type literal
+  if (ts.isTypeLiteralNode(typeNode)) {
+    return {
+      type: typeNode.getText(sourceFile),
+      typeKind: "object",
+    };
+  }
+
+  // Default: unknown
+  return {
+    type: typeNode.getText(sourceFile),
+    typeKind: "unknown",
+  };
+}
+
+/**
+ * Get JSDoc comment from a node
+ */
+function getJSDocComment(node: ts.Node): string | undefined {
+  const jsDocTags = ts.getJSDocTags(node);
+  const jsDoc = (node as unknown as { jsDoc?: ts.JSDoc[] }).jsDoc;
+
+  if (jsDoc && jsDoc.length > 0) {
+    const comment = jsDoc[0].comment;
+    if (typeof comment === "string") {
+      return comment;
+    }
+    if (Array.isArray(comment)) {
+      return comment.map((c) => (typeof c === "string" ? c : c.text)).join("");
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Get @default value from JSDoc
+ */
+function getJSDocDefault(node: ts.Node): unknown | undefined {
+  const jsDocTags = ts.getJSDocTags(node);
+
+  for (const tag of jsDocTags) {
+    if (tag.tagName.text === "default") {
+      const comment = tag.comment;
+      if (typeof comment === "string") {
+        // Try to parse as JSON
+        try {
+          return JSON.parse(comment);
+        } catch {
+          return comment;
+        }
+      }
+    }
+  }
+
+  return undefined;
+}

package/src/core/importAnalyzer.ts

@@ -0,0 +1,217 @@
+/**
+ * AST-based import analysis for detecting component relationships
+ *
+ * Analyzes TypeScript/JavaScript files to find which components import others,
+ * providing accurate "used by" relationships for the component graph.
+ */
+
+import ts from 'typescript';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname, basename } from 'node:path';
+
+export interface ComponentImport {
+  /** Name of the imported component */
+  name: string;
+  /** Import path (relative or package) */
+  path: string;
+  /** Whether this is a default import */
+  isDefault: boolean;
+  /** Whether this is a namespace import */
+  isNamespace: boolean;
+}
+
+export interface ImportAnalysisResult {
+  /** Source file path */
+  filePath: string;
+  /** Component name extracted from file */
+  componentName: string;
+  /** List of component imports found */
+  imports: ComponentImport[];
+}
+
+/**
+ * Extract component name from a file path
+ */
+function extractComponentNameFromPath(filePath: string): string {
+  const fileName = basename(filePath);
+
+  // Handle index.tsx files - use parent directory name
+  if (fileName === 'index.tsx' || fileName === 'index.ts' || fileName === 'index.jsx' || fileName === 'index.js') {
+    const parentDir = basename(dirname(filePath));
+    return parentDir;
+  }
+
+  // Remove extension and common suffixes
+  return fileName
+    .replace(/\.(tsx?|jsx?)$/, '')
+    .replace(/\.stories$/, '')
+    .replace(/\.segment$/, '')
+    .replace(/\.fragment$/, '');
+}
+
+/**
+ * Check if an import path looks like a component import (not a utility/library)
+ */
+function isComponentImportPath(importPath: string): boolean {
+  // Skip node_modules packages
+  if (!importPath.startsWith('.') && !importPath.startsWith('/')) {
+    return false;
+  }
+
+  // Skip common utility/hook patterns
+  const skipPatterns = [
+    /\/hooks\//,
+    /\/utils\//,
+    /\/helpers\//,
+    /\/lib\//,
+    /\/types\//,
+    /\/constants\//,
+    /\/styles\//,
+    /\/context\//,
+    /\.css$/,
+    /\.scss$/,
+    /\.less$/,
+    /\.json$/,
+  ];
+
+  for (const pattern of skipPatterns) {
+    if (pattern.test(importPath)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Check if an imported name looks like a React component (PascalCase)
+ */
+function isPascalCase(name: string): boolean {
+  return /^[A-Z][a-zA-Z0-9]*$/.test(name);
+}
+
+/**
+ * Analyze a single file for component imports
+ */
+export function analyzeFileImports(filePath: string): ImportAnalysisResult {
+  const componentName = extractComponentNameFromPath(filePath);
+  const imports: ComponentImport[] = [];
+
+  let sourceText: string;
+  try {
+    sourceText = readFileSync(filePath, 'utf-8');
+  } catch {
+    return { filePath, componentName, imports };
+  }
+
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    sourceText,
+    ts.ScriptTarget.Latest,
+    true,
+    filePath.endsWith('.tsx') || filePath.endsWith('.jsx')
+      ? ts.ScriptKind.TSX
+      : ts.ScriptKind.TS
+  );
+
+  ts.forEachChild(sourceFile, (node) => {
+    if (ts.isImportDeclaration(node)) {
+      const moduleSpecifier = node.moduleSpecifier;
+      if (!ts.isStringLiteral(moduleSpecifier)) return;
+
+      const importPath = moduleSpecifier.text;
+
+      // Skip non-component imports
+      if (!isComponentImportPath(importPath)) return;
+
+      const importClause = node.importClause;
+      if (!importClause) return;
+
+      // Default import: import Button from './Button'
+      if (importClause.name) {
+        const name = importClause.name.text;
+        if (isPascalCase(name)) {
+          imports.push({
+            name,
+            path: importPath,
+            isDefault: true,
+            isNamespace: false,
+          });
+        }
+      }
+
+      // Named imports: import { Button, Icon } from './components'
+      const namedBindings = importClause.namedBindings;
+      if (namedBindings) {
+        if (ts.isNamedImports(namedBindings)) {
+          for (const element of namedBindings.elements) {
+            const name = element.name.text;
+            if (isPascalCase(name)) {
+              imports.push({
+                name,
+                path: importPath,
+                isDefault: false,
+                isNamespace: false,
+              });
+            }
+          }
+        } else if (ts.isNamespaceImport(namedBindings)) {
+          // Namespace import: import * as Components from './components'
+          // We can't reliably know what components are used without more analysis
+          const name = namedBindings.name.text;
+          imports.push({
+            name,
+            path: importPath,
+            isDefault: false,
+            isNamespace: true,
+          });
+        }
+      }
+    }
+  });
+
+  return { filePath, componentName, imports };
+}
+
+/**
+ * Build a map of which components are imported by which files
+ */
+export function buildImportGraph(
+  filePaths: string[]
+): Map<string, string[]> {
+  // Map from component name -> list of component names that import it
+  const importedBy = new Map<string, string[]>();
+
+  for (const filePath of filePaths) {
+    const result = analyzeFileImports(filePath);
+
+    for (const imp of result.imports) {
+      // Skip namespace imports for now
+      if (imp.isNamespace) continue;
+
+      const importedComponent = imp.name;
+      const importingComponent = result.componentName;
+
+      // Don't add self-references
+      if (importedComponent === importingComponent) continue;
+
+      const existing = importedBy.get(importedComponent) || [];
+      if (!existing.includes(importingComponent)) {
+        existing.push(importingComponent);
+        importedBy.set(importedComponent, existing);
+      }
+    }
+  }
+
+  return importedBy;
+}
+
+/**
+ * Get components that import a specific component
+ */
+export function getImportedBy(
+  componentName: string,
+  importGraph: Map<string, string[]>
+): string[] {
+  return importGraph.get(componentName) || [];
+}