@usefragments/core 1.0.0

package/src/tokens/scss.ts

@@ -0,0 +1,171 @@
+import { inferTokenGroup, normalizeTokenGroupComment } from "./categories.js";
+import type { ParsedToken, TokenParseOutput } from "./types.js";
+
+export function detectTokenPrefix(names: string[]): string {
+  if (names.length === 0) return "--";
+
+  const stripped = names.map((name) => name.slice(2));
+  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;
+    }
+  }
+
+  const lastHyphen = prefix.lastIndexOf("-");
+  if (lastHyphen > 0) {
+    prefix = prefix.slice(0, lastHyphen + 1);
+  }
+
+  return `--${prefix}`;
+}
+
+export function parseScssVariables(content: string): Map<string, string> {
+  const vars = new Map<string, string>();
+  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();
+    if (!vars.has(name)) {
+      vars.set(name, value);
+    }
+  }
+
+  return vars;
+}
+
+export function resolveTokenValue(
+  rawValue: string,
+  scssVars: Map<string, string>,
+  cssVarValues: Map<string, string>,
+  depth = 0,
+): string {
+  if (depth > 5) return rawValue;
+
+  let resolved = rawValue;
+
+  resolved = resolved.replace(/#\{(\$[\w-]+)\}/g, (_, varName) => {
+    const val = scssVars.get(varName);
+    return val !== undefined
+      ? resolveTokenValue(val, scssVars, cssVarValues, depth + 1)
+      : `#{${varName}}`;
+  });
+
+  resolved = resolved.replace(/(?<![#\{])(\$[\w-]+)/g, (_, varName) => {
+    const val = scssVars.get(varName);
+    return val !== undefined
+      ? resolveTokenValue(val, scssVars, cssVarValues, depth + 1)
+      : varName;
+  });
+
+  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;
+}
+
+export function parseScssTokens(content: string, filePath = "tokens.scss"): TokenParseOutput {
+  const lines = content.split("\n");
+  const tokens: ParsedToken[] = [];
+  const seenNames = new Set<string>();
+  let currentCategory = "other";
+  let hasCommentCategories = false;
+
+  const scssVars = parseScssVariables(content);
+  const varDeclRegex = /^\s*(--[\w-]+)\s*:\s*(.+?)\s*;/;
+  const sectionCommentRegex = /^\s*\/\/\s+([A-Z].+)$/;
+
+  for (const line of lines) {
+    const commentMatch = line.match(sectionCommentRegex);
+    if (commentMatch) {
+      const normalized = normalizeTokenGroupComment(commentMatch[0]);
+      if (normalized) {
+        currentCategory = normalized;
+        hasCommentCategories = true;
+      }
+      continue;
+    }
+
+    const varMatch = line.match(varDeclRegex);
+    if (varMatch) {
+      const name = varMatch[1];
+      const rawValue = varMatch[2];
+
+      if (seenNames.has(name)) continue;
+      seenNames.add(name);
+
+      const inlineComment = line.match(/\/\/\s*(.+)$/);
+      const description = inlineComment ? inlineComment[1].trim() : undefined;
+      const cleanValue = rawValue.replace(/\s*\/\/.*$/, "").trim();
+
+      tokens.push({
+        name,
+        value: cleanValue || undefined,
+        category: hasCommentCategories ? currentCategory : inferTokenGroup(name),
+        description,
+      });
+    }
+  }
+
+  for (const [name, value] of scssVars) {
+    if (seenNames.has(name)) continue;
+    seenNames.add(name);
+    tokens.push({
+      name,
+      value,
+      category: hasCommentCategories ? currentCategory : inferTokenGroup(name),
+    });
+  }
+
+  const cssVarValues = new Map<string, string>();
+  for (const token of tokens) {
+    if (token.value) {
+      cssVarValues.set(token.name, token.value);
+    }
+  }
+
+  for (const token of tokens) {
+    if (token.value) {
+      const resolved = resolveTokenValue(token.value, scssVars, cssVarValues);
+      if (resolved !== token.value && !resolved.includes("#{") && !resolved.includes("$")) {
+        token.resolvedValue = resolved;
+      }
+    }
+  }
+
+  const categories: Record<string, ParsedToken[]> = {};
+  for (const token of tokens) {
+    categories[token.category] ??= [];
+    categories[token.category].push(token);
+  }
+
+  return {
+    prefix: detectTokenPrefix(tokens.map((token) => token.name)),
+    categories,
+    total: tokens.length,
+  };
+}
+
+export function parseCssTokens(content: string, filePath = "tokens.css"): TokenParseOutput {
+  return parseScssTokens(content, filePath);
+}
+
+export const parseTokenFile = parseScssTokens;

package/src/tokens/tailwind-v4.ts

@@ -0,0 +1,187 @@
+import type { DesignToken } from "../token-types.js";
+import { inferTokenCategory } from "./categories.js";
+import type { ThemeParserResult } from "./types.js";
+
+const CUSTOM_PROPERTY_PATTERN = /^\s*(--[\w-]+)\s*:\s*(.+?)\s*;?\s*$/;
+
+export function containsTailwindV4Theme(content: string): boolean {
+  return /^@theme\b/m.test(content);
+}
+
+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";
+
+  const cleaned = stripBlockComments(cssContent);
+  const lines = cleaned.split("\n");
+
+  let insideTheme = false;
+  let themeDepth = 0;
+  let pendingTheme = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i];
+    const lineNumber = i + 1;
+
+    const singleCommentIdx = line.indexOf("//");
+    if (singleCommentIdx !== -1) {
+      const beforeComment = line.slice(0, singleCommentIdx);
+      const singleQuotes = (beforeComment.match(/'/g) || []).length;
+      const doubleQuotes = (beforeComment.match(/"/g) || []).length;
+      if (singleQuotes % 2 === 0 && doubleQuotes % 2 === 0) {
+        line = beforeComment;
+      }
+    }
+
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+
+    if (!insideTheme && !pendingTheme && /^@theme\b/.test(trimmed)) {
+      pendingTheme = true;
+      const braceIdx = trimmed.indexOf("{");
+      if (braceIdx !== -1) {
+        pendingTheme = false;
+        insideTheme = true;
+        themeDepth = 1;
+
+        const afterBrace = trimmed.slice(braceIdx + 1);
+        for (const ch of afterBrace) {
+          if (ch === "{") themeDepth++;
+          else if (ch === "}") themeDepth--;
+        }
+
+        const inlineContent = afterBrace.trim();
+        if (inlineContent && themeDepth > 0) {
+          processThemeLine(inlineContent, lineNumber, source, tokens, warnings);
+        }
+
+        if (themeDepth <= 0) {
+          insideTheme = false;
+        }
+      }
+      continue;
+    }
+
+    if (pendingTheme) {
+      const braceIdx = trimmed.indexOf("{");
+      if (braceIdx !== -1) {
+        pendingTheme = false;
+        insideTheme = true;
+        themeDepth = 1;
+
+        const afterBrace = trimmed.slice(braceIdx + 1);
+        for (const ch of afterBrace) {
+          if (ch === "{") themeDepth++;
+          else if (ch === "}") themeDepth--;
+        }
+
+        const inlineContent = afterBrace.trim();
+        if (inlineContent && themeDepth > 0) {
+          processThemeLine(inlineContent, lineNumber, source, tokens, warnings);
+        }
+
+        if (themeDepth <= 0) {
+          insideTheme = false;
+        }
+      }
+      continue;
+    }
+
+    if (insideTheme) {
+      for (const ch of trimmed) {
+        if (ch === "{") {
+          themeDepth++;
+        } else if (ch === "}") {
+          themeDepth--;
+          if (themeDepth <= 0) {
+            insideTheme = false;
+            break;
+          }
+        }
+      }
+
+      if (insideTheme || themeDepth > 0) {
+        const contentLine = trimmed.replace(/\}/g, "").trim();
+        if (contentLine) {
+          processThemeLine(contentLine, lineNumber, source, tokens, warnings);
+        }
+      }
+    }
+  }
+
+  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,
+  };
+}
+
+function stripBlockComments(css: string): string {
+  return css.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+function processThemeLine(
+  line: string,
+  lineNumber: number,
+  source: string,
+  tokens: DesignToken[],
+  warnings: string[],
+): void {
+  const match = line.match(CUSTOM_PROPERTY_PATTERN);
+
+  if (!match) {
+    const partialMatch = line.match(/^\s*(--[\w-]+)\s*:\s*(.+?)\s*$/);
+    if (partialMatch) {
+      const [, name, rawValue] = partialMatch;
+      tokens.push(buildToken(name, rawValue, lineNumber, source));
+      return;
+    }
+
+    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));
+}
+
+function buildToken(
+  name: string,
+  rawValue: string,
+  lineNumber: number,
+  source: string,
+): DesignToken {
+  const value = rawValue.trim();
+
+  return {
+    name,
+    rawValue: value,
+    resolvedValue: value,
+    category: inferTokenCategory(name),
+    level: /var\(/.test(value) ? 2 : 1,
+    referenceChain: [],
+    sourceFile: source,
+    lineNumber,
+    theme: "default",
+    selector: "@theme",
+  };
+}

package/src/tokens/types.ts

@@ -0,0 +1,43 @@
+import type { DesignToken } from "../token-types.js";
+
+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 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;
+}
+
+export type TokenFormat = "auto" | "css" | "scss" | "dtcg" | "tailwind-v4";
+
+export interface ParseTokensOptions {
+  format?: TokenFormat;
+  filePath?: string;
+}
+
+export interface DesignTokenParseOptions {
+  filePath?: string;
+  themeSelectors?: Record<string, string>;
+  includeTailwindV4?: boolean;
+}
+
+export interface ThemeParserResult {
+  tokens: DesignToken[];
+  errors: string[];
+  warnings: string[];
+  parseTimeMs: number;
+}

package/src/topology/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Topology layer — barrel exports.
+ *
+ * Maps repo-relative file paths to product areas (checkout, dashboard, …) for
+ * area-scoped governance. See `apps/cloud/docs/topology/`.
+ */
+
+export { resolveArea } from "./resolve-area.js";
+export type { Area, AreaCriticality, AreaMatch, Topology } from "./resolve-area.js";

package/src/topology/resolve-area.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect } from "vitest";
+import { resolveArea, type Topology } from "./resolve-area.js";
+
+// Mirrors apps/cloud/docs/examples/fragments.config.example.ts, normalized to
+// the array shape the architecture doc locks in.
+function makeTopology(overrides?: Partial<Topology>): Topology {
+  return {
+    version: 1,
+    areas: [
+      {
+        id: "checkout",
+        name: "Checkout",
+        criticality: "revenue",
+        owners: ["checkout-platform"],
+        files: ["src/app/checkout/**", "src/features/checkout/**", "src/app/payment/**"],
+        routes: ["/checkout/**"],
+      },
+      {
+        id: "dashboard",
+        name: "Dashboard",
+        criticality: "high",
+        owners: ["dashboard-platform"],
+        files: ["src/app/dashboard/**"],
+      },
+      {
+        id: "marketing",
+        name: "Marketing",
+        criticality: "medium",
+        owners: ["growth"],
+        files: ["src/app/(marketing)/**", "src/pages/{index,pricing}.tsx"],
+      },
+    ],
+    ...overrides,
+  };
+}
+
+describe("resolveArea", () => {
+  it("matches a file to its area and records the winning glob", () => {
+    const match = resolveArea("src/app/checkout/page.tsx", makeTopology());
+    expect(match).toEqual({
+      areaId: "checkout",
+      areaName: "Checkout",
+      criticality: "revenue",
+      owners: ["checkout-platform"],
+      matchedGlob: "src/app/checkout/**",
+    });
+  });
+
+  it("matches nested files under a globstar", () => {
+    const match = resolveArea("src/features/checkout/cart/Total.tsx", makeTopology());
+    expect(match?.areaId).toBe("checkout");
+    expect(match?.matchedGlob).toBe("src/features/checkout/**");
+  });
+
+  it("returns null for an unmatched path (becomes Unassigned downstream)", () => {
+    expect(resolveArea("src/lib/utils.ts", makeTopology())).toBeNull();
+  });
+
+  it("treats Next.js route-group parens as literal path segments", () => {
+    const match = resolveArea("src/app/(marketing)/home.tsx", makeTopology());
+    expect(match?.areaId).toBe("marketing");
+    // The parens must not behave like a regex/extglob group.
+    expect(resolveArea("src/app/marketing/home.tsx", makeTopology())).toBeNull();
+  });
+
+  it("expands brace alternation", () => {
+    const topology = makeTopology();
+    expect(resolveArea("src/pages/index.tsx", topology)?.areaId).toBe("marketing");
+    expect(resolveArea("src/pages/pricing.tsx", topology)?.areaId).toBe("marketing");
+    // The literal dot must not act as a wildcard.
+    expect(resolveArea("src/pages/indexXtsx", topology)).toBeNull();
+  });
+
+  it("matches a single `*` within one segment only (no slash crossing)", () => {
+    const topology: Topology = {
+      version: 1,
+      areas: [
+        {
+          id: "features",
+          name: "Features",
+          criticality: "medium",
+          owners: [],
+          files: ["src/features/*/index.ts"],
+        },
+      ],
+    };
+    expect(resolveArea("src/features/billing/index.ts", topology)?.areaId).toBe("features");
+    // `*` is single-segment, so a nested path must not match.
+    expect(resolveArea("src/features/billing/nested/index.ts", topology)).toBeNull();
+  });
+
+  it("uses first-match by declaration order when priorities are equal", () => {
+    const topology: Topology = {
+      version: 1,
+      areas: [
+        { id: "first", name: "First", criticality: "low", owners: [], files: ["src/**"] },
+        { id: "second", name: "Second", criticality: "low", owners: [], files: ["src/app/**"] },
+      ],
+    };
+    expect(resolveArea("src/app/x.tsx", topology)?.areaId).toBe("first");
+  });
+
+  it("honors priority as a tie-break (higher wins regardless of order)", () => {
+    const topology: Topology = {
+      version: 1,
+      areas: [
+        { id: "broad", name: "Broad", criticality: "low", owners: [], files: ["src/**"] },
+        {
+          id: "specific",
+          name: "Specific",
+          criticality: "high",
+          owners: [],
+          files: ["src/app/**"],
+          priority: 10,
+        },
+      ],
+    };
+    expect(resolveArea("src/app/x.tsx", topology)?.areaId).toBe("specific");
+  });
+
+  it("normalizes Windows separators and leading ./ before matching", () => {
+    const topology = makeTopology();
+    expect(resolveArea("src\\app\\checkout\\page.tsx", topology)?.areaId).toBe("checkout");
+    expect(resolveArea("./src/app/checkout/page.tsx", topology)?.areaId).toBe("checkout");
+  });
+
+  it("matches an area's own root directory path, not just descendants", () => {
+    const topology = makeTopology();
+    // `src/app/checkout/**` should match the directory itself, not only files
+    // under it (picomatch `a/**` semantics).
+    expect(resolveArea("src/app/checkout", topology)?.areaId).toBe("checkout");
+    expect(resolveArea("src/app/checkout/page.tsx", topology)?.areaId).toBe("checkout");
+  });
+
+  it("matches a mid-path globstar against zero or more segments", () => {
+    const topology: Topology = {
+      version: 1,
+      areas: [
+        { id: "api", name: "API", criticality: "high", owners: [], files: ["src/**/route.ts"] },
+      ],
+    };
+    expect(resolveArea("src/route.ts", topology)?.areaId).toBe("api");
+    expect(resolveArea("src/app/api/route.ts", topology)?.areaId).toBe("api");
+  });
+
+  it("never throws on a malformed glob — the bad glob is skipped, not the scan", () => {
+    const topology: Topology = {
+      version: 1,
+      areas: [
+        {
+          id: "broken",
+          name: "Broken",
+          criticality: "low",
+          owners: [],
+          // Unbalanced brace → invalid RegExp. Must not abort resolution.
+          files: ["src/{a,b/x.ts", "src/good/**"],
+        },
+      ],
+    };
+    expect(() => resolveArea("src/whatever.ts", topology)).not.toThrow();
+    // The malformed glob is skipped; the valid sibling still matches.
+    expect(resolveArea("src/good/file.ts", topology)?.areaId).toBe("broken");
+    // A path only the broken glob could have matched falls through to null.
+    expect(resolveArea("src/a", topology)).toBeNull();
+  });
+
+  it("returns the same result across repeated calls (cache correctness)", () => {
+    const topology = makeTopology();
+    const a = resolveArea("src/app/dashboard/Home.tsx", topology);
+    const b = resolveArea("src/app/dashboard/Home.tsx", topology);
+    expect(a).toEqual(b);
+    expect(a?.areaId).toBe("dashboard");
+  });
+});