@fragments-sdk/cli 0.9.0 → 0.10.0

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

@@ -0,0 +1,308 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { mkdtemp, writeFile, mkdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  extractComponentJSDocFromSource,
+  detectCompoundComponentsFromSource,
+  calculateFieldConfidence,
+  scanGenerate,
+} from "../scan-generate.js";
+import type { ExtractedProp } from "../../service/enhance/props-extractor.js";
+
+// ---------------------------------------------------------------------------
+// JSDoc Extraction
+// ---------------------------------------------------------------------------
+
+describe("extractComponentJSDocFromSource", () => {
+  it("extracts JSDoc from an exported function declaration", () => {
+    const source = `
+/** A beautiful button component for user interactions. */
+export function Button(props: ButtonProps) {
+  return <button>{props.children}</button>;
+}
+`;
+    const result = extractComponentJSDocFromSource(source, "Button.tsx", "Button");
+    expect(result).toBe(
+      "A beautiful button component for user interactions."
+    );
+  });
+
+  it("extracts JSDoc from an exported const arrow function", () => {
+    const source = `
+/** Card container for grouping related content. */
+export const Card = (props: CardProps) => {
+  return <div>{props.children}</div>;
+};
+`;
+    const result = extractComponentJSDocFromSource(source, "Card.tsx", "Card");
+    expect(result).toBe("Card container for grouping related content.");
+  });
+
+  it("returns null when there is no JSDoc", () => {
+    const source = `
+export function Button(props: ButtonProps) {
+  return <button>{props.children}</button>;
+}
+`;
+    const result = extractComponentJSDocFromSource(source, "Button.tsx", "Button");
+    expect(result).toBeNull();
+  });
+
+  it("stops at JSDoc tags and only returns the description", () => {
+    const source = `
+/**
+ * A toggle switch component.
+ * @param props - The switch props
+ * @example <Switch checked />
+ */
+export function Switch(props: SwitchProps) {
+  return <input type="checkbox" />;
+}
+`;
+    const result = extractComponentJSDocFromSource(source, "Switch.tsx", "Switch");
+    expect(result).toBe("A toggle switch component.");
+  });
+
+  it("extracts JSDoc from a default export function", () => {
+    const source = `
+/** The main App component. */
+export default function App() {
+  return <div />;
+}
+`;
+    const result = extractComponentJSDocFromSource(source, "App.tsx");
+    expect(result).toBe("The main App component.");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Compound Component Detection
+// ---------------------------------------------------------------------------
+
+describe("detectCompoundComponentsFromSource", () => {
+  it("detects Object.assign with shorthand properties", () => {
+    const source = `
+const Root = () => <div />;
+const Header = () => <header />;
+const Body = () => <main />;
+const Footer = () => <footer />;
+
+export const Card = Object.assign(Root, { Header, Body, Footer });
+`;
+    const result = detectCompoundComponentsFromSource(source, "Card.tsx");
+    expect(result).toEqual(["Header", "Body", "Footer"]);
+  });
+
+  it("detects Object.assign with renamed properties", () => {
+    const source = `
+const CardRoot = () => <div />;
+const CardHeader = () => <header />;
+
+export const Card = Object.assign(CardRoot, { Header: CardHeader });
+`;
+    const result = detectCompoundComponentsFromSource(source, "Card.tsx");
+    expect(result).toEqual(["Header"]);
+  });
+
+  it("returns empty array when no compound pattern found", () => {
+    const source = `
+export function Button() {
+  return <button />;
+}
+`;
+    const result = detectCompoundComponentsFromSource(source, "Button.tsx");
+    expect(result).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Confidence Scoring
+// ---------------------------------------------------------------------------
+
+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: [],
+      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
+    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: [],
+      storyVariants: [],
+    });
+    // +15 (JSDoc), 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");
+  });
+
+  it("gives +25 for story variants", () => {
+    const result = calculateFieldConfidence({
+      component: { name: "Foo", sourcePath: "/foo.tsx", relativePath: "foo.tsx" },
+      props: null,
+      jsDoc: null,
+      compoundChildren: [],
+      storyVariants: [{ name: "Primary", args: {} }],
+    });
+    // +25 (stories)
+    expect(result.score).toBe(25);
+  });
+
+  it("gives +5 for compound children", () => {
+    const result = calculateFieldConfidence({
+      component: { name: "Foo", sourcePath: "/foo.tsx", relativePath: "foo.tsx" },
+      props: null,
+      jsDoc: null,
+      compoundChildren: ["Header", "Body"],
+      storyVariants: [],
+    });
+    expect(result.score).toBe(5);
+  });
+
+  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: [],
+      storyVariants: [{ name: "Primary", args: {} }],
+    });
+    expect(result.todoFields).toContain("usage.when");
+    expect(result.todoFields).toContain("usage.whenNot");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Integration: scanGenerate against a temp component
+// ---------------------------------------------------------------------------
+
+describe("scanGenerate integration", () => {
+  let tmpDir: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "scan-gen-test-"));
+
+    // Create a simple component structure
+    const compDir = join(tmpDir, "components", "Button");
+    await mkdir(compDir, { recursive: true });
+
+    await writeFile(
+      join(compDir, "Button.tsx"),
+      `import React from 'react';
+
+/** A primary button for user interactions. */
+export interface ButtonProps {
+  /** Button label */
+  children: React.ReactNode;
+  /** Visual variant */
+  variant?: 'primary' | 'secondary';
+  /** Disabled state */
+  disabled?: boolean;
+  /** Click handler */
+  onClick?: () => void;
+}
+
+export function Button({ children, variant = 'primary', disabled, onClick }: ButtonProps) {
+  return <button disabled={disabled} onClick={onClick}>{children}</button>;
+}
+`,
+      "utf-8"
+    );
+  });
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("generates a fragment file with correct structure", 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("Button");
+    expect(result.generated[0].confidence).toBeGreaterThan(0);
+
+    // Read the generated file and check structure
+    const { readFile: rf } = await import("node:fs/promises");
+    const content = await rf(
+      join(tmpDir, "components", "Button", "Button.fragment.tsx"),
+      "utf-8"
+    );
+
+    // Check import uses @fragments-sdk/core
+    expect(content).toContain(
+      "import { defineFragment } from '@fragments-sdk/core'"
+    );
+
+    // Check confidence header
+    expect(content).toMatch(
+      /\/\/ Auto-generated by fragments init --scan \| Confidence: \d+\/100/
+    );
+
+    // Check TODO markers exist
+    expect(content).toContain("// TODO:");
+
+    // Check component name in meta
+    expect(content).toContain("name: 'Button'");
+
+    // Check JSDoc was picked up in description
+    expect(content).toContain("A primary button for user interactions.");
+
+    // Check category was inferred (Button → Actions)
+    expect(content).toContain("category: 'Actions'");
+
+    // Check props block has content
+    expect(content).toContain("children:");
+    expect(content).toContain("variant:");
+  });
+
+  it("skips existing fragments without --force", async () => {
+    // First run already created the fragment
+    const result = await scanGenerate({
+      scanPath: join(tmpDir, "components"),
+      force: false,
+    });
+
+    expect(result.skipped.length).toBe(1);
+    expect(result.skipped[0].name).toBe("Button");
+    expect(result.skipped[0].reason).toBe("Fragment already exists");
+    expect(result.generated.length).toBe(0);
+  });
+});

package/src/commands/build.ts

@@ -112,8 +112,22 @@ export async function build(options: BuildOptions = {}): Promise<BuildResult> {
     fragmentCount = result.fragmentCount;
     outputPath = result.outputPath;
 
-    console.log(pc.green(`✓ Built ${result.fragmentCount} fragment(s)`));
-    console.log(pc.dim(`  Output: ${result.outputPath}\n`));
+    if (result.fragmentCount === 0 && result.errors.length === 0) {
+      // No compilable fragment files found — auto-fallback to scan
+      console.log(pc.dim('No compilable fragment files found. Falling back to source scan...\n'));
+
+      const scanResult = await scan({
+        config: options.config,
+        output: options.output,
+        verbose: options.verbose,
+      });
+
+      fragmentCount = scanResult.componentCount;
+      outputPath = scanResult.outputPath;
+    } else {
+      console.log(pc.green(`✓ Built ${result.fragmentCount} fragment(s)`));
+      console.log(pc.dim(`  Output: ${result.outputPath}\n`));
+    }
   }
 
   // Build .fragments/ directory if --registry or --registry-only