Skip to content

Commit 4448f8b

Browse files
feat(performance): add the analyzableBailouts hint (#21986)
* feat(performance): add the analyzableBailouts hint A reference in ESM output that keeps webpack's runtime form was reported only through `stats.optimizationBailout`, which nothing shows by default. The hint names each reason and the modules it was recorded on, through the same `hints` channel as the other checks. The reasons a module records are stored beside its generated code and reapplied when the cache restores it, so a warm build reports what a cold one did. They are recorded on the module being generated, which is the one a cached result belongs to. * test(performance): cover a second bailout reason and pin the stats message A worker loading its chunks through importScripts adds a second reason to the warning case, so the ordering of reasons runs; the stats case asserts the reason and module rather than the prefix. Trims the changeset to 80 characters. * perf(performance): collect bailouts without allocating per module The collector wrapped every module's code generation in a closure and handed back a fresh array and tuple, an allocation per module on a hot path. Begin and finish calls replace it, and the sink exists only once a reason is recorded: over the many-modules-commonjs and lodash benchmark fixtures, one pair of field writes per module and no allocation at all. * fix(performance): hand every code generation its bailout reasons A module generated once per runtime recorded a reason into the graph on the first generation only, so the other runtime's cached result carried none. If that runtime's entry is all the cache restores later, the hint loses the reason. The graph stays deduplicated; each generation's sink records on its own.
1 parent 5c38c46 commit 4448f8b

34 files changed

Lines changed: 510 additions & 4 deletions

‎.changeset/017-performance-diagnostic-gaps.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22
"webpack": minor
33
---
44

5-
Add source-map, unused-asset and unused-module hints; group config checks under `unusedConfig`.
5+
Add source-map, unused-asset, unused-module, bailout hints; group config checks.

‎declarations/WebpackOptions.d.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3438,6 +3438,11 @@ export interface PerformanceOptions {
34383438
* @since 5.110.0
34393439
*/
34403440
all?: boolean;
3441+
/**
3442+
* Report references in ESM output that keep webpack's runtime form, naming what stops each from being written as a literal 'import()' or 'new URL()' another bundler can follow (requires 'hints' to be enabled).
3443+
* @since 5.111.0
3444+
*/
3445+
analyzableBailouts?: boolean;
34413446
/**
34423447
* Filter function to select assets that are checked.
34433448
*/

‎lib/Compilation.js‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4340,6 +4340,9 @@ Or do you want to use the entrypoints '${name}' and '${runtime}' independently o
43404340
codeGenerated = true;
43414341
this.codeGeneratedModules.add(module);
43424342
this._generatingModule = module;
4343+
// Not stored, since nothing is restored here: named so a reason lands on
4344+
// the same module as it does in a cached build.
4345+
runtimeTemplate.beginAnalyzableBailouts(module);
43434346
result = module.codeGeneration({
43444347
chunkGraph,
43454348
moduleGraph,
@@ -4361,6 +4364,7 @@ Or do you want to use the entrypoints '${name}' and '${runtime}' independently o
43614364
};
43624365
} finally {
43634366
this._generatingModule = undefined;
4367+
runtimeTemplate.finishAnalyzableBailouts();
43644368
}
43654369
for (const runtime of runtimes) {
43664370
results.add(module, runtime, result);
@@ -4384,6 +4388,7 @@ Or do you want to use the entrypoints '${name}' and '${runtime}' independently o
43844388
codeGenerated = true;
43854389
this.codeGeneratedModules.add(module);
43864390
this._generatingModule = module;
4391+
runtimeTemplate.beginAnalyzableBailouts(module);
43874392
result = module.codeGeneration({
43884393
chunkGraph,
43894394
moduleGraph,
@@ -4394,6 +4399,13 @@ Or do you want to use the entrypoints '${name}' and '${runtime}' independently o
43944399
codeGenerationResults: results,
43954400
compilation: this
43964401
});
4402+
// The bailouts travel with the result: a restored module never runs
4403+
// the code generation that would record them again.
4404+
const bailouts = runtimeTemplate.finishAnalyzableBailouts();
4405+
if (bailouts !== undefined) {
4406+
if (result.data === undefined) result.data = new Map();
4407+
result.data.set("analyzableBailouts", bailouts);
4408+
}
43974409
} catch (err) {
43984410
errors.push(
43994411
new (getCodeGenerationError())(module, /** @type {Error} */ (err))
@@ -4405,9 +4417,14 @@ Or do you want to use the entrypoints '${name}' and '${runtime}' independently o
44054417
};
44064418
} finally {
44074419
this._generatingModule = undefined;
4420+
runtimeTemplate.finishAnalyzableBailouts();
44084421
}
44094422
} else {
44104423
result = cachedResult;
4424+
const bailouts = result.data && result.data.get("analyzableBailouts");
4425+
if (bailouts) {
4426+
runtimeTemplate.restoreAnalyzableBailouts(module, bailouts);
4427+
}
44114428
}
44124429
for (const runtime of runtimes) {
44134430
results.add(module, runtime, result);

‎lib/RuntimeTemplate.js‎

Lines changed: 81 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,9 @@ const HASH_PROBE = "0123456789abcdef0123";
119119
const HASH_PROBE_ALTERNATE = "3210fedcba9876543210";
120120
const HASH_IN_FILENAME_GLOBAL = /\[(?:full|chunk|content)?hash(?::[^\]]+)?\]/g;
121121

122+
// What a recorded reason is prefixed with in `stats.optimizationBailout`.
123+
const ANALYZABLE_BAILOUT_PREFIX = "Analyzable ESM bailout: ";
124+
122125
/**
123126
* @param {SpecifierPart} part one piece of a reserved name
124127
* @returns {boolean} true when it is text the deferred pass adds nothing to
@@ -489,6 +492,10 @@ class RuntimeTemplate {
489492
this._entryBaseUriByRuntime = new Map();
490493
/** @type {WasmGroups | undefined} */
491494
this._wasmGroupsValue = undefined;
495+
/** @type {string[] | undefined} */
496+
this._analyzableBailoutSink = undefined;
497+
/** @type {Module | undefined} */
498+
this._analyzableGeneratingModule = undefined;
492499
/** @type {Map<string, boolean> | undefined} */
493500
this._wasmAnchorKnownByGroup = undefined;
494501
}
@@ -826,14 +833,86 @@ class RuntimeTemplate {
826833
*/
827834
_analyzableBailout(module, reason, answer) {
828835
if (module !== undefined && this.outputOptions.module) {
829-
const text = `Analyzable ESM bailout: ${reason}`;
836+
// Recorded on the module whose code is being generated, which is the one a
837+
// cached result is restored for — an inner module of a concatenation is not.
838+
const target = this._analyzableGeneratingModule || module;
839+
const text = `${ANALYZABLE_BAILOUT_PREFIX}${reason}`;
830840
const bailouts =
831-
this.compilation.moduleGraph.getOptimizationBailout(module);
841+
this.compilation.moduleGraph.getOptimizationBailout(target);
832842
if (!bailouts.includes(text)) bailouts.push(text);
843+
// Each generation records its own: another runtime's result may be all the
844+
// cache restores later, so what the graph holds must not hide a reason.
845+
if (this._analyzableGeneratingModule !== undefined) {
846+
// The sink exists only once a reason is recorded, so a module that
847+
// bakes every reference — nearly all of them — allocates nothing here.
848+
const sink =
849+
this._analyzableBailoutSink || (this._analyzableBailoutSink = []);
850+
if (!sink.includes(reason)) sink.push(reason);
851+
}
833852
}
834853
return answer;
835854
}
836855

856+
/**
857+
* Names the module whose code generation starts, so the reasons its references
858+
* record are handed back by `finishAnalyzableBailouts` and attributed to it.
859+
* @param {Module} module the module being generated
860+
* @returns {void}
861+
*/
862+
beginAnalyzableBailouts(module) {
863+
this._analyzableGeneratingModule = module;
864+
}
865+
866+
/**
867+
* Ends the collection `beginAnalyzableBailouts` started, so the reasons can be
868+
* stored beside the result and reapplied when the cache restores it.
869+
* @returns {string[] | undefined} the reasons recorded since, or undefined for none
870+
*/
871+
finishAnalyzableBailouts() {
872+
const sink = this._analyzableBailoutSink;
873+
this._analyzableGeneratingModule = undefined;
874+
this._analyzableBailoutSink = undefined;
875+
return sink;
876+
}
877+
878+
/**
879+
* Reapplies the bailouts a cached code generation result was stored with, so a
880+
* restored module reports the same reasons a generated one does.
881+
* @param {Module} module the module the result was restored for
882+
* @param {string[]} reasons the reasons stored beside it
883+
* @returns {void}
884+
*/
885+
restoreAnalyzableBailouts(module, reasons) {
886+
const bailouts =
887+
this.compilation.moduleGraph.getOptimizationBailout(module);
888+
for (const reason of reasons) {
889+
const text = `${ANALYZABLE_BAILOUT_PREFIX}${reason}`;
890+
if (!bailouts.includes(text)) bailouts.push(text);
891+
}
892+
}
893+
894+
/**
895+
* The reasons a module's references keep the runtime form, as recorded while its
896+
* code was generated.
897+
* @param {Module} module the module, a runtime module included
898+
* @returns {string[]} the reasons, none where every reference bakes
899+
*/
900+
analyzableBailoutsOf(module) {
901+
/** @type {string[]} */
902+
const reasons = [];
903+
for (const text of this.compilation.moduleGraph.getOptimizationBailout(
904+
module
905+
)) {
906+
if (
907+
typeof text === "string" &&
908+
text.startsWith(ANALYZABLE_BAILOUT_PREFIX)
909+
) {
910+
reasons.push(text.slice(ANALYZABLE_BAILOUT_PREFIX.length));
911+
}
912+
}
913+
return reasons;
914+
}
915+
837916
/**
838917
* Whether a name that code generation cannot settle may be reserved as a stand-in
839918
* and filled in once the hashes exist without a repair behind it. Substituting

‎lib/WebpackOptionsApply.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -980,6 +980,12 @@ class WebpackOptionsApply extends OptionsApply {
980980
new LargeModulesPlugin(options.performance).apply(compiler);
981981
}
982982

983+
if (options.performance.analyzableBailouts) {
984+
const AnalyzableBailoutsPlugin = require("./performance/AnalyzableBailoutsPlugin");
985+
986+
new AnalyzableBailoutsPlugin(options.performance).apply(compiler);
987+
}
988+
983989
if (options.performance.asyncChunkWaterfalls) {
984990
const AsyncChunkWaterfallsPlugin = require("./performance/AsyncChunkWaterfallsPlugin");
985991

‎lib/config/defaults.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2395,6 +2395,7 @@ const applyPerformanceDefaults = (performance, { production }) => {
23952395
// Stands in for every check left unset, so an explicit one still wins.
23962396
const all = performance.all !== undefined ? performance.all : false;
23972397

2398+
D(performance, "analyzableBailouts", all);
23982399
D(performance, "asyncChunkWaterfalls", all);
23992400
D(performance, "broadContexts", all);
24002401
D(performance, "cacheEffectiveness", all);
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
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+
const WebpackError = require("./WebpackError");
9+
10+
/**
11+
* @typedef {object} BailoutDetails
12+
* @property {string} reason what keeps the runtime form, as the code generation recorded it
13+
* @property {string[]} modules the modules it was recorded on, as many as are printed
14+
* @property {number} count how many modules it was recorded on in all
15+
*/
16+
17+
class AnalyzableBailoutsWarning extends WebpackError {
18+
/**
19+
* Creates an instance of AnalyzableBailoutsWarning.
20+
* @param {BailoutDetails[]} bailouts the reasons found, the most frequent first
21+
* @param {number} references how many module and reason pairs there are
22+
*/
23+
constructor(bailouts, references) {
24+
const list = bailouts
25+
.map((it) => {
26+
const more = it.count - it.modules.length;
27+
const names = `${it.modules.join(", ")}${more > 0 ? `, and ${more} more` : ""}`;
28+
return `\n ${it.reason}\n ${names}`;
29+
})
30+
.join("");
31+
32+
super(
33+
`analyzable ESM output: ${references} ${references === 1 ? "reference keeps" : "references keep"} the runtime form:${list}\nA bundler reading this output cannot follow such a reference without running webpack's runtime. Each reason names the setting that keeps it; changing that setting lets the reference be written as a literal import() or new URL().\nFor more info visit https://webpack.js.org/configuration/output/#outputmodule`
34+
);
35+
36+
/** @type {string} */
37+
this.name = "AnalyzableBailoutsWarning";
38+
}
39+
}
40+
41+
module.exports = AnalyzableBailoutsWarning;
Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
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+
const AnalyzableBailoutsWarning = require("../errors/AnalyzableBailoutsWarning");
9+
10+
/** @import { PerformanceOptions } from "../../declarations/WebpackOptions" */
11+
/** @import Compiler from "../Compiler" */
12+
/** @import Module from "../Module" */
13+
/** @import { BailoutDetails } from "../errors/AnalyzableBailoutsWarning" */
14+
15+
const PLUGIN_NAME = "AnalyzableBailoutsPlugin";
16+
17+
// Enough to point at the offenders without listing every module of a build.
18+
const MAX_REPORTED_MODULES = 5;
19+
20+
class AnalyzableBailoutsPlugin {
21+
/**
22+
* Creates an instance of AnalyzableBailoutsPlugin.
23+
* @param {PerformanceOptions} options the plugin options
24+
*/
25+
constructor(options) {
26+
/** @type {PerformanceOptions["hints"]} */
27+
this.hints = options.hints;
28+
}
29+
30+
/**
31+
* Applies the plugin by registering its hooks on the compiler.
32+
* @param {Compiler} compiler the compiler instance
33+
* @returns {void}
34+
*/
35+
apply(compiler) {
36+
const hints = this.hints;
37+
38+
if (!hints) return;
39+
40+
compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
41+
// `afterSeal` is past the hash, which folds every message into it — and
42+
// past the runtime modules, which record their reasons while being hashed.
43+
compilation.hooks.afterSeal.tap(PLUGIN_NAME, () => {
44+
const { chunkGraph, runtimeTemplate, requestShortener } = compilation;
45+
46+
// Nothing is recorded outside ESM output, so there is nothing to walk.
47+
if (!runtimeTemplate.isModule()) return;
48+
49+
/** @type {Map<string, Set<string>>} */
50+
const modulesByReason = new Map();
51+
52+
/**
53+
* Files the reasons recorded on a module under its printed name.
54+
* @param {Module} module the module, a runtime module included
55+
* @returns {void}
56+
*/
57+
const collect = (module) => {
58+
const reasons = runtimeTemplate.analyzableBailoutsOf(module);
59+
if (reasons.length === 0) return;
60+
const name = module.readableIdentifier(requestShortener);
61+
for (const reason of reasons) {
62+
let modules = modulesByReason.get(reason);
63+
if (modules === undefined) {
64+
modules = new Set();
65+
modulesByReason.set(reason, modules);
66+
}
67+
modules.add(name);
68+
}
69+
};
70+
71+
for (const module of compilation.modules) collect(module);
72+
for (const chunk of compilation.chunks) {
73+
for (const module of chunkGraph.getChunkRuntimeModulesIterable(
74+
chunk
75+
)) {
76+
collect(module);
77+
}
78+
}
79+
80+
if (modulesByReason.size === 0) return;
81+
82+
/** @type {BailoutDetails[]} */
83+
const bailouts = [];
84+
let references = 0;
85+
86+
for (const [reason, modules] of modulesByReason) {
87+
const names = [...modules].sort();
88+
references += names.length;
89+
bailouts.push({
90+
reason,
91+
modules: names.slice(0, MAX_REPORTED_MODULES),
92+
count: names.length
93+
});
94+
}
95+
96+
// The reason holding the most modules leads; ties read in one order.
97+
bailouts.sort(
98+
(a, b) => b.count - a.count || (a.reason < b.reason ? -1 : 1)
99+
);
100+
101+
const warning = new AnalyzableBailoutsWarning(bailouts, references);
102+
103+
if (hints === "error") {
104+
compilation.errors.push(warning);
105+
} else if (hints === "stats") {
106+
compilation.hints.push(warning);
107+
} else {
108+
compilation.warnings.push(warning);
109+
}
110+
});
111+
});
112+
}
113+
}
114+
115+
module.exports = AnalyzableBailoutsPlugin;

‎schemas/WebpackOptions.check.js‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎schemas/WebpackOptions.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5546,6 +5546,11 @@
55465546
"type": "boolean",
55475547
"added": "5.110.0"
55485548
},
5549+
"analyzableBailouts": {
5550+
"description": "Report references in ESM output that keep webpack's runtime form, naming what stops each from being written as a literal 'import()' or 'new URL()' another bundler can follow (requires 'hints' to be enabled).",
5551+
"type": "boolean",
5552+
"added": "5.111.0"
5553+
},
55495554
"assetFilter": {
55505555
"description": "Filter function to select assets that are checked.",
55515556
"instanceof": "Function",

0 commit comments

Comments
 (0)