@fragments-sdk/cli 0.14.3 → 0.15.1

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

@@ -1,19 +1,21 @@
 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 { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import {
   extractComponentJSDocFromSource,
   detectCompoundComponentsFromSource,
   calculateFieldConfidence,
   scanGenerate,
+  detectPackageManagerForProject,
+  excludeFragmentsFromTsconfig,
   parseEnrichmentResponse,
   buildEnrichmentSystemPrompt,
   buildEnrichmentUserPrompt,
   buildEnrichedUsageBlock,
   type EnrichmentResult,
 } from "../scan-generate.js";
-import type { ComponentMeta } from "../../core/component-extractor.js";
+import type { ComponentMeta } from '@fragments-sdk/extract';
 
 // ---------------------------------------------------------------------------
 // Helper to build a minimal ComponentMeta for tests
@@ -268,39 +270,28 @@ export function Button({ children, variant = 'primary', disabled, onClick }: But
     // 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"),
+      join(tmpDir, "components", "Button", "Button.contract.json"),
       "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/
-    );
+    const contract = JSON.parse(content);
 
-    // Check TODO markers exist
-    expect(content).toContain("// TODO:");
-
-    // Check component name in meta
-    expect(content).toContain("name: 'Button'");
+    // Check required contract fields
+    expect(contract.$schema).toBe("https://usefragments.com/schemas/contract.v1.json");
+    expect(contract.name).toBe("Button");
 
     // Check JSDoc was picked up in description
-    expect(content).toContain("A primary button for user interactions.");
+    expect(contract.description).toContain("A primary button for user interactions.");
 
     // Check category was inferred (Button → Actions)
-    expect(content).toContain("category: 'Actions'");
+    expect(contract.category).toBe("Actions");
 
-    // Check props block has content
-    expect(content).toContain("children:");
-    expect(content).toContain("variant:");
+    // Check props have content
+    expect(contract.props).toHaveProperty("variant");
 
-    // Check _generated provenance block
-    expect(content).toContain("_generated:");
-    expect(content).toContain("source: 'ai'");
+    // Check provenance block
+    expect(contract.provenance).toBeDefined();
+    expect(contract.provenance.source).toBe("extracted");
   });
 
   it("skips existing fragments without --force", async () => {
@@ -326,17 +317,163 @@ export function Button({ children, variant = 'primary', disabled, onClick }: But
 
     const { readFile: rf } = await import("node:fs/promises");
     const content = await rf(
-      join(tmpDir, "components", "Button", "Button.fragment.tsx"),
+      join(tmpDir, "components", "Button", "Button.contract.json"),
       "utf-8"
     );
 
-    // Check contract block exists
-    expect(content).toContain("contract:");
-    expect(content).toContain("propsSummary:");
+    const contract = JSON.parse(content);
+
+    // Check propsSummary exists and has entries for local props
+    expect(contract.propsSummary).toBeDefined();
+    expect(contract.propsSummary.length).toBeGreaterThan(0);
+    expect(contract.propsSummary.some((s: string) => s.includes("variant"))).toBe(true);
+  });
+});
+
+describe("scanGenerate helpers", () => {
+  let tmpDir: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "scan-gen-helpers-"));
+  });
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("detects pnpm from an ancestor workspace root", async () => {
+    const workspaceRoot = join(tmpDir, "workspace-root");
+    const appDir = join(workspaceRoot, "apps", "demo");
+    await mkdir(appDir, { recursive: true });
+    await writeFile(join(workspaceRoot, "pnpm-workspace.yaml"), "packages:\n  - 'apps/*'\n");
+    await writeFile(join(workspaceRoot, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
+
+    const result = await detectPackageManagerForProject(appDir);
+
+    expect(result.manager).toBe("pnpm");
+    expect(result.lockfileDir).toBe(workspaceRoot);
+  });
+
+  it("adds fragment exclusions to JSONC tsconfig files with aliases", async () => {
+    const projectDir = join(tmpDir, "jsonc-app");
+    const scanDir = join(projectDir, "src", "components");
+    await mkdir(scanDir, { recursive: true });
+    await writeFile(
+      join(projectDir, "package.json"),
+      JSON.stringify({ name: "jsonc-app", private: true }, null, 2)
+    );
+    await writeFile(
+      join(projectDir, "tsconfig.app.json"),
+      `{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"]
+}
+`
+    );
+
+    await excludeFragmentsFromTsconfig(scanDir);
+
+    const updated = JSON.parse(await rf(join(projectDir, "tsconfig.app.json"), "utf-8"));
+    expect(updated.exclude).toContain("**/*.contract.json");
+  });
+
+  it("generates shadcn-style compound fragments without React imports or member syntax", async () => {
+    const projectDir = join(tmpDir, "shadcn-compound");
+    const componentDir = join(projectDir, "components");
+    const cardDir = join(componentDir, "Card");
+    await mkdir(cardDir, { recursive: true });
+
+    await writeFile(
+      join(projectDir, "package.json"),
+      JSON.stringify(
+        {
+          name: "shadcn-compound",
+          private: true,
+          devDependencies: {
+            "@fragments-sdk/core": "workspace:^",
+          },
+        },
+        null,
+        2
+      )
+    );
+    await writeFile(
+      join(projectDir, "tsconfig.app.json"),
+      JSON.stringify(
+        {
+          compilerOptions: {
+            jsx: "react-jsx",
+          },
+          include: ["components"],
+        },
+        null,
+        2
+      )
+    );
+    await writeFile(
+      join(cardDir, "Card.tsx"),
+      `export function Card(props: { children?: React.ReactNode; size?: 'default' | 'sm' }) {
+  return <div>{props.children}</div>;
+}
+
+export function CardHeader(props: { children?: React.ReactNode }) {
+  return <div>{props.children}</div>;
+}
+
+export function CardContent(props: { children?: React.ReactNode }) {
+  return <div>{props.children}</div>;
+}
+
+export function CardFooter(props: { children?: React.ReactNode }) {
+  return <div>{props.children}</div>;
+}
+
+export { Card as default };
+`
+    );
+
+    const result = await scanGenerate({
+      scanPath: componentDir,
+      force: true,
+    });
+
+    expect(result.success).toBe(true);
+
+    const content = await rf(join(cardDir, "Card.contract.json"), "utf-8");
+    const contract = JSON.parse(content);
+    // Contract.json should have the component name and props
+    expect(contract.name).toBe("Card");
+    expect(contract.$schema).toBe("https://usefragments.com/schemas/contract.v1.json");
+    expect(contract.provenance).toBeDefined();
+  });
+
+  it("falls back to inherited wrapper props for shadcn-style Label primitives", async () => {
+    const projectDir = resolve(__dirname, "../__fixtures__/shadcn-label-wrapper");
+    const scanDir = join(projectDir, "src", "components", "ui");
+
+    const result = await scanGenerate({
+      scanPath: scanDir,
+      force: true,
+      tsconfig: join(projectDir, "tsconfig.app.json"),
+    });
+
+    expect(result.success).toBe(true);
 
-    // Check propsSummary has entries for local props
-    expect(content).toContain("variant:");
-    expect(content).toContain("disabled:");
+    const fragment = await rf(join(scanDir, "label.contract.json"), "utf-8");
+    const contract = JSON.parse(fragment);
+    // Should have extracted inherited props like htmlFor and form
+    expect(contract.props).toBeDefined();
+    // Props may be in propsSummary or props object
+    const allKeys = [
+      ...Object.keys(contract.props ?? {}),
+      ...(contract.propsSummary ?? []).map((s: string) => s.split(':')[0]),
+    ];
+    expect(allKeys.some((k: string) => k.includes('htmlFor') || k.includes('form'))).toBe(true);
   });
 });
 
@@ -393,22 +530,16 @@ export function CardFooter({ children }: { children: React.ReactNode }) {
     expect(result.generated[0].name).toBe("Card");
 
     const content = await rf(
-      join(tmpDir, "components", "Card", "Card.fragment.tsx"),
+      join(tmpDir, "components", "Card", "Card.contract.json"),
       "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");
+    const contract = JSON.parse(content);
+    // Should have AI metadata with compound composition
+    expect(contract.ai).toBeDefined();
+    expect(contract.ai.compositionPattern).toBe("compound");
+    expect(contract.ai.subComponents).toBeDefined();
+    expect(contract.ai.subComponents.length).toBeGreaterThan(0);
   });
 });
 
@@ -697,30 +828,17 @@ export function Badge({ children, variant = 'default' }: BadgeProps) {
     expect(result.generated[0].enriched).toBe(true);
 
     const content = await rf(
-      join(tmpDir, "components", "Badge", "Badge.fragment.tsx"),
+      join(tmpDir, "components", "Badge", "Badge.contract.json"),
       "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");
+    const contract = JSON.parse(content);
+    // Enriched usage fields should be present
+    expect(contract.usage.when.length).toBeGreaterThan(0);
+    expect(contract.usage.when).toContain("Showing status counts");
+    expect(contract.usage.whenNot).toContain("Long text content — use a Tag instead");
+    expect(contract.usage.guidelines).toBeDefined();
+    expect(contract.usage.guidelines).toContain("Keep text short (1-3 words)");
 
     vi.doUnmock("../../ai-client.js");
   });
@@ -747,13 +865,14 @@ export function Badge({ children, variant = 'default' }: BadgeProps) {
     expect(result.success).toBe(true);
 
     const content = await rf(
-      join(tmpDir, "components", "Badge", "Badge.fragment.tsx"),
+      join(tmpDir, "components", "Badge", "Badge.contract.json"),
       "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");
+    const contract = JSON.parse(content);
+    // Without enrichment, usage.when/whenNot should be empty arrays
+    expect(contract.usage.when).toEqual([]);
+    expect(contract.usage.whenNot).toEqual([]);
     expect(result.generated[0].enriched).toBeFalsy();
     expect(result.enrichmentCost).toBeUndefined();
   });

package/src/commands/__tests__/verify.test.ts

@@ -0,0 +1,91 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { verify } from "../verify.js";
+
+describe("verify --ci", () => {
+  let tmpDir: string;
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "verify-ci-test-"));
+  });
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("prefers local fragments.json and ignores installed package fragments", async () => {
+    const projectDir = join(tmpDir, "project");
+    await mkdir(projectDir, { recursive: true });
+
+    await writeFile(
+      join(projectDir, "fragments.config.ts"),
+      `export default {
+  include: ['src/**/*.fragment.tsx'],
+  exclude: [],
+  components: ['src/**/*.tsx'],
+  framework: 'react',
+  outFile: 'fragments.json',
+};
+`
+    );
+
+    await writeFile(
+      join(projectDir, "fragments.json"),
+      JSON.stringify(
+        {
+          fragments: {
+            LocalButton: {
+              meta: {
+                name: "LocalButton",
+                description: "Local button",
+                category: "Actions",
+              },
+              usage: {
+                when: ["Actions"],
+                whenNot: [],
+              },
+              props: {
+                variant: { type: "enum", required: false, values: ["primary"] },
+              },
+              variants: [{ name: "Default" }],
+              relations: [],
+              filePath: "src/components/LocalButton.fragment.tsx",
+            },
+            InstalledButton: {
+              meta: {
+                name: "InstalledButton",
+                description: "Installed button",
+                category: "Actions",
+              },
+              usage: {
+                when: ["Actions"],
+                whenNot: [],
+              },
+              props: {
+                variant: { type: "enum", required: false, values: ["primary"] },
+              },
+              variants: [{ name: "Default" }],
+              relations: [],
+              filePath: "node_modules/@fragments-sdk/ui/Button.fragment.tsx",
+            },
+          },
+        },
+        null,
+        2
+      )
+    );
+
+    const summary = await verify(undefined, {
+      ci: true,
+      config: join(projectDir, "fragments.config.ts"),
+      port: 6553,
+      minCompliance: 60,
+    });
+
+    expect(summary.totalComponents).toBe(1);
+    expect(summary.results.map((result) => result.component)).toEqual(["LocalButton"]);
+  });
+});

package/src/commands/build.ts

@@ -5,7 +5,7 @@
 import pc from 'picocolors';
 import { BRAND } from '../core/index.js';
 import { loadConfig } from '../core/node.js';
-import { buildFragments, buildFragmentsDir } from '../build.js';
+import { buildFragments, buildFragmentsDir, getFragmentsJsonStatus } from '@fragments-sdk/compiler';
 import { scan } from './scan.js';
 
 /**
@@ -22,6 +22,10 @@ export interface BuildOptions {
   registryOnly?: boolean;
   /** Build from source code (zero-config, no fragment files needed) */
   fromSource?: boolean;
+  /** Skip work when fragments.json is already fresh */
+  ifNeeded?: boolean;
+  /** Check freshness and exit non-zero if fragments.json needs regeneration */
+  check?: boolean;
   /** Skip usage analysis when building from source */
   skipUsage?: boolean;
   /** Skip Storybook parsing when building from source */
@@ -88,6 +92,55 @@ export async function build(options: BuildOptions = {}): Promise<BuildResult> {
 
   // Build fragments.json unless --registry-only
   if (!options.registryOnly) {
+    const status = await getFragmentsJsonStatus(config, configDir, {
+      output: config.outFile,
+      configPath: options.config,
+    });
+
+    if (options.check) {
+      if (status.missing || status.stale) {
+        const message = status.missing
+          ? `${BRAND.outFile} is missing`
+          : `${BRAND.outFile} is stale${status.reason ? ` (${status.reason})` : ''}`;
+        console.log(pc.red(`✗ ${message}\n`));
+        errors.push({
+          file: status.outputPath,
+          error: message,
+        });
+        return {
+          success: false,
+          outputPath: status.outputPath,
+          errors,
+        };
+      }
+
+      console.log(pc.green(`✓ ${BRAND.outFile} is up to date`));
+      console.log(pc.dim(`  Output: ${status.outputPath}\n`));
+
+      if (!options.registry) {
+        return {
+          success: true,
+          fragmentCount: Object.keys(status.data?.fragments ?? {}).length,
+          outputPath: status.outputPath,
+          errors,
+        };
+      }
+    }
+
+    if (options.ifNeeded && !status.missing && !status.stale) {
+      console.log(pc.green(`✓ ${BRAND.outFile} is up to date`));
+      console.log(pc.dim(`  Output: ${status.outputPath}\n`));
+
+      if (!options.registry) {
+        return {
+          success: true,
+          fragmentCount: Object.keys(status.data?.fragments ?? {}).length,
+          outputPath: status.outputPath,
+          errors,
+        };
+      }
+    }
+
     console.log(pc.dim('Compiling fragments...\n'));
 
     const result = await buildFragments(config, configDir);

package/src/commands/context.ts

@@ -8,7 +8,7 @@ import pc from 'picocolors';
 import { generateContext } from '../core/index.js';
 import type { CompiledFragment, CompiledFragmentsFile } from '../core/index.js';
 import { loadConfig } from '../core/node.js';
-import { buildFragments } from '../build.js';
+import { buildFragments } from '@fragments-sdk/compiler';
 
 /**
  * Options for context command