@fragments-sdk/cli 0.2.2

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

@@ -0,0 +1,523 @@
+/**
+ * Documentation Extractor
+ *
+ * Extracts JSDoc, TSDoc, and TypeScript interface information from component 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 { existsSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import type { ExtractedDocs } from "./types.js";
+
+/**
+ * Extract documentation from a component source file
+ */
+export async function extractComponentDocs(
+  filePath: string
+): Promise<ExtractedDocs> {
+  const content = await readFile(filePath, "utf-8");
+  return extractDocsFromSource(content, filePath);
+}
+
+/**
+ * Extract documentation from source code
+ */
+export function extractDocsFromSource(
+  source: string,
+  filePath: string
+): ExtractedDocs {
+  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 docs: ExtractedDocs = {
+    filePath,
+    componentName: inferComponentName(filePath),
+    description: "",
+    props: [],
+    examples: [],
+    tags: {},
+  };
+
+  // Track leading comments for the main export
+  let mainExportComment: string | undefined;
+
+  traverse(ast, {
+    // Extract JSDoc from function declarations
+    FunctionDeclaration(path) {
+      const leadingComments = path.node.leadingComments;
+      if (leadingComments) {
+        const jsdoc = extractJSDoc(leadingComments);
+        if (jsdoc && isExportedComponent(path)) {
+          mergeJSDoc(docs, jsdoc);
+        }
+      }
+    },
+
+    // Extract JSDoc from arrow function variable declarations
+    VariableDeclaration(path) {
+      const leadingComments = path.node.leadingComments;
+      if (leadingComments && hasExportedArrowFunction(path)) {
+        const jsdoc = extractJSDoc(leadingComments);
+        if (jsdoc) {
+          mergeJSDoc(docs, jsdoc);
+        }
+      }
+    },
+
+    // Extract JSDoc from export default
+    ExportDefaultDeclaration(path) {
+      const leadingComments = path.node.leadingComments;
+      if (leadingComments) {
+        const jsdoc = extractJSDoc(leadingComments);
+        if (jsdoc) {
+          mergeJSDoc(docs, jsdoc);
+        }
+      }
+    },
+
+    // Extract props from TypeScript interface
+    TSInterfaceDeclaration(path) {
+      const name = path.node.id.name;
+      if (isPropsInterface(name)) {
+        const props = extractPropsFromInterface(path.node);
+        docs.props.push(...props);
+      }
+    },
+
+    // Extract props from TypeScript type alias
+    TSTypeAliasDeclaration(path) {
+      const name = path.node.id.name;
+      if (isPropsInterface(name)) {
+        const props = extractPropsFromTypeAlias(path.node);
+        docs.props.push(...props);
+      }
+    },
+  });
+
+  // Clean up duplicates
+  docs.props = deduplicateProps(docs.props);
+
+  return docs;
+}
+
+/**
+ * Extract JSDoc information from comments
+ */
+function extractJSDoc(
+  comments: readonly t.Comment[]
+): Partial<ExtractedDocs> | null {
+  const blockComments = comments.filter(
+    (c) => c.type === "CommentBlock" && c.value.startsWith("*")
+  );
+
+  if (blockComments.length === 0) return null;
+
+  const comment = blockComments[blockComments.length - 1];
+  const content = comment.value;
+
+  const result: Partial<ExtractedDocs> = {
+    description: "",
+    props: [],
+    examples: [],
+    tags: {},
+  };
+
+  // Parse JSDoc content
+  const lines = content.split("\n");
+  let currentDescription: string[] = [];
+  let currentTag: string | null = null;
+  let currentTagContent: string[] = [];
+
+  for (const line of lines) {
+    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) {
+        processTag(result, currentTag, currentTagContent.join("\n").trim());
+      } else if (currentDescription.length > 0) {
+        result.description = currentDescription.join("\n").trim();
+      }
+
+      currentTag = tagMatch[1];
+      currentTagContent = tagMatch[2] ? [tagMatch[2]] : [];
+    } else if (currentTag) {
+      currentTagContent.push(trimmed);
+    } else if (trimmed) {
+      currentDescription.push(trimmed);
+    }
+  }
+
+  // Process final tag
+  if (currentTag) {
+    processTag(result, currentTag, currentTagContent.join("\n").trim());
+  } else if (currentDescription.length > 0) {
+    result.description = currentDescription.join("\n").trim();
+  }
+
+  return result;
+}
+
+/**
+ * Process a JSDoc tag
+ */
+function processTag(
+  docs: Partial<ExtractedDocs>,
+  tag: string,
+  content: string
+): void {
+  switch (tag) {
+    case "description":
+      docs.description = content;
+      break;
+
+    case "param":
+    case "prop": {
+      const propMatch = content.match(
+        /^\{([^}]+)\}\s+(\[?\w+\]?)\s*-?\s*(.*)/
+      );
+      if (propMatch) {
+        const [, type, nameRaw, description] = propMatch;
+        const isOptional = nameRaw.startsWith("[");
+        const name = nameRaw.replace(/[\[\]]/g, "");
+        docs.props?.push({
+          name,
+          type,
+          description,
+          required: !isOptional,
+        });
+      }
+      break;
+    }
+
+    case "example": {
+      docs.examples?.push(content);
+      break;
+    }
+
+    case "deprecated":
+    case "since":
+    case "version":
+    case "see":
+    case "link":
+    case "category":
+      docs.tags = docs.tags ?? {};
+      docs.tags[tag] = content;
+      break;
+
+    default:
+      // Store other tags generically
+      docs.tags = docs.tags ?? {};
+      docs.tags[tag] = content;
+  }
+}
+
+/**
+ * Extract props from TypeScript interface
+ */
+function extractPropsFromInterface(
+  node: t.TSInterfaceDeclaration
+): ExtractedDocs["props"] {
+  const props: ExtractedDocs["props"] = [];
+
+  for (const member of node.body.body) {
+    if (t.isTSPropertySignature(member) && t.isIdentifier(member.key)) {
+      const name = member.key.name;
+      const type = member.typeAnnotation
+        ? typeAnnotationToString(member.typeAnnotation.typeAnnotation)
+        : "unknown";
+      const required = !member.optional;
+
+      // Extract description from leading comments
+      let description = "";
+      if (member.leadingComments) {
+        const comment = member.leadingComments[member.leadingComments.length - 1];
+        if (comment.type === "CommentBlock") {
+          description = comment.value
+            .replace(/^\s*\*\s?/gm, "")
+            .trim();
+        } else if (comment.type === "CommentLine") {
+          description = comment.value.trim();
+        }
+      }
+
+      props.push({ name, type, description, required });
+    }
+  }
+
+  return props;
+}
+
+/**
+ * Extract props from TypeScript type alias
+ */
+function extractPropsFromTypeAlias(
+  node: t.TSTypeAliasDeclaration
+): ExtractedDocs["props"] {
+  const props: ExtractedDocs["props"] = [];
+
+  if (t.isTSTypeLiteral(node.typeAnnotation)) {
+    for (const member of node.typeAnnotation.members) {
+      if (t.isTSPropertySignature(member) && t.isIdentifier(member.key)) {
+        const name = member.key.name;
+        const type = member.typeAnnotation
+          ? typeAnnotationToString(member.typeAnnotation.typeAnnotation)
+          : "unknown";
+        const required = !member.optional;
+
+        // Extract description from leading comments
+        let description = "";
+        if (member.leadingComments) {
+          const comment = member.leadingComments[member.leadingComments.length - 1];
+          description = comment.value.replace(/^\s*\*\s?/gm, "").trim();
+        }
+
+        props.push({ name, type, description, required });
+      }
+    }
+  }
+
+  return props;
+}
+
+/**
+ * Convert TypeScript type annotation to string representation
+ */
+function typeAnnotationToString(node: t.TSType): string {
+  if (t.isTSStringKeyword(node)) return "string";
+  if (t.isTSNumberKeyword(node)) return "number";
+  if (t.isTSBooleanKeyword(node)) return "boolean";
+  if (t.isTSNullKeyword(node)) return "null";
+  if (t.isTSUndefinedKeyword(node)) return "undefined";
+  if (t.isTSVoidKeyword(node)) return "void";
+  if (t.isTSAnyKeyword(node)) return "any";
+  if (t.isTSNeverKeyword(node)) return "never";
+  if (t.isTSUnknownKeyword(node)) return "unknown";
+
+  if (t.isTSLiteralType(node)) {
+    if (t.isStringLiteral(node.literal)) return `"${node.literal.value}"`;
+    if (t.isNumericLiteral(node.literal)) return String(node.literal.value);
+    if (t.isBooleanLiteral(node.literal)) return String(node.literal.value);
+    return "literal";
+  }
+
+  if (t.isTSTypeReference(node)) {
+    if (t.isIdentifier(node.typeName)) {
+      const name = node.typeName.name;
+      if (node.typeParameters) {
+        const params = node.typeParameters.params
+          .map(typeAnnotationToString)
+          .join(", ");
+        return `${name}<${params}>`;
+      }
+      return name;
+    }
+  }
+
+  if (t.isTSUnionType(node)) {
+    return node.types.map(typeAnnotationToString).join(" | ");
+  }
+
+  if (t.isTSIntersectionType(node)) {
+    return node.types.map(typeAnnotationToString).join(" & ");
+  }
+
+  if (t.isTSArrayType(node)) {
+    return `${typeAnnotationToString(node.elementType)}[]`;
+  }
+
+  if (t.isTSFunctionType(node)) {
+    return "(...args: any[]) => any";
+  }
+
+  if (t.isTSTupleType(node)) {
+    const elements = node.elementTypes
+      .map((el) => {
+        // Handle named tuple members: [name: string]
+        if (t.isTSNamedTupleMember(el)) {
+          return typeAnnotationToString(el.elementType);
+        }
+        return typeAnnotationToString(el);
+      })
+      .join(", ");
+    return `[${elements}]`;
+  }
+
+  if (t.isTSTypeLiteral(node)) {
+    return "object";
+  }
+
+  return "unknown";
+}
+
+/**
+ * Check if interface name looks like props
+ */
+function isPropsInterface(name: string): boolean {
+  return (
+    name.endsWith("Props") ||
+    name.endsWith("Properties") ||
+    name === "Props"
+  );
+}
+
+/**
+ * Check if a function declaration is exported
+ */
+function isExportedComponent(
+  path: babel.NodePath<t.FunctionDeclaration>
+): boolean {
+  const parent = path.parent;
+  if (t.isExportDefaultDeclaration(parent)) return true;
+  if (t.isExportNamedDeclaration(parent)) return true;
+  if (t.isProgram(parent) && path.node.id && /^[A-Z]/.test(path.node.id.name)) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Check if variable declaration has an exported arrow function component
+ */
+function hasExportedArrowFunction(
+  path: babel.NodePath<t.VariableDeclaration>
+): boolean {
+  const parent = path.parent;
+  if (!t.isExportNamedDeclaration(parent)) return false;
+
+  for (const declarator of path.node.declarations) {
+    if (
+      t.isIdentifier(declarator.id) &&
+      /^[A-Z]/.test(declarator.id.name) &&
+      (t.isArrowFunctionExpression(declarator.init) ||
+        t.isFunctionExpression(declarator.init))
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Merge JSDoc results into docs
+ */
+function mergeJSDoc(docs: ExtractedDocs, jsdoc: Partial<ExtractedDocs>): void {
+  if (jsdoc.description && !docs.description) {
+    docs.description = jsdoc.description;
+  }
+  if (jsdoc.props) {
+    docs.props.push(...jsdoc.props);
+  }
+  if (jsdoc.examples) {
+    docs.examples.push(...jsdoc.examples);
+  }
+  if (jsdoc.tags) {
+    docs.tags = { ...docs.tags, ...jsdoc.tags };
+  }
+}
+
+/**
+ * Remove duplicate props
+ */
+function deduplicateProps(
+  props: ExtractedDocs["props"]
+): ExtractedDocs["props"] {
+  const seen = new Map<string, ExtractedDocs["props"][0]>();
+
+  for (const prop of props) {
+    const existing = seen.get(prop.name);
+    if (!existing || (prop.description && !existing.description)) {
+      seen.set(prop.name, prop);
+    }
+  }
+
+  return Array.from(seen.values());
+}
+
+/**
+ * Find component source file from various patterns
+ */
+export async function findComponentSource(
+  componentName: string,
+  searchDirs: string[]
+): Promise<string | 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 fullPath;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extract documentation from multiple component files
+ */
+export async function extractAllComponentDocs(
+  componentFiles: Map<string, string>
+): Promise<Map<string, ExtractedDocs>> {
+  const results = new Map<string, ExtractedDocs>();
+
+  for (const [componentName, filePath] of componentFiles) {
+    try {
+      const docs = await extractComponentDocs(filePath);
+      docs.componentName = componentName;
+      results.set(componentName, docs);
+    } catch (error) {
+      console.warn(
+        `Failed to extract docs for ${componentName}:`,
+        (error as Error).message
+      );
+    }
+  }
+
+  return results;
+}
+
+// Type import for babel NodePath
+import type * as babel from "@babel/traverse";

package/src/service/enhance/index.ts

@@ -0,0 +1,131 @@
+/**
+ * Enhancement Module
+ *
+ * AI-powered documentation generation through codebase analysis.
+ */
+
+// Types
+export type {
+  ComponentUsage,
+  UsageProps,
+  ComponentImport,
+  UsagePattern,
+  FileContext,
+  ComponentAnalysis,
+  UsageAnalysis,
+  FileCacheEntry,
+  AnalysisCache,
+  ScanProgress,
+  ScanOptions,
+  FileChanges,
+  ExtractedDocs,
+  ComponentEnhancement,
+  EnhancementResult,
+} from "./types.js";
+
+export { CACHE_VERSION } from "./types.js";
+
+// Scanner
+export {
+  scanFileForImports,
+  scanFileForUsages,
+  scanFile,
+} from "./scanner.js";
+
+// Aggregator
+export {
+  aggregateComponentUsages,
+  aggregateAllUsages,
+  findCommonPropCombinations,
+  summarizePatternsForPrompt,
+  inferRelations,
+  inferAllRelations,
+  type ComponentRelation,
+} from "./aggregator.js";
+
+// Cache
+export {
+  getCachePath,
+  loadCache,
+  saveCache,
+  createEmptyCache,
+  computeFileHash,
+  computeFileHashFromDisk,
+  isFileCached,
+  getCachedFile,
+  updateCacheFile,
+  removeCacheFile,
+  invalidateCache,
+  detectFileChanges,
+  getAllCachedImports,
+  getAllCachedUsages,
+  getCacheStats,
+} from "./cache.js";
+
+// Codebase Scanner
+export {
+  scanCodebase,
+  incrementalScan,
+  getScanStats,
+  hasCachedAnalysis,
+} from "./codebase-scanner.js";
+
+// Documentation Extractor
+export {
+  extractComponentDocs,
+  extractDocsFromSource,
+  findComponentSource,
+  extractAllComponentDocs,
+} from "./doc-extractor.js";
+
+// Storybook Parser
+export {
+  parseStoryFile,
+  parseStorySource,
+  findStoryFiles,
+  parseAllStories,
+  mergeStorybookIntoDoc,
+  type StoryExample,
+  type StorybookMeta,
+  type ArgType,
+  type ParsedStoryFile,
+} from "./storybook-parser.js";
+
+// AI Context Generator
+export {
+  generateComponentContext,
+  generateAIContextPackage,
+  generatePromptContext,
+  generateEnhancementSuggestions,
+  generateSystemPrompt,
+  generateUserPrompt,
+  isBoilerplate,
+  filterBoilerplate,
+  type ComponentContext,
+  type AIContextPackage,
+  type EnhancedProp,
+} from "./context-generator.js";
+
+// TypeScript Props Extractor
+export {
+  extractPropsFromFile,
+  extractPropsFromSource,
+  extractPropsForComponent,
+  extractAllComponentProps,
+  convertToSegmentProps,
+  type ExtractedProp,
+  type PropsExtractionResult,
+  type PropsExtractionOptions,
+} from "./props-extractor.js";
+
+// Variant Renderer (Playwright-based)
+export {
+  renderVariants,
+  renderAllComponentVariants,
+  checkStorybookRunning,
+  getStorybookStoryIds,
+  shutdownSharedPool,
+  type RenderedVariant,
+  type VariantRenderResult,
+  type VariantRenderOptions,
+} from "./variant-renderer.js";