Skip to content

Commit 9683e21

Browse files
perf(css): drop what a declaration, a slot or a query already says (#21931)
* perf(css): drop what a declaration, a slot or a query already says Five things the minifier wrote out that say nothing: - A declaration a later one overrides, where the two are spelled from one vocabulary — a pair of numbers carrying one unit, a pair of hexes on one side of the alpha four digits state, a pair of color names as old as naming a color, or `inherit`. That is what parts an override from a fallback without asking the target: `color:#eee` before `color:lab(…)` is the older color standing where the newer one is not read, while `color:#eee;color:#333` is one an engine reading either reads both of. Two adjacent rules with one selector join on the same terms, where they used to be kept apart by any property they shared. - A shorthand slot holding its own initial, where the slot takes more than keywords: `border:medium none currentcolor` is `border:none`. The initial table now carries what each slot takes beyond its spellings, so a sibling filling it is read by the classes its own value is in — a length, a color — rather than by a list of names, and a value that classes as nothing keeps the slot. - A `<time>` of zero nothing after it depends on, in a transition or an animation, and an iteration count of one. - The `all` a media query states before an `and`, which matches what the condition alone does. - An operand a condition already states, in `@supports`, `@media` and `@container` alike. `rebeccapurple` and `transparent` are the names left out of the first, derived from the compatibility rows they carry of their own: an engine may read neither while reading the rest. Held to Chromium: every rewrite computes as what it replaced, over the equivalence fixtures a new one covers. * test(css): hold every lowering to the whole computed style, not the probes The lowering tier compared the properties each fixture names. It now compares every property the CSSOM reports for those elements, so a rewrite reaching one nobody thought to probe is one the tier sees. Two differences it turned up are real and now stated rather than hidden: - a folded color serializes differently. Chromium keeps the space a color was written in, so `color(srgb .2 .4 .6)` computes as itself where `#369` computes as `rgb(51, 102, 153)` — the same color, a different string for a script to read. Values are compared as the color they paint, which is what the rewrite preserves. - lowering `light-dark()` writes `--webpack-light` and `--webpack-dark`, which a script enumerating computed custom properties would see where the source has none. The fixtures naming that lowering now say so. The corpus tier already reads every `.css` under `configCases` and compares the CSSOM rule by rule — conditions evaluated rather than compared as text, blocks computed by the engine — and every `style=""` as the declarations it parses to. The queries and shorthand slots this session learned to shorten had no corpus entry, so they were held by unit tests alone; they have one now. * feat(css): give every target-driven rewrite a switch of its own (#21932) * feat(css): give every target-driven rewrite a switch of its own `optimization.minimize.css` says every transform keeping the stylesheet's meaning may be turned off on its own, so a document one rewrite breaks can be minimized without it. Eleven rewrites did not honour that: everything the browserslist target drives — a hex alpha as `rgba()`, a double-position stop, `inset` / `overflow` / `place-*` as longhands, `text-decoration` as its own, `system-ui` as the platform stack, a `:lang()` or `:not()` list as the `:is()` it means, a media range as the `min-`/`max-` pair, `light-dark()` as the custom-property pair — could only be escaped by dropping the target, which takes vendor prefixing with it. `lowerUnsupported` turns the policy off and leaves the rest of the minifier running; it does not make the printer write a spelling the target cannot read. Three more rewrites answered to nothing, and now answer to the switch that owns them: `@charset` and an empty rule on the collected path to `removeDeadRules` (the streaming path already asked it, so the two paths disagreed), and the `all` before an `and` and a repeated condition operand to `shortenMediaQueries` — whose description now says it shortens a condition prelude, `@supports` and `@container` included. A unit test asks each of the eleven to stand still with the switch off, and `minimize-lower-unsupported-off` is the same sheet and target as `minimize-lower-unsupported` with the one option set. * fix(css): minify what a lowering reads and what it writes Asked whether a lowered spelling is itself minified, two answers came back no: - A media feature's own number was never shortened, lowered or not: `@media (0480.0px <= width <= 768.50px)` kept every digit it was written with, and the `min-`/`max-` pair lowered out of it kept them too. A feature is a `<length>`, a `<ratio>` or an `<integer>` and nothing else, so the number in one shortens like any other — where a prelude number elsewhere is An+B and stripping a `+` there breaks the selector, which is what the guard was for. A `style()` query still compares its tokens as written, and `@supports` reads a declaration rather than a feature. - A `text-decoration` whose color is a hex or a call was not lowered at all. The print leaves out the separator between an ident and a hash — `solid #fff` is `solid#fff`, two tokens whatever stands between them — and the lowering split the printed value on its spaces, so the slots came back unreadable and the rewrite declined. For Safari 15 that means the whole declaration is dropped and the underline is lost, which is the failure the lowering exists to prevent. It now splits at the junctions the print could have left bare, by the same test the print makes; and a call that is a color rather than one that takes one fills a color slot, out of `<color>`'s own grammar. Everything else a lowering writes was already minified: the `inset` longhands drop a zero's unit, the `text-decoration` ones shorten the color, the `light-dark()` halves shorten theirs, the hex-alpha rewrite writes the shortest alpha that quantizes back, and the `system-ui` stack drops its quotes. * fix(css): drop no declaration a keyframe, a revert or a slot's arity keeps The browser tier over web-platform-tests caught three colors and animations this turn's own redundancy removal changed the meaning of. - CSS Animations 1 §3 ignores an `!important` declaration inside a keyframe, so the plain one before it is what the engine reads. `border-color:green; border-color:red!important` kept only the important one, which the engine then discards — the element lost its border color rather than gaining a red one (`css-cascade/important-prop.html`). - The rule-level override read the later block's *first* declaration of the property rather than its last, so `#t{color:green}` before `#t{color:red;color:revert-rule}` was compared against the red and dropped. `revert-rule` reads back to that very rule, so the color went green to red (`css-cascade/revert-rule-layer.html`). The last one decides now, which is also what leaves the `revert` family declining on its own terms. - One slot takes the iteration count and two take a time, so `animation:1 2`, `animation:1 1`, `animation:0s 0s 0s` and `transition:0s 0s 0s` are layers no engine reads — and dropping the default from one handed back a layer that runs. Both droppers decline where a layer names more than the slots take. The folds that were right stay: `animation:0s 0s` is still `animation:0s`, `animation:x 1 2s` still loses its count, and an `!important` outside a keyframe still stands over what precedes it. The two changesets this pull request carried are one, as the guide asks, and the `};` recovery case in the html suite names two properties now — with one, the override removal takes the pair it was written to show. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_018tNx7sU4SbnKFhFeofDVr5 * fix(css): let a url() answer as a url before it is read as a call `_valueClasses` tested for a function call before it tested for `url()`, so a well-formed `url(...)` reached the call branch first and left the url test unreachable. Reword `lowerUnsupported`'s closing clause, which did not parse. * style(css): hold the new comments to the two-line limit Also drops a leftover `@returns`-only JSDoc block stacked above `collectColorFunctions`'s real one. * test(css): drive the two dataset guards the generator grew `collectColorFunctions` and `collectLaterColorNames` read their dataset off module state, so neither guard could be reached from a test. Take it as an argument the way `collectGradientFunctions` and `collectMergeableAtRules` already do, and cover both throws. * docs: make the comment-length limit countable, and check it The rule said "as short as possible — ideally one line, at most two" in the middle of a paragraph, which reads as a preference rather than a bound, and nothing checked it before review did. State the limit first, give a command that reports any comment block a change grows past two lines, and cut the section from 33 lines to 19. Bring the comments this branch added under it. * test(css): update the CLI snapshot for the reworded description The CLI flags are derived from the schema, so rewording `lowerUnsupported` changed four lines of `Cli.basictest.js.snap`. * build: check comment length over both comment forms The awk one-liner the guide carried matched `//` runs only, so a three-line `/* … */` block passed it, and an untracked file was in no diff at all — a new file stayed unchecked until the commit that would have caught it. Move the check into `tooling/check-comment-length.js` behind `yarn lint:comments`, reading both forms and every new file, and exempting JSDoc and the license header. Covered by a unit test. * test: cover the comment-length checker's command path Codecov read 12 lines of `tooling/check-comment-length.js` uncovered — the whole `require.main` body, which no test reached. Split it into `report` and `main` and drive both over a throwaway git repository, tracked file and untracked alike, plus the command itself end to end. * fix: read the comment-length repository without changing directory `runtimes (bun)` failed all seven repository tests with `process.chdir() is not supported in workers` — jest runs them in a worker there, and the newest Bun refuses the call. Take the repository as an argument through `report` and `main` instead, which also stops the checker depending on whatever directory it is called from. --------- Co-authored-by: Claude Opus 5 <[email protected]>
1 parent c6a48f0 commit 9683e21

44 files changed

Lines changed: 2401 additions & 413 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"webpack": minor
3+
---
4+
5+
Drop what a declaration, slot or query already says, and add `lowerUnsupported`.

‎AGENTS.md‎

Lines changed: 9 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ The directory listings below are the canonical map of the repository. **Whenever
9191
- `lib/wasm/`, `lib/wasm-async/`, `lib/wasm-sync/` — WebAssembly module support.
9292
- `hot/` — Runtime code shipped to browsers for HMR (browser-side, not Node tooling).
9393
- `bin/` — `webpack` CLI entry point.
94-
- `tooling/` — Repo-internal scripts: build/codegen (runtime/wasm generators, hash-debug tool) invoked by `yarn fix:special`, plus standalone analysis tools such as `compare-css-minifiers.js` / `compare-html-minifiers.js` (`yarn benchmark:css-minifiers`, `yarn benchmark:html-minifiers`). Those two need no arguments and no reading of their source: each runs webpack's CSS/HTML minifier and the ecosystem's over popular framework stylesheets and real documents, printing one table per fixture — output size raw and under gzip/brotli/zstd (the `test:size` settings), best-of-3 wall and cpu ms, peak RSS (each minifier × fixture measured in its own worker process, so the numbers are attributable), and whether the output lost classes / changed the DOM ("rejects it" rows mean the tool errored on that input). They install the packages they compare against into `node_modules/.cache/` on first run rather than into webpack's dependencies; expect the first run to install for a minute and every full run to take a few. `measure-color-agreement.js` (`yarn measure:color-agreement`) is the third: it asks a real browser for its own color conversions rather than for a pixel, and prints how far they sit from webpack's — which is where the rounding margins in `lib/css/syntax.js` and the list of spaces an engine reads through another transfer come from. Re-run it (a few seconds; `PUPPETEER_EXECUTABLE_PATH` picks the binary) rather than adjusting either by hand.
94+
- `tooling/` — Repo-internal scripts: build/codegen (runtime/wasm generators, hash-debug tool) invoked by `yarn fix:special`, plus standalone analysis tools such as `compare-css-minifiers.js` / `compare-html-minifiers.js` (`yarn benchmark:css-minifiers`, `yarn benchmark:html-minifiers`). Those two need no arguments and no reading of their source: each runs webpack's CSS/HTML minifier and the ecosystem's over popular framework stylesheets and real documents, printing one table per fixture — output size raw and under gzip/brotli/zstd (the `test:size` settings), best-of-3 wall and cpu ms, peak RSS (each minifier × fixture measured in its own worker process, so the numbers are attributable), and whether the output lost classes / changed the DOM ("rejects it" rows mean the tool errored on that input). They install the packages they compare against into `node_modules/.cache/` on first run rather than into webpack's dependencies; expect the first run to install for a minute and every full run to take a few. `check-comment-length.js` (`yarn lint:comments`) reports the plain comments a change grows past the two-line limit of [Code comments](#code-comments). `measure-color-agreement.js` (`yarn measure:color-agreement`) is the third: it asks a real browser for its own color conversions rather than for a pixel, and prints how far they sit from webpack's — which is where the rounding margins in `lib/css/syntax.js` and the list of spaces an engine reads through another transfer come from. Re-run it (a few seconds; `PUPPETEER_EXECUTABLE_PATH` picks the binary) rather than adjusting either by hand.
9595
- `assembly/` — WebAssembly source for the hash function.
9696
- `setup/` — One-time setup scripts.
9797

@@ -214,33 +214,21 @@ Every source file under `lib/` (and `hot/`, `tooling/`) opens with the MIT licen
214214

215215
> [!REQUIRED]
216216
217-
**This rule is about plain comments only** — `//` and `/* … */` narration inside `lib/`, `hot/`, `tooling/`, and `test/`. Those must be **as short as possible** — ideally one line, at most two short lines. Every line must add information a careful reader can't get from the code itself: a hidden invariant, a non-obvious ordering constraint, a workaround, or the name of the higher-level concept the block implements. **Never** write multi-paragraph essays, restate what the next line obviously does, narrate the diff, restate the PR description, or quote the user/task framing.
217+
**A plain comment is at most two lines. Count them.** This binds every `//` and `/* … */` in `lib/`, `hot/`, `tooling/` and `test/`, and every comment a generator emits into its output. A third line is over the limit however short each line is and however true every word — split the thought, cut it, or drop it.
218218

219-
**A JSDoc block's tags are exempt — they are the type contract, not commentary, and they are multi-line by construction.** One `@param` per parameter, an `@returns`, `@template`/`@typedef` where they apply. That holds for every documented symbol, exported or internal to one file: the tags are never something to shorten, flatten onto one line, or delete.
219+
**Check your own diff before every commit. It must print nothing:**
220220

221-
**The description above those tags is prose, so it is bound by the same brevity as a plain comment: one or two sentences, never more.** Say what the function does when the name alone doesn't carry it, plus the one invariant or non-obvious constraint a caller needs. A paragraph explaining the algorithm, the history, or the alternatives considered belongs in neither place — moving an essay from a `//` comment into a JSDoc description is not a fix, it is the same essay indented differently.
222-
223-
**So never trade a JSDoc block for a shorter comment.** Turning
224-
225-
```
226-
/**
227-
* An async external is a promise, not a module record with an evaluating state.
228-
* @param {Module} module the imported module
229-
* @returns {boolean} true when the module is an async external
230-
*/
231-
const isAsyncExternal = (module) => …
221+
```sh
222+
yarn lint:comments
232223
```
233224

234-
into
225+
It reports every plain comment your added lines grow past two, in either form, and exempts JSDoc. It is not part of `yarn lint`, which has no base branch to diff against.
235226

236-
```
237-
// An async external is a promise, not a module record with an evaluating state.
238-
const isAsyncExternal = (/** @type {Module} */ module) => …
239-
```
227+
Each surviving line must carry what the code cannot: a hidden invariant, an ordering constraint, a workaround, or the name of the concept the block implements. **Never** restate the next line, narrate the diff, recap the PR description, or quote the task you were given.
240228

241-
is a regression, not a cleanup: the parameter and return documentation is gone and the types now hide inside the signature. An inline `/** @type {T} */` cast on a parameter is for a throwaway callback argument, not for a named function — every named function, module-scope helper or not, gets a JSDoc block, and one carrying an explanation gets it whatever its scope.
229+
**A JSDoc block's tags are exempt** — they are the type contract, not commentary, and are multi-line by construction. Every named function gets one, module-scope helper or not: one `@param` per parameter, an `@returns`, `@template`/`@typedef` where they apply. Never shorten, flatten or delete a tag, and never trade a JSDoc block for a `//` comment that hides the types in an inline `/** @type {T} */` cast — that loses the parameter and return documentation. (Such a cast is for a throwaway callback argument only.)
242230

243-
Prose about a documented symbol goes **inside** its JSDoc, as the description above the tags — never as a `//` comment stacked on top of the block, and never as a `//` comment standing in for the block.
231+
**The description above those tags is prose, so it is capped at two sentences.** Say what the function does when its name doesn't, plus the one constraint a caller needs. Moving an essay out of a `//` comment into a JSDoc description is the same essay indented differently, not a fix — an explanation of the algorithm, the history, or the alternatives considered belongs in neither. Prose about a documented symbol goes inside its JSDoc, never as a `//` comment stacked on top of the block or standing in for it.
244232

245233
## Testing
246234

‎declarations/WebpackOptions.d.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2433,6 +2433,11 @@ export interface OptimizationMinimizeCss {
24332433
* @since 5.110.0
24342434
*/
24352435
convertLengthUnits?: boolean;
2436+
/**
2437+
* Write a spelling the `browserslist` target cannot read as one it can — the same value said another way, rather than left for an engine that will drop it: a 4-/8-digit hex as `rgba()`, a double-position gradient stop as the two stops it names, `inset` / `overflow` / `place-*` as the longhands they set, `text-decoration` as its own longhands where a slot is newer than the shorthand, `system-ui` as the stack of platform font names it stands for, a `:lang()` or `:not()` holding a list as the `:is()` that means it, a media feature range as the `min-`/`max-` pair, and `light-dark()` as the custom-property pair a color scheme switches. On by default, and only in effect for a `browserslist` target — any other target names no browsers to answer for. Off leaves every such spelling as written, which is how a stylesheet one of these rewrites gets wrong is minified; it never makes the minifier write a spelling the target cannot read.
2438+
* @since 5.111.0
2439+
*/
2440+
lowerUnsupported?: boolean;
24362441
/**
24372442
* Write a family of longhands as the one shorthand that sets them — four sides or corners, the two a pair shorthand sets, or the slots of an order-free one — even where unrelated declarations stand between them. On by default.
24382443
* @since 5.110.0
@@ -2464,7 +2469,7 @@ export interface OptimizationMinimizeCss {
24642469
*/
24652470
reduceFunctions?: boolean;
24662471
/**
2467-
* Drop a rule or declaration nothing can read: a rule whose block ends up empty, a declaration an identical later one in the same block makes dead, and a rule an identical later sibling makes dead. On by default. Joining rules that are not dead is `mergeRules`.
2472+
* Drop a rule or declaration nothing can read: a rule whose block ends up empty, a declaration a later one in the same block overrides, a rule an identical later sibling makes dead, and the `@charset` naming an encoding the output is not written in. On by default. Joining rules that are not dead is `mergeRules`.
24682473
* @since 5.110.0
24692474
*/
24702475
removeDeadRules?: boolean;
@@ -2479,7 +2484,7 @@ export interface OptimizationMinimizeCss {
24792484
*/
24802485
shortenColors?: boolean;
24812486
/**
2482-
* Write a media feature in its range spelling where the target reads one (`(min-width:100px)` -> `(width>=100px)`), and collapse an `and` of two one-sided ranges into the interval it describes. On by default.
2487+
* Shorten a rule's condition prelude: a media feature in its range spelling where the target reads one (`(min-width:100px)` -> `(width>=100px)`), an `and` of two one-sided ranges collapsed into the interval it describes, the `all` a query states before an `and` (which matches what the condition alone matches), and an operand a condition already states — in `@supports` and `@container` as well as `@media`. On by default.
24832488
* @since 5.110.0
24842489
*/
24852490
shortenMediaQueries?: boolean;

0 commit comments

Comments
 (0)