[#1271] Validate cross-guide AsciiDoc xrefs in CI (#1272)
Documentation builds currently accept missing cross-guide AsciiDoc files
and fragments. This adds a required `check-cross-guide-xrefs` execution
to the documentation module's Linux `verify` lifecycle, after reference
generation and preprocessing. Missing target files or anchors fail the
build with the referring source, reference and source line when
available.
The resolver uses the existing AsciidoctorJ/JRuby engine for converted
file xrefs, nested/generated includes, explicit anchors and
automatically generated section IDs. It rejects unpublished staging
targets and targets outside the supplied source root, and fails on
unreadable inputs, traversal errors, parse warnings and empty
selections. Guide `index.adoc` files are read explicitly as UTF-8 and
use the Antora plugin's literal `include::./` to `* xref:` rewrite.
Other include forms remain inline and contribute anchors to the index.
Standalone quoted patterns expand relative to the supplied source root.
`CHECKS.md` documents invocation, publication rules, diagnostics and
exit statuses.
The first complete-source check also exposed four existing broken
fragment targets, corrected to the generated `ldifdiff-1` and
`makeldif-template-5` anchors. The branch is based on `master` at
5154f34503, including the guides merged in #1268.
Fixes #1271.
## Validation
- Complete documentation-module suite on the current revision: 26 tests
passed on Java 11 and Java 27, with no failures, errors or skips. Ruby
fixtures cover 24 regression checks and 12 publication checks, including
nested/generated anchors, automatic IDs, ignored
literal/comment/conditional macros, staging targets and discovery
exclusions, published index anchors and retained inline includes,
non-ASCII indexes under a US-ASCII default encoding, outside-root
targets and sibling-prefix boundaries, WARN diagnostics, external URLs,
directory symlinks and exact error statuses.
- Three tests launch separate JVMs through the actual JRuby CLI and
verify exit statuses 0, 1 and 2, together with diagnostic routing to
stdout on success and stderr on failure. Permission-test skips are named
in the visible regression summary when `chmod` cannot restrict reads; an
emulated nonrestrictive-read run reports 22 checks plus both named
skips.
- Actual Maven xref execution from the module directory passed on the
current revision: 600 file xrefs in 72 prepared guide pages. The
preceding review round refreshed the preprocessed sources; preprocessing
was not repeated for the current checker/test changes. Indexes use the
publication rewrite, so linked chapter content is not counted again
through the index.
- The actual Administration Guide index passed through the JRuby CLI on
JDK 11 and 17 with `-Dfile.encoding=US-ASCII`: 23 file xrefs each, exit
0.
- Four in-memory mutations on the current revision were caught:
replacing the missing-file diagnosis, removing explicit UTF-8 index
decoding, deleting the outside-root guard and weakening the
sibling-prefix boundary. Compiled Java CLI tests caught both
stream-routing mutations: stdout-only failed both error cases;
stderr-only failed the success case.
- In the preceding review round, eleven in-process mutations were
caught: WARN threshold, invalid-reference and discovery statuses,
external-URL filter, directory-symlink guard, staging-target guard,
index transformation and all four discovery exclusions. A separate `exit
status` to `exit 0` mutation caused both CLI failure-case tests to fail.
Those earlier mutations were not repeated for this update.
- During the initial implementation, removing a target file, renaming
`upgrade-zip`, and renaming `dsconfig-create-backend` inside a nested
generated partial each caused failure. The actual Maven execution exited
1 for the generated-anchor mutation and named referring files and lines;
an unmatched glob exited 2. Those manual guide mutations were not
repeated for this update.
- Independent code review and `git diff --check` passed on the current
revision.
The complete module `verify` has no passing result and was not rerun for
this update. An earlier attempt generated partials, preprocessed sources
and built three PDFs, then was stopped after more than ten minutes
overall while rendering the Reference PDF. The module tests and required
xref execution passed separately as described above. Existing Maven
model/plugin and JRuby/JDK warnings remain.