skills: add bulk-css-operation for safe CSS pruning, refactoring diffs, and rule locations

[paulirish]

Clean up unused CSS, refactor stylesheets with automated safety checks, and read exact character offsets from standard CSSOM rule objects.

What You Can Do

1. Prune unused CSS safely using real Chrome coverage

Point a CLI command or script at a live URL or HTML file to produce a cleaned stylesheet that strips unused classes while protecting foundational and interactive styling:

node skills/bulk-css-operation/scripts/run-coverage-prune.ts https://example.com

• Preserves design tokens and foundational rules: Automatically retains :root, html, body, @property, @layer declarations, @charset, and @import even if static coverage reports 0% hits.
• Preserves conditional styles: Keeps @media print, @media (prefers-color-scheme: dark), @media (prefers-reduced-motion), and @starting-style transitions.
• Retains interactive states: Keeps :hover, :focus-visible, and :active rules when the underlying element is present in the DOM.
• Keeps referenced assets: Retains @keyframes animations and @font-face rules when they are referenced by active declarations.
• In-place review annotations: Ambiguous rules (e.g. unreferenced animations or interactive states without active base elements) can be commented out with /* @cssom-review: <reason> */ so changes can be audited directly in git diff.

2. Safely split, bundle, and migrate CSS files

Refactor CSS—such as splitting monolithic files into modules, flattening nesting, or migrating colors to CSS custom properties—and automatically verify that no styles or cascade relationships broke:

• AST rule and declaration diffing (diffCssAst): Verifies that no selectors, properties, or !important flags were unintentionally dropped, added, or modified when moving rules between files.
• Cascade conflict detection (checkCascadeConflicts): Detects source-order reversals between rules that target overlapping selectors at identical specificity, catching accidental precedence flips when reordering files.
• DOM style comparison (diffCascadedStyles): Compares element-level cascaded values before and after refactoring on sample DOM elements to guarantee visual equivalence when renaming classes or restructuring selectors.

3. Inspect character offsets on parsed CSS rules

Read exact character offsets from the original source text directly on standard CSSRule instances:

• rule.location: Returns { start, end, bodyStart?, bodyEnd? } containing 0-based character offsets for any rule, at-rule, or nested block.
• Clean slicing and rewrites: Extract, replace, or prune rules by slicing the original source string directly, preserving original indentation, formatting, and comments without re-serializing through a stringifier.

---

Changed Files & Tests

• src/rules/base.ts, src/parser.ts, src/types.ts, src/index.ts: Added location getter to CSSRule and token offset calculation during parsing.
• skills/bulk-css-operation/scripts/coverage-prune.ts: Pruning engine that strips unused CSS based on coverage data while retaining foundational tokens and assets.
• skills/bulk-css-operation/scripts/live-coverage-collector.ts: Runs headless Chrome via Puppeteer to collect live CSS coverage.
• skills/bulk-css-operation/scripts/run-coverage-prune.ts: CLI entry point for pruning a local HTML file or web URL.
• skills/bulk-css-operation/scripts/ast-diff.ts, cascade-diff.ts, cascaded-diff.ts: Verification utilities checking AST equality, cascade conflicts, and element-level cascaded styles.
• skills/bulk-css-operation/SKILL.md: Playbook and documentation for bulk CSS refactoring workflows.
• tests/rule-location.test.ts: Unit tests verifying location offsets across style rules, at-rules, nested rules, and edge cases.
• skills/bulk-css-operation/scripts/*.test.ts: Unit and integration tests covering live headless Chrome coverage pruning, AST diffing, and cascade verification.