Skip to content

About

Deterministic review harness and Claude Code skill for Lightning CSS pull requests: base/head output diffs, browser oracle (Chromium, Firefox, WebKit), spec checklists.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

15 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

lightningcss-review

A review harness for Lightning CSS pull requests. It answers the questions that take a maintainer longest on a CSS change:

  • What does the change do to the output, isolated from everything else on master?
  • Does the output still mean the same thing as the input, in real browsers?
  • What else did it change, outside the area it claims to touch?
  • What does the spec say about it?

It ships as a Claude Code skill (SKILL.md), but the harness (bin/lcr) is a plain command-line tool you can run without an agent.

lcr review 1385         # prepare + build + corpus for parcel-bundler/lightningcss#1385
lcr oracle 1385         # browser oracle: Chromium, Firefox, WebKit (current and legacy builds)
lcr report 1385         # checks -> findings -> verdict -> report.md / report.json

Why

Lightning CSS fully parses CSS and rewrites it: it merges rules, folds longhands into shorthands, drops declarations it considers overridden, and lowers modern syntax for older browsers. Each of those is easy to get almost right. As the maintainer put it:

CSS has a lot of edge cases and many times people think they understand how it works intuitively but in reality it's more complex or a small change affects more than they think. I usually need to verify against the spec, test against browser behavior, etc. which is quite time consuming.

This project automates that verification and leaves the judgment calls, written down with evidence, to the reviewer.

What it does

Stage What happens
prepare Merges the PR head into current master with git merge-tree (no commit), exports base and head trees, maps changed files to areas, finds changed Rust items and their references (blast radius), risk flags, linked issues, overlapping open PRs and CI status.
build In a Docker builder pinned to the repo's rust-toolchain.toml: cargo fmt --check, cargo test --all-features with RUSTFLAGS=-D warnings like CI, while every test-helper call (minify_test, prefix_test, ...) is recorded as a tuple. Also the lanes CI does not run: parcel_selectors tests, --no-default-features, a wasm32 compile gate, C bindings, and drift of generated files (build-prefixes.js output, ast.d.ts).
corpus Every case through the base and the head build with identical options: all recorded test expectations of both sides, 600+ curated probes, metamorphic mutations of the PR's own tests (reversed declarations, !important, interleaved var(), prefixed siblings, @media/@layer/@supports wrapping, nesting, retargeting), the 24k-case WPT property corpus, and 25 pinned real-world stylesheets. Any difference is a delta.
oracle Synthesizes a DOM from the selectors (css-tree, not Lightning CSS), applies input, base output and head output, and compares getComputedStyle per element and pseudo-element in current Chromium, Firefox and WebKit. Lowered output is also rendered in older engines inside the targets. Classifies each delta: fixed, regressed, both-equivalent, still-different, engine divergence.
report Evaluates a fixed check catalog (config/checks.json) over the stage outputs and the reviewer's analysis.json, then renders a fixed-format report with a rule-based verdict: UNSAFE, NEEDS_CHANGES, SAFE_WITH_NITS, SAFE or INCONCLUSIVE.

Same PR, same base and same images give a byte-identical report.

Optional stages: lcr perf (release build size and timing on the real-world corpus), lcr baseline (which curated probes fail on master today), lcr spec-coverage (W3C webref inventory vs what Lightning CSS parses), lcr selftest (known-answer cases through every engine).

Requirements

  • git, gh (authenticated, read-only use), Docker with the Compose and Buildx plugins, Node.js 24 or newer (the harness needs no packages)
  • About 15 GB of disk for the images
git clone https://github.com/ovflowd/lightningcss-review
cd lightningcss-review
bin/lcr doctor      # checks the above
bin/lcr setup       # builds the builder and browser images (compose.yaml), records engine versions
bin/lcr wpt         # one-time WPT checkout + corpus extraction
bin/lcr realworld   # one-time download of the pinned real-world stylesheets
bin/lcr selftest    # every self-test case must pass (N/N)

To use it as a Claude Code skill, run ./install.sh (it symlinks the checkout into your skills directory) and ask the agent to review a Lightning CSS PR. The agent follows SKILL.md: it runs the stages, writes probes for the change, fills the analysis slots with evidence, and renders the report. It never posts to GitHub unless you ask it to.

LCR_REPO points the harness at an existing Lightning CSS checkout (otherwise it uses ~/GitHub/lightningcss if present, or clones one into the cache). LCR_CACHE moves the cache (default ~/.cache/lightningcss-review). LCR_BUILD=host builds with a local Rust toolchain instead of the builder image and runs the adapters on the host too, outside any container, so use it only for trees you trust; browsers always run in Docker. SECURITY.md says what runs where.

Layout

Path Contents
SKILL.md the review procedure for an agent (phases, rules, classification)
bin/lcr, lib/ the harness (Node.js, no runtime dependencies), one directory per stage
compose.yaml, docker/ the builder and browser images; compose.yaml pins each engine profile's Playwright release
adapter/lcr_adapter.rs JSONL bridge compiled into each tree as a Cargo example
oracle/ DOM synthesis, engine runner, comparison, spec cards; oracle/wpt/ is the WPT extractor from lightningcss#1328
config/ areas, transform modes and targets, engine profiles, check catalog, test and property maps, pins
corpus/probes/ curated probes by area (spec invariants, past regressions, issue repros)
references/ what the reviewing agent loads: per-area checklists, spec digests, architecture, conventions, browsers, ecosystem, oracle (size-budgeted, mechanisms only)
docs/ how the harness works
lib/*/test/, oracle/test/, scripts/test/, test/ unit tests (npm test), shared fixtures and the oracle's known-answer cases
scripts/ CI checks for the agent context and the checklists

Status

Early. The harness, oracle and references are complete enough to review real PRs; expect the check catalog and the probe corpus to keep changing. Bugs on master that the curated probes reproduce carry known: open-bug or known: open-issue#N; lcr baseline lists them.

Credits

See CREDITS.md. In short: the WPT extraction and the CSSOM oracle checks come from Devon Govett's lightningcss#1328, the property corpus from web-platform-tests, spec data from W3C webref, and the browsers from Playwright.

License

MPL-2.0, the same license as Lightning CSS. WPT-derived material is BSD-3-Clause (oracle/wpt/LICENSE-WPT.md).

About

Deterministic review harness and Claude Code skill for Lightning CSS pull requests: base/head output diffs, browser oracle (Chromium, Firefox, WebKit), spec checklists.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages