@fragments-sdk/cli 0.6.0 → 0.7.1

package/src/core/graph-extractor.test.ts

@@ -0,0 +1,542 @@
+import { describe, it, expect } from 'vitest';
+import type { CompiledFragment, CompiledBlock } from './types.js';
+import {
+  buildComponentGraph,
+  extractJsxUsageEdges,
+  extractBlockEdges,
+  extractRelationEdges,
+  inferRequiredChildren,
+  generateCommonPatterns,
+  mergeAndDeduplicate,
+} from './graph-extractor.js';
+import type { GraphEdge } from '@fragments-sdk/context/graph';
+import { EDGE_TYPE_WEIGHTS } from '@fragments-sdk/context/graph';
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+function makeFragment(name: string, overrides: Partial<CompiledFragment> = {}): CompiledFragment {
+  return {
+    filePath: `src/components/${name}/${name}.fragment.tsx`,
+    meta: {
+      name,
+      description: `The ${name} component`,
+      category: 'test',
+      status: 'stable',
+      ...overrides.meta,
+    },
+    usage: {
+      when: [`Use ${name} for testing`],
+      whenNot: [],
+      ...overrides.usage,
+    },
+    props: overrides.props ?? {},
+    variants: overrides.variants ?? [
+      { name: 'Default', description: `Default ${name}` },
+    ],
+    relations: overrides.relations,
+    ai: overrides.ai,
+  };
+}
+
+function makeBlock(name: string, components: string[], category = 'test'): CompiledBlock {
+  return {
+    filePath: `src/blocks/${name}.block.ts`,
+    name,
+    description: `${name} block`,
+    category,
+    components,
+    code: `<${components[0]}></${components[0]}>`,
+    tags: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// extractJsxUsageEdges
+// ---------------------------------------------------------------------------
+
+describe('extractJsxUsageEdges()', () => {
+  it('detects JSX component usage in variant code', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Dialog: makeFragment('Dialog', {
+        variants: [
+          {
+            name: 'Default',
+            description: 'Default dialog',
+            code: '<Dialog>\n  <Button>Close</Button>\n</Dialog>',
+          },
+        ],
+      }),
+      Button: makeFragment('Button'),
+    };
+
+    const edges = extractJsxUsageEdges(fragments, new Set(['Dialog', 'Button']));
+    expect(edges.length).toBe(1);
+    expect(edges[0].source).toBe('Dialog');
+    expect(edges[0].target).toBe('Button');
+    expect(edges[0].type).toBe('renders');
+  });
+
+  it('handles compound component notation (Header.Nav)', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      AppShell: makeFragment('AppShell', {
+        variants: [
+          {
+            name: 'Default',
+            description: 'Default shell',
+            code: '<AppShell>\n  <Header.Nav>...</Header.Nav>\n  <Sidebar.Content>...</Sidebar.Content>\n</AppShell>',
+          },
+        ],
+      }),
+      Header: makeFragment('Header'),
+      Sidebar: makeFragment('Sidebar'),
+    };
+
+    const edges = extractJsxUsageEdges(
+      fragments,
+      new Set(['AppShell', 'Header', 'Sidebar']),
+    );
+    expect(edges.length).toBe(2);
+    expect(edges.some(e => e.target === 'Header')).toBe(true);
+    expect(edges.some(e => e.target === 'Sidebar')).toBe(true);
+  });
+
+  it('does not create self-referencing edges', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Button: makeFragment('Button', {
+        variants: [
+          {
+            name: 'Default',
+            description: 'Default',
+            code: '<Button>Click me</Button>',
+          },
+        ],
+      }),
+    };
+
+    const edges = extractJsxUsageEdges(fragments, new Set(['Button']));
+    expect(edges.length).toBe(0);
+  });
+
+  it('deduplicates across variants', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Dialog: makeFragment('Dialog', {
+        variants: [
+          { name: 'V1', description: 'V1', code: '<Dialog><Button>OK</Button></Dialog>' },
+          { name: 'V2', description: 'V2', code: '<Dialog><Button>Cancel</Button></Dialog>' },
+        ],
+      }),
+      Button: makeFragment('Button'),
+    };
+
+    const edges = extractJsxUsageEdges(fragments, new Set(['Dialog', 'Button']));
+    // Should only create one edge even though Button appears in two variants
+    expect(edges.length).toBe(1);
+  });
+
+  it('skips variants without code', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Dialog: makeFragment('Dialog', {
+        variants: [
+          { name: 'NoCode', description: 'No code variant' },
+        ],
+      }),
+    };
+
+    const edges = extractJsxUsageEdges(fragments, new Set(['Dialog']));
+    expect(edges.length).toBe(0);
+  });
+
+  it('ignores unknown component tags', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Dialog: makeFragment('Dialog', {
+        variants: [
+          { name: 'Default', description: 'Default', code: '<Dialog><UnknownThing /></Dialog>' },
+        ],
+      }),
+    };
+
+    const edges = extractJsxUsageEdges(fragments, new Set(['Dialog']));
+    expect(edges.length).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// extractBlockEdges
+// ---------------------------------------------------------------------------
+
+describe('extractBlockEdges()', () => {
+  it('creates pairwise composes edges', () => {
+    const blocks: Record<string, CompiledBlock> = {
+      LoginForm: makeBlock('LoginForm', ['Dialog', 'Input', 'Button']),
+    };
+
+    const edges = extractBlockEdges(blocks);
+    // 3 components → 3 pairwise edges (Dialog-Input, Dialog-Button, Input-Button)
+    expect(edges.length).toBe(3);
+    expect(edges.every(e => e.type === 'composes')).toBe(true);
+    expect(edges.every(e => e.provenance === 'block:LoginForm')).toBe(true);
+  });
+
+  it('handles single-component blocks', () => {
+    const blocks: Record<string, CompiledBlock> = {
+      Solo: makeBlock('Solo', ['Button']),
+    };
+
+    const edges = extractBlockEdges(blocks);
+    expect(edges.length).toBe(0);
+  });
+
+  it('handles multiple blocks', () => {
+    const blocks: Record<string, CompiledBlock> = {
+      Login: makeBlock('Login', ['Dialog', 'Button']),
+      Search: makeBlock('Search', ['Input', 'Button']),
+    };
+
+    const edges = extractBlockEdges(blocks);
+    // Login: Dialog-Button = 1 edge; Search: Input-Button = 1 edge
+    expect(edges.length).toBe(2);
+  });
+
+  it('preserves block provenance', () => {
+    const blocks: Record<string, CompiledBlock> = {
+      Dashboard: makeBlock('Dashboard', ['Header', 'Sidebar']),
+    };
+
+    const edges = extractBlockEdges(blocks);
+    expect(edges[0].provenance).toBe('block:Dashboard');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// extractRelationEdges
+// ---------------------------------------------------------------------------
+
+describe('extractRelationEdges()', () => {
+  it('maps parent relation correctly', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Button: makeFragment('Button', {
+        relations: [
+          { component: 'Header', relationship: 'parent', note: 'Used in Header actions' },
+        ],
+      }),
+    };
+
+    const edges = extractRelationEdges(fragments);
+    expect(edges.length).toBe(1);
+    // parent relation: Header is parent of Button → source=Header, target=Button
+    expect(edges[0].source).toBe('Header');
+    expect(edges[0].target).toBe('Button');
+    expect(edges[0].type).toBe('parent-of');
+  });
+
+  it('maps child relation correctly', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Header: makeFragment('Header', {
+        relations: [
+          { component: 'Button', relationship: 'child', note: 'Renders action buttons' },
+        ],
+      }),
+    };
+
+    const edges = extractRelationEdges(fragments);
+    expect(edges.length).toBe(1);
+    expect(edges[0].source).toBe('Header');
+    expect(edges[0].target).toBe('Button');
+    expect(edges[0].type).toBe('parent-of');
+  });
+
+  it('maps alternative relation', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Dialog: makeFragment('Dialog', {
+        relations: [
+          { component: 'Popover', relationship: 'alternative', note: 'For non-modal overlays' },
+        ],
+      }),
+    };
+
+    const edges = extractRelationEdges(fragments);
+    expect(edges[0].type).toBe('alternative-to');
+    expect(edges[0].note).toBe('For non-modal overlays');
+  });
+
+  it('maps sibling relation', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Header: makeFragment('Header', {
+        relations: [
+          { component: 'Sidebar', relationship: 'sibling', note: 'Both in AppShell' },
+        ],
+      }),
+    };
+
+    const edges = extractRelationEdges(fragments);
+    expect(edges[0].type).toBe('sibling-of');
+  });
+
+  it('maps composition relation', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Input: makeFragment('Input', {
+        relations: [
+          { component: 'Button', relationship: 'composition', note: 'Often paired in forms' },
+        ],
+      }),
+    };
+
+    const edges = extractRelationEdges(fragments);
+    expect(edges[0].type).toBe('composes');
+  });
+
+  it('skips fragments without relations', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Button: makeFragment('Button'),
+    };
+
+    const edges = extractRelationEdges(fragments);
+    expect(edges.length).toBe(0);
+  });
+
+  it('skips unknown relationship types', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Button: makeFragment('Button', {
+        relations: [
+          { component: 'Icon', relationship: 'unknown-type' as any, note: 'Custom relation' },
+        ],
+      }),
+    };
+
+    const edges = extractRelationEdges(fragments);
+    expect(edges.length).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// inferRequiredChildren
+// ---------------------------------------------------------------------------
+
+describe('inferRequiredChildren()', () => {
+  it('identifies sub-components present in ALL variants', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Dialog: makeFragment('Dialog', {
+        variants: [
+          { name: 'V1', description: 'V1', code: '<Dialog><Dialog.Content>...</Dialog.Content><Dialog.Footer>...</Dialog.Footer></Dialog>' },
+          { name: 'V2', description: 'V2', code: '<Dialog><Dialog.Content>...</Dialog.Content></Dialog>' },
+        ],
+      }),
+    };
+
+    const autoDetected = new Map([['Dialog', { subComponents: ['Content', 'Footer'] }]]);
+    const result = inferRequiredChildren(fragments, autoDetected);
+
+    expect(result.get('Dialog')).toEqual(['Content']);
+  });
+
+  it('returns empty for components with no subs', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Button: makeFragment('Button', {
+        variants: [{ name: 'Default', description: 'Default', code: '<Button>Click</Button>' }],
+      }),
+    };
+
+    const autoDetected = new Map<string, any>();
+    const result = inferRequiredChildren(fragments, autoDetected);
+    expect(result.size).toBe(0);
+  });
+
+  it('uses ai.subComponents when autoDetected is empty', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Dialog: makeFragment('Dialog', {
+        ai: { subComponents: ['Content', 'Footer'] },
+        variants: [
+          { name: 'V1', description: 'V1', code: '<Dialog><Dialog.Content>...</Dialog.Content><Dialog.Footer>...</Dialog.Footer></Dialog>' },
+          { name: 'V2', description: 'V2', code: '<Dialog><Dialog.Content>...</Dialog.Content><Dialog.Footer>...</Dialog.Footer></Dialog>' },
+        ],
+      }),
+    };
+
+    const autoDetected = new Map<string, any>();
+    const result = inferRequiredChildren(fragments, autoDetected);
+    expect(result.get('Dialog')).toEqual(['Content', 'Footer']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// generateCommonPatterns
+// ---------------------------------------------------------------------------
+
+describe('generateCommonPatterns()', () => {
+  it('generates skeleton patterns from variant code', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Dialog: makeFragment('Dialog', {
+        variants: [
+          {
+            name: 'Default',
+            description: 'Default',
+            code: '<Dialog>\n  <Dialog.Content>Hello</Dialog.Content>\n  <Dialog.Footer>Close</Dialog.Footer>\n</Dialog>',
+          },
+        ],
+      }),
+    };
+
+    const autoDetected = new Map([['Dialog', { subComponents: ['Content', 'Footer'] }]]);
+    const result = generateCommonPatterns(fragments, autoDetected);
+
+    expect(result.has('Dialog')).toBe(true);
+    const patterns = result.get('Dialog')!;
+    expect(patterns[0]).toContain('<Dialog>');
+    expect(patterns[0]).toContain('Dialog.Content');
+    expect(patterns[0]).toContain('Dialog.Footer');
+  });
+
+  it('returns empty for components without sub-components', () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Button: makeFragment('Button'),
+    };
+
+    const autoDetected = new Map<string, any>();
+    const result = generateCommonPatterns(fragments, autoDetected);
+    expect(result.size).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// mergeAndDeduplicate
+// ---------------------------------------------------------------------------
+
+describe('mergeAndDeduplicate()', () => {
+  it('deduplicates by (source, target, type)', () => {
+    const edges: GraphEdge[] = [
+      { source: 'A', target: 'B', type: 'imports', weight: 0.5, provenance: 'test1' },
+      { source: 'A', target: 'B', type: 'imports', weight: 1.0, provenance: 'test2' },
+    ];
+
+    const result = mergeAndDeduplicate(edges);
+    expect(result.length).toBe(1);
+    expect(result[0].weight).toBe(1.0); // keeps highest weight
+  });
+
+  it('preserves different edge types between same components', () => {
+    const edges: GraphEdge[] = [
+      { source: 'A', target: 'B', type: 'imports', weight: 1.0, provenance: 'test' },
+      { source: 'A', target: 'B', type: 'renders', weight: 0.5, provenance: 'test' },
+    ];
+
+    const result = mergeAndDeduplicate(edges);
+    expect(result.length).toBe(2);
+  });
+
+  it('preserves edges in different directions', () => {
+    const edges: GraphEdge[] = [
+      { source: 'A', target: 'B', type: 'imports', weight: 1.0, provenance: 'test' },
+      { source: 'B', target: 'A', type: 'imports', weight: 1.0, provenance: 'test' },
+    ];
+
+    const result = mergeAndDeduplicate(edges);
+    expect(result.length).toBe(2);
+  });
+
+  it('handles empty input', () => {
+    expect(mergeAndDeduplicate([])).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildComponentGraph (integration, with skipSourceAnalysis)
+// ---------------------------------------------------------------------------
+
+describe('buildComponentGraph()', () => {
+  it('builds a graph from fragments and blocks', async () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Button: makeFragment('Button'),
+      Dialog: makeFragment('Dialog', {
+        variants: [
+          { name: 'Default', description: 'Default', code: '<Dialog><Button>OK</Button></Dialog>' },
+        ],
+        relations: [
+          { component: 'Popover', relationship: 'alternative', note: 'Non-modal' },
+        ],
+      }),
+      Input: makeFragment('Input'),
+      Popover: makeFragment('Popover'),
+    };
+
+    const blocks: Record<string, CompiledBlock> = {
+      LoginForm: makeBlock('LoginForm', ['Dialog', 'Input', 'Button']),
+    };
+
+    const result = await buildComponentGraph(fragments, blocks, '/tmp/fake', {
+      skipSourceAnalysis: true,
+    });
+
+    expect(result.graph.nodes.length).toBe(4);
+    expect(result.graph.edges.length).toBeGreaterThan(0);
+    expect(result.graph.health.nodeCount).toBe(4);
+
+    // Check renders edge: Dialog → Button
+    expect(result.graph.edges.some(
+      e => e.source === 'Dialog' && e.target === 'Button' && e.type === 'renders'
+    )).toBe(true);
+
+    // Check composes edges from block
+    expect(result.graph.edges.some(e => e.type === 'composes')).toBe(true);
+
+    // Check relation edge: Dialog → Popover alternative
+    expect(result.graph.edges.some(
+      e => e.source === 'Dialog' && e.target === 'Popover' && e.type === 'alternative-to'
+    )).toBe(true);
+  });
+
+  it('auto-detects metadata and reports warnings', async () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Dialog: makeFragment('Dialog', {
+        ai: {
+          compositionPattern: 'compound',
+          subComponents: ['Content'],
+          // Missing Footer which is auto-detected below
+        },
+        variants: [
+          { name: 'Default', description: 'Default', code: '<Dialog><Dialog.Content>...</Dialog.Content></Dialog>' },
+        ],
+      }),
+    };
+
+    const result = await buildComponentGraph(fragments, {}, '/tmp/fake', {
+      skipSourceAnalysis: true,
+    });
+
+    // Should produce a valid graph even with skipSourceAnalysis
+    expect(result.graph.nodes.length).toBe(1);
+  });
+
+  it('handles empty fragments', async () => {
+    const result = await buildComponentGraph({}, {}, '/tmp/fake', {
+      skipSourceAnalysis: true,
+    });
+
+    expect(result.graph.nodes.length).toBe(0);
+    expect(result.graph.edges.length).toBe(0);
+    expect(result.graph.health.nodeCount).toBe(0);
+  });
+
+  it('computes health metrics', async () => {
+    const fragments: Record<string, CompiledFragment> = {
+      Button: makeFragment('Button'),
+      Input: makeFragment('Input'),
+      Orphan: makeFragment('Orphan'),
+    };
+
+    const blocks: Record<string, CompiledBlock> = {
+      Form: makeBlock('Form', ['Button', 'Input']),
+    };
+
+    const result = await buildComponentGraph(fragments, blocks, '/tmp/fake', {
+      skipSourceAnalysis: true,
+    });
+
+    expect(result.graph.health.nodeCount).toBe(3);
+    // Button and Input have composes edge, Orphan has none
+    expect(result.graph.health.orphans).toContain('Orphan');
+    // Composition coverage: 2/3 components are in blocks
+    expect(result.graph.health.compositionCoverage).toBe(67);
+  });
+});