# Contributor handoff — webpack/webpack > Canonical page: https://codevetter.com/unpack/webpack/agent-handoff # Contributor handoff — webpack/webpack Scanned commit 87a62dec2304cd2c163c41feeeb43fbe3e5c21dd (2026-09-22). Generated by codevetter codevetter 1.12.0 on 2026-09-22. This repo has an unusually strict, written contract in `AGENTS.md` (symlinked as `CLAUDE.md`) with `> [!REQUIRED]` sections that reviewers enforce literally — read it before touching anything. The three rules that bite hardest: never invoke bare `jest` (use `yarn test:base`), never hand-edit generated files (run `yarn fix:special` and diff), and never sweep whole suites locally (push and read CI). Edits are safe inside `lib/` subdirectories and `test/`; they are dangerous at `lib/` root (deep-import breakage), inside generated `data.js`/`types.d.ts`/`*.check.js`, and in the hot parser methods sized to V8's inlining budget. Every user-facing change needs a `.changeset/NNN-*.md` entry and, for bug fixes, a failing test written first. - Read first, in order: `AGENTS.md` (the binding contract, including the mandatory PR template), `TESTING_DOCS.md` (suite layout and how to run one case), `lib/index.js` (the public surface), `lib/config/WebpackOptionsApply.js` (option→plugin map), and `lib/Compilation.js#L3612-3999` (the seal pipeline everything else hangs off). — [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) [TESTING_DOCS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/TESTING_DOCS.md) [lib/index.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/lib/index.js) [lib/config/WebpackOptionsApply.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/lib/config/WebpackOptionsApply.js) [lib/Compilation.js#L3612-3999](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/lib/Compilation.js#L3612-L3999) - `lib/` is CommonJS only with types as JSDoc `@typedef`/`@import` — no `import`/`export` syntax, no TypeScript syntax in `.js` files — and the annotations are compiled to `types.d.ts` by `yarn fix:special`. — [lib/webpack.js#L1-45](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/lib/webpack.js#L1-L45) [tsconfig.json#L1-12](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/tsconfig.json#L1-L12) [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) - Adding or renaming an option requires four ordered edits plus regeneration: `schemas/WebpackOptions.json` → `lib/config/defaults.js` → `lib/config/normalization.js` → the consuming site → `yarn fix:special`, then the snapshots the option's name leaks into (`test/__snapshots__/Cli.basictest.js.snap`, `Defaults.unittest.js`, `Validation.unittest.js`, the browserslist config cases). — [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) [schemas/WebpackOptions.json](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/schemas/WebpackOptions.json) [lib/config/defaults.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/lib/config/defaults.js) [lib/config/normalization.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/lib/config/normalization.js) - Never hand-edit the generated set: `types.d.ts`, `declarations/**/*.d.ts`, `schemas/**/*.check.{js,d.ts}`, generated runtime code, and `lib/{css,html,javascript}/data.js`. A new lookup table belongs in the matching `tooling/generate-*-data.js`, derived from a published dataset where possible. — [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) [lib/css/data.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/lib/css/data.js) [tooling/generate-css-data.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/tooling/generate-css-data.js) [package.json#L40-41](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/package.json#L40-L41) - Run targeted tests only: `yarn test:base --testPathPatterns=""` or `yarn test:basic --testPathPatterns="ConfigTestCases" --testNamePattern=" "`. Never pipe a jest run through `grep`/`tail` — that discards the exit code and a red run reads as green. — [package.json#L96-101](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/package.json#L96-L101) [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) [TESTING_DOCS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/TESTING_DOCS.md) - A snapshot can live in two suites: `ConfigTestCases` and `ConfigCacheTestCases` both snapshot `configCases/`, and `--testPathPatterns=ConfigTestCases` misses the second — update with `yarn test:basic --testNamePattern="" -u` and no path filter. — [test/ConfigTestCases.basictest.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/test/ConfigTestCases.basictest.js) [test/ConfigCacheTestCases.basictest.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/test/ConfigCacheTestCases.basictest.js) [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) - Writing a `configCases/` case: it is a mini project (`index.js` with assertions, `webpack.config.js`), the emitted bundle is actually executed in a `vm`, and optional `errors.js`/`warnings.js`/`test.filter.js`/`test.config.js` files control expected diagnostics, skipping and `findBundle`. — [test/templates/ConfigTestCases.js#L94-300](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/test/templates/ConfigTestCases.js#L94-L300) [test/templates/ConfigTestCases.js#L600-640](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/test/templates/ConfigTestCases.js#L600-L640) [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) - Never silence the cache suite with `test.filter.js` returning `!config.cache`; the sanctioned escape is an `infrastructure-log.js` returning `[/Pack got invalid because of write to/]` for cases whose subject is a build error (a module with `this.error` set always rebuilds by design). — [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) [test/ConfigCacheTestCases.basictest.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/test/ConfigCacheTestCases.basictest.js) [lib/module/NormalModule.js#L2059-2090](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/lib/module/NormalModule.js#L2059-L2090) - Moving a file out of `lib/` root has six carriers to rewrite — `require`/`require.resolve`, `@import` JSDoc, `@typedef {import(...)}`, `tsType` in schemas, the `makeSerializable` request, and paths written into `tooling/generate-runtime-code.js` or `eslint.config.mjs` — and `yarn find-deep-imports:check` must be run before the commit. — [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) [tooling/find-deep-webpack-imports.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/tooling/find-deep-webpack-imports.js) [tooling/deep-webpack-imports.json](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/tooling/deep-webpack-imports.json) [lib/util/makeSerializable.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/lib/util/makeSerializable.js) - Comment budget is enforced by lint: a plain `//` or `/* */` comment is capped at three lines by the `webpack/comment-length` rule (JSDoc tag blocks, the file-header block, and `// WHY:` comments are the exemptions), and `examples/` is the only directory excluded. — [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) [eslint.config.mjs#L122-150](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/eslint.config.mjs#L122-L150) - Deferred work uses exactly one wording — `TODO in the next major release: ` — never a version number, so `grep -rn "TODO in the next major release" codecov.yml bin hot lib setup test tooling` lists the whole backlog. — [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) [lib/wasm-sync/](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/lib/wasm-sync/) [lib/index.js#L315-330](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/lib/index.js#L315-L330) - Never enumerate module/source/dependency types in `lib/`: ask the object (`module.getSourceTypes()`, `chunkGraph.getModuleSourceTypes(module)`, `moduleGraph.getParentModule(dependency)`) or match the class (`dependency instanceof URLDependency`), and when a branch must name a type, write it so an unknown type takes the safe side. — [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) [lib/graph/ModuleGraph.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/lib/graph/ModuleGraph.js) [lib/module/Module.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/lib/module/Module.js) - Performance claims need the cheap, deterministic kinds of evidence first (counting > CPU-profile attribution > retained heap > wall timing); `FILTER="" yarn benchmark` drives `test/benchmarkCases/`, `yarn test:size` counts emitted bytes, and gzip is the column a size change is judged on. — [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) [package.json#L57-58](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/package.json#L57-L58) [test/CodeSizeTestCases.size.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/test/CodeSizeTestCases.size.js) [test/benchmarkCases/](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/test/benchmarkCases/) - Every user-facing change needs one `.changeset/NNN-.md` with a `patch`/`minor`/`major` bump and a single capitalized imperative sentence ≤80 chars; the numeric prefix controls ordering in `CHANGELOG.md`, and `yarn validate:changeset` checks the format (there are 42 pending entries today). — [.changeset/](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/.changeset/) [package.json#L43](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/package.json#L43) [.changeset/changeset-validate.mjs](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/.changeset/changeset-validate.mjs) [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) - Before pushing, run the full `yarn lint` (nine stages, `&&`-chained so the first failure hides the rest) — `yarn fix` alone runs no type check and no spellcheck; cspell reads every Markdown file in the repo, so even a docs-only change can red the `lint` job. — [package.json#L36-43](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/package.json#L36-L43) [cspell.json](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/cspell.json) [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) - A local failure is only yours if it does not reproduce on `main` — `Cli createColors`, `profiling-plugin`, the `many-replacements` cases and the generated-declaration check are known sandbox-environment failures, so check with `git worktree add origin/main` before chasing one. — [AGENTS.md](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/AGENTS.md) [test/Cli.basictest.js](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/test/Cli.basictest.js) [test/unitCases/](https://github.com/webpack/webpack/blob/87a62dec2304cd2c163c41feeeb43fbe3e5c21dd/test/unitCases/) Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers. ## Public product links - [CodeVetter](https://codevetter.com/) - [Download](https://codevetter.com/download) - [Documentation](https://codevetter.com/docs/) - [Source](https://github.com/Codevetter/codevetter)