Skip to content

Commit c863119

Browse files
build(html): sweep the HTML printer for spelling-dependent output
`yarn check:html-invariants` holds the printer to two properties of its own, which is the class of defect `benchmark:html-tools` cannot see: being a few bytes off webpack's own best is not being worse than another tool. Minifying an already-minified page must change nothing, and a value's spelling must not decide what it minifies to. Respellings are lexical and checked against webpack's own tokenizer before use, so a mutation that moved the document is dropped rather than reported; each finding is bisected to the attributes carrying it and re-run on the enclosing tag alone, then grouped by that repro. Over `test/**/*.html` it names 112 findings in under two seconds, 40 of which #22095 fixes.
1 parent 55c9808 commit c863119

5 files changed

Lines changed: 885 additions & 1 deletion

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ The directory listings below are the canonical map of the repository. **Whenever
9292
- `lib/wasm/`, `lib/wasm-async/`, `lib/wasm-sync/` — WebAssembly module support.
9393
- `hot/` — Runtime code shipped to browsers for HMR (browser-side, not Node tooling).
9494
- `bin/` — `webpack` CLI entry point.
95-
- `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-tools.js` / `compare-html-tools.js` / `compare-js-tools.js` (`yarn benchmark:css-tools`, `yarn benchmark:html-tools`, `yarn benchmark:js-tools`), which share the measuring harness in `compare-tools-harness.js`. Those three need no arguments and no reading of their source: each runs what webpack owns for that language and the ecosystem's equivalents over popular framework stylesheets, real documents and shipped JavaScript bundles, printing **three tables per fixture** — parsing alone, parsing and printing readably (`beautify`), and parsing and printing minified (`minify`) — so what a parse costs is separated from what the printing and the transforms on top of it cost. Every table reports best-of-3 wall and cpu ms and the worker's own peak RSS (each tool × fixture measured in its own process, so the numbers are attributable; read from `/proc/self/status`, since Linux carries `maxRSS` across `fork`+`exec` and a worker asking for its own would report the parent's). **Read wall and cpu together**: cpu above wall is a tool using more than one core (V8's background threads, a native thread pool), cpu below it is a tool waiting rather than computing. A tool that works in a service process of its own says so in its name and reports `-` for cpu and peak, which are spent where nothing here can see them — esbuild is the one today. The two printing tables add output size raw and under gzip/brotli/zstd (the `test:size` settings) and whether the output lost classes / changed the DOM / stopped naming a property ("rejects it" rows mean the tool errored on that input). The JavaScript one is shaped by webpack owning a parser there and no printer: webpack has a row in the parse table only, and that table's last column holds every ESTree parser against acorn's tree and names the first node where the two differ — which is how a divergence in `lib/javascript/syntax.js` is caught — while a parser answering in a dialect of its own reads as `own dialect` rather than as a disagreement. A round-trip printer that reformats nothing — postcss for CSS, parse5 for HTML — sits in the `beautify` table as the floor the others are read against. `FIXTURE=`, `TOOL=` and `STAGE=` narrow a run to matching rows. 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 upwards of ten. `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.
95+
- `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-tools.js` / `compare-html-tools.js` / `compare-js-tools.js` (`yarn benchmark:css-tools`, `yarn benchmark:html-tools`, `yarn benchmark:js-tools`), which share the measuring harness in `compare-tools-harness.js`. Those three need no arguments and no reading of their source: each runs what webpack owns for that language and the ecosystem's equivalents over popular framework stylesheets, real documents and shipped JavaScript bundles, printing **three tables per fixture** — parsing alone, parsing and printing readably (`beautify`), and parsing and printing minified (`minify`) — so what a parse costs is separated from what the printing and the transforms on top of it cost. Every table reports best-of-3 wall and cpu ms and the worker's own peak RSS (each tool × fixture measured in its own process, so the numbers are attributable; read from `/proc/self/status`, since Linux carries `maxRSS` across `fork`+`exec` and a worker asking for its own would report the parent's). **Read wall and cpu together**: cpu above wall is a tool using more than one core (V8's background threads, a native thread pool), cpu below it is a tool waiting rather than computing. A tool that works in a service process of its own says so in its name and reports `-` for cpu and peak, which are spent where nothing here can see them — esbuild is the one today. The two printing tables add output size raw and under gzip/brotli/zstd (the `test:size` settings) and whether the output lost classes / changed the DOM / stopped naming a property ("rejects it" rows mean the tool errored on that input). The JavaScript one is shaped by webpack owning a parser there and no printer: webpack has a row in the parse table only, and that table's last column holds every ESTree parser against acorn's tree and names the first node where the two differ — which is how a divergence in `lib/javascript/syntax.js` is caught — while a parser answering in a dialect of its own reads as `own dialect` rather than as a disagreement. A round-trip printer that reformats nothing — postcss for CSS, parse5 for HTML — sits in the `beautify` table as the floor the others are read against. `FIXTURE=`, `TOOL=` and `STAGE=` narrow a run to matching rows. 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 upwards of ten. `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. `check-html-invariants.js` (`yarn check:html-invariants`) is the fourth, and the one that installs nothing: it holds the HTML printer to two properties of webpack's own — minifying an already-minified page changes nothing, and how a value was spelled does not decide what it minifies to — over `test/**/*.html` plus whatever documents the HTML comparison's cache holds, in a couple of seconds. This is the shape of defect a comparison cannot see, because being a few bytes off its own best is not being worse than another tool: `method=GET` folding only where the source quoted it went unnoticed until this sweep, which is what #22095 fixed. A respelling is lexical (a delimiter, a character reference, the case of a name) and is checked against webpack's own tokenizer before use, so a mutation that moved the document is dropped rather than reported; whitespace inside a tag is deliberately not one, since a tag nothing beats is echoed as written. Each finding is bisected to the attributes carrying it and re-run on the enclosing tag alone, so the report names a repro, and groups by it — one printer defect reaches hundreds of pages. `FIXTURE=`, `RELATION=`, `PRESET=` and `SPELLING=` narrow a run. It exits non-zero while any finding stands and findings stand today, so read it rather than gating on it, and no embedded body is minified: the CSS minifier has a fixed point of its own and reaching it here would report every page holding a `<style>`.
9696
- `assembly/` — WebAssembly source for the hash function.
9797
- `setup/` — One-time setup. `setup.js` (`yarn setup`) is the only entry point and picks its own path: a contributor at a terminal gets the interactive one, which installs yarn when it is missing and links through yarn's registry, while everything else gets the non-interactive one — it verifies the lockfile instead of rewriting it, installs no global yarn, and links the checkout in as `node_modules/webpack` without touching yarn's machine-global registry. What it reads is both streams being a terminal plus an unset `CI`, never a list of vendor variables, so an agent nobody has heard of yet takes the safe path — but one that allocates a PTY reads as a contributor, and should set `WEBPACK_SETUP=automated`, which with `interactive` forces either path. Safe to re-run.
9898

‎cspell.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -380,6 +380,7 @@
380380
"repos",
381381
"repr",
382382
"resizer",
383+
"respellings",
383384
"return'development",
384385
"returnfalse",
385386
"revparse",

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@
5959
"benchmark:html-tools:setup": "node tooling/compare-html-tools.js --setup",
6060
"benchmark:js-tools": "node tooling/compare-js-tools.js",
6161
"measure:color-agreement": "node tooling/measure-color-agreement.js",
62+
"check:html-invariants": "node tooling/check-html-invariants.js",
6263
"pretest": "yarn lint",
6364
"test": "yarn test:base",
6465
"test:base": "node --expose-gc --max-old-space-size=4096 --experimental-vm-modules --trace-deprecation node_modules/jest-cli/bin/jest --workerIdleMemoryLimit=512MB --logHeapUsage",
Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
"use strict";
2+
3+
const {
4+
RESPELLINGS,
5+
attributeSites,
6+
oneLine,
7+
respell,
8+
sweepDocument,
9+
tokenStream
10+
} = require("../tooling/check-html-invariants");
11+
12+
// One attribute per value shape the respellings have to decide about: a
13+
// delimiter inside the value, a reference, a space, `>`, and an astral character.
14+
const SHAPES =
15+
'<input a="1" b=\'q"t\' c=bare d e="a&amp;b" f="a>b" g="x y" h="&#x1f600;">';
16+
17+
describe("check-html-invariants", () => {
18+
describe("attributeSites", () => {
19+
it("reports every attribute with the tag holding it", () => {
20+
const sites = attributeSites('<p id=a class="b c">t</p>');
21+
expect(sites.map((site) => [site.name, site.value])).toEqual([
22+
["id", "a"],
23+
["class", "b c"]
24+
]);
25+
expect(sites.map((site) => [site.tagStart, site.tagEnd])).toEqual([
26+
[0, 20],
27+
[0, 20]
28+
]);
29+
});
30+
31+
it("reads a valueless attribute as an empty value", () => {
32+
expect(attributeSites("<input checked>")[0]).toMatchObject({
33+
name: "checked",
34+
value: ""
35+
});
36+
});
37+
38+
it("leaves a close tag's attributes alone, as the tree builder does", () => {
39+
expect(attributeSites("<p>t</p id=a>")).toEqual([]);
40+
});
41+
42+
it("decodes a value through its references", () => {
43+
expect(
44+
attributeSites('<a t="a&amp;b&#x3c;c">').map((s) => s.value)
45+
).toEqual(["a&b<c"]);
46+
});
47+
});
48+
49+
describe("tokenStream", () => {
50+
it("reads three spellings of one attribute identically", () => {
51+
const quoted = tokenStream('<form method="get">');
52+
expect(tokenStream("<form method=get>")).toBe(quoted);
53+
expect(tokenStream('<form method="&#x67;et">')).toBe(quoted);
54+
expect(tokenStream("<FORM METHOD='get'>")).toBe(quoted);
55+
});
56+
57+
it("separates two documents that say different things", () => {
58+
expect(tokenStream("<form method=get>")).not.toBe(
59+
tokenStream("<form method=post>")
60+
);
61+
expect(tokenStream("<input checked>")).not.toBe(
62+
tokenStream("<input checked=checked>")
63+
);
64+
});
65+
});
66+
67+
describe("respell", () => {
68+
for (const respelling of RESPELLINGS) {
69+
it(`keeps what the document says through ${respelling.name}`, () => {
70+
const respelled = respell(SHAPES, attributeSites(SHAPES), respelling);
71+
expect(respelled).not.toBe(SHAPES);
72+
expect(tokenStream(respelled)).toBe(tokenStream(SHAPES));
73+
});
74+
}
75+
76+
it("declines a value no delimiter can hold", () => {
77+
const respelling =
78+
/** @type {import("../tooling/check-html-invariants").Respelling} */ (
79+
RESPELLINGS.find((one) => one.name === "unquote")
80+
);
81+
const respelled = respell(SHAPES, attributeSites(SHAPES), respelling);
82+
expect(respelled).toContain('g="x y"');
83+
expect(respelled).toContain('f="a>b"');
84+
expect(respelled).toContain("c=bare");
85+
});
86+
});
87+
88+
describe("oneLine", () => {
89+
// Built rather than written: a control character in this file makes git
90+
// read it as binary and stop showing its diff.
91+
const control = (/** @type {number} */ code) => String.fromCharCode(code);
92+
93+
it("shows a control character the whitespace collapse would hide", () => {
94+
expect(oneLine(`a${control(0x0b)}b`, 40)).toBe("a\\x0bb");
95+
expect(oneLine(`a${control(0)}b`, 40)).toBe("a\\x00b");
96+
});
97+
98+
it("collapses the whitespace a tag is written with", () => {
99+
expect(oneLine("<p\n\tid=a\t>", 40)).toBe("<p id=a >");
100+
});
101+
102+
it("cuts what is past the limit", () => {
103+
expect(oneLine("abcdef", 4)).toBe("abc…");
104+
});
105+
});
106+
107+
describe("sweepDocument", () => {
108+
it("reports nothing about a printer that is stable and spelling-blind", () => {
109+
// Canonicalizing, so every spelling of the tag reaches one output. An
110+
// identity printer is not it: echoing a respelling is depending on it.
111+
const minify = (/** @type {string} */ html) =>
112+
html.replace(/^<(\w+)[\S\s]*>$/, "<$1>");
113+
expect(sweepDocument(minify, SHAPES)).toEqual([]);
114+
});
115+
116+
it("reports a printer whose second pass moves", () => {
117+
// One space per pass, so no pass is ever the last.
118+
const minify = (/** @type {string} */ html) => html.replace(" ", "");
119+
const reports = sweepDocument(minify, SHAPES);
120+
expect(reports.map((one) => one.relation)).toContain("idempotence");
121+
});
122+
123+
it("reports a printer that folds one spelling and not another", () => {
124+
// Reaches the quoted spelling only, which is the shape of the defect
125+
// this sweep exists for.
126+
const minify = (/** @type {string} */ html) =>
127+
html.replace(/[=]"GET"/g, '="get"');
128+
const reports = sweepDocument(minify, '<form method="GET">');
129+
expect(reports.map((one) => one.relation)).toContain(
130+
"respelling unquote"
131+
);
132+
});
133+
134+
it("reports a printer that throws on a respelling", () => {
135+
const minify = (/** @type {string} */ html) => {
136+
if (html.includes("&#x")) throw new Error("nope");
137+
return html;
138+
};
139+
const reports = sweepDocument(minify, '<a t="ab">');
140+
expect(reports).toContainEqual(
141+
expect.objectContaining({
142+
relation: "respelling references",
143+
what: "threw: nope"
144+
})
145+
);
146+
});
147+
});
148+
});

0 commit comments

Comments
 (0)