feat(webpack): surface template diagnostics in the dev-server overlay (Task 2B, phase 4)

[0xSagaCity]

Stacked on #6 (phase 2), whose validate-templates.mjs this plugin shells out to. Independent of #7 (phase 3) — different files, no shared code.

This is the DevX phase, and the reason 2B is worth doing rather than just copying a file. A forker editing a template lives in npm run watch with the browser open; that is where a mistake should surface, not at commit time when the context is gone.

What

TemplateValidationPlugin in webpack.config.js, beside the two plugins already there (AssetManifestPlugin, CspMetaPlugin) and following the same shape — a plain class with apply(compiler) tapping compiler.hooks.

It shells out to validate-templates.mjs rather than importing it: this file is CommonJS, the validator is ESM, and NF5 requires the script stay byte-identical with ceres, so exporting a function from it is not an option. A full run measures 60–70ms, so there is no incremental logic, no caching, and no per-file scoping.

Three details that are easy to get wrong:

1. The validator exits 1 by design, and execFileSync throws on any non-zero exit — so the throw is the interesting path, not the failure path. The JSON is still on e.stdout. Treating the throw as a failure would silently drop every real diagnostic.
2. schemas/*.json is registered in compilation.fileDependencies. Nothing imports it, so webpack's module graph never reaches it and a regenerated contract would not retrigger validation. Registered before the run, so it happens even if the validator itself falls over.
3. Diagnostics are pushed, never thrown. Pushing to compilation.errors marks the build failed but webpack still emits, which is what EC7 requires: the author can keep looking at the template while fixing it. No bail, no throw from the tap, no deleteAsset.

The plugin is a pure transport — under --strict the validator has already promoted unknown-field to error severity, so re-implementing the promotion here would be a second copy of a rule 2A locked with S30.

The R13 decision

devServer.client.overlay is configured { errors: true, warnings: false }. unknown-field is a warning everywhere else — deliberately, because a lagging contract must not block anyone. But a field typo is the single most likely mistake a forker makes, so under warnings: false a plugin faithfully reporting it would show the author nothing: watch mode would loudly catch unregistered helpers and silently swallow the common case.

So strict is keyed to WEBPACK_SERVE, which webpack serve sets itself:

new TemplateValidationPlugin({ strict: process.env.WEBPACK_SERVE === "true" }),

Watch gets strict; npm run build, including #7's CI build, does not. Dev is where the feedback is free and the fix is one keystroke. Verified both ways against this repo's own pre-existing undeclared field, same commit, same template:

Command	Result
npm run build	WARNING in …template.hbs:195:56 unknown-field Unknown field 'total' — compiled, exit 0, dist/ emitted
WEBPACK_SERVE=true npx webpack	ERROR in …template.hbs:195:56 unknown-field Unknown field 'total'

Flipping overlay.warnings to true was the alternative and is rejected: it surfaces every unrelated webpack warning in the same red box, which trains people to close it.

Tests — 6 passing

#	Scenario	How
S39	a template error reaches the compilation as an error	fixture repo, unregistered helper → one compilation.errors entry naming file, line and helper; absent from warnings
S40	strict promotes unknown-field, and only the caller decides it	same fixture compiled twice, {strict:true} → errors, {strict:false} → warnings with errors empty; fixture byte-identical between runs. Driven by the constructor flag, never by asserting the string --strict, so it fails if the flag stops reaching the subprocess
S40b	watch passes strict, a plain build does not	reads the registered instance under WEBPACK_SERVE=true / unset. Added because nothing else proves the R13 wiring — S40 only proves the plugin honours the flag it is given
S41	a failing validation still emits assets	real webpack compile, not a fake: broken template → stats.hasErrors() true and bundle.js present on disk; fix the template → no errors. This is EC7's actual proof
S42	editing a schema retriggers validation	every schemas/*.json appears in compilation.fileDependencies — asserted on the registered dependency, not by driving a watch rebuild, which would test webpack's watcher
S43	no schemas/ directory does not crash the plugin	compilation completes, no plugin-level parse-failure error, no phantom dependency

The suite snapshots and restores src/**/version.json: requiring webpack.config.js runs its semver auto-bump as an import side effect (a one-time correction of stale digests, which npm run build also performs), and a unit run must not leave the working tree dirty.

Two corrections to the phase spec, both verified

1. S43's predicted diagnostics do not exist. phase-4.md expected unknown-root-context warnings for a repo with no schemas/. Running the validator directly against such a fixture returns [] at exit 0 — with no contract at all it skips field checking entirely. The test asserts what EC9 actually states ("SHALL NOT crash the plugin or the CI job") rather than a predicted diagnostic that never appears.

2. The dev server does not serve assets in this repo — and that is pre-existing. While verifying EC7 end-to-end I found npm run watch returns 404 Cannot GET /index.html for every path (/, /index.html, /main-manifest.json, /templates-list.json), with webpack confirmed listening on 127.0.0.1:1337. I reproduced this on the phase-2 branch with this plugin absent and a clean tree, so it is a pre-existing devServer configuration problem, not something this PR introduces.

It does mean R12's browser-overlay behaviour could not be visually confirmed, and it is worth its own issue: the overlay is the delivery mechanism this phase is built around. What is proven is everything on this side of the browser — the plugin emits the right diagnostics at the right severity under watch, and emission is unaffected (S41). Fixing the dev server is out of scope here.

Results

Check	phase 2 (#6)	this PR
tests	266 passed, 1 failed	272 passed, 1 failed
suites	17 (3 failed)	18 (3 failed)
typecheck	exit 0	exit 0
lint	386 errors	386 — 0 new; both changed files lint clean
npm run build	—	compiles, exit 0, dist/ emitted

The one failure is inherited S24, which belongs to PR #1 and is explained in #6. The two failing suites predate all of this work and were confirmed failing on pristine origin/master.