Skip to content

Commit 1d6bcee

Browse files
docs(tooling): keep XML comparison guidance general
1 parent 9099f00 commit 1d6bcee

1 file changed

Lines changed: 1 addition & 1 deletion

File tree

‎tooling/COMPARE_TOOLS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
- `compare-css-tools.js` / `compare-html-tools.js` / `compare-js-tools.js` / `compare-xml-tools.js` (`yarn benchmark:css-tools` / `:html-tools` / `:js-tools` / `:xml-tools`, sharing `compare-tools-harness.js`) — no arguments or source reading needed. Each runs webpack's implementation for the language and ecosystem equivalents over popular framework stylesheets, real documents, shipped JS bundles and SVG/XML files.
66
- **Three tables per fixture**: parse only, parse + readable print (`beautify`), parse + minified print (`minify`) — separating parse cost from printing/transform cost. Each shows best-of-3 wall and cpu ms and the worker's peak RSS, every tool × fixture in its own process; RSS comes from `/proc/self/status`, since Linux carries `maxRSS` across `fork`+`exec` and a worker asking for its own gets the parent's. **Read wall and cpu together**: cpu above wall = more than one core (V8 background threads, a native pool); below = waiting. A tool working in its own service process says so in its name and shows `-` for cpu and peak (esbuild today).
77
- 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 ("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-
- XML: svgo has single-pass and multipass rows and runs only over documents whose root is SVG, and 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.
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.
99
- JS: webpack's parse row is its own parser; its `webpack` printing rows are `lib/javascript/jsMinify.js` (the build's minify entry, printing through terser by default), while `webpack printer` is the same work through `syntax-printer.js`, so the two are read against each other in the same table. `webpack (2 passes)` uses `optimization.minimize`'s default options, so it isn't like for like with terser's default row. 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.
1010
- `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.
1111
- **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.

0 commit comments

Comments
 (0)