Skip to content

Commit fde3842

Browse files
feat: resolve imported ESM bindings by name in a debugger
Imported bindings compile to a namespace read, so a debugger's console and watch expressions cannot resolve the name the source uses (#3957). Two complementary halves, both semantics-preserving: `optimization.localImportBindings` (on in development) declares a real local variable for an imported name wherever that is observationally equal to the live binding: a namespace object, whose identity never changes, and a named import of a top-level `const` or an `export default` expression, which the language pins to one value. A module read from inside its own evaluation cycle, or accepted by `module.hot.accept` (where an update re-runs the import statement rather than the module body), keeps reading through the namespace. A `-scopes` devtool suffix emits the ECMA-426 "Scopes" field, naming for every remaining binding the generated expression it reads. It changes no emitted code and costs bytes only in the map.
1 parent 2e999c1 commit fde3842

47 files changed

Lines changed: 1391 additions & 27 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"webpack": minor
3+
---
4+
5+
Resolve imported ESM bindings by name in a debugger, via locals and `scopes`.

‎lib/DependencyTemplate.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@
3737
* @property {ConcatenationScope=} concatenationScope when in a concatenated module, information about other concatenated modules
3838
* @property {CodeGenerationResults} codeGenerationResults the code generation results
3939
* @property {InitFragment<GenerateContext>[]} chunkInitFragments chunkInitFragments
40+
* @property {Map<string, string>=} importBindings what each imported binding of the current module reads, by its name in the source, for the source map `scopes` field
4041
*/
4142

4243
/**

‎lib/EvalSourceMapDevToolPlugin.js‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@ const JavascriptModulesPlugin = require("./javascript/JavascriptModulesPlugin");
1414
const ConcatenatedModule = require("./optimize/ConcatenatedModule");
1515
const generateDebugId = require("./util/generateDebugId");
1616
const { makePathsAbsolute } = require("./util/identifier");
17+
const {
18+
addScopesToSourceMap,
19+
enableImportBindingScopes
20+
} = require("./util/sourceMapScopes");
1721

1822
/** @import { RawSourceMap, Source } from "webpack-sources" */
1923
/**
@@ -84,6 +88,9 @@ class EvalSourceMapDevToolPlugin {
8488
apply(compiler) {
8589
const options = this.options;
8690
compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
91+
if (options.scopes) {
92+
enableImportBindingScopes(compilation.moduleGraph);
93+
}
8794
const hooks = JavascriptModulesPlugin.getCompilationHooks(compilation);
8895
new SourceMapDevToolModuleOptionsPlugin(options).apply(compilation);
8996
const matchModule = ModuleFilenameHelpers.matchObject.bind(
@@ -211,6 +218,27 @@ class EvalSourceMapDevToolPlugin {
211218
sourceMap.debugId = generateDebugId(content, sourceMap.file);
212219
}
213220

221+
const { codeGenerationResults } = compilation;
222+
if (options.scopes && codeGenerationResults) {
223+
// The clone above shares `names` with the source's own map, and
224+
// encoding appends to it.
225+
sourceMap.names = sourceMap.names ? [...sourceMap.names] : [];
226+
addScopesToSourceMap(sourceMap, (sourceIndex) => {
227+
const module = modules[sourceIndex];
228+
if (
229+
typeof module === "string" ||
230+
!codeGenerationResults.has(module, chunk.runtime)
231+
) {
232+
return;
233+
}
234+
return codeGenerationResults.getData(
235+
module,
236+
chunk.runtime,
237+
"importBindings"
238+
);
239+
});
240+
}
241+
214242
const footer = `${this.sourceMapComment.replace(
215243
/\[url\]/g,
216244
`data:application/json;charset=utf-8;base64,${Buffer.from(

‎lib/InitFragment.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -207,5 +207,6 @@ InitFragment.STAGE_HARMONY_IMPORTS = 40;
207207
InitFragment.STAGE_PROVIDES = 50;
208208
InitFragment.STAGE_ASYNC_DEPENDENCIES = 60;
209209
InitFragment.STAGE_ASYNC_HARMONY_IMPORTS = 70;
210+
InitFragment.STAGE_HARMONY_IMPORT_BINDINGS = 80;
210211

211212
module.exports = InitFragment;

‎lib/NormalModule.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1650,6 +1650,7 @@ class NormalModule extends Module {
16501650
topLevelDeclarations: undefined,
16511651
pureFunctions: undefined,
16521652
inlineExports: undefined,
1653+
stableExports: undefined,
16531654
moduleConcatenationBailout: undefined,
16541655
moduleConcatenationRootBailout: undefined,
16551656
diagnostics: undefined,

‎lib/SourceMapDevToolPlugin.js‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,10 @@ const createHash = require("./util/createHash");
1616
const { dirname, relative } = require("./util/fs");
1717
const generateDebugId = require("./util/generateDebugId");
1818
const { makePathsAbsolute } = require("./util/identifier");
19+
const {
20+
addScopesToSourceMap,
21+
enableImportBindingScopes
22+
} = require("./util/sourceMapScopes");
1923

2024
/** @import { MapOptions, Source, RawSourceMap } from "webpack-sources" */
2125
/**
@@ -279,6 +283,7 @@ class SourceMapDevToolPlugin {
279283
options.columns !== false,
280284
Boolean(options.noSources),
281285
Boolean(options.debugIds),
286+
Boolean(options.scopes),
282287
options.sourceRoot || "",
283288
toCacheKeyValue(options.ignoreList),
284289
options.publicPath || "",
@@ -324,6 +329,9 @@ class SourceMapDevToolPlugin {
324329
);
325330

326331
compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
332+
if (options.scopes) {
333+
enableImportBindingScopes(compilation.moduleGraph);
334+
}
327335
new SourceMapDevToolModuleOptionsPlugin(options).apply(compilation);
328336

329337
// All SourceMapDevToolPlugin instances on the same compilation share
@@ -764,6 +772,29 @@ class SourceMapDevToolPlugin {
764772
if (debugIdValue !== undefined) {
765773
outputSourceMap.debugId = debugIdValue;
766774
}
775+
const { codeGenerationResults } = compilation;
776+
if (options.scopes && codeGenerationResults) {
777+
// The spread above shares `names` with a map a
778+
// `SourceMapSource` may hold, and encoding appends to it.
779+
outputSourceMap.names = sourceMap.names
780+
? [...sourceMap.names]
781+
: [];
782+
const runtime = chunk && chunk.runtime;
783+
addScopesToSourceMap(outputSourceMap, (sourceIndex) => {
784+
const module = modules[sourceIndex];
785+
if (
786+
typeof module === "string" ||
787+
!codeGenerationResults.has(module, runtime)
788+
) {
789+
return;
790+
}
791+
return codeGenerationResults.getData(
792+
module,
793+
runtime,
794+
"importBindings"
795+
);
796+
});
797+
}
767798

768799
if (sourceMapFilename) {
769800
// External `.map` file: hold the serialized map as a

‎lib/WebpackOptionsApply.js‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -460,6 +460,7 @@ class WebpackOptionsApply extends OptionsApply {
460460
const moduleMaps = use.includes("module");
461461
const noSources = use.includes("nosources");
462462
const debugIds = use.includes("debugids");
463+
const scopes = use.includes("scopes");
463464
const Plugin = evalWrapped
464465
? require("./EvalSourceMapDevToolPlugin")
465466
: require("./SourceMapDevToolPlugin");
@@ -482,7 +483,8 @@ class WebpackOptionsApply extends OptionsApply {
482483
columns: !cheap,
483484
noSources,
484485
namespace: options.output.devtoolNamespace,
485-
debugIds
486+
debugIds,
487+
scopes
486488
}).apply(compiler);
487489
} else if (use.includes("eval")) {
488490
const EvalDevToolModulePlugin = require("./EvalDevToolModulePlugin");
@@ -734,6 +736,11 @@ class WebpackOptionsApply extends OptionsApply {
734736
inlineExports
735737
}).apply(compiler);
736738

739+
if (options.optimization.localImportBindings) {
740+
const LocalImportBindingsPlugin = require("./optimize/LocalImportBindingsPlugin");
741+
742+
new LocalImportBindingsPlugin().apply(compiler);
743+
}
737744
if (options.optimization.mangleExports) {
738745
const MangleExportsPlugin = require("./optimize/MangleExportsPlugin");
739746

‎lib/config/defaults.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,7 @@ const {
171171
* mangleExports: NonNullable<Optimization["mangleExports"]>,
172172
* innerGraph: NonNullable<Optimization["innerGraph"]>,
173173
* inlineExports: NonNullable<Optimization["inlineExports"]>,
174+
* localImportBindings: NonNullable<Optimization["localImportBindings"]>,
174175
* concatenateModules: NonNullable<Optimization["concatenateModules"]>,
175176
* avoidEntryIife: NonNullable<Optimization["avoidEntryIife"]>,
176177
* emitOnErrors: NonNullable<Optimization["emitOnErrors"]>,
@@ -2493,6 +2494,7 @@ const applyOptimizationDefaults = (
24932494
D(optimization, "usedExports", production);
24942495
D(optimization, "innerGraph", production);
24952496
D(optimization, "inlineExports", production);
2497+
D(optimization, "localImportBindings", development);
24962498
D(optimization, "mangleExports", production);
24972499
D(optimization, "concatenateModules", production);
24982500
D(optimization, "avoidEntryIife", production);

‎lib/dependencies/HarmonyExportDependencyParserPlugin.js‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,11 +38,34 @@ const { ImportPhaseUtils, createGetImportPhase } = require("./ImportPhase");
3838
/** @import JavascriptParser, { Range } from "../javascript/JavascriptParser" */
3939
/** @import { HarmonySettings } from "./HarmonyImportDependencyParserPlugin" */
4040
/** @import { CompatibilitySettings } from "../CompatibilityPlugin" */
41+
/**
42+
* @import {
43+
* JavascriptModuleBuildInfo
44+
* } from "../javascript/JavascriptModule"
45+
*/
4146

4247
const { HarmonyStarExportsList } = HarmonyExportImportedSpecifierDependency;
4348

4449
const PLUGIN_NAME = "HarmonyExportDependencyParserPlugin";
4550

51+
/**
52+
* Records an export whose binding the language pins to a single value, so an
53+
* importer may read it once into a local variable.
54+
* @param {JavascriptParser} parser the parser
55+
* @param {string} name the exported name
56+
* @returns {void}
57+
*/
58+
const markStableExport = (parser, name) => {
59+
const buildInfo =
60+
/** @type {JavascriptModuleBuildInfo | undefined} */
61+
(parser.state.module.buildInfo);
62+
if (buildInfo === undefined) return;
63+
if (buildInfo.stableExports === undefined) {
64+
buildInfo.stableExports = new Set();
65+
}
66+
buildInfo.stableExports.add(name);
67+
};
68+
4669
module.exports = class HarmonyExportDependencyParserPlugin {
4770
/**
4871
* Creates an instance of HarmonyExportDependencyParserPlugin.
@@ -231,6 +254,14 @@ module.exports = class HarmonyExportDependencyParserPlugin {
231254
// A class observes its own name from a static initializer, which runs
232255
// before the name could be patched afterwards, so it is named in place.
233256
dep.isAnonymousDefaultClass = dep.isAnonymousDefault && isAnonymousClass;
257+
// A named declaration keeps a binding the module body may reassign;
258+
// every other form lands in a const or a name only webpack writes.
259+
if (!(
260+
node.type.endsWith("Declaration") &&
261+
/** @type {FunctionDeclaration | ClassDeclaration} */ (node).id
262+
)) {
263+
markStableExport(parser, "default");
264+
}
234265
dep.setLocWithIndex(parser.getLocation(statement), -1);
235266
parser.state.current.addDependency(dep);
236267
getInnerGraphUtils(parser.state.compilation).addVariableUsage(
@@ -292,6 +323,9 @@ module.exports = class HarmonyExportDependencyParserPlugin {
292323
name,
293324
tagData ? tagData.value || null : undefined
294325
);
326+
// Only a top-level `const` carries the tag, and no later statement
327+
// of the module can point that binding somewhere else.
328+
if (tagData) markStableExport(parser, name);
295329
// lazy barrel: defer the re-export at parse time when the importing module is side-effect-free
296330
const moduleFactoryMeta = parser.state.module.factoryMeta;
297331
if (

‎lib/dependencies/HarmonyImportDependencyParserPlugin.js‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ const {
1313
getImportAttributes
1414
} = require("../javascript/JavascriptParser");
1515
const { getInnerGraphUtils } = require("../optimize/InnerGraph");
16+
const { isImportBindingScopesEnabled } = require("../util/sourceMapScopes");
1617
const ConstDependency = require("./ConstDependency");
1718
const HarmonyAcceptDependency = require("./HarmonyAcceptDependency");
1819
const HarmonyAcceptImportDependency = require("./HarmonyAcceptImportDependency");
@@ -245,9 +246,21 @@ class HarmonyImportDependencyParserPlugin {
245246
lastSideEffectDependency = undefined;
246247
});
247248
parser.hooks.finish.tap(PLUGIN_NAME, () => {
249+
const recordDeclared = isImportBindingScopesEnabled(
250+
parser.state.compilation.moduleGraph
251+
);
248252
for (const settings of declaredSpecifiers) {
249253
const dependency = settings.dependency;
250-
if (dependency === undefined || settings.used) continue;
254+
if (dependency === undefined) continue;
255+
if (recordDeclared) {
256+
if (dependency.declaredSpecifiers === undefined) {
257+
dependency.declaredSpecifiers = [];
258+
}
259+
dependency.declaredSpecifiers.push([settings.ids, settings.name]);
260+
}
261+
// A namespace import names no export, so there is nothing to resolve
262+
// for it and nothing to report.
263+
if (settings.used || settings.ids.length === 0) continue;
251264
if (dependency.unusedSpecifiers === undefined) {
252265
dependency.unusedSpecifiers = {
253266
exportPresenceMode: this.exportPresenceMode,
@@ -346,8 +359,8 @@ class HarmonyImportDependencyParserPlugin {
346359
});
347360
parser.tagVariable(name, harmonySpecifierTag, settings);
348361
// The statement's dependency carries them, so a never-referenced
349-
// one still resolves; a namespace import names no export.
350-
if (ids.length !== 0) declaredSpecifiers.push(settings);
362+
// one still resolves.
363+
declaredSpecifiers.push(settings);
351364
return true;
352365
}
353366
);

0 commit comments

Comments
 (0)