You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 59ac091
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: tooling/COMPARE_TOOLS.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@
7
7
- Printing tables add output size raw and gzip/brotli/zstd (`test:size` settings), whether the output lost classes / changed the DOM / stopped naming a property / dropped a legal notice (CSS and JS: a `/*!` comment, and in JS one naming `@license` or `@preserve`) ("rejects it" = the tool errored), and `2nd`: what printing the output again moved — the idempotence question asked of every tool (`-` is a printer done printing). A round-trip printer that reformats nothing (postcss for CSS, parse5 for HTML) sits in `beautify` as the floor.
8
8
- XML: every output is read back with `@rgrove/parse-xml`, a strict parser sharing nothing with webpack's, so `differs` also says when an output stopped being well-formed. webpack's `minify` row hands each SVG or XHTML stylesheet to `builtinEmbeddedRenderer`, as a build does.
9
9
- JS: webpack's parse row is its own parser; its `webpack` printing row is `lib/javascript/jsMinify.js` (the build's minify entry, one `SourceProcessor` pass that compresses and mangles), while `webpack printer` is the same work as one `SourceProcessor` run without that function around it, so the two are read against each other in the same table. The parse table's last column compares each ESTree parser to acorn's tree and names the first differing node; with the `spans` relation this catches a divergence in `lib/javascript/syntax-parser.js` (one reads the tree, the other the offsets — a range can be wrong while every node agrees). A parser with a dialect of its own reads `own dialect`, not a disagreement.
10
-
- CSS, HTML and XML: the parse table's last column holds each parser to a reference — css-tree, parse5 (the §13.2 tree, with scripting off and again on, as the printer reads), `@rgrove/parse-xml` — and names the first differing node by its path (`/html[1]/body[1]/p[2]`), then how many more differences follow. The trees are aligned first (Myers' diff), so a node one side lacks is one difference rather than one per node after it. Both trees are flattened the same way: elements with their namespace and attributes in order, text with runs folded, comments, doctype nodes and processing instructions (HTML reads `<?…>` as the bogus comment §13.2 makes of it); CSS rules, at-rules and declarations, each prelude and value as its source wrote it, comments dropped and whitespace collapsed. Held: webpack everywhere, postcss (CSS), `@xmldom/xmldom` and htmlparser2 (XML); a parser building no tree, or a tree of its own, reads `own dialect`. Where a reader can see a reference's gap, it closes it, so a disagreement names something real: css-tree's reading of a style rule's block, which it gives up on once declarations and rules mix and reads an at-rule's block in as rules alone, is read again declarations first, and again from any declaration a rule read swallowed into its selector; a declaration whose name opens with no identifier (`*zoom`) is dropped, as the spec drops it, and postcss's `_prop` hack is read back as written; webpack's block contents are compared in source order, though its walk visits declarations before nested rules; and a `<?…` the input runs out in is dropped from parse5's tree where webpack's processing instruction rules drop it. parse-xml reads no DTD, so a source it rejects is read again with the general entities the internal subset declares, where each value is plain text once its character references are decoded. Left as disagreements: parse5 has no declarative shadow root (`<template shadowrootmode>`) or customizable `<select>`, and css-tree recovers from some invalid CSS other than the spec does. Both sides of a cell are cut from just before the first character they differ at. For webpack the column is also an invariant (`agreement`, below).
10
+
- CSS, HTML and XML: the parse table's last column holds each parser to a reference — css-tree, parse5 (the §13.2 tree, with scripting off and again on, as the printer reads), `@rgrove/parse-xml` — and names the first differing node by its path (`/html[1]/body[1]/p[2]`), then how many more differences follow. The trees are aligned first (Myers' diff), so a node one side lacks is one difference rather than one per node after it. Both trees are flattened the same way: elements with their namespace and attributes in order, text with runs folded, comments, doctype nodes with their public and system identifiers, and processing instructions (HTML reads `<?…>` as the bogus comment §13.2 makes of it); CSS rules, at-rules and declarations, names decoded and each prelude and value as its source wrote it, comments dropped and whitespace collapsed. Held: webpack everywhere, postcss (CSS), `@xmldom/xmldom` and htmlparser2 (XML); a parser building no tree, or a tree of its own, reads `own dialect`. Where a reader can see a reference's gap, it closes it, so a disagreement names something real: css-tree's reading of a style rule's block, which it gives up on once declarations and rules mix and reads an at-rule's block in as rules alone, is read again declarations first, and again from any declaration a rule read swallowed into its selector; a declaration whose name opens with no identifier (`*zoom`) is dropped, as the spec drops it, and postcss's `_prop` hack is read back as written; webpack's block contents are compared in source order, though its walk visits declarations before nested rules; and a `<?…` the input runs out in is dropped from parse5's tree where webpack's processing instruction rules drop it. parse-xml reads no DTD, so a source it rejects is read again with the general entities the internal subset declares, where each value is plain text once its character references are decoded. Left as disagreements: parse5 has no declarative shadow root (`<template shadowrootmode>`) or customizable `<select>`, and css-tree recovers from some invalid CSS other than the spec does. Both sides of a cell are cut from just before the first character they differ at. For webpack the column is also an invariant (`agreement`, below).
11
11
-`FIXTURE=`, `TOOL=`, `STAGE=` narrow the rows. `PROFILE=1` samples each row's timed runs and lists under it where the CPU went, by file (terser's and webpack's by their path in `lib`, `(generated)` for `new Function` code) — the attribution a phase is chosen and judged by.
12
12
- **Corpora** are declared in `tooling/comparison/<cache name>/`: a `package.json` pinning every package exactly and a `package-lock.json` freezing the resolution, transitive deps included, so a sweep runs what was committed rather than what the registry serves that day, and a finding names a reproducible corpus. `installPackages` runs `npm ci` into `node_modules/.cache/<cache name>/` (not webpack's deps) on first run, skipped while the lockfile it last installed from matches; expect ~a minute of install first, and 10+ minutes per full run. Bump a corpus by editing its manifest, never the script. Dependabot watches the four directories, so a bump arrives as its own PR — where a break is attributable, not on somebody else's — and there the `invariants` job — which installs and sweeps all four — reds on a broken printer invariant, an `npm ci`-refused manifest/lockfile, or a platform package the lockfile misses (`yarn benchmark:<language>-tools:setup` is the install alone). Each corpus keeps an `.npmrc` with `package-lock=true`: Dependabot reads npm config from parent directories (npm doesn't), so otherwise the root's `package-lock=false` (right for yarn's tree) leaves a bump's lockfile unregenerated — exactly what `npm ci` refuses.
13
13
-**Single stylesheets** the CSS corpus reads out of packages whose dependency trees dwarf them (component libraries, design systems) are listed in `tooling/comparison/css-tool-comparison/stylesheets.json` instead: each is fetched with `npm pack` at its pinned version, checked against its pinned integrity, and only that one file is kept, under `stylesheets/` in the cache. Dependabot does not see these, so a bump edits the version and integrity by hand (`npm view <package>@<version> dist.integrity`).
0 commit comments