feat: detect :root scope component tokens in shadow DOM checker

[himerus]

Summary

• Adds no-root-scope-token rule to check_shadow_dom_usage — detects component CSS custom properties set on :root which have no effect through Shadow DOM boundaries
• Adds root-scope-token fix to suggestFix — generates concrete fix moving the token from :root to the component host element
• Wires :root detection into styling_preflight and css-file-validator inline fix pipelines via detectShadowDomIssueType
• 9 new tests (6 detection + 3 fix generation)

Why

Agents frequently hallucinate :root { --sl-button-color: blue; } expecting it to style Shadow DOM internals. This is a no-op — component tokens must be set on the host element. Now caught and auto-fixed across all validation surfaces.

Test plan

• 6 new shadow-dom-checker tests pass (:root detection, multi-token, non-component token exclusion, var() values, no-meta skip, multi-block)
• 3 new suggest-fix tests pass (host element suggestion, var() preservation, explanation quality)
• Full suite: 2425/2426 pass (1 pre-existing hx-carousel phantom events failure)
• CI passes

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features
  • Added detection for CSS custom property tokens declared on :root that don't take effect with Shadow DOM-based components
  • Integrated automatic fix suggestions to relocate :root-scoped tokens to component host elements
  • Enhanced error reporting explains why :root-scoped tokens don't cross Shadow DOM boundaries

[coderabbitai]

Warning

Rate limit exceeded

@himerus has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 23 minutes and 12 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 14ae65b0-b0b3-4dc1-8a04-835bbb76ce85

📥 Commits

Reviewing files that changed from the base of the PR and between da00697 and ec2296d.

📒 Files selected for processing (1)

• tests/integration/server.test.ts

Walkthrough

This pull request adds a new :root scope token detection feature for CSS custom properties that don't work across Shadow DOM boundaries. It includes a new detector, issue type classification, fix mapping, and fix generation logic across multiple handlers, along with comprehensive test coverage.

Changes

Cohort / File(s)	Summary
Changeset Metadata .changeset/root-scope-token-detection.md	Added changeset documenting the new :root scope token detection capability for both Shadow DOM checker and suggest-fix pipeline at minor version level.
Detection Logic packages/core/src/handlers/shadow-dom-checker.ts	Added new checkRootScopeTokens detector that scans for CSS custom properties declared on :root blocks matching component token names, emits no-root-scope-token errors with computed line numbers and suggestions to move tokens to component host.
Issue Type Classification & Fix Mapping packages/core/src/handlers/styling-preflight.ts, packages/core/src/handlers/css-file-validator.ts	Updated issue type detection to identify :root usage in checker messages and classify as 'root-scope-token' subtype; updated fix mapping to route these issues to 'root-scope-token' fix generation.
Fix Generation packages/core/src/handlers/suggest-fix.ts	Added root-scope-token fix branch that extracts CSS custom property names and values from source, then generates error-level suggestions to move tokens from :root to component host element.
Test Coverage tests/handlers/shadow-dom-checker.test.ts, tests/handlers/suggest-fix.test.ts	Added comprehensive test suites validating :root token detection across component tokens, edge cases with var(...) values, and fix generation with proper host element substitution.
Benchmark Data tests/__fixtures__/benchmark-results/latest-benchmark.json	Updated benchmark fixture with new timestamp and performance measurements from latest test run.

Sequence Diagram

sequenceDiagram
    participant CSS as CSS Source
    participant Checker as Shadow DOM<br/>Checker
    participant Preflight as Styling<br/>Preflight
    participant FileVal as CSS File<br/>Validator
    participant FixGen as Suggest<br/>Fix

    CSS->>Checker: Scan for :root blocks<br/>with component tokens
    Checker-->>Checker: Extract tokens &<br/>compute line numbers
    Checker->>Preflight: Emit no-root-scope-token<br/>error with message
    Preflight->>Preflight: Detect :root in<br/>error message
    Preflight-->>FileVal: Classify as<br/>root-scope-token type
    FileVal->>FileVal: Map to<br/>root-scope-token fix
    FileVal->>FixGen: Route root-scope-token<br/>issue for fixing
    FixGen->>FixGen: Extract token name<br/>& value from CSS
    FixGen-->>CSS: Suggest moving token<br/>to component host

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	❓ Inconclusive	The PR description is comprehensive with a clear summary, motivation, and test plan, but does not follow the repository's required template structure.	Follow the provided template by including 'Type of change', 'Related issue', proper 'Description' section, 'Tests added' checkbox, and complete 'Checklist' items.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: detection of :root scope component tokens in the shadow DOM checker.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/root-scope-token-detection

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}