@fragments-sdk/cli 0.4.4 → 0.5.0

package/src/core/token-parser.ts

@@ -0,0 +1,211 @@
+/**
+ * Token Parser — extracts CSS custom property declarations from SCSS/CSS files.
+ *
+ * Parses files for `--prefix-*: value;` declarations and groups them
+ * by SCSS comment sections (e.g., `// Typography`, `// Colors`).
+ * Falls back to naming-convention-based categorization when comments
+ * are absent.
+ */
+
+export interface ParsedToken {
+  /** Full CSS variable name (e.g., "--fui-color-accent") */
+  name: string;
+  /** Category inferred from SCSS comment or naming convention */
+  category: string;
+  /** Description from inline comment, if any */
+  description?: string;
+}
+
+export interface TokenParseOutput {
+  /** Detected prefix (e.g., "--fui-") */
+  prefix: string;
+  /** Tokens grouped by category */
+  categories: Record<string, ParsedToken[]>;
+  /** Total number of tokens found */
+  total: number;
+}
+
+/**
+ * Category inference from naming conventions.
+ * Order matters — first match wins.
+ */
+const NAMING_RULES: Array<{ pattern: RegExp; category: string }> = [
+  { pattern: /--\w+-font-/, category: 'typography' },
+  { pattern: /--\w+-line-height-/, category: 'typography' },
+  { pattern: /--\w+-space-/, category: 'spacing' },
+  { pattern: /--\w+-padding-/, category: 'spacing' },
+  { pattern: /--\w+-radius-/, category: 'radius' },
+  { pattern: /--\w+-color-/, category: 'colors' },
+  { pattern: /--\w+-bg-/, category: 'surfaces' },
+  { pattern: /--\w+-text-/, category: 'text' },
+  { pattern: /--\w+-border/, category: 'borders' },
+  { pattern: /--\w+-shadow-/, category: 'shadows' },
+  { pattern: /--\w+-focus-/, category: 'focus' },
+  { pattern: /--\w+-transition-/, category: 'transitions' },
+  { pattern: /--\w+-scrollbar-/, category: 'scrollbar' },
+  { pattern: /--\w+-z-index/, category: 'z-index' },
+  { pattern: /--\w+-(button|input|touch)-/, category: 'component-sizing' },
+  { pattern: /--\w+-appshell-/, category: 'layout' },
+  { pattern: /--\w+-header-/, category: 'layout' },
+  { pattern: /--\w+-code-/, category: 'code' },
+  { pattern: /--\w+-tooltip-/, category: 'tooltip' },
+  { pattern: /--\w+-hero-/, category: 'marketing' },
+];
+
+/**
+ * Infer category from a CSS variable name using naming conventions.
+ */
+function inferCategory(name: string): string {
+  for (const rule of NAMING_RULES) {
+    if (rule.pattern.test(name)) {
+      return rule.category;
+    }
+  }
+  return 'other';
+}
+
+/**
+ * Detect the most common prefix from a list of CSS variable names.
+ * E.g., given ["--fui-color-accent", "--fui-bg-primary"] → "--fui-"
+ */
+function detectPrefix(names: string[]): string {
+  if (names.length === 0) return '--';
+
+  // Find common prefix after "--"
+  const stripped = names.map((n) => n.slice(2)); // remove "--"
+  let prefix = '';
+  const first = stripped[0];
+
+  for (let i = 0; i < first.length; i++) {
+    const ch = first[i];
+    if (stripped.every((s) => s[i] === ch)) {
+      prefix += ch;
+    } else {
+      break;
+    }
+  }
+
+  // Trim to last hyphen to get clean prefix
+  const lastHyphen = prefix.lastIndexOf('-');
+  if (lastHyphen > 0) {
+    prefix = prefix.slice(0, lastHyphen + 1);
+  }
+
+  return `--${prefix}`;
+}
+
+/**
+ * Normalize a SCSS comment into a category name.
+ * "// Typography" → "typography"
+ * "// Component heights" → "component-sizing"
+ * "// Hero/Marketing gradient" → "marketing"
+ */
+function normalizeCategory(comment: string): string {
+  const text = comment
+    .trim()
+    .replace(/^\/\/\s*/, '')
+    .replace(/^\/\*+\s*/, '')
+    .replace(/\s*\*+\/$/, '')
+    .trim()
+    .toLowerCase();
+
+  // Map common comment headings to clean category names
+  const mappings: Record<string, string> = {
+    'base configuration': 'base',
+    'typography': 'typography',
+    'spacing (micro)': 'spacing',
+    'spacing': 'spacing',
+    'density padding': 'spacing',
+    'border radius': 'radius',
+    'transitions': 'transitions',
+    'colors': 'colors',
+    'surfaces': 'surfaces',
+    'text': 'text',
+    'borders': 'borders',
+    'shadows': 'shadows',
+    'focus': 'focus',
+    'scrollbar': 'scrollbar',
+    'component heights': 'component-sizing',
+    'appshell layout': 'layout',
+    'codeblock': 'code',
+    'tooltip': 'tooltip',
+    'hero/marketing gradient': 'marketing',
+  };
+
+  return mappings[text] ?? text.replace(/\s+/g, '-');
+}
+
+/**
+ * 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
+ */
+export function parseTokenFile(content: string, filePath: string): TokenParseOutput {
+  const lines = content.split('\n');
+  const tokens: ParsedToken[] = [];
+  const seenNames = new Set<string>();
+  let currentCategory = 'other';
+  let hasCommentCategories = false;
+
+  // Regex for CSS custom property declarations
+  // Matches: --name: value; (with optional SCSS interpolation)
+  const varDeclRegex = /^\s*(--[\w-]+)\s*:/;
+  // Regex for section comments (// Category or /* Category */)
+  // Allow any characters after uppercase start (including / for "Hero/Marketing")
+  const sectionCommentRegex = /^\s*\/\/\s+([A-Z].+)$/;
+
+  for (const line of lines) {
+    // Check for section comment
+    const commentMatch = line.match(sectionCommentRegex);
+    if (commentMatch) {
+      const normalized = normalizeCategory(commentMatch[0]);
+      if (normalized) {
+        currentCategory = normalized;
+        hasCommentCategories = true;
+      }
+      continue;
+    }
+
+    // Check for CSS variable declaration
+    const varMatch = line.match(varDeclRegex);
+    if (varMatch) {
+      const name = varMatch[1];
+
+      // Deduplicate: keep only the first occurrence of each variable.
+      // Dark mode and high contrast blocks redefine the same variables
+      // with different values — we only want the canonical list.
+      if (seenNames.has(name)) continue;
+      seenNames.add(name);
+
+      // Extract inline comment if present
+      const inlineComment = line.match(/\/\/\s*(.+)$/);
+      const description = inlineComment ? inlineComment[1].trim() : undefined;
+
+      tokens.push({
+        name,
+        category: hasCommentCategories ? currentCategory : inferCategory(name),
+        description,
+      });
+    }
+  }
+
+  // Group by category
+  const categories: Record<string, ParsedToken[]> = {};
+  for (const token of tokens) {
+    if (!categories[token.category]) {
+      categories[token.category] = [];
+    }
+    categories[token.category].push(token);
+  }
+
+  // Detect prefix
+  const prefix = detectPrefix(tokens.map((t) => t.name));
+
+  return {
+    prefix,
+    categories,
+    total: tokens.length,
+  };
+}

package/src/core/types.ts

@@ -735,10 +735,10 @@ export interface CompiledSegment {
 }
 
 /**
- * Recipe definition — a named composition pattern showing how
+ * Block definition — a named composition pattern showing how
  * design system components wire together for a common use case.
  */
-export interface RecipeDefinition {
+export interface BlockDefinition {
   name: string;
   description: string;
   category: string;
@@ -748,9 +748,14 @@ export interface RecipeDefinition {
 }
 
 /**
- * Compiled recipe data (JSON-serializable for AI consumption)
+ * @deprecated Use BlockDefinition instead
  */
-export interface CompiledRecipe {
+export type RecipeDefinition = BlockDefinition;
+
+/**
+ * Compiled block data (JSON-serializable for AI consumption)
+ */
+export interface CompiledBlock {
   filePath: string;
   name: string;
   description: string;
@@ -760,6 +765,33 @@ export interface CompiledRecipe {
   tags?: string[];
 }
 
+/**
+ * @deprecated Use CompiledBlock instead
+ */
+export type CompiledRecipe = CompiledBlock;
+
+/**
+ * A single token entry in the compiled output
+ */
+export interface CompiledTokenEntry {
+  /** CSS variable name (e.g., "--fui-color-accent") */
+  name: string;
+  /** Description from inline comment */
+  description?: string;
+}
+
+/**
+ * Compiled token data stored in fragments.json
+ */
+export interface CompiledTokenData {
+  /** Detected variable prefix (e.g., "--fui-") */
+  prefix: string;
+  /** Total number of tokens */
+  total: number;
+  /** Tokens grouped by category */
+  categories: Record<string, CompiledTokenEntry[]>;
+}
+
 /**
  * The compiled segments.json structure
  */
@@ -776,6 +808,14 @@ export interface CompiledSegmentsFile {
   /** All compiled segments indexed by component name */
   segments: Record<string, CompiledSegment>;
 
-  /** All compiled recipes indexed by recipe name */
-  recipes?: Record<string, CompiledRecipe>;
+  /** All compiled blocks indexed by block name */
+  blocks?: Record<string, CompiledBlock>;
+
+  /** Design tokens (CSS custom properties) extracted from style files */
+  tokens?: CompiledTokenData;
+
+  /**
+   * @deprecated Use blocks instead
+   */
+  recipes?: Record<string, CompiledBlock>;
 }