@fragments-sdk/cli 0.14.3 → 0.15.1

package/src/service/ast-utils.ts

@@ -6,10 +6,11 @@
  * accurate patches for token replacement.
  */
 
-import { parse, type ParserOptions } from "@babel/parser";
+import { parse } from "@babel/parser";
 import traverse, { type NodePath } from "@babel/traverse";
 import generate from "@babel/generator";
 import * as t from "@babel/types";
+import { BABEL_PARSER_OPTIONS } from "./babel-config.js";
 
 /**
  * Style location information
@@ -43,26 +44,6 @@ export interface StyleLocation {
   context?: string;
 }
 
-/**
- * Babel parser options for React/TypeScript files
- */
-const PARSER_OPTIONS: ParserOptions = {
-  sourceType: "module",
-  plugins: [
-    "jsx",
-    "typescript",
-    ["decorators", { decoratorsBeforeExport: true }],
-    "classProperties",
-    "classPrivateProperties",
-    "classPrivateMethods",
-    "exportDefaultFrom",
-    "exportNamespaceFrom",
-    "dynamicImport",
-    "nullishCoalescingOperator",
-    "optionalChaining",
-    "objectRestSpread",
-  ],
-};
 
 /**
  * Extract style locations from a React/TypeScript source file
@@ -81,7 +62,7 @@ export function extractStyleLocations(
 
   let ast: t.File;
   try {
-    ast = parse(sourceCode, PARSER_OPTIONS);
+    ast = parse(sourceCode, BABEL_PARSER_OPTIONS);
   } catch (error) {
     console.error(`Failed to parse ${filePath}:`, error);
     return locations;
@@ -267,7 +248,7 @@ export function applyPatch(
 ): PatchResult {
   let ast: t.File;
   try {
-    ast = parse(sourceCode, PARSER_OPTIONS);
+    ast = parse(sourceCode, BABEL_PARSER_OPTIONS);
   } catch (error) {
     return {
       success: false,

package/src/service/babel-config.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared Babel parser configuration for React/TypeScript files.
+ */
+
+import type { ParserOptions } from "@babel/parser";
+
+export const BABEL_PARSER_OPTIONS: ParserOptions = {
+  sourceType: "module",
+  plugins: [
+    "jsx",
+    "typescript",
+    ["decorators", { decoratorsBeforeExport: true }],
+    "classProperties",
+    "classPrivateProperties",
+    "classPrivateMethods",
+    "exportDefaultFrom",
+    "exportNamespaceFrom",
+    "dynamicImport",
+    "nullishCoalescingOperator",
+    "optionalChaining",
+    "objectRestSpread",
+  ],
+};

package/src/service/enhance/converter.ts

@@ -0,0 +1,61 @@
+/**
+ * Converter — transforms scanner output (ComponentUsage[]) to governance engine input (UISpec)
+ *
+ * Bridge between the codebase scanner (Babel AST analysis) and the govern engine.
+ * Each file's usages become a UISpec with one UINode per component usage.
+ */
+
+import { relative } from 'node:path';
+import type { ComponentUsage } from './types.js';
+import type { UISpec, UINode } from '@fragments-sdk/govern';
+
+/**
+ * Convert a list of component usages from a single file into a UISpec
+ * suitable for the governance engine.
+ *
+ * Each ComponentUsage becomes a UINode:
+ *   - id: `${relativePath}:${line}:${column}` (unique, traceable back to source)
+ *   - type: componentName (e.g. "Button", "Card.Header")
+ *   - props: merged static + dynamic markers + spread markers
+ */
+export function usagesToSpec(
+  usages: ComponentUsage[],
+  filePath: string,
+  rootDir: string,
+): UISpec {
+  const relativePath = relative(rootDir, filePath);
+
+  const nodes: UINode[] = usages.map((usage) => ({
+    id: `${relativePath}:${usage.line}:${usage.column}`,
+    type: usage.componentName,
+    props: mergeProps(usage),
+  }));
+
+  return {
+    nodes,
+    metadata: {
+      agent: 'scan',
+      timestamp: new Date().toISOString(),
+    },
+  };
+}
+
+/**
+ * Merge static props, dynamic prop markers, and spread markers into
+ * a single Record<string, unknown> for the UINode.
+ */
+function mergeProps(usage: ComponentUsage): Record<string, unknown> {
+  const props: Record<string, unknown> = { ...usage.props.static };
+
+  // Mark dynamic props so governance rules can see them
+  for (const name of usage.props.dynamic) {
+    props[name] = '(dynamic)';
+  }
+
+  // Mark spread props
+  for (const name of usage.props.spreads) {
+    props[`...${name}`] = true;
+  }
+
+  return props;
+}

package/src/service/enhance/props-extractor.ts

@@ -586,13 +586,23 @@ function extractPropsFromInlineParams(
     // const ComponentName = (...) => ...
     if (ts.isVariableStatement(node)) {
       for (const decl of node.declarationList.declarations) {
-        if (
-          ts.isIdentifier(decl.name) &&
-          decl.name.text === componentName &&
-          decl.initializer &&
-          (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer))
-        ) {
-          targetFunc = decl.initializer;
+        if (ts.isIdentifier(decl.name) && decl.name.text === componentName && decl.initializer) {
+          if (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer)) {
+            targetFunc = decl.initializer;
+          }
+          // Handle React.forwardRef(...) or forwardRef(...)
+          else if (ts.isCallExpression(decl.initializer)) {
+            const callee = decl.initializer.expression;
+            const isForwardRef =
+              (ts.isPropertyAccessExpression(callee) && callee.name.text === 'forwardRef') ||
+              (ts.isIdentifier(callee) && callee.text === 'forwardRef');
+            if (isForwardRef && decl.initializer.arguments.length > 0) {
+              const firstArg = decl.initializer.arguments[0];
+              if (ts.isArrowFunction(firstArg) || ts.isFunctionExpression(firstArg)) {
+                targetFunc = firstArg;
+              }
+            }
+          }
         }
       }
     }
@@ -777,7 +787,12 @@ function inferComponentName(filePath: string): string {
   if (name === "index") {
     name = basename(dirname(filePath));
   }
-  return name;
+
+  return name
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join("");
 }
 
 /**
@@ -850,6 +865,7 @@ export async function extractPropsForComponent(
       if (existsSync(fullPath)) {
         return extractPropsFromFile(fullPath, {
           propsTypeName: `${componentName}Props`,
+          componentName,
         });
       }
     }
@@ -870,6 +886,7 @@ export async function extractAllComponentProps(
     try {
       const extraction = await extractPropsFromFile(filePath, {
         propsTypeName: `${componentName}Props`,
+        componentName,
       });
       results.set(componentName, extraction);
     } catch (error) {

package/src/service/enhance/scanner.ts

@@ -6,7 +6,8 @@
  * - Component usages in JSX with props
  */
 
-import { parse, type ParserOptions } from "@babel/parser";
+import { parse } from "@babel/parser";
+import { BABEL_PARSER_OPTIONS } from "../babel-config.js";
 import _traverse from "@babel/traverse";
 import * as t from "@babel/types";
 
@@ -19,26 +20,6 @@ import type {
   UsageProps,
 } from "./types.js";
 
-/**
- * Babel parser options for React/TypeScript files
- */
-const PARSER_OPTIONS: ParserOptions = {
-  sourceType: "module",
-  plugins: [
-    "jsx",
-    "typescript",
-    ["decorators", { decoratorsBeforeExport: true }],
-    "classProperties",
-    "classPrivateProperties",
-    "classPrivateMethods",
-    "exportDefaultFrom",
-    "exportNamespaceFrom",
-    "dynamicImport",
-    "nullishCoalescingOperator",
-    "optionalChaining",
-    "objectRestSpread",
-  ],
-};
 
 /**
  * Scan a file for component imports
@@ -56,7 +37,7 @@ export async function scanFileForImports(
 
   try {
     const sourceCode = await readFile(filePath, "utf-8");
-    const ast = parse(sourceCode, PARSER_OPTIONS);
+    const ast = parse(sourceCode, BABEL_PARSER_OPTIONS);
 
     traverse(ast, {
       ImportDeclaration(path) {
@@ -128,7 +109,7 @@ export async function scanFileForUsages(
   try {
     const sourceCode = await readFile(filePath, "utf-8");
     const lines = sourceCode.split("\n");
-    const ast = parse(sourceCode, PARSER_OPTIONS);
+    const ast = parse(sourceCode, BABEL_PARSER_OPTIONS);
 
     traverse(ast, {
       JSXOpeningElement(path) {
@@ -189,7 +170,7 @@ export async function scanFile(
   try {
     const sourceCode = await readFile(filePath, "utf-8");
     const lines = sourceCode.split("\n");
-    const ast = parse(sourceCode, PARSER_OPTIONS);
+    const ast = parse(sourceCode, BABEL_PARSER_OPTIONS);
 
     // Track local names to component names mapping within this file
     const localToComponent = new Map<string, string>();

package/src/service/index.ts

@@ -97,12 +97,20 @@ export { generateHtmlReport } from "./report.js";
 export {
   parseTokenFile,
   parseTokenFiles,
+  parseTailwindV4File,
+  containsTailwindV4Theme,
   hexToRgb,
   rgbToHex,
   parseRgb,
   normalizeColor,
 } from "./token-parser.js";
 
+// Tailwind v4 @theme parser
+export {
+  parseTailwindV4Theme,
+  type ThemeParserResult,
+} from "./tailwind-v4-parser.js";
+
 export {
   TokenRegistryManager,
   getSharedTokenRegistry,

package/src/service/snippet-validation.ts

@@ -494,8 +494,11 @@ function sortAndFilterBatch(
   const getComponentName = (relativePath: string): string => {
     const normalized = relativePath.replace(/\\/g, '/');
     const fileName = normalized.split('/').pop() ?? normalized;
-    if (fileName.endsWith(BRAND.fileExtension)) {
-      return fileName.slice(0, -BRAND.fileExtension.length);
+    // Handle both V2 (.contract.json) and legacy (.fragment.tsx/.fragment.ts)
+    for (const ext of [BRAND.fileExtension, '.fragment.tsx', '.fragment.ts']) {
+      if (fileName.endsWith(ext)) {
+        return fileName.slice(0, -ext.length);
+      }
     }
     return extractComponentName(relativePath);
   };
@@ -572,7 +575,10 @@ export async function validateSnippetPolicy(
   const issues: FileIssue[] = [];
 
   const discovered = await discoverFragmentFiles(config, configDir);
-  const fragmentFiles = discovered.filter((file) => file.relativePath.endsWith(BRAND.fileExtension));
+  // Snippet validation applies to TSX fragment files (not .contract.json which has no render code)
+  const fragmentFiles = discovered.filter((file) =>
+    file.relativePath.endsWith('.fragment.tsx') || file.relativePath.endsWith('.fragment.ts')
+  );
 
   const batchResult = sortAndFilterBatch(fragmentFiles, policy.componentStart, policy.componentLimit);
   if (batchResult.warning) {

package/src/service/tailwind-v4-parser.ts

@@ -0,0 +1,314 @@
+/**
+ * Tailwind v4 @theme Block Parser
+ *
+ * Extracts CSS custom properties (--name: value;) from Tailwind v4 @theme {}
+ * blocks. Tailwind v4 moves token definitions from tailwind.config.js into
+ * CSS @theme blocks, declaring design tokens as standard custom properties.
+ *
+ * Handles:
+ * - Multiple @theme blocks in one file
+ * - @theme inline { ... } variant
+ * - Empty @theme {} blocks
+ * - Comments (// single-line and multi-line)
+ * - Nested blocks inside @theme (tracks brace depth correctly)
+ * - Lines without semicolons (skipped with warning)
+ */
+
+import type {
+  DesignToken,
+  TokenCategory,
+} from "../core/index.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface ThemeParserResult {
+  tokens: DesignToken[];
+  errors: string[];
+  warnings: string[];
+  parseTimeMs: number;
+}
+
+// ─── Category Inference ──────────────────────────────────────────────────────
+
+/**
+ * Category inference patterns — same logic as token-parser.ts CATEGORY_PATTERNS
+ * to keep categorization consistent across all parsers.
+ */
+const CATEGORY_PATTERNS: Array<{
+  pattern: RegExp;
+  category: TokenCategory;
+}> = [
+  { pattern: /color|bg|background|border-color|fill|stroke/i, category: "color" },
+  { pattern: /spacing|margin|padding|gap|space|inset/i, category: "spacing" },
+  { pattern: /font|text|line-height|letter-spacing|typography/i, category: "typography" },
+  { pattern: /radius|rounded|corner/i, category: "radius" },
+  { pattern: /shadow|elevation/i, category: "shadow" },
+  { pattern: /size|width|height|min|max/i, category: "sizing" },
+  { pattern: /border(?!-color)|stroke-width|outline/i, category: "border" },
+  { pattern: /animation|transition|duration|timing|delay/i, category: "animation" },
+  { pattern: /z-index|layer|stack/i, category: "z-index" },
+];
+
+/**
+ * Infer token category from a CSS custom property name.
+ */
+function inferCategory(name: string): TokenCategory {
+  const lowerName = name.toLowerCase();
+
+  for (const { pattern, category } of CATEGORY_PATTERNS) {
+    if (pattern.test(lowerName)) {
+      return category;
+    }
+  }
+
+  return "other";
+}
+
+/**
+ * Infer token level:
+ * - 1 (base) for raw values (hex colors, numbers, named CSS values)
+ * - 2 (semantic) for var() references
+ */
+function inferLevel(rawValue: string): 1 | 2 | 3 {
+  if (/var\(/.test(rawValue)) {
+    return 2;
+  }
+  return 1;
+}
+
+// ─── Comment Stripping ───────────────────────────────────────────────────────
+
+/**
+ * Remove block comments from a CSS string, handling multi-line spans.
+ * Returns the cleaned string.
+ */
+function stripBlockComments(css: string): string {
+  return css.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+// ─── Parser ──────────────────────────────────────────────────────────────────
+
+/** Regex to match a CSS custom property declaration inside a @theme block */
+const CUSTOM_PROPERTY_PATTERN = /^\s*(--[\w-]+)\s*:\s*(.+?)\s*;?\s*$/;
+
+/**
+ * Parse Tailwind v4 @theme blocks from CSS content and extract design tokens.
+ *
+ * @param cssContent - Raw CSS file content (may contain @theme blocks)
+ * @param filePath   - Optional source file path for diagnostics
+ * @returns ThemeParserResult with extracted tokens, errors, and warnings
+ */
+export function parseTailwindV4Theme(
+  cssContent: string,
+  filePath?: string,
+): ThemeParserResult {
+  const startTime = performance.now();
+  const tokens: DesignToken[] = [];
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const source = filePath ?? "unknown";
+
+  // Strip block comments first so they don't interfere with parsing
+  const cleaned = stripBlockComments(cssContent);
+
+  const lines = cleaned.split("\n");
+
+  let insideTheme = false;
+  let themeDepth = 0; // brace depth relative to the @theme block
+  let pendingTheme = false; // saw @theme keyword, waiting for opening brace
+
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i];
+    const lineNumber = i + 1;
+
+    // Strip single-line comments (// ...)
+    const singleCommentIdx = line.indexOf("//");
+    if (singleCommentIdx !== -1) {
+      // Make sure // is not inside a string (simple heuristic: not inside quotes)
+      const beforeComment = line.slice(0, singleCommentIdx);
+      const singleQuotes = (beforeComment.match(/'/g) || []).length;
+      const doubleQuotes = (beforeComment.match(/"/g) || []).length;
+      // If both quote counts are even, the // is not inside a string
+      if (singleQuotes % 2 === 0 && doubleQuotes % 2 === 0) {
+        line = beforeComment;
+      }
+    }
+
+    const trimmed = line.trim();
+
+    // Skip empty lines
+    if (trimmed === "") {
+      continue;
+    }
+
+    // Detect @theme keyword (with optional modifiers like "inline")
+    if (!insideTheme && !pendingTheme) {
+      // Match @theme, @theme inline, @theme { ... }, etc.
+      if (/^@theme\b/.test(trimmed)) {
+        pendingTheme = true;
+        // Check if the opening brace is on the same line
+        const braceIdx = trimmed.indexOf("{");
+        if (braceIdx !== -1) {
+          pendingTheme = false;
+          insideTheme = true;
+          themeDepth = 1;
+
+          // Count any additional braces on this same line
+          const afterBrace = trimmed.slice(braceIdx + 1);
+          for (const ch of afterBrace) {
+            if (ch === "{") themeDepth++;
+            else if (ch === "}") themeDepth--;
+          }
+
+          // If there are declarations on the same line as @theme {
+          // (e.g., @theme { --color-primary: #000; })
+          const inlineContent = afterBrace.trim();
+          if (inlineContent && themeDepth > 0) {
+            processThemeLine(inlineContent, lineNumber, source, tokens, warnings);
+          }
+
+          if (themeDepth <= 0) {
+            insideTheme = false;
+          }
+        }
+        continue;
+      }
+    }
+
+    // If we saw @theme but haven't found the opening brace yet
+    if (pendingTheme) {
+      const braceIdx = trimmed.indexOf("{");
+      if (braceIdx !== -1) {
+        pendingTheme = false;
+        insideTheme = true;
+        themeDepth = 1;
+
+        // Count additional braces on this line
+        const afterBrace = trimmed.slice(braceIdx + 1);
+        for (const ch of afterBrace) {
+          if (ch === "{") themeDepth++;
+          else if (ch === "}") themeDepth--;
+        }
+
+        // Process any inline content after the brace
+        const inlineContent = afterBrace.trim();
+        if (inlineContent && themeDepth > 0) {
+          processThemeLine(inlineContent, lineNumber, source, tokens, warnings);
+        }
+
+        if (themeDepth <= 0) {
+          insideTheme = false;
+        }
+      }
+      // If no brace found, keep waiting (could be multi-line @theme declaration)
+      continue;
+    }
+
+    // Inside a @theme block — track braces and extract declarations
+    if (insideTheme) {
+      // Count braces to track depth
+      for (const ch of trimmed) {
+        if (ch === "{") {
+          themeDepth++;
+        } else if (ch === "}") {
+          themeDepth--;
+          if (themeDepth <= 0) {
+            insideTheme = false;
+            break;
+          }
+        }
+      }
+
+      // Only extract declarations at depth 1 (directly inside @theme)
+      // or if we're still inside the theme block
+      if (insideTheme || themeDepth > 0) {
+        // Remove any closing braces from the line content before matching
+        const contentLine = trimmed.replace(/\}/g, "").trim();
+        if (contentLine) {
+          processThemeLine(contentLine, lineNumber, source, tokens, warnings);
+        }
+      }
+    }
+  }
+
+  // If we ended while still expecting a @theme block, warn
+  if (pendingTheme) {
+    warnings.push(
+      `@theme keyword found but no opening brace — incomplete block in ${source}`,
+    );
+  }
+
+  if (insideTheme) {
+    warnings.push(
+      `Unclosed @theme block — missing closing brace in ${source}`,
+    );
+  }
+
+  return {
+    tokens,
+    errors,
+    warnings,
+    parseTimeMs: performance.now() - startTime,
+  };
+}
+
+/**
+ * Process a single line inside a @theme block, attempting to extract a
+ * CSS custom property declaration.
+ */
+function processThemeLine(
+  line: string,
+  lineNumber: number,
+  source: string,
+  tokens: DesignToken[],
+  warnings: string[],
+): void {
+  const match = line.match(CUSTOM_PROPERTY_PATTERN);
+
+  if (!match) {
+    // If the line looks like it has a custom property but is missing a semicolon
+    const partialMatch = line.match(/^\s*(--[\w-]+)\s*:\s*(.+?)\s*$/);
+    if (partialMatch) {
+      // It matched without semicolon — treat as valid (CSS tolerates missing trailing semicolons)
+      const [, name, rawValue] = partialMatch;
+      tokens.push(buildToken(name, rawValue, lineNumber, source));
+      return;
+    }
+
+    // Lines that contain -- but couldn't be parsed
+    if (/^\s*--/.test(line)) {
+      warnings.push(
+        `Line ${lineNumber}: Could not parse custom property declaration: ${line.trim()}`,
+      );
+    }
+    return;
+  }
+
+  const [, name, rawValue] = match;
+  tokens.push(buildToken(name, rawValue, lineNumber, source));
+}
+
+/**
+ * Build a DesignToken from a parsed custom property declaration.
+ */
+function buildToken(
+  name: string,
+  rawValue: string,
+  lineNumber: number,
+  source: string,
+): DesignToken {
+  const value = rawValue.trim();
+
+  return {
+    name,
+    rawValue: value,
+    resolvedValue: value,
+    category: inferCategory(name),
+    level: inferLevel(value),
+    referenceChain: [],
+    sourceFile: source,
+    lineNumber,
+    theme: "default",
+    selector: "@theme",
+  };
+}