@fragments-sdk/cli 0.2.2

package/src/commands/verify.ts

@@ -0,0 +1,215 @@
+/**
+ * fragments verify - Verify component compliance for CI pipelines
+ *
+ * Uses the /segments/compliance endpoint to get real token compliance data
+ * based on computed styles compared against the design token registry.
+ */
+
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+import { loadConfig } from '../core/node.js';
+import {
+  createDevServerClient,
+  DevServerConnectionError,
+  type ComplianceResult,
+  type ViolationItem,
+  type SegmentInfo,
+} from '../shared/index.js';
+
+/**
+ * Options for verify command
+ */
+export interface VerifyOptions {
+  /** Path to config file */
+  config?: string;
+  /** CI mode - output JSON and exit non-zero on failure */
+  ci?: boolean;
+  /** Minimum compliance percentage (default: 80) */
+  minCompliance?: number;
+  /** Dev server port */
+  port?: number | string;
+}
+
+/**
+ * Result item from verification
+ */
+export interface VerifyResultItem {
+  component: string;
+  compliance: number;
+  passed: boolean;
+  violations: ViolationItem[];
+  totalProperties: number;
+  hardcoded: number;
+  usingTokens: number;
+}
+
+/**
+ * Summary of verification results
+ */
+export interface VerifySummary {
+  passed: boolean;
+  compliance: number;
+  threshold: number;
+  totalComponents: number;
+  passedComponents: number;
+  failedComponents: number;
+  results: VerifyResultItem[];
+  violations: Array<{
+    component: string;
+    property: string;
+    issue: string;
+    severity: 'error' | 'warning';
+    suggestion?: string;
+  }>;
+}
+
+/**
+ * Run the verify command
+ */
+export async function verify(
+  component: string | undefined,
+  options: VerifyOptions = {}
+): Promise<VerifySummary> {
+  const { config: configPath, ci = false, port = 6006 } = options;
+
+  // Load config to get threshold
+  const { config } = await loadConfig(configPath);
+  const minCompliance = options.minCompliance ?? config.ci?.minCompliance ?? 80;
+
+  const client = createDevServerClient(port);
+  const results: VerifyResultItem[] = [];
+  let totalCompliance = 0;
+  let componentCount = 0;
+
+  if (!ci) {
+    console.log(pc.cyan(`\n${BRAND.name} Compliance Verification\n`));
+    console.log(pc.dim(`Minimum compliance: ${minCompliance}%\n`));
+  }
+
+  // Check if dev server is reachable
+  const isReachable = await client.ping();
+  if (!isReachable) {
+    throw new DevServerConnectionError(
+      `Cannot connect to dev server at http://localhost:${port}`,
+      `http://localhost:${port}`
+    );
+  }
+
+  // Fetch all segments
+  let segments = await client.getSegments();
+
+  // Filter by component if specified
+  if (component) {
+    segments = segments.filter(
+      s => s.name.toLowerCase() === component.toLowerCase()
+    );
+
+    if (segments.length === 0) {
+      const error = { error: `Component "${component}" not found` };
+      if (ci) {
+        console.log(JSON.stringify(error));
+      } else {
+        console.log(pc.red(error.error));
+      }
+      process.exit(1);
+    }
+  }
+
+  // Check compliance for each segment
+  for (const seg of segments) {
+    try {
+      // Get real compliance from the server
+      const complianceResult = await client.getCompliance({
+        component: seg.name,
+      });
+
+      const passed = complianceResult.compliance >= minCompliance;
+
+      results.push({
+        component: seg.name,
+        compliance: complianceResult.compliance,
+        passed,
+        violations: complianceResult.violations,
+        totalProperties: complianceResult.totalProperties,
+        hardcoded: complianceResult.hardcoded,
+        usingTokens: complianceResult.usingTokens,
+      });
+
+      totalCompliance += complianceResult.compliance;
+      componentCount++;
+
+      if (!ci) {
+        const icon = passed ? pc.green('✓') : pc.red('✗');
+        const complianceStr = passed
+          ? pc.green(`${complianceResult.compliance}%`)
+          : pc.red(`${complianceResult.compliance}%`);
+        console.log(`  ${icon} ${seg.name} ${complianceStr}`);
+
+        // Show violations in interactive mode
+        if (!passed && complianceResult.violations.length > 0) {
+          const violationsToShow = complianceResult.violations.slice(0, 3);
+          for (const v of violationsToShow) {
+            console.log(pc.dim(`     - ${v.property}: ${v.issue}`));
+            if (v.suggestion) {
+              console.log(pc.dim(`       ${pc.cyan('→')} ${v.suggestion}`));
+            }
+          }
+          if (complianceResult.violations.length > 3) {
+            console.log(pc.dim(`     ... and ${complianceResult.violations.length - 3} more`));
+          }
+        }
+      }
+    } catch (error) {
+      // Handle individual component errors
+      results.push({
+        component: seg.name,
+        compliance: 0,
+        passed: false,
+        violations: [{
+          property: 'unknown',
+          issue: error instanceof Error ? error.message : 'Unknown error',
+          severity: 'error',
+        }],
+        totalProperties: 0,
+        hardcoded: 0,
+        usingTokens: 0,
+      });
+
+      if (!ci) {
+        console.log(`  ${pc.red('✗')} ${seg.name} ${pc.red('error')}`);
+      }
+    }
+  }
+
+  const averageCompliance = componentCount > 0 ? totalCompliance / componentCount : 100;
+  const allPassed = results.every(r => r.passed);
+
+  const summary: VerifySummary = {
+    passed: allPassed,
+    compliance: Math.round(averageCompliance * 100) / 100,
+    threshold: minCompliance,
+    totalComponents: componentCount,
+    passedComponents: results.filter(r => r.passed).length,
+    failedComponents: results.filter(r => !r.passed).length,
+    results,
+    violations: results.flatMap(r => r.violations.map(v => ({
+      component: r.component,
+      ...v,
+    }))),
+  };
+
+  if (ci) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log();
+    if (allPassed) {
+      console.log(pc.green(`✓ All ${componentCount} component(s) meet ${minCompliance}% compliance threshold`));
+    } else {
+      const failedCount = results.filter(r => !r.passed).length;
+      console.log(pc.red(`✗ ${failedCount} component(s) below ${minCompliance}% compliance threshold`));
+    }
+    console.log(pc.dim(`  Average compliance: ${summary.compliance}%\n`));
+  }
+
+  return summary;
+}

package/src/core/composition.test.ts

@@ -0,0 +1,262 @@
+import { describe, it, expect } from "vitest";
+import { analyzeComposition } from "./composition.js";
+import type { CompiledSegment } from "./types.js";
+
+function makeSegment(overrides: Partial<CompiledSegment> & { meta: CompiledSegment["meta"] }): CompiledSegment {
+  return {
+    filePath: "src/components/Test.tsx",
+    usage: { when: [], whenNot: [] },
+    props: {},
+    variants: [],
+    ...overrides,
+  };
+}
+
+const baseSegments: Record<string, CompiledSegment> = {
+  Button: makeSegment({
+    meta: { name: "Button", description: "A button", category: "actions", status: "stable" },
+    relations: [
+      { component: "IconButton", relationship: "alternative", note: "Use for icon-only actions" },
+      { component: "ButtonGroup", relationship: "composition", note: "Wrap multiple buttons" },
+    ],
+    usage: {
+      when: ["User needs to trigger an action"],
+      whenNot: ["Use Link for navigation"],
+    },
+  }),
+  IconButton: makeSegment({
+    meta: { name: "IconButton", description: "Icon-only button", category: "actions", status: "stable" },
+    relations: [
+      { component: "Button", relationship: "alternative", note: "Use for labeled actions" },
+    ],
+  }),
+  ButtonGroup: makeSegment({
+    meta: { name: "ButtonGroup", description: "Groups buttons", category: "actions", status: "stable" },
+    relations: [
+      { component: "Button", relationship: "child", note: "Contains buttons" },
+    ],
+  }),
+  TextField: makeSegment({
+    meta: { name: "TextField", description: "Text input", category: "forms", status: "stable" },
+    relations: [
+      { component: "Form", relationship: "parent", note: "Should be inside a Form" },
+      { component: "Label", relationship: "sibling", note: "Pair with a Label" },
+    ],
+    usage: {
+      when: ["User needs to enter text"],
+      whenNot: ["Use TextArea for multiline input"],
+    },
+  }),
+  Form: makeSegment({
+    meta: { name: "Form", description: "Form container", category: "forms", status: "stable" },
+  }),
+  Label: makeSegment({
+    meta: { name: "Label", description: "Form label", category: "forms", status: "stable" },
+  }),
+  Alert: makeSegment({
+    meta: { name: "Alert", description: "Feedback alert", category: "feedback", status: "stable" },
+  }),
+  Toast: makeSegment({
+    meta: { name: "Toast", description: "Toast notification", category: "feedback", status: "experimental" },
+  }),
+  OldButton: makeSegment({
+    meta: { name: "OldButton", description: "Use Button instead", category: "actions", status: "deprecated" },
+  }),
+  Link: makeSegment({
+    meta: { name: "Link", description: "Navigation link", category: "navigation", status: "stable" },
+    usage: {
+      when: ["User needs to navigate"],
+      whenNot: ["Use Button for actions"],
+    },
+  }),
+};
+
+describe("analyzeComposition", () => {
+  describe("name validation", () => {
+    it("should split components into found and unknown", () => {
+      const result = analyzeComposition(baseSegments, ["Button", "NonExistent", "TextField", "AlsoFake"]);
+      expect(result.components).toEqual(["Button", "TextField"]);
+      expect(result.unknown).toEqual(["NonExistent", "AlsoFake"]);
+    });
+
+    it("should handle all valid names", () => {
+      const result = analyzeComposition(baseSegments, ["Button", "TextField"]);
+      expect(result.components).toEqual(["Button", "TextField"]);
+      expect(result.unknown).toEqual([]);
+    });
+
+    it("should handle all unknown names", () => {
+      const result = analyzeComposition(baseSegments, ["Foo", "Bar"]);
+      expect(result.components).toEqual([]);
+      expect(result.unknown).toEqual(["Foo", "Bar"]);
+    });
+
+    it("should handle empty input", () => {
+      const result = analyzeComposition(baseSegments, []);
+      expect(result.components).toEqual([]);
+      expect(result.unknown).toEqual([]);
+      expect(result.warnings).toEqual([]);
+      expect(result.suggestions).toEqual([]);
+      expect(result.guidelines).toEqual([]);
+    });
+  });
+
+  describe("relation checks", () => {
+    it("should warn about missing parent", () => {
+      const result = analyzeComposition(baseSegments, ["TextField"]);
+      const parentWarning = result.warnings.find((w) => w.type === "missing_parent");
+      expect(parentWarning).toBeDefined();
+      expect(parentWarning!.component).toBe("TextField");
+      expect(parentWarning!.relatedComponent).toBe("Form");
+    });
+
+    it("should not warn about parent when parent is selected", () => {
+      const result = analyzeComposition(baseSegments, ["TextField", "Form"]);
+      const parentWarning = result.warnings.find((w) => w.type === "missing_parent");
+      expect(parentWarning).toBeUndefined();
+    });
+
+    it("should suggest missing children", () => {
+      const result = analyzeComposition(baseSegments, ["ButtonGroup"]);
+      const childSuggestion = result.suggestions.find(
+        (s) => s.component === "Button" && s.relationship === "child"
+      );
+      expect(childSuggestion).toBeDefined();
+      expect(childSuggestion!.sourceComponent).toBe("ButtonGroup");
+    });
+
+    it("should warn about missing composition peers", () => {
+      const result = analyzeComposition(baseSegments, ["Button"]);
+      const compWarning = result.warnings.find((w) => w.type === "missing_composition");
+      expect(compWarning).toBeDefined();
+      expect(compWarning!.component).toBe("Button");
+      expect(compWarning!.relatedComponent).toBe("ButtonGroup");
+    });
+
+    it("should not warn when composition peer is selected", () => {
+      const result = analyzeComposition(baseSegments, ["Button", "ButtonGroup"]);
+      const compWarning = result.warnings.find((w) => w.type === "missing_composition");
+      expect(compWarning).toBeUndefined();
+    });
+
+    it("should suggest missing siblings", () => {
+      const result = analyzeComposition(baseSegments, ["TextField", "Form"]);
+      const siblingSuggestion = result.suggestions.find(
+        (s) => s.component === "Label" && s.relationship === "sibling"
+      );
+      expect(siblingSuggestion).toBeDefined();
+      expect(siblingSuggestion!.sourceComponent).toBe("TextField");
+    });
+
+    it("should warn about redundant alternatives", () => {
+      const result = analyzeComposition(baseSegments, ["Button", "IconButton"]);
+      const altWarning = result.warnings.find((w) => w.type === "redundant_alternative");
+      expect(altWarning).toBeDefined();
+      expect(altWarning!.component).toBe("Button");
+      expect(altWarning!.relatedComponent).toBe("IconButton");
+    });
+
+    it("should not warn when only one alternative is selected", () => {
+      const result = analyzeComposition(baseSegments, ["Button"]);
+      const altWarning = result.warnings.find((w) => w.type === "redundant_alternative");
+      expect(altWarning).toBeUndefined();
+    });
+  });
+
+  describe("usage conflict checks", () => {
+    it("should emit guideline when whenNot mentions another selected component", () => {
+      const result = analyzeComposition(baseSegments, ["Button", "Link"]);
+      const conflict = result.guidelines.find(
+        (g) => g.component === "Link" && g.guideline.includes("Button")
+      );
+      expect(conflict).toBeDefined();
+    });
+
+    it("should not emit guideline when no conflict exists", () => {
+      const result = analyzeComposition(baseSegments, ["Button", "Alert"]);
+      expect(result.guidelines).toEqual([]);
+    });
+  });
+
+  describe("status warnings", () => {
+    it("should warn about deprecated components", () => {
+      const result = analyzeComposition(baseSegments, ["OldButton"]);
+      const depWarning = result.warnings.find((w) => w.type === "deprecated");
+      expect(depWarning).toBeDefined();
+      expect(depWarning!.component).toBe("OldButton");
+      expect(depWarning!.message).toContain("deprecated");
+    });
+
+    it("should warn about experimental components", () => {
+      const result = analyzeComposition(baseSegments, ["Toast"]);
+      const expWarning = result.warnings.find((w) => w.type === "experimental");
+      expect(expWarning).toBeDefined();
+      expect(expWarning!.component).toBe("Toast");
+      expect(expWarning!.message).toContain("experimental");
+    });
+
+    it("should not warn about stable components", () => {
+      const result = analyzeComposition(baseSegments, ["Button"]);
+      const statusWarnings = result.warnings.filter(
+        (w) => w.type === "deprecated" || w.type === "experimental"
+      );
+      expect(statusWarnings).toEqual([]);
+    });
+  });
+
+  describe("category gap analysis", () => {
+    it("should suggest feedback component when forms are selected without feedback", () => {
+      const result = analyzeComposition(baseSegments, ["TextField", "Form"]);
+      const gapSuggestion = result.suggestions.find(
+        (s) => s.relationship === "category_gap"
+      );
+      expect(gapSuggestion).toBeDefined();
+      expect(gapSuggestion!.component).toBe("Alert");
+      expect(gapSuggestion!.reason).toContain("feedback");
+    });
+
+    it("should suggest feedback component when actions are selected without feedback", () => {
+      const result = analyzeComposition(baseSegments, ["Button", "ButtonGroup"]);
+      const gapSuggestion = result.suggestions.find(
+        (s) => s.relationship === "category_gap"
+      );
+      expect(gapSuggestion).toBeDefined();
+      expect(gapSuggestion!.component).toBe("Alert");
+    });
+
+    it("should not suggest category gap when feedback is already present", () => {
+      const result = analyzeComposition(baseSegments, ["Button", "ButtonGroup", "Alert"]);
+      const gapSuggestion = result.suggestions.find(
+        (s) => s.relationship === "category_gap"
+      );
+      expect(gapSuggestion).toBeUndefined();
+    });
+
+    it("should prefer stable components over experimental in category gap suggestions", () => {
+      // Alert is stable, Toast is experimental — should pick Alert
+      const result = analyzeComposition(baseSegments, ["TextField", "Form"]);
+      const gapSuggestion = result.suggestions.find(
+        (s) => s.relationship === "category_gap"
+      );
+      expect(gapSuggestion?.component).toBe("Alert");
+    });
+  });
+
+  describe("deduplication", () => {
+    it("should not suggest the same component twice", () => {
+      const result = analyzeComposition(baseSegments, ["ButtonGroup", "Button"]);
+      const buttonSuggestions = result.suggestions.filter(
+        (s) => s.component === "Button"
+      );
+      // Button is already selected so it shouldn't be suggested
+      expect(buttonSuggestions).toEqual([]);
+    });
+  });
+
+  describe("context parameter", () => {
+    it("should accept optional context without error", () => {
+      const result = analyzeComposition(baseSegments, ["Button"], "building a form page");
+      expect(result.components).toEqual(["Button"]);
+    });
+  });
+});