@fragments-sdk/cli 0.2.2

package/src/viewer/utils/detectRelationships.ts

@@ -0,0 +1,256 @@
+// @ts-nocheck
+/**
+ * Auto-detect component relationships from rendered elements
+ *
+ * Analyzes React elements to discover:
+ * - Composition relationships (components used within other components)
+ * - Sibling relationships (components in the same category)
+ * - Common usage patterns
+ */
+
+import { isValidElement, type ReactNode, type ReactElement, Children } from "react";
+import type { SegmentDefinition, ComponentRelation, RelationshipType } from "../../core/index.js";
+
+interface DetectedRelationship {
+  component: string;
+  relationship: RelationshipType;
+  note: string;
+  confidence: number; // 0-1, how confident we are in this relationship
+}
+
+// Cache for relationship detection to avoid repeated expensive render() calls
+const relationshipCache = new Map<string, { timestamp: number; relationships: DetectedRelationship[] }>();
+const CACHE_TTL = 60000; // 1 minute cache
+
+// Cache for known component names (expensive to recompute for 98+ components)
+let knownComponentsCache: { count: number; set: Set<string> } | null = null;
+
+/**
+ * Extract component name from a React element
+ */
+function getComponentName(element: ReactElement): string | null {
+  const type = element.type;
+
+  if (typeof type === "string") {
+    // HTML element, not a component
+    return null;
+  }
+
+  if (typeof type === "function") {
+    // Function component or class component
+    return type.displayName || type.name || null;
+  }
+
+  if (typeof type === "object" && type !== null) {
+    // Could be forwardRef, memo, etc.
+    const innerType = (type as { $$typeof?: symbol; type?: unknown; render?: unknown })?.type ||
+                      (type as { render?: unknown })?.render;
+    if (typeof innerType === "function") {
+      return (innerType as { displayName?: string; name?: string }).displayName ||
+             (innerType as { name?: string }).name || null;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Recursively collect all component names from an element tree
+ */
+function collectComponentNames(
+  element: ReactNode,
+  collected: Set<string> = new Set()
+): Set<string> {
+  if (!isValidElement(element)) {
+    return collected;
+  }
+
+  const name = getComponentName(element as ReactElement);
+  if (name) {
+    collected.add(name);
+  }
+
+  // Traverse children
+  const children = (element.props as { children?: ReactNode })?.children;
+  if (children) {
+    Children.forEach(children, (child) => {
+      collectComponentNames(child, collected);
+    });
+  }
+
+  return collected;
+}
+
+/**
+ * Get cached set of known component names
+ */
+function getKnownComponents(
+  allSegments: Array<{ path: string; segment: SegmentDefinition }>
+): Set<string> {
+  // Invalidate cache if segment count changed
+  if (!knownComponentsCache || knownComponentsCache.count !== allSegments.length) {
+    knownComponentsCache = {
+      count: allSegments.length,
+      set: new Set(allSegments.map(s => s.segment.meta.name)),
+    };
+  }
+  return knownComponentsCache.set;
+}
+
+/**
+ * Detect composition relationships from a segment's variants
+ */
+export function detectCompositionRelationships(
+  segment: SegmentDefinition,
+  allSegments: Array<{ path: string; segment: SegmentDefinition }>
+): DetectedRelationship[] {
+  const relationships: DetectedRelationship[] = [];
+  const componentName = segment.meta.name;
+  const knownComponents = getKnownComponents(allSegments);
+  const usedComponents = new Set<string>();
+
+  // Analyze each variant's render output
+  for (const variant of segment.variants || []) {
+    try {
+      const rendered = variant.render();
+      const componentNames = collectComponentNames(rendered);
+
+      for (const name of componentNames) {
+        if (name !== componentName && knownComponents.has(name)) {
+          usedComponents.add(name);
+        }
+      }
+    } catch {
+      // Render might fail, skip this variant
+    }
+  }
+
+  // Create composition relationships for used components
+  for (const usedComponent of usedComponents) {
+    relationships.push({
+      component: usedComponent,
+      relationship: "composition",
+      note: `Used within ${componentName} variants`,
+      confidence: 0.8,
+    });
+  }
+
+  return relationships;
+}
+
+/**
+ * Detect sibling relationships based on semantic connections.
+ *
+ * NOTE: Category-based sibling detection was removed because it creates
+ * meaningless relationships (e.g., Card → Separator just because both are "layout").
+ *
+ * True sibling relationships should be defined manually in the fragment definition
+ * based on actual use cases (e.g., Table uses Badge for status columns).
+ *
+ * This function now only detects siblings when:
+ * - There's a bidirectional manual relationship (A references B AND B references A)
+ * - Components share overlapping variant patterns (future enhancement)
+ */
+export function detectSiblingRelationships(
+  _segment: SegmentDefinition,
+  _allSegments: Array<{ path: string; segment: SegmentDefinition }>
+): DetectedRelationship[] {
+  // Disabled: Category-based sibling detection creates noise
+  // Meaningful sibling relationships should be defined manually
+  return [];
+}
+
+/**
+ * Detect alternative relationships.
+ *
+ * NOTE: Pattern-based alternative detection was removed because it creates
+ * weak relationships based on naming conventions rather than actual use cases.
+ *
+ * True alternative relationships should be defined manually in the fragment
+ * definition based on actual decision criteria (e.g., "Use IconButton instead
+ * of Button when only an icon is needed").
+ *
+ * A better approach would analyze the `whenNot` guidelines for semantic matches,
+ * but that requires NLP/semantic analysis which is out of scope.
+ */
+export function detectAlternativeRelationships(
+  _segment: SegmentDefinition,
+  _allSegments: Array<{ path: string; segment: SegmentDefinition }>
+): DetectedRelationship[] {
+  // Disabled: Pattern-based alternative detection is too weak
+  // Meaningful alternatives should be defined manually with clear rationale
+  return [];
+}
+
+/**
+ * Combine all detected relationships and deduplicate
+ * Uses caching to avoid expensive render() calls on subsequent views
+ */
+export function detectAllRelationships(
+  segment: SegmentDefinition,
+  allSegments: Array<{ path: string; segment: SegmentDefinition }>
+): DetectedRelationship[] {
+  const cacheKey = segment.meta.name;
+  const now = Date.now();
+
+  // Check cache first
+  const cached = relationshipCache.get(cacheKey);
+  if (cached && (now - cached.timestamp) < CACHE_TTL) {
+    return cached.relationships;
+  }
+
+  const all = [
+    ...detectCompositionRelationships(segment, allSegments),
+    ...detectSiblingRelationships(segment, allSegments),
+    ...detectAlternativeRelationships(segment, allSegments),
+  ];
+
+  // Deduplicate by component name, keeping highest confidence
+  const byComponent = new Map<string, DetectedRelationship>();
+
+  for (const rel of all) {
+    const existing = byComponent.get(rel.component);
+    if (!existing || rel.confidence > existing.confidence) {
+      byComponent.set(rel.component, rel);
+    }
+  }
+
+  // Sort by confidence descending
+  const result = Array.from(byComponent.values()).sort((a, b) => b.confidence - a.confidence);
+
+  // Cache the result
+  relationshipCache.set(cacheKey, { timestamp: now, relationships: result });
+
+  return result;
+}
+
+/**
+ * Merge manual and auto-detected relationships
+ */
+export function mergeRelationships(
+  manual: ComponentRelation[] | undefined,
+  detected: DetectedRelationship[]
+): Array<ComponentRelation & { isDetected?: boolean; confidence?: number }> {
+  const result: Array<ComponentRelation & { isDetected?: boolean; confidence?: number }> = [];
+  const manualComponents = new Set((manual || []).map(r => r.component));
+
+  // Add manual relationships first
+  for (const rel of manual || []) {
+    result.push({ ...rel, isDetected: false });
+  }
+
+  // Add detected relationships that aren't already defined manually
+  for (const rel of detected) {
+    if (!manualComponents.has(rel.component)) {
+      result.push({
+        component: rel.component,
+        relationship: rel.relationship,
+        note: rel.note,
+        isDetected: true,
+        confidence: rel.confidence,
+      });
+    }
+  }
+
+  return result;
+}