@fragments-sdk/cli 0.2.2

package/src/service/enhance/context-generator.ts

@@ -0,0 +1,529 @@
+/**
+ * AI Context Generator
+ *
+ * Packages codebase analysis, documentation, and Storybook examples
+ * into structured context for AI-powered documentation generation.
+ */
+
+import type {
+  ComponentAnalysis,
+  UsageAnalysis,
+  ExtractedDocs,
+  ComponentEnhancement,
+} from "./types.js";
+import type { ParsedStoryFile, StoryExample } from "./storybook-parser.js";
+import type { PropsExtractionResult, ExtractedProp } from "./props-extractor.js";
+import { summarizePatternsForPrompt, type ComponentRelation } from "./aggregator.js";
+
+/**
+ * Boilerplate patterns that should be filtered from AI suggestions
+ */
+const BOILERPLATE_PATTERNS = [
+  /component is needed/i,
+  /alternative.*appropriate/i,
+  /use (?:this|the) component when/i,
+  /don'?t use (?:this|the) component/i,
+  /when you need (?:this|a|the) component/i,
+  /TODO:/i,
+  /FIXME:/i,
+  /TBD/i,
+  /placeholder/i,
+  /\[.*\]/,  // Placeholder brackets like [describe when]
+];
+
+/**
+ * Check if text matches any boilerplate pattern
+ */
+export function isBoilerplate(text: string): boolean {
+  return BOILERPLATE_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+/**
+ * Filter out boilerplate suggestions
+ */
+export function filterBoilerplate(suggestions: string[]): string[] {
+  return suggestions.filter((s) => !isBoilerplate(s));
+}
+
+/**
+ * Enhanced prop data from TypeScript extraction
+ */
+export interface EnhancedProp {
+  name: string;
+  type: string;
+  description: string;
+  required: boolean;
+  defaultValue?: unknown;
+  enumValues?: string[];
+  deprecated?: string;
+}
+
+/**
+ * Full context for AI enhancement of a single component
+ */
+export interface ComponentContext {
+  componentName: string;
+  sourceFile: string;
+
+  // Existing documentation
+  existingDocs: {
+    description?: string;
+    props: Array<{
+      name: string;
+      type: string;
+      description?: string;
+      required: boolean;
+    }>;
+    examples: string[];
+    tags: Record<string, string>;
+  };
+
+  // Enhanced props from TypeScript extraction
+  extractedProps?: EnhancedProp[];
+
+  // Component relationships inferred from usage patterns
+  relations?: Array<{
+    component: string;
+    relationship: "parent" | "sibling" | "child";
+    frequency: number;
+  }>;
+
+  // Usage analysis
+  usageAnalysis: {
+    totalUsages: number;
+    uniqueFiles: number;
+    topPatterns: Array<{
+      props: Record<string, unknown>;
+      count: number;
+      sampleContext?: string;
+    }>;
+    contexts: Array<{
+      type: string;
+      count: number;
+    }>;
+  };
+
+  // Storybook examples
+  storybook?: {
+    title?: string;
+    description?: string;
+    stories: Array<{
+      name: string;
+      displayName: string;
+      description?: string;
+      args: Record<string, unknown>;
+      code: string;
+    }>;
+  };
+}
+
+/**
+ * Full context package for AI enhancement session
+ */
+export interface AIContextPackage {
+  projectName: string;
+  totalComponents: number;
+  components: ComponentContext[];
+  globalPatterns: {
+    mostUsedComponents: Array<{ name: string; usages: number }>;
+    commonPropCombinations: Array<{ props: string[]; count: number }>;
+  };
+}
+
+/**
+ * Generate full context for a single component
+ */
+export function generateComponentContext(
+  componentName: string,
+  analysis: ComponentAnalysis | undefined,
+  docs: ExtractedDocs | undefined,
+  storyFile: ParsedStoryFile | undefined,
+  propsExtraction?: PropsExtractionResult,
+  relations?: ComponentRelation[]
+): ComponentContext {
+  const context: ComponentContext = {
+    componentName,
+    sourceFile: analysis?.sourceFile || propsExtraction?.filePath || docs?.filePath || "unknown",
+    existingDocs: {
+      description: docs?.description,
+      props: docs?.props || [],
+      examples: docs?.examples || [],
+      tags: docs?.tags || {},
+    },
+    usageAnalysis: {
+      totalUsages: analysis?.totalUsages || 0,
+      uniqueFiles: analysis?.uniqueFiles || 0,
+      topPatterns: [],
+      contexts: [],
+    },
+  };
+
+  // Add enhanced props from TypeScript extraction (preferred source)
+  if (propsExtraction?.success && propsExtraction.props.length > 0) {
+    context.extractedProps = propsExtraction.props.map((p) => ({
+      name: p.name,
+      type: p.type,
+      description: p.description,
+      required: p.required,
+      defaultValue: p.defaultValue,
+      enumValues: p.enumValues,
+      deprecated: p.deprecated,
+    }));
+  }
+
+  // Add inferred relations
+  if (relations && relations.length > 0) {
+    context.relations = relations.slice(0, 10).map((r) => ({
+      component: r.component,
+      relationship: r.relationship,
+      frequency: r.frequency,
+    }));
+  }
+
+  // Add usage patterns
+  if (analysis?.patterns) {
+    context.usageAnalysis.topPatterns = analysis.patterns.slice(0, 10).map((p) => ({
+      props: p.props,
+      count: p.count,
+      sampleContext: p.sampleContexts[0],
+    }));
+  }
+
+  // Add context types
+  if (analysis?.contexts) {
+    context.usageAnalysis.contexts = analysis.contexts.map((c) => ({
+      type: c.type,
+      count: c.count,
+    }));
+  }
+
+  // Add Storybook data
+  if (storyFile) {
+    context.storybook = {
+      title: storyFile.meta.title,
+      description: storyFile.meta.description,
+      stories: storyFile.stories.map((s) => ({
+        name: s.name,
+        displayName: s.displayName,
+        description: s.description,
+        args: s.args,
+        code: s.code,
+      })),
+    };
+  }
+
+  return context;
+}
+
+/**
+ * Generate full AI context package for all components
+ */
+export function generateAIContextPackage(
+  projectName: string,
+  usageAnalysis: UsageAnalysis,
+  allDocs: Map<string, ExtractedDocs>,
+  allStories: Map<string, ParsedStoryFile>
+): AIContextPackage {
+  const components: ComponentContext[] = [];
+
+  // Get all unique component names
+  const allComponentNames = new Set<string>();
+  for (const name of Object.keys(usageAnalysis.components)) {
+    allComponentNames.add(name);
+  }
+  for (const name of allDocs.keys()) {
+    allComponentNames.add(name);
+  }
+  for (const name of allStories.keys()) {
+    allComponentNames.add(name);
+  }
+
+  // Generate context for each component
+  for (const componentName of allComponentNames) {
+    const analysis = usageAnalysis.components[componentName];
+    const docs = allDocs.get(componentName);
+    const storyFile = allStories.get(componentName);
+
+    const context = generateComponentContext(
+      componentName,
+      analysis,
+      docs,
+      storyFile
+    );
+    components.push(context);
+  }
+
+  // Sort by usage count
+  components.sort(
+    (a, b) => b.usageAnalysis.totalUsages - a.usageAnalysis.totalUsages
+  );
+
+  // Calculate global patterns
+  const mostUsedComponents = Object.values(usageAnalysis.components)
+    .map((c) => ({ name: c.name, usages: c.totalUsages }))
+    .sort((a, b) => b.usages - a.usages)
+    .slice(0, 20);
+
+  return {
+    projectName,
+    totalComponents: components.length,
+    components,
+    globalPatterns: {
+      mostUsedComponents,
+      commonPropCombinations: [], // Would need aggregation across all components
+    },
+  };
+}
+
+/**
+ * Generate a focused prompt context for a single component
+ */
+export function generatePromptContext(context: ComponentContext): string {
+  const lines: string[] = [];
+
+  lines.push(`# Component: ${context.componentName}`);
+  lines.push(`Source: ${context.sourceFile}`);
+  lines.push("");
+
+  // Existing documentation
+  if (context.existingDocs.description) {
+    lines.push("## Current Description");
+    lines.push(context.existingDocs.description);
+    lines.push("");
+  }
+
+  // Enhanced props from TypeScript extraction (preferred)
+  if (context.extractedProps && context.extractedProps.length > 0) {
+    lines.push("## Props (from TypeScript)");
+    for (const prop of context.extractedProps) {
+      const required = prop.required ? "(required)" : "(optional)";
+      const deprecated = prop.deprecated ? " [DEPRECATED]" : "";
+      const defaultVal = prop.defaultValue !== undefined
+        ? ` (default: ${JSON.stringify(prop.defaultValue)})`
+        : "";
+      const desc = prop.description || "";
+
+      lines.push(`- **${prop.name}**: \`${prop.type}\` ${required}${deprecated}${defaultVal}`);
+      if (desc) {
+        lines.push(`  ${desc}`);
+      }
+      if (prop.enumValues && prop.enumValues.length > 0) {
+        lines.push(`  Values: ${prop.enumValues.map(v => `"${v}"`).join(" | ")}`);
+      }
+    }
+    lines.push("");
+  } else if (context.existingDocs.props.length > 0) {
+    // Fallback to existing docs props
+    lines.push("## Props");
+    for (const prop of context.existingDocs.props) {
+      const required = prop.required ? "(required)" : "(optional)";
+      const desc = prop.description || "No description";
+      lines.push(`- **${prop.name}**: \`${prop.type}\` ${required} - ${desc}`);
+    }
+    lines.push("");
+  }
+
+  // Component relationships
+  if (context.relations && context.relations.length > 0) {
+    lines.push("## Related Components");
+    const parents = context.relations.filter((r) => r.relationship === "parent");
+    const siblings = context.relations.filter((r) => r.relationship === "sibling");
+
+    if (parents.length > 0) {
+      lines.push("### Commonly Used Inside");
+      for (const rel of parents.slice(0, 5)) {
+        lines.push(`- **${rel.component}**: ${rel.frequency} times`);
+      }
+    }
+
+    if (siblings.length > 0) {
+      lines.push("### Often Used With");
+      for (const rel of siblings.slice(0, 5)) {
+        lines.push(`- **${rel.component}**: appears together in ${rel.frequency} files`);
+      }
+    }
+    lines.push("");
+  }
+
+  // Usage patterns
+  if (context.usageAnalysis.totalUsages > 0) {
+    lines.push("## Usage Analysis");
+    lines.push(
+      `Found ${context.usageAnalysis.totalUsages} usages across ${context.usageAnalysis.uniqueFiles} files.`
+    );
+    lines.push("");
+
+    if (context.usageAnalysis.topPatterns.length > 0) {
+      lines.push("### Most Common Patterns");
+      for (const pattern of context.usageAnalysis.topPatterns.slice(0, 5)) {
+        const propsStr =
+          Object.keys(pattern.props).length > 0
+            ? Object.entries(pattern.props)
+                .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+                .join(", ")
+            : "(no props)";
+        lines.push(`- ${propsStr}: ${pattern.count} times`);
+      }
+      lines.push("");
+    }
+
+    if (context.usageAnalysis.contexts.length > 0) {
+      lines.push("### Where It's Used");
+      for (const ctx of context.usageAnalysis.contexts) {
+        lines.push(`- ${ctx.type}: ${ctx.count} times`);
+      }
+      lines.push("");
+    }
+
+    // Sample code context
+    const samplePattern = context.usageAnalysis.topPatterns.find(
+      (p) => p.sampleContext
+    );
+    if (samplePattern?.sampleContext) {
+      lines.push("### Sample Usage Context");
+      lines.push("```tsx");
+      lines.push(samplePattern.sampleContext.trim());
+      lines.push("```");
+      lines.push("");
+    }
+  }
+
+  // Storybook examples
+  if (context.storybook && context.storybook.stories.length > 0) {
+    lines.push("## Storybook Examples");
+    for (const story of context.storybook.stories.slice(0, 5)) {
+      lines.push(`### ${story.displayName}`);
+      if (story.description) {
+        lines.push(story.description);
+      }
+      lines.push("```tsx");
+      lines.push(story.code);
+      lines.push("```");
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate enhancement suggestions based on context
+ */
+export function generateEnhancementSuggestions(
+  context: ComponentContext
+): ComponentEnhancement {
+  const suggestions: ComponentEnhancement = {
+    componentName: context.componentName,
+    suggestions: {
+      when: [],
+      whenNot: [],
+      examples: [],
+    },
+    confidence: 0,
+    reasoning: [],
+  };
+
+  // Analyze context types to suggest "when" scenarios
+  if (context.usageAnalysis.contexts.length > 0) {
+    for (const ctx of context.usageAnalysis.contexts) {
+      if (ctx.count >= 2) {
+        suggestions.suggestions.when.push(
+          `Use in ${ctx.type} components (found in ${ctx.count} places)`
+        );
+        suggestions.reasoning.push(
+          `Component is commonly used in ${ctx.type} contexts`
+        );
+      }
+    }
+  }
+
+  // Analyze usage patterns
+  const highUsagePatterns = context.usageAnalysis.topPatterns.filter(
+    (p) => p.count >= 3
+  );
+  if (highUsagePatterns.length > 0) {
+    for (const pattern of highUsagePatterns.slice(0, 3)) {
+      const props = Object.entries(pattern.props);
+      if (props.length > 0) {
+        const propDesc = props.map(([k, v]) => `${k}="${v}"`).join(", ");
+        suggestions.suggestions.when.push(
+          `Use with ${propDesc} (common pattern, ${pattern.count} occurrences)`
+        );
+      }
+    }
+  }
+
+  // Generate examples from Storybook
+  if (context.storybook?.stories) {
+    for (const story of context.storybook.stories.slice(0, 3)) {
+      if (story.code) {
+        suggestions.suggestions.examples.push(story.code);
+      }
+    }
+  }
+
+  // Calculate confidence based on available data
+  let confidence = 0;
+  if (context.usageAnalysis.totalUsages > 10) confidence += 30;
+  else if (context.usageAnalysis.totalUsages > 5) confidence += 20;
+  else if (context.usageAnalysis.totalUsages > 0) confidence += 10;
+
+  if (context.storybook?.stories && context.storybook.stories.length > 0) {
+    confidence += 25;
+  }
+
+  // Enhanced props from TypeScript extraction are more valuable
+  if (context.extractedProps && context.extractedProps.length > 0) {
+    confidence += 25;
+  } else if (context.existingDocs.props.length > 0) {
+    confidence += 15;
+  }
+
+  if (context.usageAnalysis.contexts.length > 0) {
+    confidence += 20;
+  }
+
+  suggestions.confidence = Math.min(confidence, 100);
+
+  return suggestions;
+}
+
+/**
+ * Generate the system prompt for AI enhancement
+ */
+export function generateSystemPrompt(): string {
+  return `You are a technical writer specializing in React component documentation. Your task is to generate clear, actionable "when to use" and "when not to use" documentation based on actual usage patterns found in a codebase.
+
+Guidelines:
+1. Be specific and actionable - avoid vague statements
+2. Base recommendations on observed usage patterns
+3. Consider the contexts where components are used (forms, modals, tables, etc.)
+4. Include concrete examples when available
+5. Mention prop combinations that are commonly used together
+6. Note any patterns that suggest best practices or anti-patterns
+
+Format your response as JSON with this structure:
+{
+  "when": ["scenario 1", "scenario 2", ...],
+  "whenNot": ["anti-pattern 1", "anti-pattern 2", ...],
+  "examples": ["<Component prop=\\"value\\" />", ...]
+}`;
+}
+
+/**
+ * Generate the user prompt for a specific component
+ */
+export function generateUserPrompt(context: ComponentContext): string {
+  const promptContext = generatePromptContext(context);
+
+  return `Based on the following usage analysis, generate "when" and "whenNot" documentation for this component.
+
+${promptContext}
+
+Requirements:
+1. Generate 2-4 "when" scenarios based on the actual usage patterns
+2. Generate 1-3 "whenNot" scenarios (anti-patterns or inappropriate use cases)
+3. Include 1-3 example code snippets showing common usage patterns
+
+If there isn't enough usage data to make confident recommendations, indicate that in your response.`;
+}