@fragments-sdk/cli 0.9.1 → 0.10.1

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/init.ts

@@ -1,10 +1,11 @@
 /**
  * fragments init - Smart interactive initialization
  *
- * Handles three scenarios:
- * 1. Stories found → Configure and load existing stories
- * 2. Components found (no stories) → Auto-generate documentation
- * 3. Fresh project → Guided setup with example component
+ * Handles four scenarios:
+ * 1. --scan <path> → Scan external component library, generate fragment files
+ * 2. Stories found → Configure and load existing stories
+ * 3. Components found (no stories) → Auto-generate documentation
+ * 4. Fresh project → Guided setup with example component
  */
 
 import { readFile, writeFile, mkdir, access } from "node:fs/promises";
@@ -29,12 +30,14 @@ export interface InitOptions {
   yes?: boolean;
   /** Explicit framework override */
   framework?: string;
+  /** Path to scan for components (enables scan mode) */
+  scan?: string;
 }
 
 export interface InitResult {
   success: boolean;
   configPath?: string;
-  scenario: "stories" | "components" | "fresh";
+  scenario: "stories" | "components" | "fresh" | "scan";
   storiesFound: number;
   componentsFound: number;
   errors: string[];
@@ -396,6 +399,70 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
   const projectRoot = resolve(options.projectRoot || process.cwd());
   const errors: string[] = [];
 
+  // Early return for scan mode — non-interactive
+  if (options.scan) {
+    const scanPath = resolve(projectRoot, options.scan);
+
+    // Verify scan path exists
+    try {
+      await access(scanPath);
+    } catch {
+      console.error(pc.red(`\nScan path not found: ${scanPath}\n`));
+      return {
+        success: false,
+        scenario: "scan",
+        storiesFound: 0,
+        componentsFound: 0,
+        errors: [`Scan path not found: ${scanPath}`],
+      };
+    }
+
+    // Run scan-generate
+    const { scanGenerate } = await import("./scan-generate.js");
+    const scanResult = await scanGenerate({
+      scanPath,
+      force: options.force,
+      verbose: true,
+    });
+
+    // Create config pointing at the scanned path
+    const relScanPath = relative(projectRoot, scanPath);
+    const configPath = join(projectRoot, BRAND.configFile);
+    const configContent = generateConfig({
+      includePaths: [`${relScanPath}/**/*.fragment.tsx`],
+      componentPaths: [`${relScanPath}/**/*.tsx`],
+      framework: "react",
+    });
+
+    try {
+      await writeFile(configPath, configContent, "utf-8");
+      console.log(pc.green(`✓ Created ${BRAND.configFile}`));
+    } catch (e) {
+      errors.push(`Failed to create config: ${e}`);
+    }
+
+    // Next steps
+    if (scanResult.success) {
+      console.log(pc.cyan("Next steps:"));
+      console.log(`  1. Search generated files for ${pc.bold("TODO:")} markers and fill in human knowledge`);
+      console.log(`  2. Run ${pc.bold(`${BRAND.cliCommand} dev`)} to preview your components`);
+      console.log(`  3. Run ${pc.bold(`${BRAND.cliCommand} build`)} to compile fragments.json`);
+      console.log();
+    }
+
+    return {
+      success: scanResult.success && errors.length === 0,
+      configPath: errors.length === 0 ? configPath : undefined,
+      scenario: "scan",
+      storiesFound: 0,
+      componentsFound: scanResult.generated.length,
+      errors: [
+        ...errors,
+        ...scanResult.errors.map((e) => `${e.name}: ${e.error}`),
+      ],
+    };
+  }
+
   console.log(pc.cyan(`\n✨ Welcome to ${BRAND.name}!\n`));
 
   // Step 1: Detect what exists

package/src/commands/perf.ts

@@ -16,7 +16,7 @@ import {
   budgetBar,
   type PerformanceConfig,
   type ComplexityTier,
-} from '../core/performance-presets.js';
+} from '../core/index.js';
 import {
   measureBundleSizes,
   toPerformanceData,