@fragments-sdk/cli 0.7.1 → 0.7.3

package/src/core/__tests__/token-resolver.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveTokensWithSass } from '../token-resolver.js';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+// The actual tokens directory in the workspace
+const TOKENS_DIR = resolve(__dirname, '../../../../../libs/ui/src/tokens');
+
+// ---------------------------------------------------------------------------
+// resolveTokensWithSass
+// ---------------------------------------------------------------------------
+
+describe('resolveTokensWithSass', () => {
+  it('resolves spacing tokens to CSS values', async () => {
+    const resolved = await resolveTokensWithSass(
+      [{ name: '--fui-space-4', value: '#{$fui-space-4}' }],
+      TOKENS_DIR,
+    );
+    const value = resolved.get('--fui-space-4');
+    expect(value).toBeDefined();
+    // Should be a CSS length value (rem, px, or calc expression), not an SCSS interpolation
+    expect(value).not.toContain('#{');
+    expect(value).not.toContain('$');
+  });
+
+  it('resolves color tokens to hex or rgb values', async () => {
+    const resolved = await resolveTokensWithSass(
+      [{ name: '--fui-color-accent', value: '#{$fui-color-accent}' }],
+      TOKENS_DIR,
+    );
+    const value = resolved.get('--fui-color-accent');
+    expect(value).toBeDefined();
+    expect(value).not.toContain('#{');
+    expect(value).not.toContain('$');
+  });
+
+  it('resolves multiple tokens in one pass', async () => {
+    const tokens = [
+      { name: '--fui-space-1', value: '#{$fui-space-1}' },
+      { name: '--fui-space-2', value: '#{$fui-space-2}' },
+      { name: '--fui-color-accent', value: '#{$fui-color-accent}' },
+      { name: '--fui-bg-primary', value: '#{$fui-bg-primary}' },
+    ];
+    const resolved = await resolveTokensWithSass(tokens, TOKENS_DIR);
+
+    // All should be resolved
+    for (const token of tokens) {
+      const value = resolved.get(token.name);
+      expect(value, `${token.name} should be resolved`).toBeDefined();
+      expect(value, `${token.name} should not contain #{`).not.toContain('#{');
+      expect(value, `${token.name} should not contain $`).not.toContain('$');
+    }
+  });
+
+  it('returns empty map when sass compilation fails (bad path)', async () => {
+    const resolved = await resolveTokensWithSass(
+      [{ name: '--fui-space-4', value: '#{$fui-space-4}' }],
+      '/nonexistent/path/to/tokens',
+    );
+    expect(resolved.size).toBe(0);
+  });
+
+  it('skips tokens that are already resolved (no unresolved refs)', async () => {
+    const tokens = [
+      { name: '--fui-radius-sm', value: '4px' }, // already resolved
+      { name: '--fui-space-4', value: '#{$fui-space-4}' }, // needs resolution
+    ];
+    const resolved = await resolveTokensWithSass(tokens, TOKENS_DIR);
+
+    // Already-resolved token should not be in the map
+    expect(resolved.has('--fui-radius-sm')).toBe(false);
+    // Unresolved token should be resolved
+    expect(resolved.has('--fui-space-4')).toBe(true);
+  });
+
+  it('returns empty map for empty token list', async () => {
+    const resolved = await resolveTokensWithSass([], TOKENS_DIR);
+    expect(resolved.size).toBe(0);
+  });
+});

package/src/core/loader.ts

@@ -11,9 +11,6 @@ const DEFINE_FRAGMENT_SHIM = `
 export function defineFragment(def) {
   return def;
 }
-export function defineFragment(def) {
-  return def;
-}
 export function defineBlock(def) {
   return def;
 }

package/src/core/parser.ts

@@ -8,7 +8,7 @@
  */
 
 import ts from "typescript";
-import type { FragmentMeta, FragmentUsage, PropDefinition, AIMetadata } from "./types.js";
+import type { FragmentMeta, FragmentUsage, PropDefinition, AIMetadata, FragmentContract } from "./types.js";
 
 /**
  * Parsed fragment metadata (extracted statically from AST)
@@ -48,6 +48,9 @@ export interface ParsedFragmentMetadata {
   /** AI-specific metadata for playground context generation */
   ai?: AIMetadata;
 
+  /** Agent-optimized contract metadata */
+  contract?: FragmentContract;
+
   /** Parse warnings */
   warnings: string[];
 }
@@ -135,6 +138,9 @@ export function parseFragmentFile(
   // Extract AI metadata
   const ai = extractAIMetadata(arg, warnings);
 
+  // Extract contract metadata
+  const contract = extractContractMetadata(arg);
+
   return {
     componentImport,
     componentName,
@@ -144,6 +150,7 @@ export function parseFragmentFile(
     variants,
     relations,
     ai,
+    contract,
     warnings,
   };
 }
@@ -561,6 +568,39 @@ function extractAIMetadata(
   return undefined;
 }
 
+/**
+ * Extract contract metadata from defineFragment call.
+ */
+function extractContractMetadata(
+  arg: ts.ObjectLiteralExpression,
+): FragmentContract | undefined {
+  const contractProp = findProperty(arg, "contract");
+  if (!contractProp || !ts.isObjectLiteralExpression(contractProp)) {
+    return undefined;
+  }
+
+  const contract: FragmentContract = {};
+
+  // Extract propsSummary array
+  const propsSummary = extractStringArray(contractProp, "propsSummary");
+  if (propsSummary.length > 0) {
+    contract.propsSummary = propsSummary;
+  }
+
+  // Extract a11yRules array
+  const a11yRules = extractStringArray(contractProp, "a11yRules");
+  if (a11yRules.length > 0) {
+    contract.a11yRules = a11yRules;
+  }
+
+  // Only return if we have any fields
+  if (Object.keys(contract).length > 0) {
+    return contract;
+  }
+
+  return undefined;
+}
+
 /**
  * Extract a string property from an object literal.
  */

package/src/core/token-parser.ts

@@ -10,6 +10,10 @@
 export interface ParsedToken {
   /** Full CSS variable name (e.g., "--fui-color-accent") */
   name: string;
+  /** Raw value from the declaration (e.g., "#{$fui-space-4}" or "16px") */
+  value?: string;
+  /** Resolved value after SCSS variable substitution (e.g., "16px") */
+  resolvedValue?: string;
   /** Category inferred from SCSS comment or naming convention */
   category: string;
   /** Description from inline comment, if any */
@@ -135,12 +139,90 @@ function normalizeCategory(comment: string): string {
   return mappings[text] ?? text.replace(/\s+/g, '-');
 }
 
+/**
+ * Extract SCSS variable declarations ($name: value;) from file content.
+ * Returns a map of variable name → value.
+ */
+function extractScssVariables(content: string): Map<string, string> {
+  const vars = new Map<string, string>();
+  // Match: $var-name: value; (handles multi-word values, stops at semicolon)
+  const scssVarRegex = /^\s*(\$[\w-]+)\s*:\s*(.+?)\s*(?:!default\s*)?;/gm;
+
+  let match: RegExpExecArray | null;
+  while ((match = scssVarRegex.exec(content)) !== null) {
+    const name = match[1];
+    const value = match[2].replace(/\s*\/\/.*$/, '').trim();
+    // Only store the first occurrence (canonical definition)
+    if (!vars.has(name)) {
+      vars.set(name, value);
+    }
+  }
+
+  return vars;
+}
+
+/**
+ * Resolve SCSS interpolations and variable references in a token value.
+ *
+ * Handles:
+ * - `#{$var}` → looks up $var in scssVars map
+ * - `$var` standalone → looks up in scssVars map
+ * - `var(--other-token, fallback)` → returns fallback if provided
+ * - Recursive resolution up to 5 levels deep
+ */
+function resolveTokenValue(
+  rawValue: string,
+  scssVars: Map<string, string>,
+  cssVarValues: Map<string, string>,
+  depth = 0
+): string {
+  if (depth > 5) return rawValue; // Prevent infinite recursion
+
+  let resolved = rawValue;
+
+  // Resolve #{$var} interpolations
+  resolved = resolved.replace(/#\{(\$[\w-]+)\}/g, (_, varName) => {
+    const val = scssVars.get(varName);
+    return val !== undefined
+      ? resolveTokenValue(val, scssVars, cssVarValues, depth + 1)
+      : `#{${varName}}`;
+  });
+
+  // Resolve standalone $var references (not inside #{})
+  resolved = resolved.replace(/(?<![#\{])(\$[\w-]+)/g, (_, varName) => {
+    const val = scssVars.get(varName);
+    return val !== undefined
+      ? resolveTokenValue(val, scssVars, cssVarValues, depth + 1)
+      : varName;
+  });
+
+  // Resolve var(--token, fallback) — use the referenced token value or fallback
+  resolved = resolved.replace(
+    /var\((--[\w-]+)(?:\s*,\s*(.+?))?\)/g,
+    (original, tokenName, fallback) => {
+      const tokenVal = cssVarValues.get(tokenName);
+      if (tokenVal !== undefined) {
+        return resolveTokenValue(tokenVal, scssVars, cssVarValues, depth + 1);
+      }
+      if (fallback) {
+        return resolveTokenValue(fallback.trim(), scssVars, cssVarValues, depth + 1);
+      }
+      return original;
+    }
+  );
+
+  return resolved;
+}
+
 /**
  * Parse a SCSS or CSS file and extract CSS custom property declarations.
  *
  * Handles two grouping strategies:
  * 1. Comment-based: Uses `// Category` comments above groups of declarations
  * 2. Naming-based: Falls back to inferring category from variable name patterns
+ *
+ * Also resolves SCSS variable interpolations (e.g., `#{$fui-space-4}` → `16px`)
+ * when the SCSS variable definitions are found in the same file content.
  */
 export function parseTokenFile(content: string, filePath: string): TokenParseOutput {
   const lines = content.split('\n');
@@ -149,9 +231,13 @@ export function parseTokenFile(content: string, filePath: string): TokenParseOut
   let currentCategory = 'other';
   let hasCommentCategories = false;
 
+  // First pass: extract SCSS variable declarations for resolution
+  const scssVars = extractScssVariables(content);
+
   // Regex for CSS custom property declarations
   // Matches: --name: value; (with optional SCSS interpolation)
-  const varDeclRegex = /^\s*(--[\w-]+)\s*:/;
+  // Captures both the variable name and its value
+  const varDeclRegex = /^\s*(--[\w-]+)\s*:\s*(.+?)\s*;/;
   // Regex for section comments (// Category or /* Category */)
   // Allow any characters after uppercase start (including / for "Hero/Marketing")
   const sectionCommentRegex = /^\s*\/\/\s+([A-Z].+)$/;
@@ -172,6 +258,7 @@ export function parseTokenFile(content: string, filePath: string): TokenParseOut
     const varMatch = line.match(varDeclRegex);
     if (varMatch) {
       const name = varMatch[1];
+      const rawValue = varMatch[2];
 
       // Deduplicate: keep only the first occurrence of each variable.
       // Dark mode and high contrast blocks redefine the same variables
@@ -183,14 +270,37 @@ export function parseTokenFile(content: string, filePath: string): TokenParseOut
       const inlineComment = line.match(/\/\/\s*(.+)$/);
       const description = inlineComment ? inlineComment[1].trim() : undefined;
 
+      // Clean the value: strip trailing inline comments
+      const cleanValue = rawValue.replace(/\s*\/\/.*$/, '').trim();
+
       tokens.push({
         name,
+        value: cleanValue || undefined,
         category: hasCommentCategories ? currentCategory : inferCategory(name),
         description,
       });
     }
   }
 
+  // Second pass: build a CSS custom property → raw value map for cross-references
+  const cssVarValues = new Map<string, string>();
+  for (const token of tokens) {
+    if (token.value) {
+      cssVarValues.set(token.name, token.value);
+    }
+  }
+
+  // Third pass: resolve SCSS interpolations and var() references
+  for (const token of tokens) {
+    if (token.value) {
+      const resolved = resolveTokenValue(token.value, scssVars, cssVarValues);
+      // Only set resolvedValue if it's different from raw and doesn't still contain unresolved refs
+      if (resolved !== token.value && !resolved.includes('#{') && !resolved.includes('$')) {
+        token.resolvedValue = resolved;
+      }
+    }
+  }
+
   // Group by category
   const categories: Record<string, ParsedToken[]> = {};
   for (const token of tokens) {

package/src/core/token-resolver.ts

@@ -0,0 +1,155 @@
+/**
+ * Token Resolver — resolves unresolved SCSS token values using actual sass compilation.
+ *
+ * The regex-based resolver in token-parser.ts cannot handle SCSS module namespaces,
+ * functions (color.scale, math.div), or map lookups. This module provides a fallback
+ * that compiles the actual SCSS sources to extract computed CSS custom property values.
+ *
+ * Used at build time only — no runtime sass dependency in the MCP server.
+ */
+
+import { resolve, dirname, basename } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+
+/**
+ * Round fractional RGB channel values produced by Sass color math.
+ *
+ * Sass functions like color.scale() and color.adjust() can produce
+ * fractional values like rgb(217.8, 217.8, 217.8). This normalizes
+ * them to clean integers: rgb(218, 218, 218).
+ *
+ * Alpha channels in rgba() are preserved as-is (they're legitimately fractional).
+ */
+function roundRgbValues(value: string): string {
+  return value
+    .replace(
+      /rgb\(([^)]+)\)/g,
+      (_full, inner: string) => {
+        const parts = inner.split(',').map(p => p.trim());
+        const rounded = parts.map(p => {
+          const num = parseFloat(p);
+          return isNaN(num) ? p : String(Math.round(num));
+        });
+        return `rgb(${rounded.join(', ')})`;
+      },
+    )
+    .replace(
+      /rgba\(([^)]+)\)/g,
+      (_full, inner: string) => {
+        const parts = inner.split(',').map(p => p.trim());
+        // Round RGB channels (first 3), preserve alpha as-is
+        const rounded = parts.map((p, i) => {
+          if (i >= 3) return p; // alpha channel — don't round
+          const num = parseFloat(p);
+          return isNaN(num) ? p : String(Math.round(num));
+        });
+        return `rgba(${rounded.join(', ')})`;
+      },
+    );
+}
+
+/**
+ * Resolve unresolved SCSS token values by compiling the project's token SCSS.
+ *
+ * Generates a temporary SCSS string that imports the project's _variables.scss
+ * and includes the fui-css-variables mixin, then compiles it with sass to extract
+ * the actual computed values for all CSS custom properties.
+ *
+ * @param unresolvedTokens - Tokens with values containing #{} or $ that need resolution
+ * @param tokensDir - Absolute path to the directory containing _variables.scss
+ * @returns Map of token name → resolved CSS value (only for tokens that were unresolved)
+ */
+export async function resolveTokensWithSass(
+  unresolvedTokens: Array<{ name: string; value: string }>,
+  tokensDir: string,
+): Promise<Map<string, string>> {
+  const resolvedMap = new Map<string, string>();
+
+  // Filter to only tokens that actually need resolution
+  const needsResolution = unresolvedTokens.filter(
+    t => t.value.includes('#{') || t.value.includes('$'),
+  );
+
+  if (needsResolution.length === 0) {
+    return resolvedMap;
+  }
+
+  try {
+    // Dynamic import so sass is only loaded when needed (build-time only)
+    const sass = await import('sass');
+
+    // Find the _variables.scss file and determine the mixin name
+    const variablesPath = findVariablesFile(tokensDir);
+    if (!variablesPath) {
+      return resolvedMap;
+    }
+
+    // Determine the module name for @use (filename without _ prefix and .scss suffix)
+    const fileName = basename(variablesPath);
+    const moduleName = fileName.replace(/^_/, '').replace(/\.scss$/, '');
+
+    // Generate a SCSS string that imports the variables and includes the mixin
+    const scssSource = `
+@use '${moduleName}' as vars;
+:root { @include vars.fui-css-variables; }
+`;
+
+    // Compile the SCSS with the tokens directory as a load path
+    const compiled = sass.compileString(scssSource, {
+      loadPaths: [tokensDir, dirname(tokensDir)],
+      style: 'expanded',
+      // Suppress sass deprecation warnings during build
+      logger: { warn() {}, debug() {} } as never,
+    });
+
+    // Parse the compiled CSS for --fui-* custom property declarations
+    const cssVarRegex = /(--[\w-]+)\s*:\s*([^;]+)/g;
+    let match: RegExpExecArray | null;
+    const allResolved = new Map<string, string>();
+
+    while ((match = cssVarRegex.exec(compiled.css)) !== null) {
+      allResolved.set(match[1], roundRgbValues(match[2].trim()));
+    }
+
+    // Only return values for the tokens that were originally unresolved
+    for (const token of needsResolution) {
+      const value = allResolved.get(token.name);
+      if (value !== undefined) {
+        resolvedMap.set(token.name, value);
+      }
+    }
+  } catch {
+    // Sass compilation failure is non-fatal — fall back to regex-resolved values
+  }
+
+  return resolvedMap;
+}
+
+/**
+ * Find the _variables.scss file in the tokens directory.
+ */
+function findVariablesFile(tokensDir: string): string | null {
+  const candidates = ['_variables.scss', 'variables.scss'];
+  for (const name of candidates) {
+    const path = resolve(tokensDir, name);
+    if (existsSync(path)) {
+      return path;
+    }
+  }
+
+  // Fallback: look for any SCSS file containing 'css-variables' mixin
+  try {
+    const files = readdirSync(tokensDir).filter(f => f.endsWith('.scss'));
+    for (const file of files) {
+      const path = resolve(tokensDir, file);
+      // We just need to find it exists; the @use import will handle the rest
+      if (file.includes('variables') || file.includes('tokens')) {
+        return path;
+      }
+    }
+  } catch {
+    // Directory read failure
+  }
+
+  return null;
+}

package/src/service/__tests__/patch-generator.test.ts

@@ -72,8 +72,8 @@ describe("patch-generator", () => {
 
       const result = generateTokenPatches("Button", styleDiffs, registry);
 
-      // All values are already tokens
-      expect(result.summary).toContain("compliance");
+      // All values are already tokens — message confirms compliant status
+      expect(result.summary).toContain("token-compliant");
     });
 
     it("identifies unfixable values without matching tokens", () => {

package/src/service/patch-generator.ts

@@ -85,9 +85,16 @@ export function generateTokenPatches(
   const summary = registry.calculateUsageSummary(styleDiffs, theme);
 
   if (summary.hardcodedProperties.length === 0) {
+    // No hardcoded values → either fully compliant or no styles were analyzed
+    let message: string;
+    if (summary.totalProperties === 0) {
+      message = `No style properties analyzed for ${componentName}. Ensure the component renders visible styles.`;
+    } else {
+      message = `${componentName} is fully token-compliant — no hardcoded values found.`;
+    }
     return {
       patches: [],
-      summary: `No hardcoded values found in ${componentName}. Token compliance is at ${summary.compliancePercent}%.`,
+      summary: message,
       fixableCount: 0,
       unfixableCount: 0,
     };

package/src/viewer/render-utils.ts

@@ -8,6 +8,8 @@ export interface RenderRequest {
   component: string;
   /** Props to pass to the component */
   props?: Record<string, unknown>;
+  /** Variant name to render (uses variant's render function) */
+  variant?: string;
   /** Viewport dimensions */
   viewport?: {
     width: number;
@@ -161,6 +163,145 @@ render();
 `;
 }
 
+/**
+ * Generate a render script that renders a specific variant by name.
+ * The variant lookup happens in the browser using the fragment's variants array.
+ */
+export function generateVariantRenderScript(
+  fragmentPath: string,
+  componentName: string,
+  variantName: string
+): string {
+  const variantNameLower = JSON.stringify(variantName.toLowerCase());
+
+  return `
+import React from "react";
+import { createRoot } from "react-dom/client";
+
+async function render() {
+  const root = document.getElementById("render-root");
+
+  try {
+    const fragmentModule = await import("${fragmentPath}");
+    const fragment = fragmentModule.default;
+
+    if (!fragment || !fragment.variants || fragment.variants.length === 0) {
+      throw new Error("Fragment has no variants");
+    }
+
+    const variant = fragment.variants.find(
+      v => v.name.toLowerCase() === ${variantNameLower}
+    );
+
+    if (!variant) {
+      const available = fragment.variants.map(v => v.name).join(", ");
+      throw new Error("Variant '" + ${JSON.stringify(variantName)} + "' not found. Available: " + available);
+    }
+
+    const element = variant.render();
+
+    const reactRoot = createRoot(root);
+    reactRoot.render(element);
+
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        root.classList.add("ready");
+        window.__RENDER_READY__ = true;
+      });
+    });
+  } catch (error) {
+    console.error("Render error:", error);
+    root.innerHTML = \`
+      <div class="render-error">
+        <strong>Render Error</strong>
+        <pre>\${error.message}</pre>
+      </div>
+    \`;
+    root.classList.add("ready");
+    window.__RENDER_READY__ = true;
+    window.__RENDER_ERROR__ = error.message;
+  }
+}
+
+render();
+`;
+}
+
+/**
+ * Generate a render script that also runs axe-core for accessibility auditing.
+ * When variantName is provided, renders that specific variant; otherwise renders
+ * the component with empty props.
+ */
+export function generateA11yRenderScript(
+  fragmentPath: string,
+  componentName: string,
+  variantName?: string
+): string {
+  const variantLookup = variantName
+    ? `
+    const variant = fragment.variants?.find(
+      v => v.name.toLowerCase() === ${JSON.stringify(variantName.toLowerCase())}
+    );
+    if (!variant) {
+      throw new Error("Variant '${variantName}' not found");
+    }
+    element = variant.render();`
+    : `
+    element = React.createElement(fragment.component, {});`;
+
+  return `
+import React from "react";
+import { createRoot } from "react-dom/client";
+import axe from "axe-core";
+
+async function render() {
+  const root = document.getElementById("render-root");
+
+  try {
+    const fragmentModule = await import("${fragmentPath}");
+    const fragment = fragmentModule.default;
+
+    if (!fragment || !fragment.component) {
+      throw new Error("Fragment does not export a component");
+    }
+
+    let element;
+    ${variantLookup}
+
+    const reactRoot = createRoot(root);
+    reactRoot.render(element);
+
+    // Wait for React to flush rendering
+    await new Promise(resolve => {
+      requestAnimationFrame(() => {
+        requestAnimationFrame(resolve);
+      });
+    });
+
+    // Additional settle time for CSS/animations
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    // Run axe-core accessibility audit
+    const results = await axe.run('#render-root', {
+      runOnly: {
+        type: 'tag',
+        values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice'],
+      },
+    });
+
+    window.__AXE_RESULTS__ = results;
+    window.__RENDER_READY__ = true;
+  } catch (error) {
+    console.error("A11y audit error:", error);
+    window.__AXE_ERROR__ = error.message;
+    window.__RENDER_READY__ = true;
+  }
+}
+
+render();
+`;
+}
+
 /**
  * Generate a virtual module ID for a render request.
  * This creates a unique ID that Vite can resolve.