Skip to content

Commit eba6cf0

Browse files
build(tooling): close the reference parsers' gaps in the parser-agreement column (#22937)
* build(tooling): close the reference parsers' gaps in the parser-agreement column Re-read what css-tree gives up on inside a style rule, drop declarations the spec drops, compare webpack's CSS blocks in source order, mirror webpack's processing instruction rules in parse5's tree, and cut both sides of a cell at the first character they differ at. * build(tooling): find an EOF processing instruction by position and keep postcss declarations after a stray semicolon
1 parent 49fb573 commit eba6cf0

7 files changed

Lines changed: 473 additions & 63 deletions

File tree

‎test/unitCases/tooling/compare-css.unittest.js‎

Lines changed: 184 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -227,12 +227,191 @@ describe("compare-css-tools — agreeing with css-tree", () => {
227227
expect(await cell("postcss")).toBe("yes");
228228
});
229229

230-
it("names a block css-tree left unparsed", async () => {
231-
mockCssTree.parse.mockReturnValue(
232-
parsed({ type: "Raw", ...at(".b{x:y;z:}") })
230+
/**
231+
* @param {string} source a stylesheet
232+
* @returns {(text: string, before?: string) => { loc: { start: { offset: number }, end: { offset: number } } }} where a part of it is
233+
*/
234+
const within = (source) => (text, before = "") => {
235+
const offset = source.indexOf(before + text) + before.length;
236+
return { loc: { start: { offset }, end: { offset: offset + text.length } } };
237+
};
238+
239+
/**
240+
* A css-tree that answers each parse from a table, keyed by the context
241+
* it is asked for and the offset it starts at.
242+
* @param {Record<string, EXPECTED_ANY[]>} answers the nodes each parse returns
243+
*/
244+
const answering = (answers) => {
245+
mockCssTree.parse.mockImplementation(
246+
(
247+
/** @type {string} */ _text,
248+
/** @type {{ context: string, offset: number }} */ options
249+
) => ({ children: answers[`${options.context}@${options.offset}`] })
233250
);
234-
expect(await agreement("css-tree", TREE_READERS, css)("webpack")).toBe(
235-
"no — /.a .d[1]: css-tree unparsed .b{x:y;z:}, tool rule .b"
251+
};
252+
253+
it("reads again a style rule's block css-tree gave up on, and holds webpack in source order", async () => {
254+
// Declarations around a nested rule and a nested at-rule holding declarations.
255+
const source = ".a{color:red;.b{x:y}@media (x){top:0}left:0}";
256+
const loc = within(source);
257+
const raw = ".b{x:y}@media (x){top:0}left:0";
258+
answering({
259+
"stylesheet@0": [
260+
{
261+
type: "Rule",
262+
prelude: loc(".a"),
263+
block: {
264+
children: [
265+
{
266+
type: "Declaration",
267+
property: "color",
268+
important: false,
269+
value: loc("red")
270+
},
271+
{ type: "Raw", ...loc(raw) }
272+
]
273+
}
274+
}
275+
],
276+
[`declarationList@${source.indexOf(raw)}`]: [{ type: "Raw", ...loc(raw) }],
277+
[`stylesheet@${source.indexOf(raw)}`]: [
278+
{
279+
type: "Rule",
280+
prelude: loc(".b"),
281+
block: {
282+
children: [
283+
{
284+
type: "Declaration",
285+
property: "x",
286+
important: false,
287+
value: loc("y")
288+
}
289+
]
290+
}
291+
},
292+
{
293+
type: "Atrule",
294+
name: "media",
295+
prelude: loc("(x)"),
296+
block: loc("{top:0}")
297+
},
298+
{ type: "Raw", ...loc("left:0") }
299+
],
300+
[`declarationList@${source.indexOf("top:0")}`]: [
301+
{
302+
type: "Declaration",
303+
property: "top",
304+
important: false,
305+
value: loc("0", "top:")
306+
}
307+
],
308+
[`declarationList@${source.indexOf("left:0")}`]: [
309+
{
310+
type: "Declaration",
311+
property: "left",
312+
important: false,
313+
value: loc("0", "left:")
314+
}
315+
]
316+
});
317+
const cell = agreement("css-tree", TREE_READERS, source);
318+
expect(await cell("webpack")).toBe("yes");
319+
expect(await cell("postcss")).toBe("yes");
320+
});
321+
322+
it("reads a nested at-rule the input ends inside", async () => {
323+
const source = ".a{@media (x){top:0";
324+
const loc = within(source);
325+
answering({
326+
"stylesheet@0": [
327+
{
328+
type: "Rule",
329+
prelude: loc(".a"),
330+
block: {
331+
children: [
332+
{
333+
type: "Atrule",
334+
name: "media",
335+
prelude: loc("(x)"),
336+
block: loc("{top:0")
337+
}
338+
]
339+
}
340+
}
341+
],
342+
[`declarationList@${source.indexOf("top")}`]: [
343+
{
344+
type: "Declaration",
345+
property: "top",
346+
important: false,
347+
value: loc("0")
348+
}
349+
]
350+
});
351+
expect(await agreement("css-tree", TREE_READERS, source)("webpack")).toBe(
352+
"yes"
236353
);
237354
});
355+
356+
it("names what css-tree can't read as declarations or rules", async () => {
357+
const source = ".a{%}";
358+
const loc = within(source);
359+
answering({
360+
"stylesheet@0": [
361+
{
362+
type: "Rule",
363+
prelude: loc(".a"),
364+
block: { children: [{ type: "Raw", ...loc("%") }] }
365+
}
366+
],
367+
"declarationList@3": [{ type: "Raw", ...loc("%") }],
368+
"stylesheet@3": []
369+
});
370+
expect(await agreement("css-tree", TREE_READERS, source)("webpack")).toBe(
371+
"no — /.a[1]: css-tree unparsed %, tool }"
372+
);
373+
answering({ "stylesheet@0": [{ type: "Raw", ...within("%")("%") }] });
374+
expect(await agreement("css-tree", TREE_READERS, "%")("webpack")).toBe(
375+
"no — /: css-tree unparsed %, tool nothing"
376+
);
377+
});
378+
379+
it("drops an IE hack the spec drops, and reads postcss's as written", async () => {
380+
const source =
381+
".a{*zoom:1;;_display:inline;-webkit-box:2;--v:3;-1x:4;\\61:5;-\\62:6}";
382+
const loc = within(source);
383+
/**
384+
* @param {string} property a declaration's name, as written
385+
* @param {string} value its value, written once in the source
386+
* @returns {EXPECTED_ANY} the css-tree declaration
387+
*/
388+
const declared = (property, value) => ({
389+
type: "Declaration",
390+
property,
391+
important: false,
392+
value: loc(value, `${property}:`)
393+
});
394+
answering({
395+
"stylesheet@0": [
396+
{
397+
type: "Rule",
398+
prelude: loc(".a"),
399+
block: {
400+
children: [
401+
declared("*zoom", "1"),
402+
declared("_display", "inline"),
403+
declared("-webkit-box", "2"),
404+
declared("--v", "3"),
405+
declared("-1x", "4"),
406+
declared("\\61", "5"),
407+
declared("-\\62", "6")
408+
]
409+
}
410+
}
411+
]
412+
});
413+
const cell = agreement("css-tree", TREE_READERS, source);
414+
expect(await cell("webpack")).toBe("yes");
415+
expect(await cell("postcss")).toBe("yes");
416+
});
238417
});

‎test/unitCases/tooling/compare-harness.unittest.js‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1123,6 +1123,15 @@ describe("parser agreement", () => {
11231123
expect(treeDifference(deep("a"), deep("b"), "ref")).toBe(
11241124
`…${"/section[1]".repeat(20).slice(-59)}: ref a, tool b`
11251125
);
1126+
// Two sides alike past the cut are shown from just before they differ.
1127+
const long = (/** @type {string} */ tail) => {
1128+
const events = new TreeEvents();
1129+
events.leaf(`<path d="${"m0 0".repeat(20)}${tail}">`);
1130+
return events;
1131+
};
1132+
expect(treeDifference(long("h1"), long("v1"), "ref")).toBe(
1133+
'/: ref …m0 0m0 0m0 0h1">, tool …m0 0m0 0m0 0v1">'
1134+
);
11261135
});
11271136

11281137
it("answers each parser's cell, reading the reference once", async () => {

‎test/unitCases/tooling/compare-html.unittest.js‎

Lines changed: 65 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -308,7 +308,71 @@ describe("compare-html-tools — agreeing with parse5", () => {
308308
expect(await cell("htmlparser2")).toBe("own dialect");
309309
expect(await cell("webpack")).toBe("yes");
310310
// The byte order mark is the decoder's, gone before tree construction.
311-
expect(mockParse5.parse).toHaveBeenLastCalledWith(html.slice(1));
311+
expect(mockParse5.parse).toHaveBeenLastCalledWith(html.slice(1), {
312+
sourceCodeLocationInfo: true
313+
});
314+
});
315+
316+
// Each a `<?…` the input runs out in, which webpack's processing instruction
317+
// rules drop or keep as a comment; parse5 always keeps the bogus comment.
318+
it.each([
319+
["nothing after `<?`", "?"],
320+
["a cut target", "?x"],
321+
["a cut instruction", "?x y"],
322+
["a target no name starts", "?1x"],
323+
["a target spelled out of name characters", "?x$y"],
324+
["a target the XML reserves", "?xml v"],
325+
["a target the XML reserves, before a line break", "?xml\nv"]
326+
])("agrees about %s at the end of the input", async (_name, data) => {
327+
const source = `<p>a</p><${data}`;
328+
mockParse5.parse.mockReturnValue({
329+
nodeName: "#document",
330+
childNodes: [
331+
element("html", HTML_NAMESPACE, [
332+
element("head", HTML_NAMESPACE, []),
333+
element("body", HTML_NAMESPACE, [
334+
element("p", HTML_NAMESPACE, [{ nodeName: "#text", value: "a" }]),
335+
{
336+
nodeName: "#comment",
337+
data,
338+
sourceCodeLocation: {
339+
startOffset: source.indexOf("<?"),
340+
// Where parse5 ends a token the input ran out in.
341+
endOffset: source.length + 1
342+
}
343+
}
344+
])
345+
])
346+
]
347+
});
348+
expect(await agreement("parse5", TREE_READERS, source)("webpack")).toBe(
349+
"yes"
350+
);
351+
});
352+
353+
it("keeps a closed `<?…>` whose text the input happens to end with", async () => {
354+
const source = "<?x y><script><?x y";
355+
mockParse5.parse.mockReturnValue({
356+
nodeName: "#document",
357+
childNodes: [
358+
{
359+
nodeName: "#comment",
360+
data: "?x y",
361+
sourceCodeLocation: { startOffset: 0, endOffset: 6 }
362+
},
363+
element("html", HTML_NAMESPACE, [
364+
element("head", HTML_NAMESPACE, [
365+
element("script", HTML_NAMESPACE, [
366+
{ nodeName: "#text", value: "<?x y" }
367+
])
368+
]),
369+
element("body", HTML_NAMESPACE, [])
370+
])
371+
]
372+
});
373+
expect(await agreement("parse5", TREE_READERS, source)("webpack")).toBe(
374+
"yes"
375+
);
312376
});
313377

314378
it("names the first node the two trees differ at", async () => {

‎tooling/COMPARE_TOOLS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
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 / 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.
88
- 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.
10-
- CSS, HTML and XML: the parse table's last column holds each parser to a reference — css-tree, parse5 (the §13.2 tree), `@rgrove/parse-xml` — and names the first differing node by its path (`/html[1]/body[1]/p[2]`). 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`. A reference's own gaps read as disagreements too: css-tree leaves a nested rule it can't parse as `unparsed` and keeps IE hacks (`*zoom`) the spec drops; webpack's tree keeps a `<template shadowrootmode>` and a customizable `<select>`'s `<button>`, where parse5's has neither. Table-only, never a gate.
10+
- CSS, HTML and XML: the parse table's last column holds each parser to a reference — css-tree, parse5 (the §13.2 tree), `@rgrove/parse-xml` — and names the first differing node by its path (`/html[1]/body[1]/p[2]`). 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; 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. 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. Table-only, never a gate.
1111
- `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.
1212
- **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.
1313
- **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

Comments
 (0)