Skip to content

Commit dbc7b37

Browse files
build(tooling): count the modules each way of using webpack loads
`yarn lint:module-loading` (in `yarn lint`) loads webpack through require, import, each minifier and a production build, each in a fresh process, and fails when a count grows past tooling/module-loading.json or a package outside webpack loads one of its internal files. Claude-Session: https://claude.ai/code/session_013FhutPJQq4FqAi1cjUXmv1
1 parent 0850c05 commit dbc7b37

8 files changed

Lines changed: 305 additions & 8 deletions

File tree

‎AGENTS.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -273,14 +273,13 @@ Runtime-emitting code (chunk loading, resource hints, library and externals pres
273273

274274
> [!REQUIRED]
275275
276-
**Read [docs/caching.md](docs/caching.md) whenever `ConfigCacheTestCases` fails or a change alters which module loads a `lib/` file.** The rules it enforces:
276+
**Read [docs/caching.md](docs/caching.md) whenever `ConfigCacheTestCases` fails.** The rules it enforces:
277277

278278
- `Pack got invalid because of write to: <identifier>` means work redone every incremental build: **treat it as a defect and find the cause**.
279279
- Every new serializable class (`Module`, `Dependency`, error subclass, cached value) calls `makeSerializable(...)`; `yarn fix:serializables` regenerates `internalSerializables`.
280280
- Deserialization re-enters a constructor with **no arguments**, so one dereferencing a parameter must guard.
281281
- **Never silence it with `test.filter.js`**; a new case passes both suites (post-baseline syntax gating is different — [Target the Node baseline](#target-the-node-baseline)).
282282
- Only a case whose subject is a build error may expect the write, via `infrastructure-log.js`; any other expectation states why it isn't a bug.
283-
- **Build dependencies follow imports**: the cache walks every `require` and `import` from the config, `node_modules` included, so a `lib/` file another package loads by path pulls in all it imports, `webpack` too; hand packages functions, not paths, and count the files ([how](docs/caching.md#build-dependencies)).
284283

285284
### Performance and memory
286285

@@ -293,7 +292,8 @@ Every process starts cold, and loading code is most of that start, so pay only f
293292
- **Load on first use**: reach a module that some inputs or options never need through one lazy accessor, not an import at the top of the file.
294293
- **Keep cheap things light**: constants and option helpers callers need live apart from the heavy code that uses them.
295294
- **Turned-off work costs nothing**: build tables, regexes and closures on first use, not at load or construction.
296-
- **Prove it by counting** which modules a fresh process loads, not by timing it.
295+
- **Only webpack loads its own files**: hand another package a function, never a path to a `lib/` file; loaded by that package, the file and all it imports (`require("webpack")` included) count wherever that package is walked, such as the cache's build dependencies ([why](docs/caching.md#build-dependencies)).
296+
- **Prove it by counting** which modules a fresh process loads, not by timing it: `yarn lint:module-loading` reports each way webpack is used, and fails on a count past `tooling/module-loading.json` or a package loading webpack's files. Lower the baseline with `--write`.
297297

298298
### Keep instance shapes stable
299299

‎docs/architecture.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ This is the canonical repository map. **When you add, rename or remove a top-lev
6060
- `tooling/` — repo-internal scripts:
6161
- Codegen run by `yarn fix:special`: runtime/wasm generators, the hash-debug tool, `generate-schemas.js` — which derives each schema from the module declaring its options and reports what no longer derives — `precompile-schemas.js`, which compiles each schema into the standalone validator webpack validates with, and `generate-types.js`, which prints `types.d.ts` from the types the sources under `lib/` declare. Each names its own stale outputs.
6262
- `check-agents-md-size.js` / `check-class-names.js` (`yarn lint:agents` / `lint:class-names`, both inside `yarn lint`) — the two invariants nothing else enforces: AGENTS.md's character budget, and that no two classes under `lib/` share a name, since a collision makes `generate-types.js` invent one for the published `types.d.ts`.
63+
- `check-module-loading.js` (`yarn lint:module-loading`, inside `yarn lint`) — counts the modules a fresh process loads per way webpack is used (`require`, `import`, each minifier, a production build) against `module-loading.json`, and fails when a package outside webpack loads one of its internal files.
6364
- `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`) and the invariants gate every PR runs (`yarn test:invariants`) — how to read the tables, the pinned corpora and the invariant relations: [tooling/COMPARE_TOOLS.md](../tooling/COMPARE_TOOLS.md). Read it before claiming anything about webpack's CSS/HTML/JS/XML implementation vs the ecosystem, or when `invariants` is red.
6465
- `hash-css-outputs.js` (`yarn hash:css-outputs`) — a digest of every minified (five option presets) and beautified output, map and diagnostic over the CSS corpus, one JSON line each; `--repo <checkout>` prints another checkout's over this one's corpus, so `diff`ing two runs proves a CSS printer change byte-identical.
6566
- `type-coverage.js` (`yarn types:cover`) — how much of `lib/` is precisely typed.

‎docs/caching.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,4 @@ webpack's own directory is a managed path, so the walk normally stops there. A `
3434
So:
3535

3636
- **Hand webpack's own code to a third-party package as a value** (a function or object `lib/` already required), not a path it `require`s, unless the module never loads `webpack` in the main process.
37-
- **Nothing in the repo catches this.** Here webpack isn't under `node_modules`, so it isn't a managed path, and a test whose config `require`s webpack reaches everything anyway. Measure when a change alters which module loads a `lib/` file.
38-
39-
**Measuring.** Install webpack as a real directory under a project's `node_modules` (copy `lib/`, `hot/`, `schemas/`, `package.json`, `types.d.ts`; dependencies may be symlinks, but a package that loads webpack's files must be a real copy so `webpack` resolves as its sibling). Use a config that imports the plugin, as users do, and doesn't `require` webpack. Wrap `FileSystemInfo.prototype.resolveBuildDependencies` to log `result.files.size`, delete the cache directory, and compare a cold build on `main` and on the branch.
37+
- **`yarn lint:module-loading` catches it**: it fails when a module outside webpack loads one of webpack's internal files.

‎docs/verifying.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ How to prove a change before pushing it and how to read CI when it is red, behin
1414

1515
**A generated file is stale as soon as any JSDoc it copies changes — prose included.** `types.d.ts` carries the comment above `process()`, not just its signature; a reworded comment, or a signature edited without its doc paragraph, fails `lint` with the same `types.d.ts need to be updated` a missing member gives. After splicing your hunks, diff your file against the generator's whole output for that symbol's **region**, not just the lines you meant to change.
1616

17-
`yarn lint` runs `lint:agents` and `lint:special` in sequence and the rest in parallel, so `lint:special` tripping on sandbox drift hides every later stage. If it reports declarations "need to be updated" that `main` reports too, run the rest by hand: `lint:agents`, `lint:code`, `lint:class-names`, `lint:redundant-casts`, `lint:types`, `lint:types-test`, `lint:types-benchmark`, `lint:types-module-test`, `lint:types-hot`, `fmt:check`, `lint:spellcheck`. `lint:types-test` catches `tsc` errors in `test/`; skipping it is how a red `lint` survives "lint passed locally".
17+
`yarn lint` runs `lint:agents` and `lint:special` in sequence and the rest in parallel, so `lint:special` tripping on sandbox drift hides every later stage. If it reports declarations "need to be updated" that `main` reports too, run the rest by hand: `lint:agents`, `lint:code`, `lint:class-names`, `lint:module-loading`, `lint:redundant-casts`, `lint:types`, `lint:types-test`, `lint:types-benchmark`, `lint:types-module-test`, `lint:types-hot`, `fmt:check`, `lint:spellcheck`. `lint:types-test` catches `tsc` errors in `test/`; skipping it is how a red `lint` survives "lint passed locally".
1818

1919
## Long runs
2020

‎eslint.config.mjs‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -377,6 +377,15 @@ export default defineConfig([
377377
"n/no-unsupported-features/node-builtins": "off"
378378
}
379379
},
380+
{
381+
// Records every module a fresh process loads through `module.registerHooks`,
382+
// so it runs on the Node `lint` uses and skips itself on an older one.
383+
files: ["tooling/check-module-loading.js"],
384+
rules: {
385+
"n/no-unsupported-features/es-syntax": "off",
386+
"n/no-unsupported-features/node-builtins": "off"
387+
}
388+
},
380389
{
381390
// The code generators run under the repo's own Node, not the baseline the
382391
// code they emit has to meet.

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,10 @@
3232
"prepare": "husky",
3333
"setup": "node ./setup/setup.js",
3434
"prelint": "yarn setup",
35-
"lint": "yarn lint:agents && yarn lint:special && node tooling/run-parallel.js lint:code lint:class-names lint:redundant-casts lint:types-all fmt:check lint:spellcheck",
35+
"lint": "yarn lint:agents && yarn lint:special && node tooling/run-parallel.js lint:code lint:class-names lint:module-loading lint:redundant-casts lint:types-all fmt:check lint:spellcheck",
3636
"lint:agents": "node tooling/check-agents-md-size.js",
3737
"lint:class-names": "node tooling/check-class-names.js",
38+
"lint:module-loading": "node tooling/check-module-loading.js",
3839
"lint:code": "node node_modules/eslint/bin/eslint.js --cache --concurrency auto .",
3940
"lint:redundant-casts": "node tooling/check-redundant-type-assertions.js",
4041
"lint:special": "node tooling/generate-runtime-code.js && node tooling/generate-wasm-code.js && node tooling/generate-css-data.js && node tooling/generate-html-data.js && node tooling/generate-js-data.js && node tooling/generate-schemas.js && node tooling/precompile-schemas.js && node tooling/generate-types.js --no-template-literals && node tooling/generate-internal-serializables.js",

‎tooling/check-module-loading.js‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
/*
2+
MIT License http://www.opensource.org/licenses/mit-license.php
3+
Author Alexander Akait @alexander-akait
4+
*/
5+
6+
"use strict";
7+
8+
// Counts the modules a fresh process loads for each way webpack is used, and
9+
// fails when a count grows past `module-loading.json` or a module outside
10+
// webpack loads one of its internal files: such a file then hangs under that
11+
// package, so the cache's build-dependency walk drags all of webpack in.
12+
//
13+
// node tooling/check-module-loading.js # check
14+
// node tooling/check-module-loading.js --write # rewrite the baseline
15+
16+
const { fork } = require("child_process");
17+
const fs = require("fs");
18+
const os = require("os");
19+
const path = require("path");
20+
const { fileURLToPath, pathToFileURL } = require("url");
21+
22+
const ROOT = path.resolve(__dirname, "..");
23+
const INDEX = path.join(ROOT, "lib/index.js");
24+
const NODE_MODULES = path.join(ROOT, "node_modules") + path.sep;
25+
const BASELINE = path.join(__dirname, "module-loading.json");
26+
27+
/** @typedef {{ webpack: number, dependencies: number }} Counts */
28+
/** @typedef {Counts & { outsideLoads: string[] }} ScenarioResult */
29+
30+
/**
31+
* @param {string} name a minifier's path under `lib/`
32+
* @param {string} file the asset's filename
33+
* @param {string} code the asset's source
34+
* @returns {() => Promise<void>} a scenario running that minifier once
35+
*/
36+
const minify = (name, file, code) => async () => {
37+
await require(path.join(ROOT, "lib", name))({ [file]: code });
38+
};
39+
40+
/**
41+
* @returns {Promise<void>} resolves once a production build of JavaScript, CSS
42+
* and HTML with the default minimizers has finished
43+
*/
44+
const build = async () => {
45+
const context = fs.mkdtempSync(path.join(os.tmpdir(), "webpack-loading-"));
46+
fs.writeFileSync(
47+
path.join(context, "index.html"),
48+
'<!doctype html><link rel="stylesheet" href="./style.css"><script src="./index.js"></script>'
49+
);
50+
fs.writeFileSync(path.join(context, "style.css"), "body { color: red; }");
51+
fs.writeFileSync(path.join(context, "index.js"), "console.log(1 + 1);");
52+
53+
const webpack = require(INDEX);
54+
55+
try {
56+
await new Promise((resolve, reject) => {
57+
webpack(
58+
{
59+
mode: "production",
60+
context,
61+
entry: "./index.html",
62+
output: { path: path.join(context, "dist") },
63+
experiments: { css: true, html: true }
64+
},
65+
/**
66+
* @param {Error | null} err a fatal error
67+
* @param {import("../lib/stats/Stats") | undefined} stats the build's stats
68+
* @returns {void}
69+
*/
70+
(err, stats) => {
71+
if (err) return reject(err);
72+
if (stats && stats.hasErrors()) {
73+
return reject(new Error(stats.toString("errors-only")));
74+
}
75+
resolve(undefined);
76+
}
77+
);
78+
});
79+
} finally {
80+
fs.rmSync(context, { recursive: true, force: true });
81+
}
82+
};
83+
84+
/** @type {Record<string, () => Promise<void>>} */
85+
const SCENARIOS = {
86+
'require("webpack")': async () => {
87+
require(INDEX);
88+
},
89+
'import "webpack"': async () => {
90+
await import(pathToFileURL(INDEX).href);
91+
},
92+
"javascript minify": minify(
93+
"javascript/jsMinify",
94+
"a.js",
95+
"function add(a, b) { return a + b; } console.log(add(1, 2));"
96+
),
97+
"css minify": minify("css/cssMinify", "a.css", "a { color: #ff0000; }"),
98+
"html minify": minify(
99+
"html/htmlMinify",
100+
"a.html",
101+
"<!doctype html><p class=' a '>text</p><style>a { color: red }</style>"
102+
),
103+
"xml minify": minify(
104+
"html/xmlMinify",
105+
"a.svg",
106+
'<svg xmlns="http://www.w3.org/2000/svg"> <g/> </svg>'
107+
),
108+
"json minify": minify("json/jsonMinify", "a.json", '{ "a": [1, 2] }'),
109+
"production build": build
110+
};
111+
112+
/**
113+
* Runs one scenario in this process, recording every module it loads and the
114+
* module that first asked for it, then reports to the parent process.
115+
* @param {string} name the scenario
116+
* @returns {Promise<void>} resolves once the result has been sent
117+
*/
118+
const runScenario = async (name) => {
119+
const { registerHooks } = require("module");
120+
121+
/** @type {Map<string, string | undefined>} */
122+
const firstParent = new Map();
123+
/** @type {Set<string>} */
124+
const loaded = new Set();
125+
registerHooks({
126+
resolve(specifier, context, nextResolve) {
127+
const result = nextResolve(specifier, context);
128+
if (!firstParent.has(result.url)) {
129+
firstParent.set(result.url, context.parentURL);
130+
}
131+
return result;
132+
},
133+
load(url, context, nextLoad) {
134+
loaded.add(url);
135+
return nextLoad(url, context);
136+
}
137+
});
138+
await SCENARIOS[name]();
139+
const self = pathToFileURL(__filename).href;
140+
/** @type {ScenarioResult} */
141+
const result = { webpack: 0, dependencies: 0, outsideLoads: [] };
142+
for (const url of loaded) {
143+
if (!url.startsWith("file:")) continue;
144+
const file = fs.realpathSync(fileURLToPath(url));
145+
if (file.startsWith(NODE_MODULES)) {
146+
result.dependencies++;
147+
continue;
148+
}
149+
if (!file.startsWith(ROOT + path.sep) || file === __filename) continue;
150+
result.webpack++;
151+
const parentUrl = firstParent.get(url);
152+
if (file === INDEX || !parentUrl || parentUrl === self) continue;
153+
const parent = fs.realpathSync(fileURLToPath(parentUrl));
154+
if (parent.startsWith(NODE_MODULES) || !parent.startsWith(ROOT)) {
155+
result.outsideLoads.push(
156+
`${path.relative(ROOT, parent)} -> ${path.relative(ROOT, file)}`
157+
);
158+
}
159+
}
160+
/** @type {NonNullable<typeof process.send>} */ (process.send)(result);
161+
};
162+
163+
/**
164+
* @param {string} name the scenario
165+
* @returns {Promise<ScenarioResult>} what a fresh process running it loaded
166+
*/
167+
const measure = (name) =>
168+
new Promise((resolve, reject) => {
169+
/** @type {ScenarioResult | undefined} */
170+
let result;
171+
const child = fork(__filename, ["--scenario", name], { stdio: "inherit" });
172+
child.on("message", (message) => {
173+
result = /** @type {ScenarioResult} */ (message);
174+
});
175+
child.on("error", reject);
176+
child.on("exit", (code) => {
177+
if (code === 0 && result) return resolve(result);
178+
reject(new Error(`scenario "${name}" exited with code ${code}`));
179+
});
180+
});
181+
182+
const main = async () => {
183+
if (typeof require("module").registerHooks !== "function") {
184+
console.log(
185+
`Skipped: module.registerHooks needs Node.js 22.15 or newer (running ${process.version}).`
186+
);
187+
return;
188+
}
189+
const write = process.argv.includes("--write");
190+
/** @type {Record<string, Counts>} */
191+
const baseline = fs.existsSync(BASELINE)
192+
? JSON.parse(fs.readFileSync(BASELINE, "utf8"))
193+
: {};
194+
/** @type {Record<string, Counts>} */
195+
const next = {};
196+
/** @type {string[]} */
197+
const failures = [];
198+
/** @type {string[]} */
199+
const rows = [];
200+
for (const name of Object.keys(SCENARIOS)) {
201+
const { webpack, dependencies, outsideLoads } = await measure(name);
202+
next[name] = { webpack, dependencies };
203+
const before = baseline[name] || { webpack: 0, dependencies: 0 };
204+
rows.push(
205+
`| ${name} | ${webpack} | ${before.webpack} | ${dependencies} | ${before.dependencies} |`
206+
);
207+
for (const load of outsideLoads) {
208+
failures.push(
209+
`${name}: a module outside webpack loads an internal file: ${load}`
210+
);
211+
}
212+
if (!write) {
213+
for (const key of /** @type {(keyof Counts)[]} */ ([
214+
"webpack",
215+
"dependencies"
216+
])) {
217+
if (next[name][key] > before[key]) {
218+
failures.push(
219+
`${name}: loads ${next[name][key]} ${key} modules, over its baseline of ${before[key]}`
220+
);
221+
}
222+
}
223+
}
224+
}
225+
console.log(
226+
"| Scenario | webpack files | baseline | dependency files | baseline |"
227+
);
228+
console.log("| :-- | --: | --: | --: | --: |");
229+
for (const row of rows) console.log(row);
230+
if (write) {
231+
fs.writeFileSync(BASELINE, `${JSON.stringify(next, null, 2)}\n`);
232+
console.log(`Wrote ${path.relative(ROOT, BASELINE)}`);
233+
}
234+
if (failures.length > 0) {
235+
console.error(`\n${failures.join("\n")}`);
236+
console.error(
237+
"\nLoad a module only where it is used, and hand other packages functions rather than paths to webpack's files; if the growth is intended, run with --write."
238+
);
239+
process.exitCode = 1;
240+
}
241+
};
242+
243+
const scenarioIndex = process.argv.indexOf("--scenario");
244+
if (scenarioIndex === -1) {
245+
main().catch((err) => {
246+
console.error(err);
247+
process.exitCode = 1;
248+
});
249+
} else {
250+
runScenario(process.argv[scenarioIndex + 1]).catch((err) => {
251+
console.error(err);
252+
process.exitCode = 1;
253+
});
254+
}

‎tooling/module-loading.json‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{
2+
"require(\"webpack\")": {
3+
"webpack": 2,
4+
"dependencies": 0
5+
},
6+
"import \"webpack\"": {
7+
"webpack": 2,
8+
"dependencies": 0
9+
},
10+
"javascript minify": {
11+
"webpack": 11,
12+
"dependencies": 0
13+
},
14+
"css minify": {
15+
"webpack": 14,
16+
"dependencies": 0
17+
},
18+
"html minify": {
19+
"webpack": 19,
20+
"dependencies": 0
21+
},
22+
"xml minify": {
23+
"webpack": 14,
24+
"dependencies": 0
25+
},
26+
"json minify": {
27+
"webpack": 1,
28+
"dependencies": 0
29+
},
30+
"production build": {
31+
"webpack": 444,
32+
"dependencies": 133
33+
}
34+
}

0 commit comments

Comments
 (0)