The javadoc reference gate reaches test sources, and the capture-API residue it missed

R711 removed a nodehood predicate parameter from every capture entry point, because deciding nodehood needs the jOOQ catalog and a crawler answering for the SDL corpus may not read it. The removal is complete in the code that runs. Seven files still name the parameter in prose or in an import.

Six carry an import no.sikt.graphitron.rewrite.NodeDeclaration; with no other mention of the type in the file, so the import is dead:

Two neighbours are not on that list and must not be swept with it. graphitron/src/test/java/no/sikt/graphitron/rewrite/derive/NodeTypeShadowTest.java:5 carries the same import and uses the type four times, and graphitron/src/test/java/no/sikt/graphitron/rewrite/derive/TypeBackingClassTest.java never names the type at all; its line 5 is a live CompletionData import.

The seventh is the one that motivates the rest. graphitron/src/test/java/no/sikt/graphitron/rewrite/capture/WarmStartRefreshTest.java:296 documents aWarmRefreshOverAMultiPackageCatalogCompletes with a {@link} whose target is a FactCapture#capture overload ending ..., Map, JooqCatalog, List, NodeDeclaration). No such overload exists. That file needs two edits, the link and then the import it was the last reader of.

Note which of the two problems has an enforcer and which does not. A dead import is not a javadoc reference issue, so no configuration of the existing gate would ever have flagged the six; nothing in this build catches an unused import at all. Only the seventh site is a gate escape. Sweeping the six is hygiene the same commit can afford, not evidence about the gate.

The gate lives in the root pom as the check-link-references execution of maven-javadoc-plugin, bound to verify, running doclint’s reference group with failOnError left at its default so a dangling link reddens the build. Its own comment states the stakes: javac ignores javadoc, so without this a dangling {@link} compiles clean and ships.

It runs the plugin’s javadoc goal. That goal documents main sources. Test sources are the test-javadoc goal’s subject, and that goal has no execution here, so graphitron/src/test/java has never been looked at by anything that resolves a reference.

The Backlog body deferred this question on the guess that extending the gate would cost real wall-clock and surface a large pre-existing backlog. Both halves of the guess are wrong, and the measurement is recorded here so the implementer starts from a number instead of re-deriving one.

Two traps make a naive implementation pass vacuously, and both fail by reporting zero. They are the reason this section exists at all.

The first is pom.xml:349. A pluginManagement block pins <sourcepath>${project.build.sourceDirectory}</sourcepath> for the whole plugin, deliberately, so that the release profile’s javadoc jar shares the gate’s parse. An explicit sourcepath overrides whatever source roots a goal would otherwise choose, so test-javadoc documents src/main/java and emits nothing about the test tree. Invoking the goal with the gate’s own flags produced a clean run and a directory of main-source documentation; the tell was the generated argfile, which listed 455 main sources and zero test sources. A -Dsourcepath on the command line does not fix it either, since explicit plugin configuration outranks a user property. The execution needs its own <sourcepath> naming the test root.

The second is the show level. JUnit classes and methods here are package-private by convention, and javadoc’s default level documents protected and public only, so the test tree’s javadoc is never parsed and doclint never sees a link inside it. This is the same mechanism a previously shipped item already recorded for private main members, whose dangling link sat invisible to this gate for the same reason. The execution needs show at private.

With both avoided, the backlog is eleven references and one module. Measured by running javadoc directly over each module’s test tree with -Xdoclint:reference -private, main types resolved from bytecode:

One of the eleven is this item’s own. The other ten are pre-existing, and they sort into four kinds, every one a single-line edit:

Each fix takes the choice CLAUDE.md already prescribes: repoint the link at the current symbol, and downgrade to {@code} only where the target genuinely is not a resolvable symbol.

Cost is about five seconds. That is raw javadoc over `graphitron’s 479 test files, the largest tree in the reactor. The plugin adds a per-module process fork on top, and only six modules have a test tree, so the realistic addition is well under the main gate’s own cost rather than a doubling of it.

Two slices. The first is independent of the second and can land alone.

Both traps fail silently by reporting zero findings, which means a green build after slice two is indistinguishable from a gate that documented the wrong source root. So the slice does not land on a green build. It lands on a demonstration: plant a dangling {@link} in a test source, observe the build go red and name that file, then remove it. Record in the commit message which file was used and what the failure said.

The same reasoning covers the show level specifically, since the two failures are independent. A gate configured with the right source root but the default show level would still report zero, so the planted link has to sit inside a package-private test class, which is to say a perfectly ordinary one, rather than in a public helper.