@fragments-sdk/cli 0.6.0 → 0.7.1

package/src/core/graph-extractor.ts

@@ -0,0 +1,601 @@
+/**
+ * Graph extraction pipeline — builds the ComponentGraph from source code,
+ * fragment metadata, and block definitions.
+ *
+ * Absorbs and enhances the logic from importAnalyzer.ts:
+ * - Import detection (PascalCase component imports)
+ * - Hook dependency detection (useX() calls)
+ * - Object.assign sub-component detection
+ * - JSX usage in variant code
+ * - Block co-occurrence
+ * - Fragment relation mapping
+ * - Auto-detection of requiredChildren and commonPatterns
+ */
+
+import ts from 'typescript';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join, basename } from 'node:path';
+import { readdirSync } from 'node:fs';
+import type {
+  ComponentGraph,
+  ComponentNode,
+  GraphEdge,
+  GraphEdgeType,
+  GraphHealth,
+} from '@fragments-sdk/context/graph';
+import { EDGE_TYPE_WEIGHTS, computeHealthFromData } from '@fragments-sdk/context/graph';
+import type { CompiledFragment, CompiledBlock } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface GraphBuildOptions {
+  /** Skip source-code AST analysis (for testing with mock data) */
+  skipSourceAnalysis?: boolean;
+}
+
+export interface GraphBuildResult {
+  graph: ComponentGraph;
+  /** Auto-detected metadata keyed by component name */
+  autoDetected: Map<string, AutoDetectedMetadata>;
+  /** Warnings about drift between manual declarations and auto-detected values */
+  warnings: string[];
+}
+
+export interface AutoDetectedMetadata {
+  subComponents?: string[];
+  compositionPattern?: 'compound' | 'simple' | 'controlled';
+  commonPatterns?: string[];
+  requiredChildren?: string[];
+}
+
+/**
+ * Build the full ComponentGraph from fragments, blocks, and source code.
+ */
+export async function buildComponentGraph(
+  fragments: Record<string, CompiledFragment>,
+  blocks: Record<string, CompiledBlock>,
+  componentDir: string,
+  options?: GraphBuildOptions,
+): Promise<GraphBuildResult> {
+  const knownComponents = new Set(Object.keys(fragments));
+  const allEdges: GraphEdge[] = [];
+  const autoDetected = new Map<string, AutoDetectedMetadata>();
+  const warnings: string[] = [];
+
+  // 1. Extract edges from source code (imports, hooks, sub-components)
+  if (!options?.skipSourceAnalysis) {
+    const sourceEdges = extractImportAndHookEdges(componentDir, knownComponents);
+    allEdges.push(...sourceEdges);
+
+    const subComponentResults = extractSubComponents(componentDir, knownComponents);
+    for (const [name, subs] of subComponentResults) {
+      autoDetected.set(name, {
+        ...autoDetected.get(name),
+        subComponents: subs,
+        compositionPattern: subs.length > 0 ? 'compound' : 'simple',
+      });
+    }
+  }
+
+  // 2. Extract JSX usage from variant code
+  const jsxEdges = extractJsxUsageEdges(fragments, knownComponents);
+  allEdges.push(...jsxEdges);
+
+  // 3. Extract block co-occurrence edges
+  const blockEdges = extractBlockEdges(blocks);
+  allEdges.push(...blockEdges);
+
+  // 4. Extract relation edges from fragment metadata
+  const relationEdges = extractRelationEdges(fragments);
+  allEdges.push(...relationEdges);
+
+  // 5. Infer requiredChildren
+  const requiredChildrenMap = inferRequiredChildren(fragments, autoDetected);
+  for (const [name, children] of requiredChildrenMap) {
+    const existing = autoDetected.get(name) ?? {};
+    autoDetected.set(name, { ...existing, requiredChildren: children });
+  }
+
+  // 6. Generate common patterns
+  const patternsMap = generateCommonPatterns(fragments, autoDetected);
+  for (const [name, patterns] of patternsMap) {
+    const existing = autoDetected.get(name) ?? {};
+    autoDetected.set(name, { ...existing, commonPatterns: patterns });
+  }
+
+  // 7. Merge and deduplicate edges
+  const mergedEdges = mergeAndDeduplicate(allEdges);
+
+  // 8. Build nodes
+  const nodes: ComponentNode[] = Object.entries(fragments).map(([name, fragment]) => {
+    const detected = autoDetected.get(name);
+    return {
+      name,
+      category: fragment.meta.category,
+      status: fragment.meta.status ?? 'stable',
+      compositionPattern: fragment.ai?.compositionPattern ?? detected?.compositionPattern,
+      subComponents: fragment.ai?.subComponents ?? detected?.subComponents,
+    };
+  });
+
+  // 9. Build block index for health computation
+  const blockIndex = new Map<string, string[]>();
+  for (const [blockName, block] of Object.entries(blocks)) {
+    for (const comp of block.components) {
+      const existing = blockIndex.get(comp);
+      if (existing) existing.push(blockName);
+      else blockIndex.set(comp, [blockName]);
+    }
+  }
+
+  // 10. Compute health
+  const health = computeHealthFromData(nodes, mergedEdges, blockIndex);
+
+  // 11. Generate drift warnings
+  for (const [name, fragment] of Object.entries(fragments)) {
+    const detected = autoDetected.get(name);
+    if (!detected) continue;
+
+    // Sub-components drift
+    if (fragment.ai?.subComponents && detected.subComponents) {
+      const declared = new Set(fragment.ai.subComponents);
+      const found = new Set(detected.subComponents);
+      const missing = detected.subComponents.filter(s => !declared.has(s));
+      const extra = fragment.ai.subComponents.filter(s => !found.has(s));
+
+      if (missing.length > 0) {
+        warnings.push(
+          `${name}: declares ${declared.size} subComponents but code has ${found.size}. ` +
+          `Missing from declaration: ${missing.join(', ')}`
+        );
+      }
+      if (extra.length > 0) {
+        warnings.push(
+          `${name}: declares subComponents [${extra.join(', ')}] not found in Object.assign`
+        );
+      }
+    }
+  }
+
+  return {
+    graph: { nodes, edges: mergedEdges, health },
+    autoDetected,
+    warnings,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Extraction functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse index.tsx files for import declarations and hook calls.
+ * Returns import edges and hook-depends edges.
+ */
+export function extractImportAndHookEdges(
+  componentDir: string,
+  knownComponents: Set<string>,
+): GraphEdge[] {
+  const edges: GraphEdge[] = [];
+
+  for (const componentName of knownComponents) {
+    const indexPath = findComponentIndex(componentDir, componentName);
+    if (!indexPath) continue;
+
+    let sourceText: string;
+    try {
+      sourceText = readFileSync(indexPath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const sourceFile = ts.createSourceFile(
+      indexPath,
+      sourceText,
+      ts.ScriptTarget.Latest,
+      true,
+      indexPath.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+    );
+
+    // Walk AST for imports and hook calls
+    const visitNode = (node: ts.Node) => {
+      // Import declarations
+      if (ts.isImportDeclaration(node)) {
+        const moduleSpecifier = node.moduleSpecifier;
+        if (ts.isStringLiteral(moduleSpecifier)) {
+          const importPath = moduleSpecifier.text;
+          // Only relative imports
+          if (importPath.startsWith('.') || importPath.startsWith('/')) {
+            const clause = node.importClause;
+            if (clause) {
+              // Default import
+              if (clause.name && isPascalCase(clause.name.text) && knownComponents.has(clause.name.text)) {
+                edges.push({
+                  source: componentName,
+                  target: clause.name.text,
+                  type: 'imports',
+                  weight: EDGE_TYPE_WEIGHTS['imports'],
+                  provenance: `source:${componentName}/index.tsx`,
+                });
+              }
+              // Named imports
+              if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+                for (const element of clause.namedBindings.elements) {
+                  const name = element.name.text;
+                  if (isPascalCase(name) && knownComponents.has(name) && name !== componentName) {
+                    edges.push({
+                      source: componentName,
+                      target: name,
+                      type: 'imports',
+                      weight: EDGE_TYPE_WEIGHTS['imports'],
+                      provenance: `source:${componentName}/index.tsx`,
+                    });
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+
+      // Hook calls: useX() where X is a known component
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+        const callName = node.expression.text;
+        const hookMatch = callName.match(/^use([A-Z][a-zA-Z]*)$/);
+        if (hookMatch) {
+          const hookTarget = hookMatch[1];
+          if (knownComponents.has(hookTarget) && hookTarget !== componentName) {
+            edges.push({
+              source: componentName,
+              target: hookTarget,
+              type: 'hook-depends',
+              weight: EDGE_TYPE_WEIGHTS['hook-depends'],
+              provenance: `source:${componentName}/index.tsx`,
+            });
+          }
+        }
+      }
+
+      ts.forEachChild(node, visitNode);
+    };
+
+    ts.forEachChild(sourceFile, visitNode);
+  }
+
+  return edges;
+}
+
+/**
+ * Detect Object.assign(Root, { Sub1, Sub2 }) patterns in index.tsx files.
+ * Returns a map of component name → sub-component names.
+ */
+export function extractSubComponents(
+  componentDir: string,
+  knownComponents: Set<string>,
+): Map<string, string[]> {
+  const result = new Map<string, string[]>();
+
+  for (const componentName of knownComponents) {
+    const indexPath = findComponentIndex(componentDir, componentName);
+    if (!indexPath) continue;
+
+    let sourceText: string;
+    try {
+      sourceText = readFileSync(indexPath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    // Quick regex check first for performance
+    if (!sourceText.includes('Object.assign')) continue;
+
+    const sourceFile = ts.createSourceFile(
+      indexPath,
+      sourceText,
+      ts.ScriptTarget.Latest,
+      true,
+      indexPath.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+    );
+
+    const subComponents: string[] = [];
+
+    const visitNode = (node: ts.Node) => {
+      // Look for Object.assign(X, { A, B, C })
+      if (
+        ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        ts.isIdentifier(node.expression.expression) &&
+        node.expression.expression.text === 'Object' &&
+        node.expression.name.text === 'assign' &&
+        node.arguments.length >= 2
+      ) {
+        const propsArg = node.arguments[1];
+        if (ts.isObjectLiteralExpression(propsArg)) {
+          for (const prop of propsArg.properties) {
+            if (ts.isShorthandPropertyAssignment(prop)) {
+              subComponents.push(prop.name.text);
+            } else if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+              subComponents.push(prop.name.text);
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, visitNode);
+    };
+
+    ts.forEachChild(sourceFile, visitNode);
+
+    if (subComponents.length > 0) {
+      result.set(componentName, subComponents);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Scan variant code strings for JSX element names → renders edges.
+ */
+export function extractJsxUsageEdges(
+  fragments: Record<string, CompiledFragment>,
+  knownComponents: Set<string>,
+): GraphEdge[] {
+  const edges: GraphEdge[] = [];
+  const jsxTagRegex = /<([A-Z][a-zA-Z]*(?:\.[A-Z][a-zA-Z]*)?)/g;
+
+  for (const [name, fragment] of Object.entries(fragments)) {
+    const usedComponents = new Set<string>();
+
+    for (const variant of fragment.variants) {
+      if (!variant.code) continue;
+
+      let match: RegExpExecArray | null;
+      jsxTagRegex.lastIndex = 0;
+      while ((match = jsxTagRegex.exec(variant.code)) !== null) {
+        let tagName = match[1];
+        // Handle compound: Header.Nav → Header
+        if (tagName.includes('.')) {
+          tagName = tagName.split('.')[0];
+        }
+        if (knownComponents.has(tagName) && tagName !== name) {
+          usedComponents.add(tagName);
+        }
+      }
+    }
+
+    for (const target of usedComponents) {
+      edges.push({
+        source: name,
+        target,
+        type: 'renders',
+        weight: EDGE_TYPE_WEIGHTS['renders'],
+        provenance: `variant:${name}`,
+      });
+    }
+  }
+
+  return edges;
+}
+
+/**
+ * Create composes edges from block component lists (pairwise).
+ */
+export function extractBlockEdges(
+  blocks: Record<string, CompiledBlock>,
+): GraphEdge[] {
+  const edges: GraphEdge[] = [];
+
+  for (const [blockName, block] of Object.entries(blocks)) {
+    const components = block.components;
+    // Create pairwise edges (avoid duplicates by only going i < j)
+    for (let i = 0; i < components.length; i++) {
+      for (let j = i + 1; j < components.length; j++) {
+        edges.push({
+          source: components[i],
+          target: components[j],
+          type: 'composes',
+          weight: EDGE_TYPE_WEIGHTS['composes'],
+          provenance: `block:${blockName}`,
+        });
+      }
+    }
+  }
+
+  return edges;
+}
+
+/**
+ * Map fragment ComponentRelation[] to typed graph edges.
+ */
+export function extractRelationEdges(
+  fragments: Record<string, CompiledFragment>,
+): GraphEdge[] {
+  const edges: GraphEdge[] = [];
+
+  const relationToEdgeType: Record<string, GraphEdgeType> = {
+    parent: 'parent-of',
+    child: 'parent-of', // reversed: if A declares child B, edge is A parent-of B
+    composition: 'composes',
+    alternative: 'alternative-to',
+    sibling: 'sibling-of',
+  };
+
+  for (const [name, fragment] of Object.entries(fragments)) {
+    if (!fragment.relations) continue;
+
+    for (const rel of fragment.relations) {
+      const edgeType = relationToEdgeType[rel.relationship];
+      if (!edgeType) continue;
+
+      // For 'child' relation, source is the current component (parent)
+      // For 'parent' relation, source is the related component
+      let source: string;
+      let target: string;
+
+      if (rel.relationship === 'parent') {
+        source = rel.component;
+        target = name;
+      } else {
+        source = name;
+        target = rel.component;
+      }
+
+      edges.push({
+        source,
+        target,
+        type: edgeType,
+        weight: EDGE_TYPE_WEIGHTS[edgeType],
+        note: rel.note,
+        provenance: 'relation',
+      });
+    }
+  }
+
+  return edges;
+}
+
+/**
+ * Infer requiredChildren: sub-components that appear in ALL variant code strings.
+ */
+export function inferRequiredChildren(
+  fragments: Record<string, CompiledFragment>,
+  autoDetected: Map<string, AutoDetectedMetadata>,
+): Map<string, string[]> {
+  const result = new Map<string, string[]>();
+
+  for (const [name, fragment] of Object.entries(fragments)) {
+    const detected = autoDetected.get(name);
+    const subs = detected?.subComponents ?? fragment.ai?.subComponents;
+    if (!subs || subs.length === 0) continue;
+
+    const variantsWithCode = fragment.variants.filter(v => v.code);
+    if (variantsWithCode.length === 0) continue;
+
+    const required: string[] = [];
+    for (const sub of subs) {
+      // Check if this sub-component appears in ALL variants
+      const inAll = variantsWithCode.every(v => {
+        // Match <ComponentName.SubName or just <SubName
+        const patterns = [
+          new RegExp(`<${name}\\.${sub}[\\s/>]`),
+          new RegExp(`<${sub}[\\s/>]`),
+        ];
+        return patterns.some(p => p.test(v.code!));
+      });
+      if (inAll) required.push(sub);
+    }
+
+    if (required.length > 0) {
+      result.set(name, required);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Generate simplified JSX skeleton patterns from variant code.
+ */
+export function generateCommonPatterns(
+  fragments: Record<string, CompiledFragment>,
+  autoDetected: Map<string, AutoDetectedMetadata>,
+): Map<string, string[]> {
+  const result = new Map<string, string[]>();
+
+  for (const [name, fragment] of Object.entries(fragments)) {
+    const detected = autoDetected.get(name);
+    const subs = detected?.subComponents ?? fragment.ai?.subComponents;
+    if (!subs || subs.length === 0) continue;
+
+    // Build a simplified pattern from the first variant that has code
+    const firstVariant = fragment.variants.find(v => v.code);
+    if (!firstVariant?.code) continue;
+
+    // Extract used sub-components from the code
+    const usedSubs: string[] = [];
+    for (const sub of subs) {
+      const patterns = [
+        new RegExp(`<${name}\\.${sub}`),
+        new RegExp(`<${sub}[\\s/>]`),
+      ];
+      if (patterns.some(p => p.test(firstVariant.code!))) {
+        usedSubs.push(sub);
+      }
+    }
+
+    if (usedSubs.length > 0) {
+      const pattern = `<${name}>\n${usedSubs.map(s => `  <${name}.${s}>...</${name}.${s}>`).join('\n')}\n</${name}>`;
+      result.set(name, [pattern]);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Merge edges: key by (source, target, type), keep highest weight.
+ */
+export function mergeAndDeduplicate(edges: GraphEdge[]): GraphEdge[] {
+  const edgeMap = new Map<string, GraphEdge>();
+
+  for (const edge of edges) {
+    const key = `${edge.source}→${edge.target}:${edge.type}`;
+    const existing = edgeMap.get(key);
+    if (!existing || edge.weight > existing.weight) {
+      edgeMap.set(key, edge);
+    }
+  }
+
+  return [...edgeMap.values()];
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function isPascalCase(name: string): boolean {
+  return /^[A-Z][a-zA-Z0-9]*$/.test(name);
+}
+
+/**
+ * Find the index.tsx file for a component in the component directory.
+ */
+function findComponentIndex(componentDir: string, componentName: string): string | null {
+  // Try direct path: componentDir/ComponentName/index.tsx
+  const candidates = [
+    join(componentDir, componentName, 'index.tsx'),
+    join(componentDir, componentName, 'index.ts'),
+    join(componentDir, componentName, `${componentName}.tsx`),
+    join(componentDir, componentName, `${componentName}.ts`),
+  ];
+
+  // Also search within subdirectories matching the component structure
+  // e.g., src/components/ComponentName/index.tsx
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  // Try scanning componentDir for directories matching the component name
+  try {
+    const entries = readdirSync(componentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name === componentName) {
+        const subCandidates = [
+          join(componentDir, entry.name, 'index.tsx'),
+          join(componentDir, entry.name, 'index.ts'),
+        ];
+        for (const sc of subCandidates) {
+          if (existsSync(sc)) return sc;
+        }
+      }
+    }
+  } catch {
+    // Directory might not exist
+  }
+
+  return null;
+}

package/src/core/importAnalyzer.ts

@@ -3,6 +3,11 @@
  *
  * Analyzes TypeScript/JavaScript files to find which components import others,
  * providing accurate "used by" relationships for the component graph.
+ *
+ * @deprecated Import analysis is now handled by graph-extractor.ts which provides
+ * richer edge-typed relationships via the ComponentGraph. These functions are
+ * maintained for backward compatibility. For new code, use
+ * `buildComponentGraph()` from `./graph-extractor.js` instead.
  */
 
 import ts from 'typescript';
@@ -45,7 +50,7 @@ function extractComponentNameFromPath(filePath: string): string {
   return fileName
     .replace(/\.(tsx?|jsx?)$/, '')
     .replace(/\.stories$/, '')
-    .replace(/\.segment$/, '')
+    .replace(/\.fragment$/, '')
     .replace(/\.fragment$/, '');
 }