Merge branch 'dev'

Author: himerus

.changeset/root-scope-token-detection.md

@@ -0,0 +1,9 @@
+---
+'@anthropic/helixir-core': minor
+---
+
+Add :root scope token detection to shadow DOM checker and suggest-fix pipeline
+
+Detects component CSS custom properties set on :root (which have no effect through Shadow DOM)
+and suggests moving them to the host element. Wired into both styling_preflight and
+css-file-validator inline fix generation.

packages/core/src/handlers/css-file-validator.ts

@@ -307,7 +307,7 @@ function mapIssueToFixInput(
     case 'shadowDom':
       return {
         type: 'shadow-dom',
-        issue: 'descendant-piercing',
+        issue: issue.message.includes(':root') ? 'root-scope-token' : 'descendant-piercing',
         original,
         tagName,
         partNames,

packages/core/src/handlers/shadow-dom-checker.ts

@@ -451,6 +451,49 @@ function checkMisspelledTokens(lines: string[], meta: ComponentMetadata): Shadow
   return issues;
 }
 
+function checkRootScopeTokens(lines: string[], meta: ComponentMetadata): ShadowDomIssue[] {
+  const issues: ShadowDomIssue[] = [];
+  const validTokens = new Set(meta.cssProperties.map((p) => p.name));
+  if (validTokens.size === 0) return issues;
+
+  // Find :root blocks and check for component tokens inside them
+  const text = lines.join('\n');
+  const rootBlockPattern = /:root\s*\{([^}]*)}/g;
+  let blockMatch: RegExpExecArray | null;
+
+  while ((blockMatch = rootBlockPattern.exec(text)) !== null) {
+    const blockContent = blockMatch[1] ?? '';
+    const blockStartOffset = blockMatch.index;
+    const linesBeforeBlock = text.slice(0, blockStartOffset).split('\n').length;
+
+    // Find each token declaration inside this :root block
+    const tokenPattern = /(--[\w-]+)\s*:/g;
+    let tokenMatch: RegExpExecArray | null;
+
+    while ((tokenMatch = tokenPattern.exec(blockContent)) !== null) {
+      const tokenName = tokenMatch[1] ?? '';
+      if (validTokens.has(tokenName)) {
+        // Calculate line number: lines before block + lines within block content before this token
+        const contentBefore = blockContent.slice(0, tokenMatch.index);
+        const extraLines = (contentBefore.match(/\n/g) ?? []).length;
+        const line = linesBeforeBlock + extraLines;
+
+        issues.push({
+          line,
+          column: 1,
+          severity: 'error',
+          rule: 'no-root-scope-token',
+          message: `Component token "${tokenName}" set on :root has no effect through Shadow DOM.`,
+          suggestion: `Set it on the host element instead: ${meta.tagName} { ${tokenName}: value; }`,
+          code: `:root { ${tokenName}: ...; }`,
+        });
+      }
+    }
+  }
+
+  return issues;
+}
+
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 function escapeRegex(str: string): string {
@@ -502,6 +545,7 @@ export function checkShadowDomUsage(
   if (meta) {
     issues.push(...checkUnknownParts(lines, meta));
     issues.push(...checkMisspelledTokens(lines, meta));
+    issues.push(...checkRootScopeTokens(lines, meta));
   }
 
   issues.sort((a, b) => a.line - b.line || a.column - b.column);

packages/core/src/handlers/styling-preflight.ts

@@ -323,6 +323,7 @@ function extractPropertyFromMessage(message: string): string | undefined {
 }
 
 function detectShadowDomIssueType(message: string): string {
+  if (message.includes(':root')) return 'root-scope-token';
   if (message.includes('descendant') || message.includes('child')) return 'descendant-piercing';
   if (message.includes('::part') && message.includes('class')) return 'part-structural';
   if (message.includes('/deep/') || message.includes('>>>')) return 'deprecated-deep';

packages/core/src/handlers/suggest-fix.ts

@@ -157,6 +157,22 @@ function fixShadowDom(input: SuggestFixInput): FixSuggestion {
     };
   }
 
+  if (input.issue === 'root-scope-token') {
+    const tag = tagName ?? 'the-element';
+    // Extract token name from the original CSS
+    const tokenMatch = original.match(/(--[\w-]+)\s*:/);
+    const token = tokenMatch?.[1] ?? '--component-token';
+    const valueMatch = original.match(/:\s*([^;]+)/);
+    const value = valueMatch?.[1]?.trim() ?? 'value';
+
+    return {
+      original,
+      suggestion: `${tag} { ${token}: ${value}; }`,
+      explanation: `Component tokens set on :root have no effect through Shadow DOM boundaries. The token "${token}" must be set on the component's host element (<${tag}>) for the shadow root to inherit it.`,
+      severity: 'error',
+    };
+  }
+
   if (input.issue === 'external-host') {
     const tag = tagName ?? 'the-element';
     return {

tests/__fixtures__/benchmark-results/latest-benchmark.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-03-21T08:59:37.296Z",
+  "timestamp": "2026-03-21T09:09:08.872Z",
   "scorecards": {
     "material": {
       "library": "material",
@@ -187,7 +187,7 @@
         "heuristic": 426,
         "untested": 747
       },
-      "timestamp": "2026-03-21T08:59:37.291Z"
+      "timestamp": "2026-03-21T09:09:08.869Z"
     },
     "spectrum": {
       "library": "spectrum",
@@ -375,7 +375,7 @@
         "heuristic": 404,
         "untested": 601
       },
-      "timestamp": "2026-03-21T08:59:37.292Z"
+      "timestamp": "2026-03-21T09:09:08.869Z"
     },
     "vaadin": {
       "library": "vaadin",
@@ -563,7 +563,7 @@
         "heuristic": 439,
         "untested": 717
       },
-      "timestamp": "2026-03-21T08:59:37.292Z"
+      "timestamp": "2026-03-21T09:09:08.870Z"
     },
     "fluentui": {
       "library": "fluentui",
@@ -751,7 +751,7 @@
         "heuristic": 139,
         "untested": 293
       },
-      "timestamp": "2026-03-21T08:59:37.292Z"
+      "timestamp": "2026-03-21T09:09:08.870Z"
     },
     "carbon": {
       "library": "carbon",
@@ -939,7 +939,7 @@
         "heuristic": 397,
         "untested": 793
       },
-      "timestamp": "2026-03-21T08:59:37.292Z"
+      "timestamp": "2026-03-21T09:09:08.870Z"
     },
     "ui5": {
       "library": "ui5",
@@ -1127,7 +1127,7 @@
         "heuristic": 582,
         "untested": 1304
       },
-      "timestamp": "2026-03-21T08:59:37.293Z"
+      "timestamp": "2026-03-21T09:09:08.870Z"
     },
     "calcite": {
       "library": "calcite",
@@ -1315,7 +1315,7 @@
         "heuristic": 318,
         "untested": 848
       },
-      "timestamp": "2026-03-21T08:59:37.294Z"
+      "timestamp": "2026-03-21T09:09:08.871Z"
     },
     "porsche": {
       "library": "porsche",
@@ -1503,7 +1503,7 @@
         "heuristic": 304,
         "untested": 702
       },
-      "timestamp": "2026-03-21T08:59:37.294Z"
+      "timestamp": "2026-03-21T09:09:08.871Z"
     },
     "ionic": {
       "library": "ionic",
@@ -1691,7 +1691,7 @@
         "heuristic": 331,
         "untested": 744
       },
-      "timestamp": "2026-03-21T08:59:37.294Z"
+      "timestamp": "2026-03-21T09:09:08.871Z"
     },
     "wired": {
       "library": "wired",
@@ -1879,7 +1879,7 @@
         "heuristic": 78,
         "untested": 208
       },
-      "timestamp": "2026-03-21T08:59:37.294Z"
+      "timestamp": "2026-03-21T09:09:08.871Z"
     },
     "elix": {
       "library": "elix",
@@ -2067,7 +2067,7 @@
         "heuristic": 148,
         "untested": 740
       },
-      "timestamp": "2026-03-21T08:59:37.295Z"
+      "timestamp": "2026-03-21T09:09:08.871Z"
     },
     "helix": {
       "library": "helix",
@@ -2255,7 +2255,7 @@
         "heuristic": 440,
         "untested": 555
       },
-      "timestamp": "2026-03-21T08:59:37.295Z"
+      "timestamp": "2026-03-21T09:09:08.872Z"
     }
   },
   "comparisonTable": {
@@ -3278,74 +3278,74 @@
       "API Surface Quality",
       "Event Architecture"
     ],
-    "timestamp": "2026-03-21T08:59:37.296Z"
+    "timestamp": "2026-03-21T09:09:08.872Z"
   },
   "performance": {
-    "totalMs": 2876,
+    "totalMs": 2442,
     "phases": [
       {
         "name": "load-libraries",
-        "durationMs": 143
+        "durationMs": 151
       },
       {
         "name": "score-all-libraries",
-        "durationMs": 2727
+        "durationMs": 2288
       },
       {
         "name": "score-material",
-        "durationMs": 178
+        "durationMs": 220
       },
       {
         "name": "score-spectrum",
-        "durationMs": 148
+        "durationMs": 162
       },
       {
         "name": "score-vaadin",
-        "durationMs": 916
+        "durationMs": 696
       },
       {
         "name": "score-fluentui",
-        "durationMs": 38
+        "durationMs": 52
       },
       {
         "name": "score-carbon",
-        "durationMs": 132
+        "durationMs": 105
       },
       {
         "name": "score-ui5",
-        "durationMs": 225
+        "durationMs": 180
       },
       {
         "name": "score-calcite",
-        "durationMs": 578
+        "durationMs": 257
       },
       {
         "name": "score-porsche",
-        "durationMs": 62
+        "durationMs": 73
       },
       {
         "name": "score-ionic",
-        "durationMs": 119
+        "durationMs": 60
       },
       {
         "name": "score-wired",
-        "durationMs": 24
+        "durationMs": 46
       },
       {
         "name": "score-elix",
-        "durationMs": 236
+        "durationMs": 372
       },
       {
         "name": "score-helix",
-        "durationMs": 71
+        "durationMs": 65
       },
       {
         "name": "generate-scorecards",
-        "durationMs": 5
+        "durationMs": 3
       },
       {
         "name": "generate-comparison",
-        "durationMs": 1
+        "durationMs": 0
       }
     ],
     "withinGate": true

tests/handlers/shadow-dom-checker.test.ts

@@ -346,6 +346,51 @@ describe('checkShadowDomUsage', () => {
     });
   });
 
+  describe(':root scope token detection', () => {
+    it('detects component tokens set on :root', () => {
+      const css = `:root { --my-button-bg: blue; }`;
+      const result = checkShadowDomUsage(css, 'my-button', buttonMeta);
+      expect(result.clean).toBe(false);
+      expect(result.issues).toHaveLength(1);
+      expect(result.issues[0]!.rule).toBe('no-root-scope-token');
+      expect(result.issues[0]!.severity).toBe('error');
+      expect(result.issues[0]!.message).toContain(':root');
+      expect(result.issues[0]!.suggestion).toContain('my-button');
+    });
+
+    it('detects multiple component tokens on :root', () => {
+      const css = `:root {\n  --my-button-bg: blue;\n  --my-button-color: white;\n}`;
+      const result = checkShadowDomUsage(css, 'my-button', buttonMeta);
+      expect(result.issues.filter((i) => i.rule === 'no-root-scope-token')).toHaveLength(2);
+    });
+
+    it('ignores non-component tokens on :root', () => {
+      const css = `:root { --global-font-size: 16px; }`;
+      const result = checkShadowDomUsage(css, 'my-button', buttonMeta);
+      const rootIssues = result.issues.filter((i) => i.rule === 'no-root-scope-token');
+      expect(rootIssues).toHaveLength(0);
+    });
+
+    it('detects tokens in :root with var() usage', () => {
+      const css = `:root { --my-button-bg: var(--theme-primary); }`;
+      const result = checkShadowDomUsage(css, 'my-button', buttonMeta);
+      expect(result.issues.some((i) => i.rule === 'no-root-scope-token')).toBe(true);
+    });
+
+    it('skips :root check when no metadata provided', () => {
+      const css = `:root { --my-button-bg: blue; }`;
+      const result = checkShadowDomUsage(css, 'my-button');
+      const rootIssues = result.issues.filter((i) => i.rule === 'no-root-scope-token');
+      expect(rootIssues).toHaveLength(0);
+    });
+
+    it('detects :root tokens in multi-block CSS', () => {
+      const css = `my-button { color: red; }\n:root { --my-button-bg: blue; }\n.container { display: flex; }`;
+      const result = checkShadowDomUsage(css, 'my-button', buttonMeta);
+      expect(result.issues.some((i) => i.rule === 'no-root-scope-token')).toBe(true);
+    });
+  });
+
   describe('result structure', () => {
     it('includes tagName when provided', () => {
       const result = checkShadowDomUsage('', 'my-button');