@fragments-sdk/cli 0.14.2 → 0.15.0

package/src/service/__tests__/token-normalizer.test.ts

@@ -0,0 +1,690 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  normalizeCSSVarTokens,
+  normalizeTailwindTheme,
+  loadTailwindConfig,
+  findTailwindConfig,
+  NormalizedTokenLookup,
+  createTokenLookup,
+} from "../token-normalizer.js";
+import type { DesignToken, NormalizedToken } from "@fragments-sdk/core";
+
+// ─── normalizeCSSVarTokens ──────────────────────────────────────────────────
+
+describe("normalizeCSSVarTokens", () => {
+  it("converts DesignToken[] to NormalizedToken[]", () => {
+    const tokens: DesignToken[] = [
+      {
+        name: "--color-primary",
+        rawValue: "var(--color-cobalt-50)",
+        resolvedValue: "#0051c2",
+        category: "color",
+        level: 2,
+        referenceChain: ["--color-cobalt-50"],
+        sourceFile: "src/tokens.css",
+        lineNumber: 5,
+        theme: "default",
+        selector: ":root",
+        description: "Primary brand color",
+      },
+    ];
+
+    const normalized = normalizeCSSVarTokens(tokens);
+
+    expect(normalized).toHaveLength(1);
+    expect(normalized[0]).toEqual({
+      name: "--color-primary",
+      value: "#0051c2",
+      category: "color",
+      source: "css-var",
+      originalName: "--color-primary",
+      theme: "default",
+    });
+  });
+
+  it("preserves category and theme from source tokens", () => {
+    const tokens: DesignToken[] = [
+      {
+        name: "--spacing-md",
+        rawValue: "16px",
+        resolvedValue: "16px",
+        category: "spacing",
+        level: 1,
+        referenceChain: [],
+        sourceFile: "tokens.css",
+        theme: "default",
+        selector: ":root",
+      },
+      {
+        name: "--color-bg",
+        rawValue: "#1a1a1a",
+        resolvedValue: "#1a1a1a",
+        category: "color",
+        level: 1,
+        referenceChain: [],
+        sourceFile: "tokens.css",
+        theme: "dark",
+        selector: "[data-theme='dark']",
+      },
+    ];
+
+    const normalized = normalizeCSSVarTokens(tokens);
+
+    expect(normalized[0].category).toBe("spacing");
+    expect(normalized[0].theme).toBe("default");
+    expect(normalized[1].category).toBe("color");
+    expect(normalized[1].theme).toBe("dark");
+  });
+
+  it("handles empty input", () => {
+    expect(normalizeCSSVarTokens([])).toEqual([]);
+  });
+});
+
+// ─── normalizeTailwindTheme ──────────────────────────────────────────────────
+
+describe("normalizeTailwindTheme", () => {
+  it("extracts flat color tokens", () => {
+    const theme = {
+      colors: {
+        primary: "#0051c2",
+        secondary: "#6b7280",
+      },
+    };
+
+    const tokens = normalizeTailwindTheme(theme);
+
+    expect(tokens).toContainEqual({
+      name: "colors.primary",
+      value: "#0051c2",
+      category: "color",
+      source: "tailwind",
+      originalName: "colors.primary",
+      theme: "default",
+    });
+    expect(tokens).toContainEqual({
+      name: "colors.secondary",
+      value: "#6b7280",
+      category: "color",
+      source: "tailwind",
+      originalName: "colors.secondary",
+      theme: "default",
+    });
+  });
+
+  it("extracts nested color scale tokens", () => {
+    const theme = {
+      colors: {
+        blue: {
+          50: "#eff6ff",
+          500: "#3b82f6",
+          900: "#1e3a5f",
+        },
+      },
+    };
+
+    const tokens = normalizeTailwindTheme(theme);
+
+    expect(tokens).toHaveLength(3);
+    expect(tokens).toContainEqual(
+      expect.objectContaining({ name: "colors.blue.50", value: "#eff6ff" })
+    );
+    expect(tokens).toContainEqual(
+      expect.objectContaining({ name: "colors.blue.500", value: "#3b82f6" })
+    );
+    expect(tokens).toContainEqual(
+      expect.objectContaining({ name: "colors.blue.900", value: "#1e3a5f" })
+    );
+  });
+
+  it("collapses DEFAULT key to parent path", () => {
+    const theme = {
+      colors: {
+        blue: {
+          DEFAULT: "#3b82f6",
+          light: "#93c5fd",
+        },
+      },
+    };
+
+    const tokens = normalizeTailwindTheme(theme);
+
+    expect(tokens).toContainEqual(
+      expect.objectContaining({ name: "colors.blue", value: "#3b82f6" })
+    );
+    expect(tokens).toContainEqual(
+      expect.objectContaining({ name: "colors.blue.light", value: "#93c5fd" })
+    );
+  });
+
+  it("extracts spacing tokens", () => {
+    const theme = {
+      spacing: {
+        "1": "4px",
+        "2": "8px",
+        "4": "16px",
+        "8": "32px",
+      },
+    };
+
+    const tokens = normalizeTailwindTheme(theme);
+
+    expect(tokens).toHaveLength(4);
+    expect(tokens.every((t) => t.category === "spacing")).toBe(true);
+    expect(tokens).toContainEqual(
+      expect.objectContaining({ name: "spacing.4", value: "16px" })
+    );
+  });
+
+  it("extracts typography tokens", () => {
+    const theme = {
+      fontSize: {
+        sm: "14px",
+        base: "16px",
+        lg: "18px",
+      },
+      fontWeight: {
+        normal: "400",
+        bold: "700",
+      },
+    };
+
+    const tokens = normalizeTailwindTheme(theme);
+
+    expect(tokens).toContainEqual(
+      expect.objectContaining({
+        name: "fontSize.base",
+        value: "16px",
+        category: "typography",
+      })
+    );
+    expect(tokens).toContainEqual(
+      expect.objectContaining({
+        name: "fontWeight.bold",
+        value: "700",
+        category: "typography",
+      })
+    );
+  });
+
+  it("extracts borderRadius tokens", () => {
+    const theme = {
+      borderRadius: {
+        sm: "4px",
+        md: "8px",
+        lg: "16px",
+        full: "9999px",
+      },
+    };
+
+    const tokens = normalizeTailwindTheme(theme);
+
+    expect(tokens).toHaveLength(4);
+    expect(tokens.every((t) => t.category === "radius")).toBe(true);
+  });
+
+  it("handles fontFamily arrays by joining", () => {
+    const theme = {
+      fontFamily: {
+        sans: ["Inter", "system-ui", "sans-serif"],
+        mono: ["JetBrains Mono", "monospace"],
+      },
+    };
+
+    const tokens = normalizeTailwindTheme(theme);
+
+    expect(tokens).toContainEqual(
+      expect.objectContaining({
+        name: "fontFamily.sans",
+        value: "Inter, system-ui, sans-serif",
+      })
+    );
+  });
+
+  it("handles fontSize tuples by taking first element", () => {
+    const theme = {
+      fontSize: {
+        sm: ["14px", { lineHeight: "20px" }],
+        base: ["16px", { lineHeight: "24px" }],
+      },
+    };
+
+    const tokens = normalizeTailwindTheme(theme);
+
+    expect(tokens).toContainEqual(
+      expect.objectContaining({ name: "fontSize.sm", value: "14px" })
+    );
+    expect(tokens).toContainEqual(
+      expect.objectContaining({ name: "fontSize.base", value: "16px" })
+    );
+  });
+
+  it("handles numeric values", () => {
+    const theme = {
+      fontWeight: {
+        light: 300,
+        normal: 400,
+        bold: 700,
+      },
+    };
+
+    const tokens = normalizeTailwindTheme(theme);
+
+    expect(tokens).toContainEqual(
+      expect.objectContaining({ name: "fontWeight.normal", value: "400" })
+    );
+  });
+
+  it("skips function values", () => {
+    const theme = {
+      colors: {
+        primary: "#0051c2",
+        dynamic: () => "#ff0000",
+      },
+    };
+
+    const tokens = normalizeTailwindTheme(theme);
+
+    expect(tokens).toHaveLength(1);
+    expect(tokens[0].name).toBe("colors.primary");
+  });
+
+  it("skips unknown theme keys", () => {
+    const theme = {
+      colors: { primary: "#0051c2" },
+      screens: { sm: "640px", md: "768px" },
+      plugins: [],
+    };
+
+    const tokens = normalizeTailwindTheme(theme);
+
+    // Only colors should be extracted, screens and plugins are not mapped
+    expect(tokens).toHaveLength(1);
+  });
+
+  it("respects custom source option", () => {
+    const tokens = normalizeTailwindTheme(
+      { colors: { primary: "#000" } },
+      { source: "tailwind-v4" }
+    );
+
+    expect(tokens[0].source).toBe("tailwind-v4");
+  });
+
+  it("respects custom theme option", () => {
+    const tokens = normalizeTailwindTheme(
+      { colors: { primary: "#000" } },
+      { defaultTheme: "dark" }
+    );
+
+    expect(tokens[0].theme).toBe("dark");
+  });
+});
+
+// ─── loadTailwindConfig ──────────────────────────────────────────────────────
+
+describe("loadTailwindConfig", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(
+      tmpdir(),
+      `tw-config-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    try {
+      await rm(testDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  it("loads a CJS tailwind config", async () => {
+    const config = `
+module.exports = {
+  theme: {
+    colors: {
+      primary: '#0051c2',
+      secondary: '#6b7280',
+    },
+    spacing: {
+      '1': '4px',
+      '2': '8px',
+    },
+  },
+};
+`;
+    const configPath = join(testDir, "tailwind.config.cjs");
+    await writeFile(configPath, config);
+
+    const tokens = await loadTailwindConfig(configPath);
+
+    expect(tokens.length).toBeGreaterThanOrEqual(4);
+    expect(tokens).toContainEqual(
+      expect.objectContaining({
+        name: "colors.primary",
+        value: "#0051c2",
+        source: "tailwind",
+      })
+    );
+    expect(tokens).toContainEqual(
+      expect.objectContaining({
+        name: "spacing.2",
+        value: "8px",
+        category: "spacing",
+      })
+    );
+  });
+
+  it("loads a config with theme.extend", async () => {
+    const config = `
+module.exports = {
+  theme: {
+    colors: {
+      white: '#ffffff',
+    },
+    extend: {
+      colors: {
+        brand: '#ff6600',
+      },
+    },
+  },
+};
+`;
+    const configPath = join(testDir, "tailwind.config.cjs");
+    await writeFile(configPath, config);
+
+    const tokens = await loadTailwindConfig(configPath);
+
+    // Should have both base and extended colors
+    expect(tokens).toContainEqual(
+      expect.objectContaining({ name: "colors.white", value: "#ffffff" })
+    );
+    expect(tokens).toContainEqual(
+      expect.objectContaining({ name: "colors.brand", value: "#ff6600" })
+    );
+  });
+
+  it("throws for missing config", async () => {
+    await expect(
+      loadTailwindConfig(join(testDir, "nonexistent.config.js"))
+    ).rejects.toThrow("Tailwind config not found");
+  });
+});
+
+// ─── findTailwindConfig ──────────────────────────────────────────────────────
+
+describe("findTailwindConfig", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(
+      tmpdir(),
+      `tw-find-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    try {
+      await rm(testDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  it("returns null when no config exists", () => {
+    expect(findTailwindConfig(testDir)).toBeNull();
+  });
+
+  it("finds tailwind.config.ts", async () => {
+    await writeFile(join(testDir, "tailwind.config.ts"), "export default {}");
+
+    const result = findTailwindConfig(testDir);
+    expect(result).toContain("tailwind.config.ts");
+  });
+
+  it("prefers .ts over .js", async () => {
+    await writeFile(join(testDir, "tailwind.config.ts"), "export default {}");
+    await writeFile(join(testDir, "tailwind.config.js"), "module.exports = {}");
+
+    const result = findTailwindConfig(testDir);
+    expect(result).toContain("tailwind.config.ts");
+  });
+});
+
+// ─── NormalizedTokenLookup ───────────────────────────────────────────────────
+
+describe("NormalizedTokenLookup", () => {
+  const sampleTokens: NormalizedToken[] = [
+    {
+      name: "--color-primary",
+      value: "#ff0000",
+      category: "color",
+      source: "css-var",
+      originalName: "--color-primary",
+      theme: "default",
+    },
+    {
+      name: "--color-bg-dark",
+      value: "#1a1a1a",
+      category: "color",
+      source: "css-var",
+      originalName: "--color-bg-dark",
+      theme: "dark",
+    },
+    {
+      name: "--spacing-md",
+      value: "16px",
+      category: "spacing",
+      source: "css-var",
+      originalName: "--spacing-md",
+      theme: "default",
+    },
+    {
+      name: "colors.primary",
+      value: "#ff0000",
+      category: "color",
+      source: "tailwind",
+      originalName: "colors.primary",
+      theme: "default",
+    },
+  ];
+
+  describe("findByValue", () => {
+    it("finds tokens by exact value", () => {
+      const lookup = new NormalizedTokenLookup(sampleTokens);
+      const names = lookup.findByValue("#ff0000");
+
+      expect(names).toContain("--color-primary");
+      expect(names).toContain("colors.primary");
+    });
+
+    it("normalizes hex case for lookup", () => {
+      const lookup = new NormalizedTokenLookup(sampleTokens);
+      const names = lookup.findByValue("#FF0000");
+
+      expect(names).toContain("--color-primary");
+    });
+
+    it("normalizes rgb to hex for lookup", () => {
+      const lookup = new NormalizedTokenLookup(sampleTokens);
+      const names = lookup.findByValue("rgb(255, 0, 0)");
+
+      expect(names).toContain("--color-primary");
+    });
+
+    it("filters by theme", () => {
+      const lookup = new NormalizedTokenLookup(sampleTokens);
+      const defaultNames = lookup.findByValue("#ff0000", "default");
+      const darkNames = lookup.findByValue("#1a1a1a", "dark");
+
+      expect(defaultNames).toContain("--color-primary");
+      expect(darkNames).toContain("--color-bg-dark");
+    });
+
+    it("includes default-theme tokens when filtering by theme", () => {
+      const lookup = new NormalizedTokenLookup(sampleTokens);
+      // When requesting dark theme, default-theme tokens should also appear
+      const names = lookup.findByValue("#ff0000", "dark");
+
+      expect(names).toContain("--color-primary");
+    });
+
+    it("returns empty array for unknown value", () => {
+      const lookup = new NormalizedTokenLookup(sampleTokens);
+      expect(lookup.findByValue("#ffffff")).toEqual([]);
+    });
+  });
+
+  describe("getToken", () => {
+    it("returns a DesignToken for known name", () => {
+      const lookup = new NormalizedTokenLookup(sampleTokens);
+      const token = lookup.getToken("--color-primary");
+
+      expect(token).toBeDefined();
+      expect(token?.name).toBe("--color-primary");
+      expect(token?.resolvedValue).toBe("#ff0000");
+      expect(token?.category).toBe("color");
+    });
+
+    it("returns undefined for unknown name", () => {
+      const lookup = new NormalizedTokenLookup(sampleTokens);
+      expect(lookup.getToken("--nonexistent")).toBeUndefined();
+    });
+  });
+
+  describe("calculateUsageSummary", () => {
+    it("calculates compliance for token-using properties", () => {
+      const lookup = new NormalizedTokenLookup(sampleTokens);
+      const summary = lookup.calculateUsageSummary([
+        {
+          property: "backgroundColor",
+          figma: "#ff0000",
+          rendered: "#ff0000",
+          match: true,
+        },
+      ]);
+
+      expect(summary.totalProperties).toBe(1);
+      expect(summary.compliancePercent).toBeGreaterThan(0);
+    });
+
+    it("detects hardcoded values", () => {
+      const lookup = new NormalizedTokenLookup(sampleTokens);
+      const summary = lookup.calculateUsageSummary([
+        {
+          property: "backgroundColor",
+          figma: "#ff0000",
+          rendered: "#cccccc",
+          match: false,
+        },
+      ]);
+
+      expect(summary.hardcoded).toBe(1);
+      expect(summary.hardcodedProperties).toHaveLength(1);
+    });
+
+    it("handles empty diffs", () => {
+      const lookup = new NormalizedTokenLookup(sampleTokens);
+      const summary = lookup.calculateUsageSummary([]);
+
+      expect(summary.totalProperties).toBe(0);
+      expect(summary.compliancePercent).toBe(100);
+    });
+  });
+});
+
+// ─── createTokenLookup factory ───────────────────────────────────────────────
+
+describe("createTokenLookup", () => {
+  it("creates a working TokenLookup from NormalizedToken[]", () => {
+    const tokens: NormalizedToken[] = [
+      {
+        name: "colors.primary",
+        value: "#0051c2",
+        category: "color",
+        source: "tailwind",
+        originalName: "colors.primary",
+        theme: "default",
+      },
+    ];
+
+    const lookup = createTokenLookup(tokens);
+
+    expect(lookup.findByValue("#0051c2")).toContain("colors.primary");
+    expect(lookup.getToken("colors.primary")).toBeDefined();
+  });
+});
+
+// ─── Cross-source consistency ────────────────────────────────────────────────
+
+describe("cross-source consistency", () => {
+  it("lookup works consistently across CSS var and Tailwind tokens", () => {
+    const cssTokens = normalizeCSSVarTokens([
+      {
+        name: "--color-primary",
+        rawValue: "#3b82f6",
+        resolvedValue: "#3b82f6",
+        category: "color",
+        level: 1,
+        referenceChain: [],
+        sourceFile: "tokens.css",
+        theme: "default",
+        selector: ":root",
+      },
+    ]);
+
+    const twTokens = normalizeTailwindTheme({
+      colors: { primary: "#3b82f6" },
+    });
+
+    // Combine tokens from both sources
+    const lookup = createTokenLookup([...cssTokens, ...twTokens]);
+
+    // Both should be found for the same value
+    const names = lookup.findByValue("#3b82f6");
+    expect(names).toContain("--color-primary");
+    expect(names).toContain("colors.primary");
+  });
+
+  it("produces same NormalizedToken shape from both sources", () => {
+    const cssTokens = normalizeCSSVarTokens([
+      {
+        name: "--spacing-md",
+        rawValue: "16px",
+        resolvedValue: "16px",
+        category: "spacing",
+        level: 1,
+        referenceChain: [],
+        sourceFile: "tokens.css",
+        theme: "default",
+        selector: ":root",
+      },
+    ]);
+
+    const twTokens = normalizeTailwindTheme({
+      spacing: { md: "16px" },
+    });
+
+    // Both should have the required NormalizedToken fields
+    for (const token of [...cssTokens, ...twTokens]) {
+      expect(token).toHaveProperty("name");
+      expect(token).toHaveProperty("value");
+      expect(token).toHaveProperty("category");
+      expect(token).toHaveProperty("source");
+      expect(token).toHaveProperty("originalName");
+      expect(token).toHaveProperty("theme");
+    }
+
+    // Categories should match for equivalent tokens
+    expect(cssTokens[0].category).toBe("spacing");
+    expect(twTokens[0].category).toBe("spacing");
+  });
+});