@fragments-sdk/cli 0.2.2

package/src/service/enhance/aggregator.ts

@@ -0,0 +1,489 @@
+/**
+ * Usage Pattern Aggregator
+ *
+ * Aggregates component usages into patterns for AI analysis.
+ */
+
+import type {
+  ComponentUsage,
+  ComponentImport,
+  ComponentAnalysis,
+  UsagePattern,
+  FileContext,
+  UsageAnalysis,
+} from "./types.js";
+
+/**
+ * Aggregate usages for a single component into patterns
+ */
+export function aggregateComponentUsages(
+  componentName: string,
+  sourceFile: string,
+  usages: ComponentUsage[],
+  imports: ComponentImport[]
+): ComponentAnalysis {
+  // Count unique files
+  const uniqueFiles = new Set(usages.map((u) => u.filePath));
+
+  // Group usages by prop pattern
+  const patternMap = new Map<string, UsagePattern>();
+
+  for (const usage of usages) {
+    // Create a key from static props (sorted for consistency)
+    const propKey = createPropKey(usage.props.static);
+
+    const existing = patternMap.get(propKey);
+    if (existing) {
+      existing.count++;
+      if (!existing.files.includes(usage.filePath)) {
+        existing.files.push(usage.filePath);
+      }
+      if (existing.sampleContexts.length < 3) {
+        existing.sampleContexts.push(usage.context);
+      }
+    } else {
+      patternMap.set(propKey, {
+        props: { ...usage.props.static },
+        count: 1,
+        files: [usage.filePath],
+        sampleContexts: [usage.context],
+      });
+    }
+  }
+
+  // Sort patterns by frequency
+  const patterns = Array.from(patternMap.values()).sort(
+    (a, b) => b.count - a.count
+  );
+
+  // Classify file contexts
+  const contextMap = new Map<FileContext, { count: number; files: string[] }>();
+
+  for (const usage of usages) {
+    const context = classifyFileContext(usage.filePath, usage.context);
+    const existing = contextMap.get(context);
+    if (existing) {
+      existing.count++;
+      if (!existing.files.includes(usage.filePath)) {
+        existing.files.push(usage.filePath);
+      }
+    } else {
+      contextMap.set(context, { count: 1, files: [usage.filePath] });
+    }
+  }
+
+  // Convert to sorted array
+  const contexts = Array.from(contextMap.entries())
+    .map(([type, data]) => ({ type, ...data }))
+    .sort((a, b) => b.count - a.count);
+
+  return {
+    name: componentName,
+    sourceFile,
+    totalUsages: usages.length,
+    uniqueFiles: uniqueFiles.size,
+    patterns,
+    contexts,
+    usages,
+    imports,
+  };
+}
+
+/**
+ * Aggregate all usages across the codebase
+ */
+export function aggregateAllUsages(
+  usages: ComponentUsage[],
+  imports: ComponentImport[],
+  componentSources: Map<string, string>
+): UsageAnalysis {
+  // Group usages by component
+  const usagesByComponent = new Map<string, ComponentUsage[]>();
+  for (const usage of usages) {
+    const existing = usagesByComponent.get(usage.componentName) ?? [];
+    existing.push(usage);
+    usagesByComponent.set(usage.componentName, existing);
+  }
+
+  // Group imports by component
+  const importsByComponent = new Map<string, ComponentImport[]>();
+  for (const imp of imports) {
+    const existing = importsByComponent.get(imp.componentName) ?? [];
+    existing.push(imp);
+    importsByComponent.set(imp.componentName, existing);
+  }
+
+  // Build component analyses
+  const components: Record<string, ComponentAnalysis> = {};
+  const allComponentNames = new Set([
+    ...usagesByComponent.keys(),
+    ...importsByComponent.keys(),
+  ]);
+
+  for (const componentName of allComponentNames) {
+    const componentUsages = usagesByComponent.get(componentName) ?? [];
+    const componentImports = importsByComponent.get(componentName) ?? [];
+    const sourceFile = componentSources.get(componentName) ?? "unknown";
+
+    components[componentName] = aggregateComponentUsages(
+      componentName,
+      sourceFile,
+      componentUsages,
+      componentImports
+    );
+  }
+
+  // Collect unique files
+  const allFiles = new Set<string>();
+  for (const usage of usages) {
+    allFiles.add(usage.filePath);
+  }
+  for (const imp of imports) {
+    allFiles.add(imp.filePath);
+  }
+
+  return {
+    timestamp: new Date().toISOString(),
+    rootDir: "", // Will be set by caller
+    totalFiles: allFiles.size,
+    totalComponents: Object.keys(components).length,
+    components,
+    errorFiles: [], // Will be populated by scanner
+  };
+}
+
+/**
+ * Create a stable key from props for pattern grouping
+ */
+function createPropKey(props: Record<string, string | boolean | number>): string {
+  const entries = Object.entries(props).sort(([a], [b]) => a.localeCompare(b));
+  return entries.map(([k, v]) => `${k}=${JSON.stringify(v)}`).join("|");
+}
+
+/**
+ * Classify file context based on path and content
+ */
+function classifyFileContext(filePath: string, context: string): FileContext {
+  const lowerPath = filePath.toLowerCase();
+  const lowerContext = context.toLowerCase();
+
+  // Check path patterns first
+  if (
+    lowerPath.includes("/modal") ||
+    lowerPath.includes("modal.") ||
+    lowerContext.includes("<modal")
+  ) {
+    return "modal";
+  }
+
+  if (
+    lowerPath.includes("/dialog") ||
+    lowerPath.includes("dialog.") ||
+    lowerContext.includes("<dialog")
+  ) {
+    return "dialog";
+  }
+
+  if (
+    lowerPath.includes("/form") ||
+    lowerPath.includes("form.") ||
+    lowerContext.includes("<form") ||
+    lowerContext.includes("onsubmit")
+  ) {
+    return "form";
+  }
+
+  if (
+    lowerPath.includes("/page") ||
+    lowerPath.includes("pages/") ||
+    lowerPath.includes("/routes/")
+  ) {
+    return "page";
+  }
+
+  if (
+    lowerPath.includes("/layout") ||
+    lowerPath.includes("layout.") ||
+    lowerPath.includes("/layouts/")
+  ) {
+    return "layout";
+  }
+
+  if (
+    lowerPath.includes("/card") ||
+    lowerPath.includes("card.") ||
+    lowerContext.includes("<card")
+  ) {
+    return "card";
+  }
+
+  if (
+    lowerPath.includes("/table") ||
+    lowerPath.includes("table.") ||
+    lowerContext.includes("<table") ||
+    lowerContext.includes("<tr")
+  ) {
+    return "table";
+  }
+
+  if (
+    lowerPath.includes("/list") ||
+    lowerPath.includes("list.") ||
+    lowerContext.includes("<ul") ||
+    lowerContext.includes("<ol") ||
+    lowerContext.includes("<li")
+  ) {
+    return "list";
+  }
+
+  if (
+    lowerPath.includes("/nav") ||
+    lowerPath.includes("navigation") ||
+    lowerContext.includes("<nav")
+  ) {
+    return "navigation";
+  }
+
+  if (
+    lowerPath.includes("/header") ||
+    lowerPath.includes("header.") ||
+    lowerContext.includes("<header")
+  ) {
+    return "header";
+  }
+
+  if (
+    lowerPath.includes("/footer") ||
+    lowerPath.includes("footer.") ||
+    lowerContext.includes("<footer")
+  ) {
+    return "footer";
+  }
+
+  if (
+    lowerPath.includes("/sidebar") ||
+    lowerPath.includes("sidebar.") ||
+    lowerContext.includes("<aside")
+  ) {
+    return "sidebar";
+  }
+
+  return "unknown";
+}
+
+/**
+ * Find common prop combinations across usages
+ */
+export function findCommonPropCombinations(
+  usages: ComponentUsage[],
+  minOccurrences: number = 3
+): { props: string[]; count: number }[] {
+  const combinations = new Map<string, number>();
+
+  for (const usage of usages) {
+    // Get all prop names (static and dynamic)
+    const allProps = [
+      ...Object.keys(usage.props.static),
+      ...usage.props.dynamic,
+    ].sort();
+
+    // Generate all combinations of 2+ props
+    for (let size = 2; size <= Math.min(allProps.length, 4); size++) {
+      for (const combo of combinations_k(allProps, size)) {
+        const key = combo.join(",");
+        combinations.set(key, (combinations.get(key) ?? 0) + 1);
+      }
+    }
+  }
+
+  // Filter and sort by frequency
+  return Array.from(combinations.entries())
+    .filter(([, count]) => count >= minOccurrences)
+    .map(([key, count]) => ({ props: key.split(","), count }))
+    .sort((a, b) => b.count - a.count);
+}
+
+/**
+ * Generate k-combinations of an array
+ */
+function* combinations_k<T>(arr: T[], k: number): Generator<T[]> {
+  if (k === 0) {
+    yield [];
+    return;
+  }
+  if (arr.length < k) return;
+
+  for (let i = 0; i <= arr.length - k; i++) {
+    for (const combo of combinations_k(arr.slice(i + 1), k - 1)) {
+      yield [arr[i], ...combo];
+    }
+  }
+}
+
+/**
+ * Component relationship with frequency data
+ */
+export interface ComponentRelation {
+  /** Related component name */
+  component: string;
+  /** Type of relationship */
+  relationship: "parent" | "sibling" | "child";
+  /** How often this relationship occurs */
+  frequency: number;
+  /** Sample files where this relationship occurs */
+  sampleFiles: string[];
+}
+
+/**
+ * Infer component relationships from usage patterns
+ *
+ * Analyzes parent/sibling relationships from actual usage data:
+ * - parent: Components that contain this component (from parentElement)
+ * - sibling: Components that appear alongside this component in the same parent
+ */
+export function inferRelations(
+  componentName: string,
+  analysis: ComponentAnalysis,
+  allAnalyses: Record<string, ComponentAnalysis>
+): ComponentRelation[] {
+  const relations: ComponentRelation[] = [];
+  const parentCounts = new Map<string, { count: number; files: string[] }>();
+  const siblingCounts = new Map<string, { count: number; files: string[] }>();
+
+  // Count parent relationships
+  for (const usage of analysis.usages) {
+    if (usage.parentElement && usage.parentElement !== "div" && usage.parentElement !== "span") {
+      const parent = usage.parentElement;
+      const existing = parentCounts.get(parent);
+      if (existing) {
+        existing.count++;
+        if (!existing.files.includes(usage.filePath)) {
+          existing.files.push(usage.filePath);
+        }
+      } else {
+        parentCounts.set(parent, { count: 1, files: [usage.filePath] });
+      }
+    }
+  }
+
+  // Infer sibling relationships: other components used in the same files
+  const filesWithThisComponent = new Set(analysis.usages.map((u) => u.filePath));
+
+  for (const [otherName, otherAnalysis] of Object.entries(allAnalyses)) {
+    if (otherName === componentName) continue;
+
+    // Count how many files have both components
+    let sharedFiles = 0;
+    const sharedFileList: string[] = [];
+
+    for (const usage of otherAnalysis.usages) {
+      if (filesWithThisComponent.has(usage.filePath)) {
+        if (!sharedFileList.includes(usage.filePath)) {
+          sharedFiles++;
+          sharedFileList.push(usage.filePath);
+        }
+      }
+    }
+
+    // Only include if they appear together frequently
+    if (sharedFiles >= 3) {
+      siblingCounts.set(otherName, {
+        count: sharedFiles,
+        files: sharedFileList.slice(0, 5),
+      });
+    }
+  }
+
+  // Convert to relations array (parents)
+  for (const [parent, data] of parentCounts) {
+    // Only include meaningful parent relationships (count >= 2)
+    if (data.count >= 2) {
+      relations.push({
+        component: parent,
+        relationship: "parent",
+        frequency: data.count,
+        sampleFiles: data.files.slice(0, 3),
+      });
+    }
+  }
+
+  // Convert to relations array (siblings)
+  for (const [sibling, data] of siblingCounts) {
+    relations.push({
+      component: sibling,
+      relationship: "sibling",
+      frequency: data.count,
+      sampleFiles: data.files.slice(0, 3),
+    });
+  }
+
+  // Sort by frequency
+  relations.sort((a, b) => b.frequency - a.frequency);
+
+  return relations;
+}
+
+/**
+ * Infer relations for all components in the analysis
+ */
+export function inferAllRelations(
+  analysis: UsageAnalysis
+): Map<string, ComponentRelation[]> {
+  const allRelations = new Map<string, ComponentRelation[]>();
+
+  for (const [componentName, componentAnalysis] of Object.entries(analysis.components)) {
+    const relations = inferRelations(componentName, componentAnalysis, analysis.components);
+    if (relations.length > 0) {
+      allRelations.set(componentName, relations);
+    }
+  }
+
+  return allRelations;
+}
+
+/**
+ * Summarize patterns for AI prompt
+ */
+export function summarizePatternsForPrompt(
+  analysis: ComponentAnalysis,
+  maxPatterns: number = 10,
+  maxContexts: number = 5
+): string {
+  const lines: string[] = [];
+
+  lines.push(`## ${analysis.name}`);
+  lines.push(`Total usages: ${analysis.totalUsages} across ${analysis.uniqueFiles} files`);
+  lines.push("");
+
+  // Top patterns
+  lines.push("### Usage Patterns (by frequency)");
+  const topPatterns = analysis.patterns.slice(0, maxPatterns);
+  for (const pattern of topPatterns) {
+    const propsStr = Object.entries(pattern.props)
+      .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+      .join(", ");
+    lines.push(`- ${propsStr || "(no props)"}: ${pattern.count} usages in ${pattern.files.length} files`);
+  }
+  lines.push("");
+
+  // File contexts
+  lines.push("### File Contexts");
+  const topContexts = analysis.contexts.slice(0, maxContexts);
+  for (const ctx of topContexts) {
+    lines.push(`- ${ctx.type}: ${ctx.count} usages`);
+  }
+  lines.push("");
+
+  // Sample code contexts (one per pattern)
+  lines.push("### Sample Usages");
+  for (const pattern of topPatterns.slice(0, 3)) {
+    if (pattern.sampleContexts[0]) {
+      lines.push("```tsx");
+      lines.push(pattern.sampleContexts[0].trim());
+      lines.push("```");
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n");
+}