@fragments-sdk/cli 0.11.1 → 0.13.0

package/src/commands/__tests__/scan-generate.test.ts

@@ -1,5 +1,5 @@
-import { describe, it, expect, beforeAll, afterAll } from "vitest";
-import { mkdtemp, writeFile, mkdir, rm } from "node:fs/promises";
+import { describe, it, expect, beforeAll, afterAll, vi } from "vitest";
+import { mkdtemp, writeFile, mkdir, rm, readFile as rf } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import {
@@ -7,8 +7,29 @@ import {
   detectCompoundComponentsFromSource,
   calculateFieldConfidence,
   scanGenerate,
+  parseEnrichmentResponse,
+  buildEnrichmentSystemPrompt,
+  buildEnrichmentUserPrompt,
+  buildEnrichedUsageBlock,
+  type EnrichmentResult,
 } from "../scan-generate.js";
-import type { ExtractedProp } from "../../service/enhance/props-extractor.js";
+import type { ComponentMeta } from "../../core/component-extractor.js";
+
+// ---------------------------------------------------------------------------
+// Helper to build a minimal ComponentMeta for tests
+// ---------------------------------------------------------------------------
+
+function makeMeta(overrides: Partial<ComponentMeta> = {}): ComponentMeta {
+  return {
+    name: overrides.name ?? 'Test',
+    filePath: overrides.filePath ?? '/test.tsx',
+    description: overrides.description ?? '',
+    props: overrides.props ?? {},
+    composition: overrides.composition ?? null,
+    exports: overrides.exports ?? [],
+    dependencies: overrides.dependencies ?? [],
+  };
+}
 
 // ---------------------------------------------------------------------------
 // JSDoc Extraction
@@ -121,44 +142,27 @@ export function Button() {
 // ---------------------------------------------------------------------------
 
 describe("calculateFieldConfidence", () => {
-  const makeProps = (names: string[]): ExtractedProp[] =>
-    names.map((name) => ({
-      name,
-      type: "string",
-      propType: { type: "string" as const },
-      description: "",
-      required: false,
-    }));
-
   it("gives +30 for extracted props", () => {
     const result = calculateFieldConfidence({
       component: { name: "Foo", sourcePath: "/foo.tsx", relativePath: "foo.tsx" },
-      props: {
-        filePath: "/foo.tsx",
-        componentName: "Foo",
-        props: makeProps(["children"]),
-        success: true,
-        warnings: [],
-      },
-      jsDoc: null,
-      compoundChildren: [],
+      meta: makeMeta({
+        props: {
+          children: { name: "children", type: "ReactNode", typeKind: "node", required: true, source: "local" },
+        },
+      }),
       storyVariants: [],
     });
-    // +30 (props) + 0 (no JSDoc → TODO) + 0 (category fallback → TODO) + 0 (no stories) + 10 (all resolved) + 0 (no defaults) = 40
-    // But "children" prop → category "Layout" (+10)
-    // So: 30 + 10 + 10 = 50
+    // +30 (props) + 0 (no description → TODO) + 10 (children → category "Layout") + 10 (all resolved) + 0 (no stories) + 0 (no composition) + 0 (no defaults) = 50
     expect(result.score).toBe(50);
   });
 
   it("gives +15 for JSDoc description", () => {
     const result = calculateFieldConfidence({
       component: { name: "Foo", sourcePath: "/foo.tsx", relativePath: "foo.tsx" },
-      props: null,
-      jsDoc: "A component",
-      compoundChildren: [],
+      meta: makeMeta({ description: "A component" }),
       storyVariants: [],
     });
-    // +15 (JSDoc), no props, category fallback → TODO, no stories
+    // +15 (description), no props, category fallback → TODO, no stories
     expect(result.score).toBe(15);
     expect(result.todoFields).not.toContain("meta.description");
     expect(result.todoFields).toContain("meta.category");
@@ -167,38 +171,40 @@ describe("calculateFieldConfidence", () => {
   it("gives +25 for story variants", () => {
     const result = calculateFieldConfidence({
       component: { name: "Foo", sourcePath: "/foo.tsx", relativePath: "foo.tsx" },
-      props: null,
-      jsDoc: null,
-      compoundChildren: [],
+      meta: null,
       storyVariants: [{ name: "Primary", args: {} }],
     });
     // +25 (stories)
     expect(result.score).toBe(25);
   });
 
-  it("gives +5 for compound children", () => {
+  it("gives +10 for compound composition with parts", () => {
     const result = calculateFieldConfidence({
       component: { name: "Foo", sourcePath: "/foo.tsx", relativePath: "foo.tsx" },
-      props: null,
-      jsDoc: null,
-      compoundChildren: ["Header", "Body"],
+      meta: makeMeta({
+        composition: {
+          pattern: "compound",
+          parts: [
+            { name: "Header", props: {} },
+            { name: "Body", props: {} },
+          ],
+          required: [],
+        },
+      }),
       storyVariants: [],
     });
-    expect(result.score).toBe(5);
+    expect(result.score).toBe(10);
   });
 
   it("always includes usage.when and usage.whenNot in TODOs", () => {
     const result = calculateFieldConfidence({
       component: { name: "Button", sourcePath: "/button.tsx", relativePath: "button.tsx" },
-      props: {
-        filePath: "/button.tsx",
-        componentName: "Button",
-        props: makeProps(["onClick"]),
-        success: true,
-        warnings: [],
-      },
-      jsDoc: "A button",
-      compoundChildren: [],
+      meta: makeMeta({
+        description: "A button",
+        props: {
+          onClick: { name: "onClick", type: "() => void", typeKind: "function", required: false, source: "local" },
+        },
+      }),
       storyVariants: [{ name: "Primary", args: {} }],
     });
     expect(result.todoFields).toContain("usage.when");
@@ -291,6 +297,10 @@ export function Button({ children, variant = 'primary', disabled, onClick }: But
     // Check props block has content
     expect(content).toContain("children:");
     expect(content).toContain("variant:");
+
+    // Check _generated provenance block
+    expect(content).toContain("_generated:");
+    expect(content).toContain("source: 'ai'");
   });
 
   it("skips existing fragments without --force", async () => {
@@ -305,4 +315,446 @@ export function Button({ children, variant = 'primary', disabled, onClick }: But
     expect(result.skipped[0].reason).toBe("Fragment already exists");
     expect(result.generated.length).toBe(0);
   });
+
+  it("generates a contract block with propsSummary", async () => {
+    const result = await scanGenerate({
+      scanPath: join(tmpDir, "components"),
+      force: true,
+    });
+
+    expect(result.success).toBe(true);
+
+    const { readFile: rf } = await import("node:fs/promises");
+    const content = await rf(
+      join(tmpDir, "components", "Button", "Button.fragment.tsx"),
+      "utf-8"
+    );
+
+    // Check contract block exists
+    expect(content).toContain("contract:");
+    expect(content).toContain("propsSummary:");
+
+    // Check propsSummary has entries for local props
+    expect(content).toContain("variant:");
+    expect(content).toContain("disabled:");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Integration: compound component contract generation
+// ---------------------------------------------------------------------------
+
+describe("scanGenerate compound contract", () => {
+  let tmpDir: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "scan-compound-test-"));
+
+    const compDir = join(tmpDir, "components", "Card");
+    await mkdir(compDir, { recursive: true });
+
+    await writeFile(
+      join(compDir, "Card.tsx"),
+      `import React from 'react';
+
+/** A card container for grouped content. */
+export function Card({ children }: { children: React.ReactNode }) {
+  return <div>{children}</div>;
+}
+
+export function CardHeader({ children }: { children: React.ReactNode }) {
+  return <header>{children}</header>;
+}
+
+export function CardBody({ children }: { children: React.ReactNode }) {
+  return <main>{children}</main>;
+}
+
+export function CardFooter({ children }: { children: React.ReactNode }) {
+  return <footer>{children}</footer>;
+}
+`,
+      "utf-8"
+    );
+  });
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("generates compoundChildren in contract for compound components", async () => {
+    const result = await scanGenerate({
+      scanPath: join(tmpDir, "components"),
+      force: true,
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.generated.length).toBe(1);
+    expect(result.generated[0].name).toBe("Card");
+
+    const content = await rf(
+      join(tmpDir, "components", "Card", "Card.fragment.tsx"),
+      "utf-8"
+    );
+
+    // Should have contract with compoundChildren
+    expect(content).toContain("contract:");
+    expect(content).toContain("compoundChildren:");
+    expect(content).toContain("Header:");
+    expect(content).toContain("Body:");
+    expect(content).toContain("Footer:");
+
+    // Should have canonicalUsage
+    expect(content).toContain("canonicalUsage:");
+    expect(content).toContain("Card.Header");
+    expect(content).toContain("Card.Body");
+    expect(content).toContain("Card.Footer");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Enrichment: parseEnrichmentResponse
+// ---------------------------------------------------------------------------
+
+describe("parseEnrichmentResponse", () => {
+  it("parses valid JSON response", () => {
+    const result = parseEnrichmentResponse(JSON.stringify({
+      when: ["Display grouped content", "Card-based layouts"],
+      whenNot: ["Simple text — use a div"],
+      guidelines: ["Use Card.Header for titles"],
+      a11yRules: ["Must have accessible name"],
+      scenarioTags: ["layout.container.card"],
+      tags: ["card", "container"],
+    }));
+
+    expect(result.when).toEqual(["Display grouped content", "Card-based layouts"]);
+    expect(result.whenNot).toEqual(["Simple text — use a div"]);
+    expect(result.guidelines).toEqual(["Use Card.Header for titles"]);
+    expect(result.a11yRules).toEqual(["Must have accessible name"]);
+    expect(result.scenarioTags).toEqual(["layout.container.card"]);
+    expect(result.tags).toEqual(["card", "container"]);
+  });
+
+  it("handles ```json fences", () => {
+    const text = '```json\n{"when": ["Use for actions"], "whenNot": [], "guidelines": [], "a11yRules": [], "scenarioTags": [], "tags": []}\n```';
+    const result = parseEnrichmentResponse(text);
+    expect(result.when).toEqual(["Use for actions"]);
+  });
+
+  it("returns safe empty defaults on malformed JSON", () => {
+    const result = parseEnrichmentResponse("this is not json at all");
+    expect(result.when).toEqual([]);
+    expect(result.whenNot).toEqual([]);
+    expect(result.guidelines).toEqual([]);
+    expect(result.a11yRules).toEqual([]);
+    expect(result.scenarioTags).toEqual([]);
+    expect(result.tags).toEqual([]);
+  });
+
+  it("truncates arrays exceeding max length", () => {
+    const result = parseEnrichmentResponse(JSON.stringify({
+      when: ["a", "b", "c", "d", "e", "f", "g"],
+      whenNot: ["a", "b", "c", "d", "e"],
+      guidelines: ["a", "b", "c", "d"],
+      a11yRules: ["a", "b", "c", "d", "e"],
+      scenarioTags: ["a", "b", "c", "d", "e", "f"],
+      tags: ["a", "b", "c", "d", "e", "f"],
+    }));
+
+    expect(result.when).toHaveLength(5);
+    expect(result.whenNot).toHaveLength(4);
+    expect(result.guidelines).toHaveLength(3);
+    expect(result.a11yRules).toHaveLength(4);
+    expect(result.scenarioTags).toHaveLength(5);
+    expect(result.tags).toHaveLength(5);
+  });
+
+  it("filters out non-string array items", () => {
+    const result = parseEnrichmentResponse(JSON.stringify({
+      when: ["valid", 42, null, "also valid"],
+      whenNot: [],
+      guidelines: [],
+      a11yRules: [],
+      scenarioTags: [],
+      tags: [],
+    }));
+
+    expect(result.when).toEqual(["valid", "also valid"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Enrichment: calculateFieldConfidence with enrichment
+// ---------------------------------------------------------------------------
+
+describe("calculateFieldConfidence with enrichment", () => {
+  const enrichment: EnrichmentResult = {
+    when: ["Use for grouped content"],
+    whenNot: ["Simple text grouping"],
+    guidelines: ["Always include a header"],
+    a11yRules: ["Use semantic landmarks"],
+    scenarioTags: ["layout.card"],
+    tags: ["card", "container"],
+  };
+
+  it("gives higher score with enrichment", () => {
+    const withoutEnrich = calculateFieldConfidence({
+      component: { name: "Card", sourcePath: "/card.tsx", relativePath: "card.tsx" },
+      meta: makeMeta({ description: "A card" }),
+      storyVariants: [],
+    });
+
+    const withEnrich = calculateFieldConfidence(
+      {
+        component: { name: "Card", sourcePath: "/card.tsx", relativePath: "card.tsx" },
+        meta: makeMeta({ description: "A card" }),
+        storyVariants: [],
+      },
+      enrichment
+    );
+
+    expect(withEnrich.score).toBeGreaterThan(withoutEnrich.score);
+  });
+
+  it("removes usage.when and usage.whenNot from todoFields when enriched", () => {
+    const result = calculateFieldConfidence(
+      {
+        component: { name: "Card", sourcePath: "/card.tsx", relativePath: "card.tsx" },
+        meta: makeMeta({ description: "A card" }),
+        storyVariants: [],
+      },
+      enrichment
+    );
+
+    expect(result.todoFields).not.toContain("usage.when");
+    expect(result.todoFields).not.toContain("usage.whenNot");
+  });
+
+  it("still includes usage TODOs without enrichment (backward compat)", () => {
+    const result = calculateFieldConfidence({
+      component: { name: "Card", sourcePath: "/card.tsx", relativePath: "card.tsx" },
+      meta: makeMeta({ description: "A card" }),
+      storyVariants: [],
+    });
+
+    expect(result.todoFields).toContain("usage.when");
+    expect(result.todoFields).toContain("usage.whenNot");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Enrichment: buildEnrichmentSystemPrompt / buildEnrichmentUserPrompt
+// ---------------------------------------------------------------------------
+
+describe("enrichment prompts", () => {
+  it("buildEnrichmentSystemPrompt returns a non-empty system prompt", () => {
+    const prompt = buildEnrichmentSystemPrompt();
+    expect(prompt).toContain("senior frontend architect");
+    expect(prompt).toContain("when");
+    expect(prompt).toContain("whenNot");
+    expect(prompt).toContain("a11yRules");
+    expect(prompt).toContain("scenarioTags");
+  });
+
+  it("buildEnrichmentUserPrompt includes component metadata", () => {
+    const prompt = buildEnrichmentUserPrompt("Button", {
+      component: { name: "Button", sourcePath: "/button.tsx", relativePath: "button.tsx" },
+      meta: makeMeta({
+        name: "Button",
+        description: "A clickable button",
+        props: {
+          variant: {
+            name: "variant",
+            type: "string",
+            typeKind: "enum",
+            required: false,
+            source: "local",
+            values: ["primary", "secondary"],
+          },
+        },
+      }),
+      storyVariants: [{ name: "Primary", args: { variant: "primary" } }],
+    });
+
+    expect(prompt).toContain("Component: Button");
+    expect(prompt).toContain("A clickable button");
+    expect(prompt).toContain("variant");
+    expect(prompt).toContain("primary | secondary");
+    expect(prompt).toContain("Known variants: Primary");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Enrichment: buildEnrichedUsageBlock
+// ---------------------------------------------------------------------------
+
+describe("buildEnrichedUsageBlock", () => {
+  it("generates usage block with all enrichment fields", () => {
+    const block = buildEnrichedUsageBlock({
+      when: ["Grouped content", "Dashboard cards"],
+      whenNot: ["Simple text"],
+      guidelines: ["Always include header"],
+      a11yRules: [],
+      scenarioTags: [],
+      tags: [],
+    });
+
+    expect(block).toContain("usage: {");
+    expect(block).toContain("when: [");
+    expect(block).toContain("'Grouped content'");
+    expect(block).toContain("'Dashboard cards'");
+    expect(block).toContain("whenNot: [");
+    expect(block).toContain("'Simple text'");
+    expect(block).toContain("guidelines: [");
+    expect(block).toContain("'Always include header'");
+  });
+
+  it("omits guidelines block when empty", () => {
+    const block = buildEnrichedUsageBlock({
+      when: ["Use for actions"],
+      whenNot: [],
+      guidelines: [],
+      a11yRules: [],
+      scenarioTags: [],
+      tags: [],
+    });
+
+    expect(block).toContain("when: [");
+    expect(block).not.toContain("guidelines:");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Integration: scanGenerate with --enrich (mocked AI)
+// ---------------------------------------------------------------------------
+
+describe("scanGenerate with enrichment", () => {
+  let tmpDir: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "scan-enrich-test-"));
+
+    const compDir = join(tmpDir, "components", "Badge");
+    await mkdir(compDir, { recursive: true });
+
+    await writeFile(
+      join(compDir, "Badge.tsx"),
+      `import React from 'react';
+
+/** A badge for showing counts or labels. */
+export interface BadgeProps {
+  /** Badge content */
+  children: React.ReactNode;
+  /** Visual variant */
+  variant?: 'default' | 'success' | 'warning' | 'error';
+}
+
+export function Badge({ children, variant = 'default' }: BadgeProps) {
+  return <span>{children}</span>;
+}
+`,
+      "utf-8"
+    );
+  });
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("generates enriched fragment with mocked AI", async () => {
+    // Mock the ai-client module
+    vi.doMock("../../ai-client.js", () => ({
+      detectProvider: () => "anthropic",
+      getApiKey: () => "sk-ant-test-key",
+      createAIClient: async () => ({}),
+      generateCompletion: async () => ({
+        text: JSON.stringify({
+          when: ["Showing status counts", "Labeling items"],
+          whenNot: ["Long text content — use a Tag instead"],
+          guidelines: ["Keep text short (1-3 words)"],
+          a11yRules: ["Use aria-label for icon-only badges"],
+          scenarioTags: ["feedback.indicator.badge"],
+          tags: ["badge", "count", "label"],
+        }),
+        inputTokens: 200,
+        outputTokens: 100,
+      }),
+      calculateCost: () => 0.001,
+      ENRICHMENT_MODELS: { anthropic: "claude-haiku-4-5-20251001", openai: "gpt-4o-mini", none: "" },
+    }));
+
+    // Re-import to pick up the mock
+    const { scanGenerate: scanGenerateMocked } = await import("../scan-generate.js");
+
+    const result = await scanGenerateMocked({
+      scanPath: join(tmpDir, "components"),
+      force: true,
+      enrich: true,
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.generated.length).toBe(1);
+    expect(result.generated[0].enriched).toBe(true);
+
+    const content = await rf(
+      join(tmpDir, "components", "Badge", "Badge.fragment.tsx"),
+      "utf-8"
+    );
+
+    // Enriched usage fields should be present (not TODO markers)
+    expect(content).toContain("'Showing status counts'");
+    expect(content).toContain("'Labeling items'");
+    expect(content).toContain("'Long text content — use a Tag instead'");
+    expect(content).toContain("guidelines:");
+    expect(content).toContain("'Keep text short (1-3 words)'");
+
+    // Meta tags should be present
+    expect(content).toContain("tags:");
+    expect(content).toContain("'badge'");
+
+    // Contract should have enriched a11yRules and scenarioTags
+    expect(content).toContain("a11yRules:");
+    expect(content).toContain("'Use aria-label for icon-only badges'");
+    expect(content).toContain("scenarioTags:");
+    expect(content).toContain("'feedback.indicator.badge'");
+
+    // Should NOT have TODO markers for usage.when or usage.whenNot
+    expect(content).not.toContain("// TODO: Describe when to use Badge");
+    expect(content).not.toContain("// TODO: Describe when NOT to use Badge");
+
+    vi.doUnmock("../../ai-client.js");
+  });
+
+  it("skips enrichment in dry-run mode without API calls", async () => {
+    const result = await scanGenerate({
+      scanPath: join(tmpDir, "components"),
+      force: true,
+      enrich: true,
+      dryRun: true,
+    });
+
+    expect(result.success).toBe(true);
+    // Dry run should not enrich (no API key in env for real calls)
+    expect(result.generated[0].enriched).toBeFalsy();
+  });
+
+  it("generates identical output without --enrich (backward compat)", async () => {
+    const result = await scanGenerate({
+      scanPath: join(tmpDir, "components"),
+      force: true,
+    });
+
+    expect(result.success).toBe(true);
+
+    const content = await rf(
+      join(tmpDir, "components", "Badge", "Badge.fragment.tsx"),
+      "utf-8"
+    );
+
+    // Should have TODO markers (no enrichment)
+    expect(content).toContain("// TODO: Describe when to use Badge");
+    expect(content).toContain("// TODO: Describe when NOT to use Badge");
+    expect(result.generated[0].enriched).toBeFalsy();
+    expect(result.enrichmentCost).toBeUndefined();
+  });
 });

package/src/commands/enhance.ts

@@ -34,11 +34,14 @@ import {
   type PropsExtractionResult,
   type RenderedVariant,
 } from '../service/index.js';
+import {
+  type AIProvider,
+  detectProvider as detectProviderShared,
+  getApiKey as getApiKeyShared,
+  createAIClient,
+} from '../ai-client.js';
 
-/**
- * Supported AI providers
- */
-export type AIProvider = 'anthropic' | 'openai' | 'none';
+export type { AIProvider };
 
 /**
  * Options for enhance command
@@ -558,45 +561,18 @@ For each component, provide your response in JSON format:
 }
 
 /**
- * Detect which AI provider to use based on available API keys
+ * Detect which AI provider to use, with enhance-specific contextOnly mapping.
  */
 function detectProvider(options: EnhanceOptions): AIProvider {
   if (options.contextOnly) return 'none';
-  if (options.provider) return options.provider;
-  if (options.apiKey) {
-    // Try to guess from key format
-    if (options.apiKey.startsWith('sk-ant-')) return 'anthropic';
-    if (options.apiKey.startsWith('sk-')) return 'openai';
-  }
-  // Check environment variables
-  if (process.env.ANTHROPIC_API_KEY) return 'anthropic';
-  if (process.env.OPENAI_API_KEY) return 'openai';
-  return 'none';
+  return detectProviderShared({ provider: options.provider, apiKey: options.apiKey });
 }
 
 /**
- * Get API key for the provider
+ * Get API key for the provider.
  */
 function getApiKey(provider: AIProvider, explicitKey?: string): string | undefined {
-  if (explicitKey) return explicitKey;
-  if (provider === 'anthropic') return process.env.ANTHROPIC_API_KEY;
-  if (provider === 'openai') return process.env.OPENAI_API_KEY;
-  return undefined;
-}
-
-/**
- * Create AI client for the provider
- */
-async function createAIClient(provider: AIProvider, apiKey: string): Promise<unknown> {
-  if (provider === 'anthropic') {
-    const Anthropic = (await import('@anthropic-ai/sdk')).default;
-    return new Anthropic({ apiKey });
-  }
-  if (provider === 'openai') {
-    const OpenAI = (await import('openai')).default;
-    return new OpenAI({ apiKey });
-  }
-  throw new Error(`Unknown provider: ${provider}`);
+  return getApiKeyShared(provider, explicitKey);
 }
 
 /**