test(docs): cover the READMEs, the backend packages, and the showcase register

[DemchaAV]

Why

Three documented surfaces had no build behind them.

The snippet guard compiled docs/ only. The pages a reader reaches first — the root README and each module's — were free to name a method the library no longer has.

The package map was a hand-kept list. The backend-neutral fixed-layout SPI was missing from the contributing guide, which is the one document a reader consults before adding an output format: a contributor registers a fragment kind with the backend they can find, and a kind registered with only one fixed-layout backend renders in one output and vanishes from the other.

The showcase register falls back to a filename-derived card, so an entry keyed on a document the runner never writes is simply never read — no card, no warning, no failure.

What

Every Java fence in a README is accounted for. The scan adds the root README and every module README, taken from the root pom's <modules> so "a module" means what it means to Maven. Marking stays opt-in under docs/, where pages teach with deliberate fragments; in a README it is mandatory — a fence carries either doc-example or <!-- doc-example-ignore: reason -->, and the reason is required. Seven compile against the current API on every build; forty-five are exempt on the record. Nothing is silent.

A module README opens with a three-line taste of the API, which the imports it needs would double in length, so a snippet can take them from the marker instead: imports=a.b.C,d.e.F, verified by the compile like any other name. Two marker mistakes are reported where they happen rather than as an unresolved symbol inside a snippet: an unknown attribute and a stray token from a space after a comma.

docs/private/ leaves the scan, and both guards that read the published documentation now resolve the page set through one helper — they were two hand-kept lists and had already drifted.

The package map is derived from the source tree. Packages qualify by containing a *Backend type, in every module the reactor builds, so a backend arriving in a new module is covered the day it lands. Each must be named in CONTRIBUTING.md and docs/architecture/package-map.md in its own right: accepting an ancestor reads as reasonable and guts the guard, because adding the missing parent would make every package beneath it uncheckable. Matching is boundary-aware and takes either the fully-qualified name or the document.backend.… tail the docs also use.

The showcase register is checked against the catalogue. Every entry must match a generated document, and its source link must resolve to a file in the tree — a renamed example fails the build instead of leaving a 404 behind the card. The tree is emptied before it is rebuilt: the runner only writes, so a document deleted from it survived in target/ and answered for the entry that no longer had one. That made the guard green locally and red only on a clean checkout. Generation is shared between the example suites and runs once per JVM.

The reverse direction is deliberately not asserted: a generated document without an entry still reaches the site through the fallback, which is what the fallback is for.

render-docx joins the qa test classpath, so its README compiles against the real DocxSemanticBackend.

Tests

Reactor gate green (clean verify over the ten CI modules), qa alone at 684 tests, examples at 52, javadoc:javadoc clean.

Each rule was run in both directions:

Rule	Negative check	Result
package map	drop a documented backend package from CONTRIBUTING.md	fails, names the package
package map	plant a backend in a module the old scan never reached	fails in both documents
README fences	leave a java fence unmarked	fails, names file:line
README fences	exempt a fence with an empty reason	fails, names the reason as the point
README compilation	rename buildPdf() in core/README.md	fails, names the snippet
marker attributes	write import= instead of imports=	fails, names the attribute
marker attributes	put a space after a comma in the list	fails, names the stray token
scan roots	drop the module-README root	fails on the coverage assertion
scan roots	move the docs root while READMEs still supply snippets	fails on the docs side
docs/private/	put a broken snippet there	ignored, as intended
showcase register	add an entry for a document nobody generates	fails, names the basename
showcase links	rename the class a codeUrl points at	fails, names the path
stale artefact	plant a leftover PDF, run without clean	removed; the entry it covered now fails
generation	run the metadata guard alone on a clean tree	passes; it builds the catalogue itself