Skip to content

Commit 55cc577

Browse files
ci: report the deep imports a pull request breaks
The record already said which `webpack/lib/…` paths published plugins and loaders import, but only someone running the check by hand learned that a move broke one. `--check` now writes the finding as markdown, and a job posts it on the pull request: which path stopped resolving, which packages import it and how many weekly downloads sit behind them. It comments only once there is something to say and edits that comment away when the paths resolve again, so a green pull request stays quiet. The check reads the record and the checkout alone, so the job needs no install and no network — `prettier` moves into the one function that writes the record. It runs in under a second, and fails after commenting so the thread names the break rather than only the red check.
1 parent 2c61121 commit 55cc577

3 files changed

Lines changed: 170 additions & 5 deletions

File tree

‎.github/workflows/deep-imports.yml‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
name: Deep Imports
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
workflow_dispatch:
9+
10+
concurrency:
11+
group: ${{ github.workflow }}-${{ github.ref }}
12+
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
13+
14+
permissions:
15+
contents: read
16+
# Posting the report as a pull request comment.
17+
pull-requests: write
18+
19+
jobs:
20+
deep-imports:
21+
runs-on: ubuntu-latest
22+
steps:
23+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
24+
25+
- name: Use Node.js
26+
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
27+
with:
28+
node-version: lts/*
29+
30+
# No install: `--check` reads the recorded scan and this checkout, and
31+
# nothing else. It takes no network and runs in well under a second.
32+
- name: Check the paths the ecosystem imports directly
33+
id: check
34+
run: |
35+
if node tooling/find-deep-webpack-imports.js \
36+
--check --summary deep-imports-report.md; then
37+
echo "broken=false" >> "$GITHUB_OUTPUT"
38+
else
39+
echo "broken=true" >> "$GITHUB_OUTPUT"
40+
fi
41+
cat deep-imports-report.md >> "$GITHUB_STEP_SUMMARY"
42+
43+
# Only once something is broken, and afterwards to retract it — a comment
44+
# on every green pull request is noise nobody reads. Skipped for forks,
45+
# whose token cannot comment; the job summary still carries the report.
46+
- name: Comment the report on the pull request
47+
if: >
48+
github.event_name == 'pull_request' &&
49+
github.event.pull_request.head.repo.full_name == github.repository
50+
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
51+
env:
52+
BROKEN: ${{ steps.check.outputs.broken }}
53+
with:
54+
script: |
55+
const body = require("fs").readFileSync("deep-imports-report.md", "utf8");
56+
const marker = "<!-- deep-imports-report -->";
57+
const comments = await github.paginate(
58+
github.rest.issues.listComments,
59+
{ ...context.repo, issue_number: context.issue.number, per_page: 100 }
60+
);
61+
// Only a comment this workflow itself wrote: anyone can post one
62+
// carrying the marker, and overwriting it would let them edit the
63+
// report afterwards and pass their own findings off as CI's.
64+
const previous = comments.find(
65+
(comment) =>
66+
comment.user.type === "Bot" &&
67+
comment.user.login === "github-actions[bot]" &&
68+
comment.body.startsWith(marker)
69+
);
70+
if (previous) {
71+
await github.rest.issues.updateComment({
72+
...context.repo,
73+
comment_id: previous.id,
74+
body
75+
});
76+
} else if (process.env.BROKEN === "true") {
77+
await github.rest.issues.createComment({
78+
...context.repo,
79+
issue_number: context.issue.number,
80+
body
81+
});
82+
}
83+
84+
# After the comment, so the thread names what failed rather than only the
85+
# red check.
86+
- name: Fail on a path that stopped resolving
87+
if: steps.check.outputs.broken == 'true'
88+
run: exit 1

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ The directory listings below are the canonical map of the repository. **Whenever
109109
- `lib/watch/` — Watch mode: the watching handles a compiler returns, and `WatchIgnorePlugin`.
110110
- `hot/` — Runtime code shipped to browsers for HMR (browser-side, not Node tooling).
111111
- `bin/` — `webpack` CLI entry point.
112-
- `tooling/` — Repo-internal scripts: build/codegen (runtime/wasm generators, hash-debug tool, and `generate-types.js`, the one entry point and one file for everything derived from `schemas/**/*.json` — it reads each schema once, emits that schema's declaration and its precompiled validator, then emits `types.d.ts`, so ordering is internal and one check run names every stale output) 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), plus what printing the output a second time moved (`2nd`). 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. `type-coverage.js` (`yarn types:cover`) reports how much of `lib/` is precisely typed. `find-deep-webpack-imports.js` (`yarn find-deep-imports`) answers which `webpack/lib/…` paths the published ecosystem imports directly: it ranks the most downloaded `webpack`, `webpack-plugin` and `webpack-loader` packages off the registry's search endpoint — which carries weekly downloads with each hit, so `api.npmjs.org` is never needed — then reads each one's tarball rather than installing it, so no lifecycle script of a stranger's package runs. It counts a path only where it is imported, never a bare string, because a package that bundled webpack carries webpack's own `makeSerializable` requests and imports none of them. What it finds is kept in `tooling/deep-webpack-imports.json`, which `--write` refreshes and whose `removed` map names the paths no webpack 5 build can reach with the reason — deleted with the webpack 4 API, imported only by a package that is webpack 4 only, or probed for inside a `try` to detect webpack 4, where a re-export would pick the wrong branch — so only a genuine break fails. `--check` reads that record and nothing else — no network — and fails when a recorded path stopped resolving, naming the packages and the downloads behind it; `test/unitCases/deepPathShims.unittest.js` asserts the same thing off the same record, so a move out of `lib/` root learns it owes a re-export from a test rather than from a bug report. `COUNT=` sets how many packages per keyword (default 200), and a package the broad keyword shares with a narrow one is scanned once; tarballs cache under `node_modules/.cache/`, so a re-run costs nothing. Only the collecting half needs the network. `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. **The CSS and HTML comparisons open with a section no one has to ask for**: before the install, each holds webpack's own printer to what it owes whatever it printed, over `test/**/*.css` / `test/**/*.html` plus its own fixtures and whatever the cache already holds, in seconds rather than minutes. `--invariants` runs that section and stops, for a caller that wants the relations without the comparison behind them. Two relations, under each option set the script's own webpack rows are measured with: minifying an already-minified source changes nothing, and (HTML) how a value was spelled does not decide what it minifies to. 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 what carries 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. `--invariants` 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>`. The same question is asked of every other tool in the comparison's own tables, where the `2nd` column is what a second pass over the tool's own output moved — `-` being the answer a printer that is done printing gives.
112+
- `tooling/` — Repo-internal scripts: build/codegen (runtime/wasm generators, hash-debug tool, and `generate-types.js`, the one entry point and one file for everything derived from `schemas/**/*.json` — it reads each schema once, emits that schema's declaration and its precompiled validator, then emits `types.d.ts`, so ordering is internal and one check run names every stale output) 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), plus what printing the output a second time moved (`2nd`). 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. `type-coverage.js` (`yarn types:cover`) reports how much of `lib/` is precisely typed. `find-deep-webpack-imports.js` (`yarn find-deep-imports`) answers which `webpack/lib/…` paths the published ecosystem imports directly: it ranks the most downloaded `webpack`, `webpack-plugin` and `webpack-loader` packages off the registry's search endpoint — which carries weekly downloads with each hit, so `api.npmjs.org` is never needed — then reads each one's tarball rather than installing it, so no lifecycle script of a stranger's package runs. It counts a path only where it is imported, never a bare string, because a package that bundled webpack carries webpack's own `makeSerializable` requests and imports none of them. What it finds is kept in `tooling/deep-webpack-imports.json`, which `--write` refreshes and whose `removed` map names the paths no webpack 5 build can reach with the reason — deleted with the webpack 4 API, imported only by a package that is webpack 4 only, or probed for inside a `try` to detect webpack 4, where a re-export would pick the wrong branch — so only a genuine break fails. `--check` reads that record and nothing else — no network, and no install, so the `Deep Imports` job runs it on every pull request in under a second, comments what broke and what imports it, and fails; it names the packages and the downloads behind each one, and retracts the comment once the paths resolve again; `test/unitCases/deepPathShims.unittest.js` asserts the same thing off the same record, so a move out of `lib/` root learns it owes a re-export from a test rather than from a bug report. `COUNT=` sets how many packages per keyword (default 200), and a package the broad keyword shares with a narrow one is scanned once; tarballs cache under `node_modules/.cache/`, so a re-run costs nothing. Only the collecting half needs the network. `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. **The CSS and HTML comparisons open with a section no one has to ask for**: before the install, each holds webpack's own printer to what it owes whatever it printed, over `test/**/*.css` / `test/**/*.html` plus its own fixtures and whatever the cache already holds, in seconds rather than minutes. `--invariants` runs that section and stops, for a caller that wants the relations without the comparison behind them. Two relations, under each option set the script's own webpack rows are measured with: minifying an already-minified source changes nothing, and (HTML) how a value was spelled does not decide what it minifies to. 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 what carries 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. `--invariants` 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>`. The same question is asked of every other tool in the comparison's own tables, where the `2nd` column is what a second pass over the tool's own output moved — `-` being the answer a printer that is done printing gives.
113113
- `assembly/` — WebAssembly source for the hash function.
114114
- `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.
115115

0 commit comments

Comments
 (0)