Skip to content

Commit bf58839

Browse files
refactor: move PlatformPlugin and the HMR plugin into their directories
`PlatformPlugin` pins the target platform a `target: false` build cannot infer, so it joins the rest of the option handling in `lib/config/`, and `HotModuleReplacementPlugin` joins the runtime modules and backend it drives in `lib/hmr/`. Neither is imported by any package the ecosystem scan reaches, so neither needs a re-export. Root goes from 51 files to 49. The scan itself gains a rule and loses an ambiguity: `--write` now skips a path the `removed` map names instead of recording it as a request too, so the two maps are disjoint and the request count means what it says. Refreshing the record over today's registry moved 25 such paths out of `requests`. AGENTS.md gains a required section on moving a file out of `lib/` root — run the scan, what earns a re-export, and the five places a path hides, of which only `require()` is obvious. Two references it already carried had gone stale under earlier moves and are corrected.
1 parent 0478bca commit bf58839

10 files changed

Lines changed: 168 additions & 252 deletions

‎AGENTS.md‎

Lines changed: 46 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,8 @@ The directory listings below are the canonical map of the repository. **Whenever
6565
shape, `defaults.js` fills values in, and `WebpackOptionsApply` reads the result into
6666
the plugins it implies. `WebpackOptionsDefaulter` is the normalize-then-default pair
6767
under one deprecated name, and `OptionsApply` the base class the apply step extends.
68-
Also holds the target presets and `defineConfig`.
68+
Also holds the target presets, `defineConfig`, and `PlatformPlugin`, which pins the
69+
target platform a `target: false` build cannot infer.
6970
- `lib/container/` — Module Federation.
7071
- `lib/context/` — Context modules (`require.context`, dynamic request directories) and the plugins narrowing them.
7172
- `lib/css/` — CSS Modules, CSS parsing and generation.
@@ -88,7 +89,8 @@ The directory listings below are the canonical map of the repository. **Whenever
8889
- `lib/graph/` — The module and chunk graphs a compilation holds: `ModuleGraph` and its
8990
connections, `ChunkGraph` and the `buildChunkGraph` that fills it, and the `ExportsInfo`
9091
recording what each module exports and who uses it.
91-
- `lib/hmr/` — Hot Module Replacement plugins.
92+
- `lib/hmr/` — Hot Module Replacement: `HotModuleReplacementPlugin` and the runtime
93+
modules, lazy-compilation backend and helpers it drives.
9294
- `lib/html/` — Experimental HTML support.
9395
- `lib/ids/` — Module/chunk id assignment plugins, and `RecordIdsPlugin`, which persists
9496
the assignment across builds through `recordsPath`.
@@ -174,7 +176,7 @@ Keep `--depth 1`: `wpt` alone is ~161k files. `--remote` changes the commit the
174176

175177
- `declarations.d.ts`, `declarations.test.d.ts`, `module.d.ts`.
176178

177-
The loader context is not one of these: `LoaderContext` and the loader-definition types are JSDoc in `lib/` like every other type, declared where the code that adds each part lives (`lib/NormalModule.js`, `lib/loaders/LoaderRunner.js`, `lib/dependencies/LoaderPlugin.js`, `lib/HotModuleReplacementPlugin.js`) and re-exported from `lib/index.js`, which is the file `generate-types.js` reads webpack's public type surface from.
179+
The loader context is not one of these: `LoaderContext` and the loader-definition types are JSDoc in `lib/` like every other type, declared where the code that adds each part lives (`lib/module/NormalModule.js`, `lib/loaders/LoaderRunner.js`, `lib/dependencies/LoaderPlugin.js`, `lib/hmr/HotModuleReplacementPlugin.js`) and re-exported from `lib/index.js`, which is the file `generate-types.js` reads webpack's public type surface from.
178180

179181
**Configuration**
180182

@@ -221,6 +223,47 @@ The two config layers differ: **`normalization.js`** canonicalizes the user-supp
221223

222224
**Adding a runtime requirement:** declare the symbol in `lib/runtime/RuntimeGlobals.js`, emit its code with a `RuntimeModule` subclass, and inject it by tapping `runtimeRequirementInTree`/`additionalTreeRuntimeRequirements` on `compilation.hooks` (the `…InModule` variants for per-module needs).
223225

226+
### Moving a file out of `lib/` root
227+
228+
> [!REQUIRED]
229+
230+
**Run `yarn find-deep-imports:check` on every move, before the commit.** A path that
231+
leaves `lib/` root breaks any published package importing it, and the recorded scan in
232+
`tooling/deep-webpack-imports.json` is what says which those are. `--write` refreshes it
233+
off the registry; `--check` needs no network and is what CI runs. Its `removed` map names
234+
the paths no webpack 5 build can reach, and the two maps are disjoint — `--write` skips a
235+
path `removed` names rather than recording it as a request.
236+
237+
**A re-export is owed only to a webpack-5 package that imports the path unconditionally.**
238+
Read the importer's tarball, not its download count: a package whose `peerDependencies`
239+
or `dependencies` name webpack 5 and which requires the path at the top level gets a
240+
`// TODO remove in webpack 6` re-export at the old path. One that is webpack 4 only — it
241+
imports something webpack 5 deleted — or that probes for the path inside a `try` to detect
242+
webpack 4 gets an entry under `removed` with that reason instead, because a re-export
243+
would send it down the wrong branch.
244+
245+
**Five things carry a path, and only the first is obvious.** Rewrite every one, then
246+
confirm the move by regenerating rather than by reading:
247+
248+
1. `require("…")` and `require.resolve("…")`, including template literals and a string
249+
sitting in a ternary branch lines away from its call.
250+
2. `@import … from "…"` in a JSDoc block.
251+
3. `@typedef {import("…")}` — a different form from the one above, and missing it drops
252+
the type from webpack's public surface without failing anything.
253+
4. `tsType` in `schemas/**/*.json`, which can fail loudly in `fix:special` or silently
254+
degrade a public type to `any`.
255+
5. `makeSerializable(Class, "webpack/lib/…")` — the request moves with the class and the
256+
old one stays restorable through `registerLegacyRequest`, or a pre-move cache pack
257+
stops loading.
258+
259+
`yarn fix:special` leaving `types.d.ts` byte-identical is the check that 3 and 4 are done;
260+
`ConfigCacheTestCases` reporting no `Pack got invalid` line is the check that 5 is. Nothing
261+
static catches 1 — only building `lib/index.js` does.
262+
263+
**Update the Architecture listing above in the same commit**, and grep it for the old path:
264+
prose elsewhere in this guide names files too, and those references go stale just as
265+
quietly.
266+
224267
### Diagnostics and hints
225268

226269
> [!REQUIRED]

‎lib/Compiler.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ const getConcurrentCompilationError = memoize(() =>
6565
* ChunkRuntime,
6666
* FullHashChunkModuleHashes,
6767
* HotIndex
68-
* } from "./HotModuleReplacementPlugin"
68+
* } from "./hmr/HotModuleReplacementPlugin"
6969
*/
7070
/** @import Module, { BuildInfo } from "./module/Module" */
7171
/** @import Watching from "./watch/Watching" */
Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@
55

66
"use strict";
77

8-
/** @import Compiler from "./Compiler" */
9-
/** @import { PlatformTargetProperties } from "./config/target" */
8+
/** @import Compiler from "../Compiler" */
9+
/** @import { PlatformTargetProperties } from "./target" */
1010

1111
const PLUGIN_NAME = "PlatformPlugin";
1212

Lines changed: 37 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -6,60 +6,62 @@
66
"use strict";
77

88
const { RawSource } = require("webpack-sources");
9-
const Compilation = require("./Compilation");
10-
const HotUpdateChunk = require("./HotUpdateChunk");
9+
const Compilation = require("../Compilation");
10+
const HotUpdateChunk = require("../HotUpdateChunk");
1111
const {
1212
chunkHasCss,
1313
getChunkFilenameTemplate: getCssChunkFilenameTemplate
14-
} = require("./css/CssModulesPlugin");
15-
const ConstDependency = require("./dependencies/ConstDependency");
16-
const ImportMetaHotAcceptDependency = require("./dependencies/ImportMetaHotAcceptDependency");
17-
const ImportMetaHotDeclineDependency = require("./dependencies/ImportMetaHotDeclineDependency");
18-
const { isImportMetaFieldEnabled } = require("./dependencies/ImportMetaPlugin");
19-
const ModuleHotAcceptDependency = require("./dependencies/ModuleHotAcceptDependency");
20-
const ModuleHotDeclineDependency = require("./dependencies/ModuleHotDeclineDependency");
21-
const WebpackError = require("./errors/WebpackError");
22-
const ChunkGraph = require("./graph/ChunkGraph");
23-
const HotModuleReplacementRuntimeModule = require("./hmr/HotModuleReplacementRuntimeModule");
24-
const getParserHooks = require("./hmr/parserHooks");
14+
} = require("../css/CssModulesPlugin");
15+
const ConstDependency = require("../dependencies/ConstDependency");
16+
const ImportMetaHotAcceptDependency = require("../dependencies/ImportMetaHotAcceptDependency");
17+
const ImportMetaHotDeclineDependency = require("../dependencies/ImportMetaHotDeclineDependency");
18+
const {
19+
isImportMetaFieldEnabled
20+
} = require("../dependencies/ImportMetaPlugin");
21+
const ModuleHotAcceptDependency = require("../dependencies/ModuleHotAcceptDependency");
22+
const ModuleHotDeclineDependency = require("../dependencies/ModuleHotDeclineDependency");
23+
const WebpackError = require("../errors/WebpackError");
24+
const ChunkGraph = require("../graph/ChunkGraph");
2525
const {
2626
evaluateToIdentifier
27-
} = require("./javascript/JavascriptParserHelpers");
27+
} = require("../javascript/JavascriptParserHelpers");
2828
const {
2929
JAVASCRIPT_MODULE_TYPE_AUTO,
3030
JAVASCRIPT_MODULE_TYPE_DYNAMIC,
3131
JAVASCRIPT_MODULE_TYPE_ESM,
3232
WEBPACK_MODULE_TYPE_RUNTIME
33-
} = require("./module/ModuleTypeConstants");
34-
const NormalModule = require("./module/NormalModule");
35-
const ConcatenatedModule = require("./optimize/ConcatenatedModule");
36-
const RuntimeGlobals = require("./runtime/RuntimeGlobals");
37-
const { getPresentKinds } = require("./template/TemplatedPathPlugin");
38-
const { find, isSubset } = require("./util/SetHelpers");
39-
const TupleSet = require("./util/TupleSet");
40-
const { compareModulesById } = require("./util/comparators");
33+
} = require("../module/ModuleTypeConstants");
34+
const NormalModule = require("../module/NormalModule");
35+
const ConcatenatedModule = require("../optimize/ConcatenatedModule");
36+
const RuntimeGlobals = require("../runtime/RuntimeGlobals");
37+
const { getPresentKinds } = require("../template/TemplatedPathPlugin");
38+
const { find, isSubset } = require("../util/SetHelpers");
39+
const TupleSet = require("../util/TupleSet");
40+
const { compareModulesById } = require("../util/comparators");
4141
const {
4242
forEachRuntime,
4343
getRuntimeKey,
4444
intersectRuntime,
4545
keyToRuntime,
4646
mergeRuntimeOwned,
4747
subtractRuntime
48-
} = require("./util/runtime");
48+
} = require("../util/runtime");
49+
const HotModuleReplacementRuntimeModule = require("./HotModuleReplacementRuntimeModule");
50+
const getParserHooks = require("./parserHooks");
4951

5052
/** @import { CallExpression, Expression } from "estree" */
51-
/** @import Chunk, { ChunkId } from "./Chunk" */
52-
/** @import { ModuleId } from "./graph/ChunkGraph" */
53-
/** @import { AssetInfo } from "./Compilation" */
54-
/** @import Compiler, { Records } from "./Compiler" */
55-
/** @import CodeGenerationResults from "./module/CodeGenerationResults" */
56-
/** @import Module, { BuildInfo } from "./module/Module" */
57-
/** @import { CssModuleBuildMeta } from "./css/CssModule" */
58-
/** @import { HMRJavascriptParserHooks } from "./hmr/parserHooks" */
59-
/** @import RuntimeModule from "./runtime/RuntimeModule" */
60-
/** @import BasicEvaluatedExpression from "./javascript/BasicEvaluatedExpression" */
61-
/** @import JavascriptParser, { Range } from "./javascript/JavascriptParser" */
62-
/** @import { RuntimeSpec } from "./util/runtime" */
53+
/** @import Chunk, { ChunkId } from "../Chunk" */
54+
/** @import { ModuleId } from "../graph/ChunkGraph" */
55+
/** @import { AssetInfo } from "../Compilation" */
56+
/** @import Compiler, { Records } from "../Compiler" */
57+
/** @import CodeGenerationResults from "../module/CodeGenerationResults" */
58+
/** @import Module, { BuildInfo } from "../module/Module" */
59+
/** @import { CssModuleBuildMeta } from "../css/CssModule" */
60+
/** @import { HMRJavascriptParserHooks } from "./parserHooks" */
61+
/** @import RuntimeModule from "../runtime/RuntimeModule" */
62+
/** @import BasicEvaluatedExpression from "../javascript/BasicEvaluatedExpression" */
63+
/** @import JavascriptParser, { Range } from "../javascript/JavascriptParser" */
64+
/** @import { RuntimeSpec } from "../util/runtime" */
6365

6466
/** @typedef {string[]} Requests */
6567

‎lib/index.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -285,7 +285,7 @@ module.exports = mergeExports(fn, {
285285
return require("./HotUpdateChunk");
286286
},
287287
get HotModuleReplacementPlugin() {
288-
return require("./HotModuleReplacementPlugin");
288+
return require("./hmr/HotModuleReplacementPlugin");
289289
},
290290
get InitFragment() {
291291
return require("./template/InitFragment");
@@ -347,7 +347,7 @@ module.exports = mergeExports(fn, {
347347
return require("./Parser");
348348
},
349349
get PlatformPlugin() {
350-
return require("./PlatformPlugin");
350+
return require("./config/PlatformPlugin");
351351
},
352352
get PrefetchPlugin() {
353353
return require("./prefetch/PrefetchPlugin");

‎lib/module/NormalModule.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -226,7 +226,7 @@ const getModuleBuildError = memoize(() =>
226226

227227
/**
228228
* @template T
229-
* @typedef {NormalModuleLoaderContext<T> & import("../loaders/LoaderRunner").LoaderRunnerLoaderContext<T> & import("../dependencies/LoaderPlugin").LoaderPluginLoaderContext & import("../HotModuleReplacementPlugin").HotModuleReplacementPluginLoaderContext} LoaderContext
229+
* @typedef {NormalModuleLoaderContext<T> & import("../loaders/LoaderRunner").LoaderRunnerLoaderContext<T> & import("../dependencies/LoaderPlugin").LoaderPluginLoaderContext & import("../hmr/HotModuleReplacementPlugin").HotModuleReplacementPluginLoaderContext} LoaderContext
230230
*/
231231

232232
/** @typedef {(content: string) => boolean} NoParseFn */

‎test/unitCases/Compiler.unittest.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -383,7 +383,7 @@ describe("Compiler", () => {
383383
path: "/directory"
384384
},
385385
plugins: [
386-
new (require("../../lib/PlatformPlugin"))({ node: true }),
386+
new (require("../../lib/config/PlatformPlugin"))({ node: true }),
387387
(compiler) => {
388388
compiler.hooks.afterEnvironment.tap("test", () => {
389389
const platform = compiler.platform;

‎test/unitCases/HotModuleReplacementPlugin.unittest.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
"use strict";
22

3-
const HotModuleReplacementPlugin = require("../../lib/HotModuleReplacementPlugin");
3+
const HotModuleReplacementPlugin = require("../../lib/hmr/HotModuleReplacementPlugin");
44
const getParserHooks = require("../../lib/hmr/parserHooks");
55
const JavascriptParser = require("../../lib/javascript/JavascriptParser");
66

0 commit comments

Comments
 (0)