@fragments-sdk/cli 0.14.3 → 0.15.0

package/src/service/token-normalizer.ts

@@ -0,0 +1,510 @@
+/**
+ * Token Normalizer
+ *
+ * One normalization layer that produces NormalizedToken[] regardless of source:
+ * - CSS custom properties (from token-parser.ts)
+ * - Tailwind theme tokens (from tailwind.config.{js,ts,mjs,cjs})
+ *
+ * Also provides NormalizedTokenLookup implementing the core TokenLookup
+ * interface so the canonical comparison engine can consume any token source.
+ */
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { createJiti } from "jiti";
+import { parseColor } from "@fragments-sdk/core";
+import type {
+  DesignToken,
+  EnhancedStyleDiffItem,
+  NormalizedToken,
+  TokenCategory,
+  TokenLookup,
+  TokenUsageSummary,
+} from "@fragments-sdk/core";
+
+// ─── CSS Custom Property Normalization ───────────────────────────────────────
+
+/**
+ * Convert parsed DesignToken[] (CSS custom properties) to NormalizedToken[].
+ */
+export function normalizeCSSVarTokens(tokens: DesignToken[]): NormalizedToken[] {
+  return tokens.map((token) => ({
+    name: token.name,
+    value: token.resolvedValue,
+    category: token.category,
+    source: "css-var" as const,
+    originalName: token.name,
+    theme: token.theme,
+  }));
+}
+
+// ─── Tailwind Theme Normalization ────────────────────────────────────────────
+
+/**
+ * Tailwind theme key → NormalizedToken category mapping.
+ * Only keys that map to meaningful token categories are listed.
+ */
+const TAILWIND_CATEGORY_MAP: Record<string, TokenCategory> = {
+  colors: "color",
+  backgroundColor: "color",
+  textColor: "color",
+  borderColor: "color",
+  fill: "color",
+  stroke: "color",
+  accentColor: "color",
+  ringColor: "color",
+  outlineColor: "color",
+
+  spacing: "spacing",
+  margin: "spacing",
+  padding: "spacing",
+  gap: "spacing",
+  space: "spacing",
+  inset: "spacing",
+
+  fontSize: "typography",
+  fontFamily: "typography",
+  fontWeight: "typography",
+  lineHeight: "typography",
+  letterSpacing: "typography",
+
+  borderRadius: "radius",
+
+  borderWidth: "border",
+
+  boxShadow: "shadow",
+
+  width: "sizing",
+  height: "sizing",
+  maxWidth: "sizing",
+  maxHeight: "sizing",
+  minWidth: "sizing",
+  minHeight: "sizing",
+  size: "sizing",
+
+  zIndex: "z-index",
+
+  animation: "animation",
+  transitionDuration: "animation",
+  transitionTimingFunction: "animation",
+  transitionDelay: "animation",
+};
+
+/**
+ * Convert a Tailwind theme object into NormalizedToken[].
+ *
+ * Handles:
+ * - Flat values: `{ primary: '#0051c2' }` → `colors.primary`
+ * - Nested values: `{ blue: { 50: '#eff6ff', 500: '#3b82f6' } }` → `colors.blue.50`
+ * - DEFAULT key: `{ blue: { DEFAULT: '#3b82f6' } }` → `colors.blue`
+ * - Array values for fontFamily: `{ sans: ['Inter', 'sans-serif'] }` → joined
+ * - Tuple values for fontSize: `{ sm: ['14px', { lineHeight: '20px' }] }` → first element
+ */
+export function normalizeTailwindTheme(
+  theme: Record<string, unknown>,
+  options: {
+    /** Source identifier (default: "tailwind") */
+    source?: string;
+    /** Theme name (default: "default") */
+    defaultTheme?: string;
+  } = {}
+): NormalizedToken[] {
+  const { source = "tailwind", defaultTheme = "default" } = options;
+  const tokens: NormalizedToken[] = [];
+
+  for (const [themeKey, themeValue] of Object.entries(theme)) {
+    const category = TAILWIND_CATEGORY_MAP[themeKey];
+    if (!category || themeValue == null || typeof themeValue === "function") {
+      continue;
+    }
+
+    if (typeof themeValue !== "object") {
+      continue;
+    }
+
+    flattenThemeValue(
+      themeValue as Record<string, unknown>,
+      themeKey,
+      category,
+      source,
+      defaultTheme,
+      tokens
+    );
+  }
+
+  return tokens;
+}
+
+/**
+ * Recursively flatten a Tailwind theme value object into NormalizedToken entries.
+ */
+function flattenThemeValue(
+  obj: Record<string, unknown>,
+  prefix: string,
+  category: TokenCategory,
+  source: string,
+  theme: string,
+  out: NormalizedToken[]
+): void {
+  for (const [key, value] of Object.entries(obj)) {
+    // Build the path, collapsing DEFAULT to the parent
+    const path = key === "DEFAULT" ? prefix : `${prefix}.${key}`;
+
+    if (value == null || typeof value === "function") {
+      continue;
+    }
+
+    // String value → leaf token
+    if (typeof value === "string") {
+      out.push({
+        name: path,
+        value,
+        category,
+        source,
+        originalName: path,
+        theme,
+      });
+      continue;
+    }
+
+    // Number value → convert to string
+    if (typeof value === "number") {
+      out.push({
+        name: path,
+        value: String(value),
+        category,
+        source,
+        originalName: path,
+        theme,
+      });
+      continue;
+    }
+
+    // Array value → handle fontFamily (join) and fontSize tuples (first element)
+    if (Array.isArray(value)) {
+      const resolved = resolveArrayValue(value, category);
+      if (resolved !== null) {
+        out.push({
+          name: path,
+          value: resolved,
+          category,
+          source,
+          originalName: path,
+          theme,
+        });
+      }
+      continue;
+    }
+
+    // Nested object → recurse
+    if (typeof value === "object") {
+      flattenThemeValue(
+        value as Record<string, unknown>,
+        path,
+        category,
+        source,
+        theme,
+        out
+      );
+    }
+  }
+}
+
+/**
+ * Resolve an array theme value to a string.
+ * - fontFamily: ['Inter', 'sans-serif'] → 'Inter, sans-serif'
+ * - fontSize: ['14px', { lineHeight: '20px' }] → '14px'
+ */
+function resolveArrayValue(
+  value: unknown[],
+  category: TokenCategory
+): string | null {
+  if (value.length === 0) return null;
+
+  // fontFamily arrays: join with comma
+  if (category === "typography" && value.every((v) => typeof v === "string")) {
+    return value.join(", ");
+  }
+
+  // fontSize tuples: [size, config] — take the first element
+  if (typeof value[0] === "string") {
+    return value[0];
+  }
+
+  return null;
+}
+
+/**
+ * Recursively deep-merge two objects. Values in `override` take precedence.
+ * Nested plain objects are merged recursively; arrays and primitives are replaced.
+ */
+function deepMerge(
+  base: Record<string, unknown>,
+  override: Record<string, unknown>,
+): Record<string, unknown> {
+  const result = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const existing = result[key];
+    if (
+      existing &&
+      typeof existing === "object" &&
+      !Array.isArray(existing) &&
+      value &&
+      typeof value === "object" &&
+      !Array.isArray(value)
+    ) {
+      result[key] = deepMerge(
+        existing as Record<string, unknown>,
+        value as Record<string, unknown>,
+      );
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+/**
+ * Load a Tailwind config file and extract normalized tokens from its theme.
+ *
+ * Supports tailwind.config.{js,ts,mjs,cjs} via jiti.
+ * Reads both `theme` and `theme.extend` (extend values are merged).
+ */
+export async function loadTailwindConfig(
+  configPath: string
+): Promise<NormalizedToken[]> {
+  const absolutePath = resolve(configPath);
+
+  if (!existsSync(absolutePath)) {
+    throw new Error(`Tailwind config not found: ${absolutePath}`);
+  }
+
+  const jiti = createJiti(absolutePath);
+  const mod = await jiti.import(absolutePath);
+  const config = (mod as { default?: unknown }).default ?? mod;
+
+  if (!config || typeof config !== "object") {
+    throw new Error(
+      `Tailwind config at ${absolutePath} does not export a valid object`
+    );
+  }
+
+  const configObj = config as Record<string, unknown>;
+  const theme = (configObj.theme ?? {}) as Record<string, unknown>;
+
+  // Merge base theme with extend overrides
+  const extend = (theme.extend ?? {}) as Record<string, unknown>;
+  const merged: Record<string, unknown> = {};
+
+  // Copy base theme keys (except 'extend')
+  for (const [key, value] of Object.entries(theme)) {
+    if (key !== "extend") {
+      merged[key] = value;
+    }
+  }
+
+  // Deep merge extend values on top (preserves nested tokens like colors.blue.50)
+  for (const [key, value] of Object.entries(extend)) {
+    const existing = merged[key];
+    if (
+      existing &&
+      typeof existing === "object" &&
+      !Array.isArray(existing) &&
+      value &&
+      typeof value === "object" &&
+      !Array.isArray(value)
+    ) {
+      merged[key] = deepMerge(
+        existing as Record<string, unknown>,
+        value as Record<string, unknown>,
+      );
+    } else {
+      merged[key] = value;
+    }
+  }
+
+  return normalizeTailwindTheme(merged);
+}
+
+// ─── Tailwind Config Discovery ───────────────────────────────────────────────
+
+const TAILWIND_CONFIG_FILENAMES = [
+  "tailwind.config.ts",
+  "tailwind.config.js",
+  "tailwind.config.mjs",
+  "tailwind.config.cjs",
+];
+
+/**
+ * Find a Tailwind config file in the given directory.
+ */
+export function findTailwindConfig(projectRoot: string): string | null {
+  for (const filename of TAILWIND_CONFIG_FILENAMES) {
+    const fullPath = resolve(projectRoot, filename);
+    if (existsSync(fullPath)) {
+      return fullPath;
+    }
+  }
+  return null;
+}
+
+// ─── NormalizedTokenLookup ───────────────────────────────────────────────────
+
+/**
+ * Implements the core TokenLookup interface over NormalizedToken[].
+ *
+ * This is the single adapter that lets the canonical comparison engine
+ * consume tokens from any source (CSS vars, Tailwind, DTCG, Figma).
+ */
+export class NormalizedTokenLookup implements TokenLookup {
+  private byName = new Map<string, DesignToken>();
+  private byValue = new Map<string, string[]>();
+
+  constructor(tokens: NormalizedToken[]) {
+    for (const token of tokens) {
+      const dt = normalizedToDesignToken(token);
+      this.byName.set(token.name, dt);
+
+      const normalizedValue = normalizeForLookup(token.value);
+      const existing = this.byValue.get(normalizedValue) || [];
+      existing.push(token.name);
+      this.byValue.set(normalizedValue, existing);
+    }
+  }
+
+  findByValue(value: string, theme?: string): string[] {
+    const normalized = normalizeForLookup(value);
+    const names = this.byValue.get(normalized) || [];
+
+    if (theme && names.length > 0) {
+      return names.filter((name) => {
+        const token = this.byName.get(name);
+        return token?.theme === theme || token?.theme === "default";
+      });
+    }
+
+    return names;
+  }
+
+  getToken(name: string): DesignToken | undefined {
+    return this.byName.get(name);
+  }
+
+  calculateUsageSummary(
+    styleDiffs: Array<{
+      property: string;
+      figma: string;
+      rendered: string;
+      match: boolean;
+    }>,
+    theme = "default"
+  ): TokenUsageSummary {
+    const hardcodedProperties: EnhancedStyleDiffItem[] = [];
+    let usingTokens = 0;
+    let hardcoded = 0;
+    let implicitMatches = 0;
+
+    for (const diff of styleDiffs) {
+      const figmaTokens = this.findByValue(diff.figma, theme);
+      const renderedTokens = this.findByValue(diff.rendered, theme);
+
+      const figmaToken = figmaTokens.length > 0 ? figmaTokens[0] : undefined;
+      const renderedToken =
+        renderedTokens.length > 0 ? renderedTokens[0] : undefined;
+      const isHardcoded = !!figmaToken && !renderedToken;
+
+      if (renderedToken) {
+        usingTokens++;
+      } else if (isHardcoded) {
+        hardcoded++;
+        hardcodedProperties.push({
+          ...diff,
+          figmaToken,
+          renderedToken,
+          isHardcoded: true,
+        } as EnhancedStyleDiffItem);
+      } else if (diff.match && figmaToken) {
+        implicitMatches++;
+      }
+    }
+
+    const totalProperties = styleDiffs.length;
+    const compliancePercent =
+      totalProperties > 0
+        ? Math.round(
+            ((usingTokens + implicitMatches) / totalProperties) * 100
+          )
+        : 100;
+
+    return {
+      totalProperties,
+      usingTokens,
+      hardcoded,
+      implicitMatches,
+      compliancePercent,
+      hardcodedProperties,
+    };
+  }
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Create a TokenLookup from NormalizedToken[].
+ * Convenience factory for the most common use case.
+ */
+export function createTokenLookup(tokens: NormalizedToken[]): TokenLookup {
+  return new NormalizedTokenLookup(tokens);
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Convert a NormalizedToken to a DesignToken for TokenLookup compatibility.
+ * Fills source-specific fields with sensible defaults.
+ */
+function normalizedToDesignToken(token: NormalizedToken): DesignToken {
+  return {
+    name: token.name,
+    rawValue: token.value,
+    resolvedValue: token.value,
+    category: token.category,
+    level: 2,
+    referenceChain: [],
+    sourceFile: token.source,
+    theme: token.theme,
+    selector: token.source === "css-var" ? ":root" : "",
+  };
+}
+
+/**
+ * Normalize a value for consistent reverse lookup.
+ * Matches the normalization logic in TokenRegistryManager for parity.
+ */
+function normalizeForLookup(value: string): string {
+  let normalized = value.toLowerCase().trim();
+
+  // Normalize color formats to lowercase hex
+  if (looksLikeColor(normalized)) {
+    const rgb = parseColor(value);
+    if (rgb) {
+      normalized = `#${[rgb.r, rgb.g, rgb.b]
+        .map((x) => x.toString(16).padStart(2, "0"))
+        .join("")}`;
+    }
+  }
+
+  normalized = normalized.replace(/\s+/g, " ");
+  return normalized;
+}
+
+/**
+ * Check if a value looks like a color.
+ */
+function looksLikeColor(value: string): boolean {
+  return (
+    value.startsWith("#") ||
+    value.startsWith("rgb") ||
+    value.startsWith("hsl")
+  );
+}

package/src/shared/index.ts

@@ -6,3 +6,4 @@ export * from './types.js';
 export * from './dev-server-client.js';
 export * from './command-wrapper.js';
 export * from './fragment-loader.js';
+export * from './project-fields.js';

package/src/shared/project-fields.ts

@@ -0,0 +1,46 @@
+/**
+ * Extract specific fields from an object using dot notation paths.
+ * E.g., projectFields(obj, ['meta.name', 'usage.when']) returns { meta: { name: ... }, usage: { when: ... } }
+ *
+ * @param obj - The source object to extract fields from
+ * @param fields - Array of field paths (supports dot notation for nested fields)
+ * @returns A new object containing only the requested fields
+ */
+export function projectFields<T extends Record<string, unknown>>(
+  obj: T,
+  fields: string[],
+): Partial<T> {
+  if (!fields || fields.length === 0) return obj;
+
+  const result: Record<string, unknown> = {};
+
+  for (const field of fields) {
+    const parts = field.split('.');
+    let source: unknown = obj;
+    let target = result;
+
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      const isLast = i === parts.length - 1;
+
+      if (source === null || source === undefined || typeof source !== 'object') {
+        break;
+      }
+
+      const sourceObj = source as Record<string, unknown>;
+      const value = sourceObj[part];
+
+      if (isLast) {
+        target[part] = value;
+      } else {
+        if (!(part in target)) {
+          target[part] = {};
+        }
+        target = target[part] as Record<string, unknown>;
+        source = value;
+      }
+    }
+  }
+
+  return result as Partial<T>;
+}

package/src/viewer/__tests__/viewer-integration.test.ts

@@ -191,12 +191,12 @@ describe("discoverInstalledFragments", () => {
       JSON.stringify({ name: "@acme/ui", fragments: { src: "src" } })
     );
     await writeFile(
-      resolve(acmeDir, "src/components/Button.fragment.tsx"),
-      "export default {};"
+      resolve(acmeDir, "src/components/Button.contract.json"),
+      "{}"
     );
     await writeFile(
-      resolve(acmeDir, "src/components/Card.fragment.tsx"),
-      "export default {};"
+      resolve(acmeDir, "src/components/Card.contract.json"),
+      "{}"
     );
 
     const someLibDir = resolve(tmpDir, "node_modules/some-lib");
@@ -206,8 +206,8 @@ describe("discoverInstalledFragments", () => {
       JSON.stringify({ name: "some-lib" })
     );
     await writeFile(
-      resolve(someLibDir, "src/Foo.fragment.tsx"),
-      "export default {};"
+      resolve(someLibDir, "src/Foo.contract.json"),
+      "{}"
     );
   });
 
@@ -219,8 +219,8 @@ describe("discoverInstalledFragments", () => {
     const results = await discoverInstalledFragments(tmpDir);
     const paths = results.map((r) => r.relativePath).sort();
     expect(paths).toEqual([
-      "@acme/ui/src/components/Button.fragment.tsx",
-      "@acme/ui/src/components/Card.fragment.tsx",
+      "@acme/ui/src/components/Button.contract.json",
+      "@acme/ui/src/components/Card.contract.json",
     ]);
   });