Skip to content

Commit d7e0fd9

Browse files
docs: bring lib/ comments under the three-line limit and enable webpack/comment-length repo-wide (#22152)
* docs(html): bring HtmlParser comments under the three-line limit * docs(html): bring HtmlModulesPlugin comments under the three-line limit * docs(html): bring HtmlEntryDependency comments under the three-line limit * docs(html): bring HtmlGenerator comments under the three-line limit * docs(config): bring defaults comments under the three-line limit * docs: bring SourceMapDevToolPlugin comments under the three-line limit * docs(javascript): bring syntax comments under the three-line limit * docs(optimize): bring ConcatenatedModule comments under the three-line limit * docs: bring RuntimeTemplate comments under the three-line limit * docs(runtime): bring deferred namespace comments under the three-line limit * docs: bring ConstPlugin comments under the three-line limit * docs: bring TemplatedPathPlugin comments under the three-line limit * docs(javascript): bring JavascriptModulesPlugin comments under the three-line limit * docs: bring core plugin comments under the three-line limit * docs: bring module graph and flag plugin comments under the three-line limit * docs: bring asset, chunk graph and cache comments under the three-line limit * docs(css): bring parser, generator and config comments under the three-line limit * docs(css): bring cssMinify comments under the three-line limit * docs(dependencies): bring dependency comments under the three-line limit * docs(dependencies): bring harmony, html and worker comments under the three-line limit * docs(dependencies): finish the harmony and worker comment sweep * docs: bring worker, html minify and parser comments under the three-line limit * docs(optimize): bring optimization plugin comments under the three-line limit * docs(node): finish the watch file system comment sweep * docs: bring side effects, prefetch and performance comments under the three-line limit * docs(serialization): move format grammars into the file preamble * docs(util): bring the remaining util and wasm comments under the limit * docs(html): compress the quoted tokenizer spec arcs * docs(html): bring syntax.js comments under the limit * docs(css): shorten the parser comments in syntax.js * docs(css): shorten the streaming and printer comments * docs(css): shorten the color and prefixing comments * docs(css): shorten the shorthand and value comments * docs(css): bring syntax.js comments under the limit * build: enable webpack/comment-length across the repository lib/ is swept, so the rule no longer needs a directory allowlist. examples/ keeps it off: a commented-out config there is what a reader copies. * docs: restore the rationale the sweep compressed away, under WHY: An audit of the sweep against main found comments where a contract, an option's semantics or a measured number was cut rather than shortened. Those are back in full behind the WHY: marker the limit exempts. * docs: restore more compressed-away rationale under WHY: * docs: restore the worked examples and version facts the sweep dropped * docs: drop the WHY marker where three lines already carry it * docs: say that runtime chunks can still cycle when hashing
1 parent 5f3a2ff commit d7e0fd9

105 files changed

Lines changed: 2270 additions & 3496 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: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -238,7 +238,7 @@ Every source file under `lib/` (and `hot/`, `tooling/`) opens with the MIT licen
238238
239239
**A plain comment is at most three lines. Count them.** This binds every `//` and `/* … */` in `lib/`, `hot/`, `tooling/` and `test/`, and every comment a generator emits into its output. A fourth line is over the limit however short each line is and however true every word — split the thought, cut it, or drop it.
240240

241-
`webpack/comment-length` reports it, so `yarn lint:code` is where you see it — over whole files rather than a diff, and it reads comment tokens, so comment-shaped lines inside a string are not comments. It is switched on for `test/`, `tooling/` and `hot/` only: `lib/` has never been swept, so until the TODO in `eslint.config.mjs` goes, the limit still binds there but nothing reports it for you.
241+
`webpack/comment-length` reports it, so `yarn lint:code` is where you see it — over whole files rather than a diff, and it reads comment tokens, so comment-shaped lines inside a string are not comments. It is on for the whole repository, `lib/` included, so a comment over the limit fails `lint` rather than waiting for a reviewer. `examples/` is the one exception: a commented-out config there is what a reader copies, and the prose is the example's own documentation.
242242

243243
**Three things are exempt. JSDoc is a type contract rather than commentary, and the other two are not commentary either.** The block before a file's first statement documents the file, like the license header above it — the `"use strict"` directive between the two does not end it. And a comment whose first line opens `// WHY:` states why the code is shaped the way it is — the spec prose behind a `SUPPLEMENT` entry, a measured engine disagreement, a constraint some other file depends on — which is the one kind of explanation that cannot be made shorter without losing it:
244244

‎eslint.config.mjs‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ export default defineConfig([
3737
"*.check.js",
3838

3939
// Ignore not supported files
40-
"*.d.ts",
40+
"**/*.d.ts",
4141

4242
// Ignore precompiled schemas
4343
"schemas/**/*.check.js",
@@ -99,10 +99,14 @@ export default defineConfig([
9999
},
100100
configs["webpack/schemas"],
101101
configs["webpack/types"],
102+
configs["webpack/comments"],
102103
{
103-
// TODO extend to lib/, which carries 652 comments over the limit
104-
files: ["test/**/*.{js,mjs,cjs}", "tooling/**/*.js", "hot/**/*.js"],
105-
extends: [configs["webpack/comments"]]
104+
// An example's commented-out config is what a reader copies, and its prose
105+
// is the example's own documentation — neither is commentary to shorten.
106+
files: ["examples/**/*.{js,cjs,mjs}"],
107+
rules: {
108+
"webpack/comment-length": "off"
109+
}
106110
},
107111
{
108112
files: ["lib/**/*.js"],
@@ -295,10 +299,9 @@ export default defineConfig([
295299
}
296300
},
297301
{
298-
// `color-name` is ESM, so the CSS data generator reaches its table
299-
// through a dynamic import rather than a `require` no jest `vm` supports.
300-
// `html-minifier-next` is ESM only, and the HTML comparison imports it the
301-
// same way.
302+
// `color-name` is ESM, so the CSS data generator reaches its table through a
303+
// dynamic import rather than a `require` no jest `vm` supports.
304+
// `html-minifier-next` is ESM only and is imported the same way.
302305
files: ["tooling/generate-css-data.js", "tooling/compare-html-tools.js"],
303306
rules: {
304307
"n/no-unsupported-features/es-syntax": [

‎lib/APIPlugin.js‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,10 +45,9 @@ const getConcatenatedModule = memoize(() =>
4545
/** @import { RuntimeSpec } from "./util/runtime" */
4646
/** @import JavascriptParser, { Range } from "./javascript/JavascriptParser" */
4747

48-
// Modules that reassign `__webpack_public_path__` at runtime, by compilation. A baked
49-
// analyzable specifier can't reflect that, so those forms fall back. Also recorded per
50-
// module in `buildInfo`, because a module restored from the persistent cache is never
51-
// re-parsed and would otherwise lose the flag.
48+
// Modules reassigning `__webpack_public_path__` at runtime, per compilation, since
49+
// a baked specifier cannot reflect that. Also kept in `buildInfo`: a module
50+
// restored from the persistent cache is never re-parsed.
5251
/** @type {WeakMap<Compilation, Set<Module>>} */
5352
const runtimePublicPathOverride = new WeakMap();
5453

‎lib/CompatibilityPlugin.js‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -180,10 +180,9 @@ class CompatibilityPlugin {
180180
});
181181
return true;
182182
});
183-
// `const`/`let` are block-pre-walked, by which point the name is no
184-
// longer free and `hooks.pattern` is not dispatched for it — tag
185-
// them through the kind-specific declaration hooks instead.
186-
// Returning nothing lets the variable be defined, keeping the tag.
183+
// `const` and `let` are block-pre-walked, by which point the name is no
184+
// longer free and `hooks.pattern` never fires, so they are tagged
185+
// through the declaration hooks instead.
187186
for (const hookMap of [
188187
parser.hooks.varDeclarationConst,
189188
parser.hooks.varDeclarationLet

‎lib/Compilation.js‎

Lines changed: 6 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -2659,12 +2659,9 @@ BREAKING CHANGE: Asset processing hooks in Compilation has been merged into a si
26592659
return;
26602660
}
26612661

2662-
// lazy barrel:
2663-
// 1. first call: barrel module is not classified yet, so this records the requested
2664-
// ids and returns undefined; the targets get built below when
2665-
// `processModuleDependencies` runs `_lazyBarrelController.classify` and replays them.
2666-
// 2. later call: barrel module is already built, so `processModuleDependencies` won't
2667-
// re-walk it; the newly requested targets must be built here.
2662+
// lazy barrel: on the first call the module is unclassified, so this only
2663+
// records the ids and `processModuleDependencies` replays them. Later the
2664+
// module is built and never re-walked, so the targets are built here.
26682665
const unlazyItems = this._lazyBarrelController.request(
26692666
module,
26702667
dependencies
@@ -5207,22 +5204,9 @@ Or do you want to use the entrypoints '${name}' and '${runtime}' independently o
52075204
}
52085205

52095206
this.logger.time("hashing: sort chunks");
5210-
/*
5211-
* Chunks are hashed in 4 categories, in this order:
5212-
* 1. Async chunks - no hash dependencies on other chunks
5213-
* 2. Non-entry initial chunks (e.g. shared split chunks) - no hash
5214-
* dependencies on other chunks, but runtime chunks may read their
5215-
* hashes via GetChunkFilenameRuntimeModule (dependentHash)
5216-
* 3. Runtime chunks - may use hashes of async and non-entry initial
5217-
* chunks (via GetChunkFilenameRuntimeModule). Ordered by references
5218-
* between each other (for async entrypoints)
5219-
* 4. Entry chunks - may depend on runtimeChunk.hash (via
5220-
* createChunkHashHandler for ESM/CJS entry importing runtime)
5221-
*
5222-
* This ordering ensures all hash dependencies flow in one direction:
5223-
* async/initial → runtime → entry, with no circular dependencies.
5224-
* Chunks within each category are sorted by id for determinism.
5225-
*/
5207+
// Hashed as async, then non-entry initial, then runtime, then entry chunks,
5208+
// so hash dependencies flow one way between those groups. A cycle among the
5209+
// runtime chunks is still possible, and is warned about below.
52265210
/** @type {Chunk[]} */
52275211
const unorderedRuntimeChunks = [];
52285212
/** @type {Chunk[]} */

‎lib/Compiler.js‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1063,10 +1063,9 @@ ${other}`);
10631063

10641064
updateWithReplacementSource(content.length);
10651065

1066-
// if it exists and content on disk matches content
1067-
// skip writing the same content again
1068-
// (to keep mtime and don't trigger watchers)
1069-
// for a fast negative match file size is compared first
1066+
// Skip rewriting content already on disk, which would move the
1067+
// mtime and wake watchers. Size is compared first, as a cheap
1068+
// negative match.
10701069
if (content.length === stats.size) {
10711070
compilation.comparedForEmitAssets.add(file);
10721071
return /** @type {OutputFileSystem} */ (

‎lib/ConstPlugin.js‎

Lines changed: 16 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -219,17 +219,8 @@ class ConstPlugin {
219219
} else {
220220
parser.walkExpression(expression.test);
221221
}
222-
// Expressions do not hoist.
223-
// It is safe to remove the dead branch.
224-
//
225-
// Given the following code:
226-
//
227-
// false ? someExpression() : otherExpression();
228-
//
229-
// the generated code is:
230-
//
231-
// false ? 0 : otherExpression();
232-
//
222+
// Expressions do not hoist, so the dead branch is safe to remove:
223+
// `false ? someExpression() : other()` becomes `false ? 0 : other()`.
233224
const branchToRemove = bool
234225
? expression.alternate
235226
: expression.consequent;
@@ -254,49 +245,9 @@ class ConstPlugin {
254245
const param = parser.evaluateExpression(expression.left);
255246
const bool = param.asBool();
256247
if (typeof bool === "boolean") {
257-
// Expressions do not hoist.
258-
// It is safe to remove the dead branch.
259-
//
260-
// ------------------------------------------
261-
//
262-
// Given the following code:
263-
//
264-
// falsyExpression() && someExpression();
265-
//
266-
// the generated code is:
267-
//
268-
// falsyExpression() && false;
269-
//
270-
// ------------------------------------------
271-
//
272-
// Given the following code:
273-
//
274-
// truthyExpression() && someExpression();
275-
//
276-
// the generated code is:
277-
//
278-
// true && someExpression();
279-
//
280-
// ------------------------------------------
281-
//
282-
// Given the following code:
283-
//
284-
// truthyExpression() || someExpression();
285-
//
286-
// the generated code is:
287-
//
288-
// truthyExpression() || false;
289-
//
290-
// ------------------------------------------
291-
//
292-
// Given the following code:
293-
//
294-
// falsyExpression() || someExpression();
295-
//
296-
// the generated code is:
297-
//
298-
// false && someExpression();
299-
//
248+
// Expressions do not hoist, so the dead branch is safe to remove.
249+
// Whichever side cannot decide the result is replaced, leaving the
250+
// deciding side and its side effects in place.
300251
const keepRight =
301252
(expression.operator === "&&" && bool) ||
302253
(expression.operator === "||" && !bool);
@@ -305,14 +256,8 @@ class ConstPlugin {
305256
!param.couldHaveSideEffects() &&
306257
(param.isBoolean() || keepRight)
307258
) {
308-
// for case like
309-
//
310-
// return'development'===process.env.NODE_ENV&&'foo'
311-
//
312-
// we need a space before the bool to prevent result like
313-
//
314-
// returnfalse&&'foo'
315-
//
259+
// The bool needs a leading space: `return'a'===b&&'foo'` would
260+
// otherwise become `returnfalse&&'foo'`.
316261
const dep = new ConstDependency(
317262
` ${bool}`,
318263
/** @type {Range} */ (param.range)
@@ -336,36 +281,12 @@ class ConstPlugin {
336281
const param = parser.evaluateExpression(expression.left);
337282
const keepRight = param.asNullish();
338283
if (typeof keepRight === "boolean") {
339-
// ------------------------------------------
340-
//
341-
// Given the following code:
342-
//
343-
// nonNullish ?? someExpression();
344-
//
345-
// the generated code is:
346-
//
347-
// nonNullish ?? 0;
348-
//
349-
// ------------------------------------------
350-
//
351-
// Given the following code:
352-
//
353-
// nullish ?? someExpression();
354-
//
355-
// the generated code is:
356-
//
357-
// null ?? someExpression();
358-
//
284+
// `nonNullish ?? x` becomes `nonNullish ?? 0`, and `nullish ?? x`
285+
// becomes `null ?? x`: the unreachable side is replaced.
359286
if (!param.couldHaveSideEffects() && keepRight) {
360287
// cspell:word returnnull
361-
// for case like
362-
//
363-
// return('development'===process.env.NODE_ENV&&null)??'foo'
364-
//
365-
// we need a space before the bool to prevent result like
366-
//
367-
// returnnull??'foo'
368-
//
288+
// As above, the value needs a leading space, or `return(…&&null)`
289+
// would become `returnnull??'foo'`.
369290
const dep = new ConstDependency(
370291
" null",
371292
/** @type {Range} */ (param.range)
@@ -423,18 +344,8 @@ class ConstPlugin {
423344
);
424345

425346
if (evaluated.asNullish()) {
426-
// ------------------------------------------
427-
//
428-
// Given the following code:
429-
//
430-
// nullishMemberChain?.a.b();
431-
//
432-
// the generated code is:
433-
//
434-
// undefined;
435-
//
436-
// ------------------------------------------
437-
//
347+
// A nullish chain short-circuits whole, so `nullish?.a.b()`
348+
// becomes `undefined`.
438349
const dep = new ConstDependency(
439350
" undefined",
440351
/** @type {Range} */ (expr.range)
@@ -519,36 +430,9 @@ class ConstPlugin {
519430
* @returns {void}
520431
*/
521432
eliminateUnusedStatement(parser, statement, alwaysInBlock) {
522-
// Before removing the unused branch, the hoisted declarations
523-
// must be collected.
524-
//
525-
// Given the following code:
526-
//
527-
// if (true) f() else g()
528-
// if (false) {
529-
// function f() {}
530-
// const g = function g() {}
531-
// if (someTest) {
532-
// let a = 1
533-
// var x, {y, z} = obj
534-
// }
535-
// } else {
536-
// …
537-
// }
538-
//
539-
// the generated code is:
540-
//
541-
// if (true) f() else {}
542-
// if (false) {
543-
// var f, x, y, z; (in loose mode)
544-
// var x, y, z; (in strict mode)
545-
// } else {
546-
// …
547-
// }
548-
//
549-
// NOTE: When code runs in strict mode, `var` declarations
550-
// are hoisted but `function` declarations don't.
551-
//
433+
// The hoisted declarations must be collected before the unused branch goes,
434+
// since the removed code still contributes them. In strict mode `var` is
435+
// hoisted but `function` is not, so the two modes collect different sets.
552436
const declarations = parser.scope.isStrict
553437
? getHoistedDeclarations(statement, false)
554438
: getHoistedDeclarations(statement, true);

‎lib/DotenvPlugin.js‎

Lines changed: 24 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -3,28 +3,6 @@
33
Author Natsu @xiaoxiaojx
44
*/
55

6-
"use strict";
7-
8-
const FileSystemInfo = require("./FileSystemInfo");
9-
const DotenvFileError = require("./errors/DotenvFileError");
10-
const { join } = require("./util/fs");
11-
12-
/** @import { DotenvPluginOptions } from "../declarations/WebpackOptions" */
13-
/** @import Compiler from "./Compiler" */
14-
/** @import { ItemCacheFacade } from "./CacheFacade" */
15-
/** @import { InputFileSystem } from "./util/fs" */
16-
/** @import { Snapshot } from "./FileSystemInfo" */
17-
18-
/** @typedef {Exclude<DotenvPluginOptions["prefix"], string | undefined>} Prefix */
19-
/** @typedef {Record<string, string>} Env */
20-
21-
const DEFAULT_TEMPLATE = [
22-
".env",
23-
".env.local",
24-
".env.[mode]",
25-
".env.[mode].local"
26-
];
27-
286
// cspell:ignore Motte, motdotla
297

308
/*
@@ -62,6 +40,28 @@ const DEFAULT_TEMPLATE = [
6240
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
6341
*/
6442

43+
"use strict";
44+
45+
const FileSystemInfo = require("./FileSystemInfo");
46+
const DotenvFileError = require("./errors/DotenvFileError");
47+
const { join } = require("./util/fs");
48+
49+
/** @import { DotenvPluginOptions } from "../declarations/WebpackOptions" */
50+
/** @import Compiler from "./Compiler" */
51+
/** @import { ItemCacheFacade } from "./CacheFacade" */
52+
/** @import { InputFileSystem } from "./util/fs" */
53+
/** @import { Snapshot } from "./FileSystemInfo" */
54+
55+
/** @typedef {Exclude<DotenvPluginOptions["prefix"], string | undefined>} Prefix */
56+
/** @typedef {Record<string, string>} Env */
57+
58+
const DEFAULT_TEMPLATE = [
59+
".env",
60+
".env.local",
61+
".env.[mode]",
62+
".env.[mode].local"
63+
];
64+
6565
// Regex for parsing .env files
6666
// ported from https://github.com/motdotla/dotenv/blob/v17.4.2/lib/main.js#L38
6767
const LINE =
@@ -223,12 +223,8 @@ function expand(options) {
223223
runningParsed[key] = resolvedValue;
224224
}
225225

226-
// Part of `dotenv-expand` code, but we don't need it because of we don't modify `process.env`
227-
// for (const processKey in options.parsed) {
228-
// if (processEnv) {
229-
// processEnv[processKey] = options.parsed[processKey];
230-
// }
231-
// }
226+
// `dotenv-expand` writes the parsed values back into `process.env` here.
227+
// Omitted: webpack never mutates the ambient environment.
232228

233229
return options;
234230
}

0 commit comments

Comments
 (0)