fix(server): report the webjs.headers rule dropped for having no directives

[vivek7405]

Follow-up to #1300, fixing two defects a review found in the webjs.headers warning pass that landed in #1355 (merged as b4488f4).

Both are in packages/server/src/headers.js. Neither was catchable by the tests that shipped with them, which is how they got past a green suite and ten green CI checks.

The rule that loses every directive is dropped in silence

if (directives.length) rules.push(...) discarded a whole rule with no warning. Two ways in, and both are the failure the warning pass exists to end.

{ "source": "/x", "headers": [] } is schema-valid: webjs-config.schema.json puts no minItems on headers, and the boot config check added in the same PR does not descend into headers. So the rule was dropped and nothing anywhere said so, four lines below a docblock sentence claiming every malformed rule is dropped with a warning. Measured before the fix: compileHeaderRules({ webjs: { headers: [{ source: '/empty', headers: [] }] } }) returned [] and emitted zero warnings.

The other way in is a rule whose every directive was individually dropped. Those directives each warned, but nothing said the rule went with them, so an author reading the log saw three directive complaints and no indication that the path now has no rule at all.

compileHeaderRules had lost its docblock

warnDrop's JSDoc was inserted between that function's JSDoc and its declaration. Two consecutive JSDoc blocks means the second binds to what follows, so warnDrop was documented twice and compileHeaderRules was left with none: its @param, its @returns, the "Shape consumed" example, and the value: null removal contract were all orphaned. dev.js types readHeaderRules off ReturnType<typeof compileHeaderRules>, which was inferring rather than reading a declared return.

redirects.js never had this problem because its warnDrop sits after the function. This now matches it, with a comment recording why the order is load-bearing rather than cosmetic.

Also fixed here, from the review

The same silence existed one level UP, at the config key itself, in both readers. "headers": {} or "redirects": "nope" discarded the entire config and returned [] with nothing said: the schema types both keys array, but the boot check inspects only boolean / integer / enum leaves, so it never looked. That is the identical failure this PR fixes at the rule level, and the warnDrop docblock claimed every drop branch already went through it, which was untrue.

Both now warn, and an ABSENT key deliberately does not, since that is the default rather than a mistake. Asserted both ways, because a warning on every app that simply has no webjs.headers would be worse than the silence it replaces.

Verified against the real configs: examples/blog and website produce 0 warnings between them across both readers, and the scaffold emits neither key.

Behaviour change worth naming: an explicit null now warns

{"headers": null} and {"redirects": null} previously produced no warning and now produce one. That is deliberate rather than incidental: the author wrote the key, so it is present and wrong-typed, not absent. It is the one shape where this PR's presence rule differs from "did the old code warn", so it is called out rather than buried, and both tests assert it explicitly.

Everything else moves the other way, toward silence. Eight of the sixteen no-key shapes in the new sweep warned before this PR ('a-string', 42, 0, false, '', and a falsy or non-object config block), and the truthy-non-object-pkg class is unbounded, since any such value short-circuited the old chain to the boolean false.

Test plan

• packages/server/test/headers/headers.test.js: a new case for the empty-array form (asserts the warning names /empty AND that the valid sibling still compiles), plus the existing multi-drop case extended to assert the rule-level warning for /bad-dir, whose count moves 7 to 8.
• Counterfactual: revert the !directives.length guard to if (directives.length) rules.push(...) and 2 tests red; restore and 19 pass.
• Docblock binding verified structurally rather than by eye, re-derived from the committed file at each push: compileHeaderRules is at line 72 with its docblock opening at 51, warnDrop at 178 with its own at 160, so no two JSDoc blocks are adjacent.
• Browser, e2e: N/A. Config parsing with no browser-facing surface.
• Bun: this is a console.warn in a config parser, on none of the runtime-sensitive surfaces AGENTS.md lists. The full matrix is run below regardless, since headers.js is adjacent to the response path.

Docs

No surface changed. The docblock sentence this restores was already accurate about the intent; it just was not attached to the function any more, and the code now does what it says.

[vivek7405]

Read the whole diff against the schema, the boot validator, the dev.js call site, and the doc surfaces. The two fixes hold and the new tests are discriminating, but the change stopped one level too early and the PR body overstated its own verification.

The warnDrop docblock says every drop branch goes through it. It does not: the early if (!Array.isArray(raw)) return [] throws away the ENTIRE config in silence, and nothing else catches it either, since the schema types the key array while the boot validator only inspects boolean, integer, and enum leaves. So "headers": {} is the exact silent-config failure this PR exists to end, one level above the one it fixed, in the same function, under a comment claiming it was covered. redirects.js had the identical hole.

Both fixed in 4df5257b, with an absent key kept deliberately silent and asserted that way, since warning on every app that simply has no webjs.headers would be worse than the silence it replaces. Measured on the real configs: blog and website emit 0 warnings between them across both readers.

The line numbers in the body were also stale, from a run against a pre-commit revision of the file. Corrected and re-derived from the committed file, which is the whole point of checking it structurally rather than by eye.

[vivek7405]

This round found a real bug in my own guard, not a wording problem, so it was worth the round.

The presence test read raw off the && chain walking pkg.webjs.<key>. A chain short-circuits to whatever link FAILED, so for a non-object pkg the value was the boolean false produced by typeof pkg === 'object', and for a falsy config block it was that block. Six shapes therefore warned about a headers or redirects key nobody wrote, and printed false as the offending value, in a change whose entire point is diagnostic accuracy. It also contradicted webjs-config-validate.js, which returns [] for a non-object config block precisely because the readers treat it as unconfigured.

My tests covered only null, which is the one non-object value the chain passes through unchanged, so the bug sat under a green suite. Both readers now read the block explicitly and test presence with in, and the tests sweep every absent shape: a string, a number, 0, false, '', [], a falsy block, a non-object block. An explicit "headers": null still warns, since the author did write the key. Counterfactual: restore the chain and 4 tests red.

Also fixed: the config-level message called itself an "entry" when an entry is an array element, and the docs said nothing about a new user-visible boot warning. Three surfaces updated.

[vivek7405]

Final read over the whole change. No code defects. Both readers were executed over 27 input shapes and agree on every one, 'headers' in block cannot throw because hasBlock already proved the block a non-null object, the !Array.isArray(block) clause is the exact complement of validateAppWebjsConfig's guard so the two cannot disagree, the renamed warning string has no other match anywhere in the repo, and the new assertions do fail on revert.

Three documentation inaccuracies, all mine, all now fixed.

The drop-level counts overstated the symmetry: a redirect entry carries no directives, so redirects has TWO levels (key, entry) where headers has three (key, rule, directive). The built-ins reference claimed three of both and the module table said headers mirrors redirects exactly, when only the presence test does. Fixed in 8521a3d3.

The third is worth more than a correction. {"headers": null} produced NO warning before this PR and produces one now, so this is a behaviour change I described as unchanged. It is the right behaviour, since the author wrote the key and a present wrong-typed value is exactly what the warning is for, and the tests and docs already say so. But it is the one shape where the presence rule diverges from the old code, so it is now named in the PR body rather than left to be discovered. Everything else moves toward silence: eight of the sixteen no-key shapes warned before, and the truthy-non-object-pkg class is unbounded.

Stopping the cycle here. Nothing must-fix is open.