@fragments-sdk/cli 0.14.3 → 0.15.1

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/service/token-parser.ts

@@ -7,9 +7,11 @@
  * - Reference resolution (var(--other-token))
  * - Theme detection via selectors
  * - Category inference from naming conventions
+ * - Tailwind v4 @theme blocks (via tailwind-v4-parser)
  */
 
 import { readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { resolve, relative } from "node:path";
 import fastGlob from "fast-glob";
 import type {
@@ -19,6 +21,7 @@ import type {
   TokenParseResult,
   TokenParseError,
 } from "../core/index.js";
+import { parseTailwindV4Theme } from "./tailwind-v4-parser.js";
 
 /**
  * Pattern to match CSS custom property declarations
@@ -78,6 +81,16 @@ export async function parseTokenFile(
       ? relative(projectRoot, filePath)
       : filePath;
 
+    // If the file contains @theme blocks, also extract tokens via the v4 parser
+    if (containsTailwindV4Theme(content)) {
+      const v4Result = parseTailwindV4Theme(content, relativePath);
+      tokens.push(...v4Result.tokens);
+      warnings.push(...v4Result.warnings);
+      for (const err of v4Result.errors) {
+        errors.push({ message: err, file: filePath });
+      }
+    }
+
     // Track which tokens we've seen for reference resolution
     const tokensByName = new Map<string, { rawValue: string; line?: number }>();
 
@@ -502,3 +515,46 @@ export function normalizeColor(color: string): string {
 
   return color.toLowerCase();
 }
+
+// ─── Tailwind v4 @theme Parser Integration ──────────────────────────────────
+
+/**
+ * Parse a CSS file containing Tailwind v4 @theme blocks.
+ *
+ * Reads the file synchronously and delegates to parseTailwindV4Theme.
+ * Returns a TokenParseResult compatible with the rest of the token pipeline.
+ */
+export function parseTailwindV4File(filePath: string): TokenParseResult {
+  const startTime = performance.now();
+
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const result = parseTailwindV4Theme(content, filePath);
+
+    return {
+      tokens: result.tokens,
+      errors: result.errors.map((message) => ({ message, file: filePath })),
+      warnings: result.warnings,
+      parseTimeMs: result.parseTimeMs,
+    };
+  } catch (error) {
+    return {
+      tokens: [],
+      errors: [
+        {
+          message: error instanceof Error ? error.message : "Unknown error",
+          file: filePath,
+        },
+      ],
+      warnings: [],
+      parseTimeMs: performance.now() - startTime,
+    };
+  }
+}
+
+/**
+ * Check whether a CSS file contains Tailwind v4 @theme blocks.
+ */
+export function containsTailwindV4Theme(content: string): boolean {
+  return /^@theme\b/m.test(content);
+}

package/src/setup.ts

@@ -1,7 +1,7 @@
 import pc from 'picocolors';
 import { BRAND } from './core/index.js';
 import { loadConfig, discoverFragmentFiles } from './core/node.js';
-import { buildFragments } from './build.js';
+import { buildFragments, getFragmentsJsonStatus } from '@fragments-sdk/compiler';
 import { scan } from './commands/scan.js';
 import {
   detectStorybookConfig,
@@ -31,41 +31,6 @@ interface FragmentInfo {
   hasFigma: boolean;
 }
 
-/**
- * Check if fragments.json exists and is newer than all fragment files.
- */
-async function isFragmentsJsonStale(configDir: string, outFile: string): Promise<{ stale: boolean; missing: boolean }> {
-  const fs = await import('node:fs/promises');
-  const path = await import('node:path');
-  const fg = await import('fast-glob');
-
-  const fragmentsJsonPath = path.join(configDir, outFile);
-
-  try {
-    const fragmentsJsonStat = await fs.stat(fragmentsJsonPath);
-
-    // Find all fragment files
-    const fragmentFiles = await fg.default(`**/*${BRAND.fileExtension}`, {
-      cwd: configDir,
-      ignore: ['**/node_modules/**'],
-      absolute: true,
-    });
-
-    // Check if any fragment file is newer than fragments.json
-    for (const file of fragmentFiles) {
-      const stat = await fs.stat(file);
-      if (stat.mtimeMs > fragmentsJsonStat.mtimeMs) {
-        return { stale: true, missing: false };
-      }
-    }
-
-    return { stale: false, missing: false };
-  } catch {
-    // fragments.json doesn't exist
-    return { stale: false, missing: true };
-  }
-}
-
 /**
  * Load fragment files and check which ones have Figma links.
  */
@@ -200,11 +165,17 @@ export async function runSetup(options: SetupOptions = {}): Promise<SetupResult>
     // Step 2: Build fragments.json if needed (only when fragment files exist)
     if (fragmentFiles.length > 0 && !options.skipBuild) {
       const outFile = config.outFile || BRAND.outFile;
-      const { stale, missing } = await isFragmentsJsonStale(configDir, outFile);
+      const status = await getFragmentsJsonStatus(config, configDir, {
+        output: outFile,
+        configPath: options.configPath,
+      });
 
-      if (missing || stale) {
-        const reason = missing ? 'Building' : 'Rebuilding';
+      if (status.missing || status.stale) {
+        const reason = status.missing ? 'Building' : 'Rebuilding';
         log(pc.dim(`\n${reason} ${BRAND.outFile}...`));
+        if (status.reason) {
+          log(pc.dim(`   Reason: ${status.reason}`));
+        }
 
         try {
           const buildResult = await buildFragments(config, configDir);

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>;
+}