Skip to content

Commit 8165624

Browse files
refactor: group the module model, the diagnostics and four more out of lib/ root (#22202)
* refactor: group the diagnostic plugins, and two more into their homes A new `lib/diagnostics/` holds the plugins that raise a build-wide warning of their own — a case-insensitive filesystem collision, a deprecated option, a missing `mode` — plus `IgnoreWarningsPlugin`, which filters what they produced, and `NoEmitOnErrorsPlugin`, which reacts to errors rather than raising one. The classes they construct stay in `lib/errors/` and the `performance` hints in `lib/performance/`. `CircularModulesPlugin` joins `lib/optimize/` beside the passes that reason about the same cycles, and `LibraryTemplatePlugin` `lib/library/`. `lib/` root goes from 66 files to 60. `LibraryTemplatePlugin` keeps a re-export at its old path: `@aiot-toolkit/` and `@hap-toolkit/dsl-xvm` depend on webpack 5 directly and `@stylable/webpack-extensions` peers `^5.30.0`, and all three require it at the top level, for 139k weekly downloads. Nothing else moved here is imported from outside. `schemas/WebpackOptions.json` follows the file its `tsType` points at, without which `ignoreWarnings` regenerates as `any[]`. `types.d.ts` is byte-identical. * refactor: group the module model into lib/module/ The `Module` base class and `NormalModule`, the `ModuleFactory` hierarchy that builds them, the `Generator` base class and the `CodeGenerationResults` its output lands in, `ModuleProfile`, and the two type-constant files leave `lib/` root together. A module subclass a plugin owns stays with that plugin, so this holds the ones every build has. Root goes from 60 files to 51. Three classes carry a serialization request. Each moves to `webpack/lib/module/<Name>` and keeps the old one restorable through `registerLegacyRequest`, so a pack written before this still loads; `internalSerializables` records both. `NormalModule`, `RawModule` and `NullFactory` keep a re-export at their old paths — webpack-5 packages require each at the top level, for 271k weekly downloads between them. `Module` and `Generator` do not: their only importer is hard-source-webpack-plugin, which also imports `lib/DependenciesBlockVariable` and `lib/JavascriptGenerator`, both removed in webpack 5, so both paths are recorded as unreachable instead. Two `schemas/WebpackOptions.json` `tsType` paths follow the files they point at. `types.d.ts` regenerates byte-identical. * 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 6b73fee commit 8165624

328 files changed

Lines changed: 3609 additions & 3580 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 62 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -65,13 +65,19 @@ 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.
7273
- `lib/debug/` — Debug helpers.
7374
- `lib/dependencies/` — `Dependency` classes and their templates (HarmonyImport, CommonJsRequire, RequireContext, …).
7475
- `lib/devtool/` — Source maps: the `devtool` plugins and the filename helpers they template with.
76+
- `lib/diagnostics/` — Plugins that raise a build-wide error or warning of their own:
77+
a case-insensitive filesystem collision, a deprecated option, a missing `mode`, and
78+
`IgnoreWarningsPlugin`, which filters what the others produced. `NoEmitOnErrorsPlugin`
79+
joins them because it reacts to the errors rather than raising one. The classes they
80+
construct live in `lib/errors/`, and the `performance` hints in `lib/performance/`.
7581
- `lib/dll/` — DllPlugin / DllReferencePlugin.
7682
- `lib/deno/`, `lib/electron/`, `lib/node/`, `lib/web/`, `lib/webworker/` — Target-specific runtime templates and externals presets.
7783
- `lib/entry/` — The `entry` option: `EntryPlugin`, the `EntryOptionPlugin` that reads
@@ -83,18 +89,28 @@ The directory listings below are the canonical map of the repository. **Whenever
8389
- `lib/graph/` — The module and chunk graphs a compilation holds: `ModuleGraph` and its
8490
connections, `ChunkGraph` and the `buildChunkGraph` that fills it, and the `ExportsInfo`
8591
recording what each module exports and who uses it.
86-
- `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.
8794
- `lib/html/` — Experimental HTML support.
8895
- `lib/ids/` — Module/chunk id assignment plugins, and `RecordIdsPlugin`, which persists
8996
the assignment across builds through `recordsPath`.
9097
- `lib/javascript/` — JavaScript parsing (webpack's own ECMAScript parser, ported from acorn), generation, exports analysis. `syntax.js` serves every production a build reaches, so `grammar.js` (the full grammar) and `regexp.js` (the pattern validator) are installed onto the parser's prototype only when something asks for one — keep it that way and never `require` either from a path a build takes.
9198
- `lib/json/` — JSON modules.
92-
- `lib/library/` — UMD/AMD/ESM/CommonJS library output formats.
99+
- `lib/library/` — UMD/AMD/ESM/CommonJS library output formats, and the deprecated
100+
`LibraryTemplatePlugin` that reaches them through the old two-argument API.
93101
- `lib/loaders/` — Loader execution runtime (vendored loader-runner): pitching/normal loader
94102
iteration and loader module loading, plus the `LoaderOptionsPlugin` and
95103
`LoaderTargetPlugin` that feed the loader context.
96104
- `lib/logging/` — Logger API and console formatting.
97-
- `lib/optimize/` — Optimization plugins (`SplitChunksPlugin`, `ConcatenatedModule`, …).
105+
- `lib/module/` — What a module is and what makes one: the `Module` base class and
106+
`NormalModule`, the `ModuleFactory` hierarchy that builds them (`NormalModuleFactory`,
107+
`NullFactory`, `SelfModuleFactory`), the `Generator` base class and the
108+
`CodeGenerationResults` its output lands in, `ModuleProfile`, and the two constant
109+
files naming module and source types. A module subclass a plugin owns lives with
110+
that plugin — `ExternalModule` in `lib/externals/`, `CssModule` in `lib/css/` — so
111+
this holds the ones every build has.
112+
- `lib/optimize/` — Optimization plugins (`SplitChunksPlugin`, `ConcatenatedModule`, …),
113+
including `CircularModulesPlugin`, which flags the import cycles the others reason about.
98114
- `lib/performance/` — Asset/entrypoint size hints.
99115
- `lib/prefetch/` — Prefetch and preload, which are two mechanisms sharing a word:
100116
the runtime modules emitting `<link rel="prefetch">` for a chunk, and `PrefetchPlugin`
@@ -160,7 +176,7 @@ Keep `--depth 1`: `wpt` alone is ~161k files. `--remote` changes the commit the
160176

161177
- `declarations.d.ts`, `declarations.test.d.ts`, `module.d.ts`.
162178

163-
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.
164180

165181
**Configuration**
166182

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

208224
**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).
209225

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+
210267
### Diagnostics and hints
211268

212269
> [!REQUIRED]

‎lib/APIPlugin.js‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,6 @@
55

66
"use strict";
77

8-
const {
9-
JAVASCRIPT_MODULE_TYPE_AUTO,
10-
JAVASCRIPT_MODULE_TYPE_DYNAMIC,
11-
JAVASCRIPT_MODULE_TYPE_ESM
12-
} = require("./ModuleTypeConstants");
138
const ConstDependency = require("./dependencies/ConstDependency");
149
const ModuleInitFragmentDependency = require("./dependencies/ModuleInitFragmentDependency");
1510
const RuntimeRequirementsDependency = require("./dependencies/RuntimeRequirementsDependency");
@@ -23,6 +18,11 @@ const {
2318
evaluateToString,
2419
toConstantDependency
2520
} = require("./javascript/JavascriptParserHelpers");
21+
const {
22+
JAVASCRIPT_MODULE_TYPE_AUTO,
23+
JAVASCRIPT_MODULE_TYPE_DYNAMIC,
24+
JAVASCRIPT_MODULE_TYPE_ESM
25+
} = require("./module/ModuleTypeConstants");
2626
const ChunkNameRuntimeModule = require("./runtime/ChunkNameRuntimeModule");
2727
const GetFullHashRuntimeModule = require("./runtime/GetFullHashRuntimeModule");
2828
const RuntimeGlobals = require("./runtime/RuntimeGlobals");
@@ -34,7 +34,7 @@ const getConcatenatedModule = memoize(() =>
3434
);
3535

3636
/** @import Compiler from "./Compiler" */
37-
/** @import Module, { BuildInfo } from "./Module" */
37+
/** @import Module, { BuildInfo } from "./module/Module" */
3838
/**
3939
* @import {
4040
* JavascriptModuleBuildInfo

‎lib/Chunk.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ const { mergeRuntime } = require("./util/runtime");
2828
*/
2929
/** @import ChunkGroup from "./ChunkGroup" */
3030
/** @import { EntryOptions } from "./Entrypoint" */
31-
/** @import Module from "./Module" */
31+
/** @import Module from "./module/Module" */
3232
/** @import { PathDataChunk } from "./Compilation" */
3333
/** @typedef {import("./template/TemplatedPathPlugin").TemplatePathFn<PathDataChunk>} ChunkFilenameTemplateFn */
3434
/** @typedef {string | ChunkFilenameTemplateFn} ChunkFilenameTemplate */

‎lib/ChunkGroup.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ const {
1818
/** @import ChunkGraph from "./graph/ChunkGraph" */
1919
/** @import { DependencyLocation } from "./Dependency" */
2020
/** @import Entrypoint from "./Entrypoint" */
21-
/** @import Module from "./Module" */
21+
/** @import Module from "./module/Module" */
2222
/** @import ModuleGraph from "./graph/ModuleGraph" */
2323

2424
/** @typedef {{ module: Module | null, loc: DependencyLocation, request: string }} OriginRecord */

‎lib/CompatibilityPlugin.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,12 @@
55

66
"use strict";
77

8+
const ConstDependency = require("./dependencies/ConstDependency");
89
const {
910
JAVASCRIPT_MODULE_TYPE_AUTO,
1011
JAVASCRIPT_MODULE_TYPE_DYNAMIC,
1112
JAVASCRIPT_MODULE_TYPE_ESM
12-
} = require("./ModuleTypeConstants");
13-
const ConstDependency = require("./dependencies/ConstDependency");
13+
} = require("./module/ModuleTypeConstants");
1414
const RuntimeGlobals = require("./runtime/RuntimeGlobals");
1515

1616
/** @import { CallExpression } from "estree" */

‎lib/Compilation.js‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,10 @@ const {
1919
const { CachedSource } = require("webpack-sources");
2020
const Chunk = require("./Chunk");
2121
const ChunkGroup = require("./ChunkGroup");
22-
const CodeGenerationResults = require("./CodeGenerationResults");
2322
const Dependency = require("./Dependency");
2423
const Entrypoint = require("./Entrypoint");
2524
const FileSystemInfo = require("./FileSystemInfo");
2625
const LazyBarrelController = require("./LazyBarrel");
27-
const Module = require("./Module");
28-
const ModuleProfile = require("./ModuleProfile");
29-
const { WEBPACK_MODULE_TYPE_RUNTIME } = require("./ModuleTypeConstants");
3026
const Stats = require("./Stats");
3127
const { MultiItemCache } = require("./cache/CacheFacade");
3228
const ErrorHelpers = require("./errors/ErrorHelpers");
@@ -39,6 +35,10 @@ const ChunkGraph = require("./graph/ChunkGraph");
3935
const ModuleGraph = require("./graph/ModuleGraph");
4036
const buildChunkGraph = require("./graph/buildChunkGraph");
4137
const { LogType, Logger } = require("./logging/Logger");
38+
const CodeGenerationResults = require("./module/CodeGenerationResults");
39+
const Module = require("./module/Module");
40+
const ModuleProfile = require("./module/ModuleProfile");
41+
const { WEBPACK_MODULE_TYPE_RUNTIME } = require("./module/ModuleTypeConstants");
4242
const RuntimeGlobals = require("./runtime/RuntimeGlobals");
4343
const StatsFactory = require("./stats/StatsFactory");
4444
const StatsPrinter = require("./stats/StatsPrinter");
@@ -150,21 +150,21 @@ const { toError } = ErrorHelpers;
150150
* SourceType,
151151
* FactoryMeta,
152152
* CodeGenerationResult
153-
* } from "./Module"
153+
* } from "./module/Module"
154154
*/
155155
/**
156156
* @import NormalModule, {
157157
* NormalModuleCompilationHooks,
158158
* AnyLoaderContext,
159159
* ParserOptions,
160160
* GeneratorOptions
161-
* } from "./NormalModule"
161+
* } from "./module/NormalModule"
162162
*/
163163
/**
164164
* @import ModuleFactory, {
165165
* ModuleFactoryCreateDataContextInfo,
166166
* ModuleFactoryResult
167-
* } from "./ModuleFactory"
167+
* } from "./module/ModuleFactory"
168168
*/
169169
/** @import { ModuleId } from "./graph/ChunkGraph" */
170170
/** @import ModuleGraphConnection from "./graph/ModuleGraphConnection" */
@@ -556,7 +556,7 @@ const deprecatedNormalModuleLoaderHook = util.deprecate(
556556
* @returns {NormalModuleCompilationHooks["loader"]} hooks
557557
*/
558558
(compilation) =>
559-
require("./NormalModule").getCompilationHooks(compilation).loader,
559+
require("./module/NormalModule").getCompilationHooks(compilation).loader,
560560
"Compilation.hooks.normalModuleLoader was moved to NormalModule.getCompilationHooks(compilation).loader",
561561
"DEP_WEBPACK_COMPILATION_NORMAL_MODULE_LOADER_HOOK"
562562
);

‎lib/Compiler.js‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@ const {
1313
} = require("tapable");
1414
const { SizeOnlySource } = require("webpack-sources");
1515
const Compilation = require("./Compilation");
16-
const NormalModuleFactory = require("./NormalModuleFactory");
1716
const Stats = require("./Stats");
1817
const Cache = require("./cache/Cache");
1918
const CacheFacade = require("./cache/CacheFacade");
@@ -22,6 +21,7 @@ const WebpackError = require("./errors/WebpackError");
2221
const ChunkGraph = require("./graph/ChunkGraph");
2322
const ModuleGraph = require("./graph/ModuleGraph");
2423
const { Logger } = require("./logging/Logger");
24+
const NormalModuleFactory = require("./module/NormalModuleFactory");
2525
const ResolverFactory = require("./resolve/ResolverFactory");
2626
const RequestShortener = require("./util/RequestShortener");
2727
const asyncLib = require("./util/async");
@@ -65,9 +65,9 @@ const getConcurrentCompilationError = memoize(() =>
6565
* ChunkRuntime,
6666
* FullHashChunkModuleHashes,
6767
* HotIndex
68-
* } from "./HotModuleReplacementPlugin"
68+
* } from "./hmr/HotModuleReplacementPlugin"
6969
*/
70-
/** @import Module, { BuildInfo } from "./Module" */
70+
/** @import Module, { BuildInfo } from "./module/Module" */
7171
/** @import Watching from "./watch/Watching" */
7272
/** @import { RecordsChunks, RecordsModules } from "./ids/RecordIdsPlugin" */
7373
/** @import { PlatformTargetProperties } from "./config/target" */

‎lib/ConcatenationScope.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ const {
1111
} = require("./util/concatenate");
1212

1313
/** @import { Source } from "webpack-sources" */
14-
/** @import Module from "./Module" */
14+
/** @import Module from "./module/Module" */
1515
/**
1616
* @import {
1717
* ConcatenatedModuleInfo,

‎lib/ConstPlugin.js‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@
55

66
"use strict";
77

8+
const CachedConstDependency = require("./dependencies/CachedConstDependency");
9+
const ConstDependency = require("./dependencies/ConstDependency");
10+
const { evaluateToString } = require("./javascript/JavascriptParserHelpers");
811
const {
912
JAVASCRIPT_MODULE_TYPE_AUTO,
1013
JAVASCRIPT_MODULE_TYPE_DYNAMIC,
1114
JAVASCRIPT_MODULE_TYPE_ESM
12-
} = require("./ModuleTypeConstants");
13-
const CachedConstDependency = require("./dependencies/CachedConstDependency");
14-
const ConstDependency = require("./dependencies/ConstDependency");
15-
const { evaluateToString } = require("./javascript/JavascriptParserHelpers");
15+
} = require("./module/ModuleTypeConstants");
1616
const { parseResource } = require("./util/identifier");
1717

1818
/**

‎lib/DefinePlugin.js‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,6 @@
66
"use strict";
77

88
const { SyncWaterfallHook } = require("tapable");
9-
const {
10-
JAVASCRIPT_MODULE_TYPE_AUTO,
11-
JAVASCRIPT_MODULE_TYPE_DYNAMIC,
12-
JAVASCRIPT_MODULE_TYPE_ESM
13-
} = require("./ModuleTypeConstants");
149
const ConstDependency = require("./dependencies/ConstDependency");
1510
const WebpackError = require("./errors/WebpackError");
1611
const BasicEvaluatedExpression = require("./javascript/BasicEvaluatedExpression");
@@ -19,6 +14,11 @@ const {
1914
evaluateToString,
2015
toConstantDependency
2116
} = require("./javascript/JavascriptParserHelpers");
17+
const {
18+
JAVASCRIPT_MODULE_TYPE_AUTO,
19+
JAVASCRIPT_MODULE_TYPE_DYNAMIC,
20+
JAVASCRIPT_MODULE_TYPE_ESM
21+
} = require("./module/ModuleTypeConstants");
2222
const RuntimeGlobals = require("./runtime/RuntimeGlobals");
2323
const { getBuildDiagnostics } = require("./util/buildDiagnostics");
2424
const createHash = require("./util/createHash");
@@ -31,9 +31,9 @@ const createHooksRegistry = require("./util/createHooksRegistry");
3131
* BuildInfo,
3232
* ValueCacheVersion,
3333
* ValueCacheVersions
34-
* } from "./Module"
34+
* } from "./module/Module"
3535
*/
36-
/** @import NormalModule, { NormalModuleBuildInfo } from "./NormalModule" */
36+
/** @import NormalModule, { NormalModuleBuildInfo } from "./module/NormalModule" */
3737
/** @import RuntimeTemplate from "./template/RuntimeTemplate" */
3838
/**
3939
* @import JavascriptParser, {

0 commit comments

Comments
 (0)