build(wrapper): the graph-compose coordinate publishes an API reference

[DemchaAV]

Why

javadoc.io/doc/io.github.demchaav/graph-compose is the only API-reference link in the repository — README.md Distribution block and CONTRIBUTING.md release flow both point there. It renders graph-compose 1.9.1 javadoc.

The cause is not a broken link. wrapper/ has no sources, and maven-javadoc-plugin's jar goal does not build an empty archive in that case — it builds none and attaches nothing. Running the exact release profile the publish workflow runs prints No Javadoc in project. Archive not created., and Central agrees: graph-compose-2.1.0-javadoc.jar → 404, while graph-compose-core-2.1.0-javadoc.jar → 200. javadoc.io falls back to the newest version that carries one, which is 1.9.1. So the page is not empty — it is a complete, convincing API reference for a version two majors old, presented as current, next to prose promising documentation fresh after each Central release.

Repointing the link at graph-compose-core was the obvious fix and is worse: javadoc.io has indexed no 2.x coordinate — -core, -render-pdf, -templates, -testing all return No versions in the database. That trades a stale page for an empty one.

What changed

• wrapper/pom.xml — the attach-javadocs execution sets includeDependencySources over io.github.demchaav:graph-compose-core, so the jar is built from the engine's sources: the surface a caller of this coordinate actually authors against. render-pdf is deliberately excluded — it is the backend the wrapper carries, not the API the caller writes.
• Lombok is fed to the javadoc classpath via additionalDependencies. It is provided-scope in the engine and so never arrives transitively; without it the build stops at package lombok does not exist. Its version is a second literal, so VersionConsistencyGuardTest.wrapperJavadocLombokVersionTracksTheEngine holds it in lockstep with core/pom.xml — the drift would surface only during a release build.
• doclint is off, matching the engine's own release jar. failOnError=false is removed. That flag is what let the empty state ship silently; a hard failure must now fail the publish.
• PublishedJavadocCoordinateGuardTest (new) — every coordinate the docs advertise as an API reference must resolve to a module that will produce a javadoc jar: own sources, or includeDependencySources. It reads build files, so it stays offline and deterministic.
• README, CONTRIBUTING and the release checklist say what is actually true, including which version the hosted page reflects until 2.1.1 lands.

Verification

./mvnw -B -ntp clean verify — BUILD SUCCESS, exit 0, 692 tests in the closing module.

The release build now produces wrapper/target/graph-compose-2.1.1-SNAPSHOT-javadoc.jar, 3.17 MB: 1024 entries, 903 HTML pages, including com/demcha/compose/GraphCompose.html, com/demcha/compose/document/api/DocumentSession.html (titled DocumentSession (GraphCompose 2.1.1-SNAPSHOT API), buildPdf present), DocumentDsl.html and DocumentTextStyle.html. Before this commit the goal attached nothing.

The guard was confirmed red first: flipping includeDependencySources to false reports graph-compose (wrapper) has no sources of its own and does not set includeDependencySources.

Publish-order check: publish.yml:188 deploys the engine with -P release, which attaches sources and installs them locally, before :210 builds the wrapper — so the aggregation resolves.

Known limit

The wrapper's release profile is not exercised by ordinary CI, so a broken aggregation still surfaces at publish time rather than on a PR. It surfaces loudly now, which is the change that matters: with failOnError back at its default the publish fails instead of shipping a coordinate with no API reference. A CI pre-check would catch it earlier and is worth a follow-up if you want it.

Lane: build. No production code, no public API.

[DemchaAV]

Rebased onto develop after #493 landed. Both ### Build entries are kept in CHANGELOG.md — the CI-Gate one first, then this one.

Applied the three review points:

• Release checklist assumed a warm ~/.m2. It now installs the engine with -P release first, because a plain install attaches no -sources.jar and the aggregation would have nothing to read on a cold repository. The expected jar contents (index.html, GraphCompose.html, DocumentSession.html) are named in the checklist rather than left implicit.
• "Four artefacts" was inaccurate. CONTRIBUTING.md and docs/contributing/release-process.md now say the wrapper publishes no sources jar, matching what the pom comment states.
• A wrong dependencySourceInclude could pass the guard. It now resolves each include to a reactor module and requires that module to have sources, so a typo fails the same way a missing config does. Confirmed red by changing the include to graph-compose-cores: sets includeDependencySources but no <dependencySourceInclude> names a reactor module that has sources.

Left as a follow-up, as you suggested: the CI pre-check that actually builds the wrapper's javadoc jar and asserts its contents. The static guard covers configuration; only a real build covers the artifact.

./mvnw -B -ntp clean verify on the rebased branch — BUILD SUCCESS, 692 tests in the closing module.