Skip to content

docs: say what absence from Spring's metadata actually proves - #46

Open
vianbas wants to merge 1 commit into
mainfrom
fix/metadata-absence-means-unconfirmed
Open

docs: say what absence from Spring's metadata actually proves#46
vianbas wants to merge 1 commit into
mainfrom
fix/metadata-absence-means-unconfirmed

Conversation

@vianbas

@vianbas vianbas commented Aug 16, 2026

Copy link
Copy Markdown
Owner

What

Wording only. No rule, no key, no assertion, no fixture.

ConfigKeyMetadataTest still fails on any rule key missing from the vendored
index. That default is right and it earned its place. What the failure claims
on the way down was wrong in one direction.

Before After
@DisplayName every declared rule key is a property Spring Boot actually reads every declared rule key is confirmed by Spring Boot's metadata, or explained
failure message "these rules cannot fire on a real project and any finding they produce is wrong" absence is not proof the key is wrong; it means unconfirmed, so confirm it against the Boot source or a running app
class javadoc metadata absence closed the gap metadata absence pointed at spring.web.cors.* and spring.security.debug; runtime observation and a jar search condemned them
ACCEPTED_ABSENCES javadoc "an entry is a deliberate, explained decision" states the bar: a runtime observation naming the Boot version and the behaviour that changed, or a pointer to the binding class
CONTRIBUTING.md a rule keyed on an undeclared property "can never fire" it fires on nothing while every fixture stays green, and a missing key is unconfirmed rather than disproved

Why

Closes #44

The metadata is authoritative for presence, never for absence. Boot binds
properties it never declares. management.endpoint.<id>.access is the
counterexample #44 documents: absent from all 2920 indexed properties, and on
3.5.16 a POST /actuator/shutdown goes from 404 to 200 and ends the process
once it is set.

So the old text told a contributor the opposite of what to do next, and it
blocks #45, whose rule is keyed on exactly that property.

The ACCEPTED_ABSENCES bar matters for the same reason. A map documented only
as needing "a reason" is where the next contributor with a red test will go.
Naming the evidence it takes is what keeps it a record rather than a mute
button.

How was this verified?

mvn -B -ntp clean verify on JDK 17, run twice:

Tests run: 59, Failures: 0, Errors: 0, Skipped: 0
Spotless.Java is keeping 73 files clean - 0 needs changes to be clean
BUILD SUCCESS

The suite count is unchanged at 59, which is the point. Nothing here is meant to
change what passes or what fails. Local JDK is 17; CI builds on 21.

Also rendered the new failure message against a synthetic offender, to check the
concatenated chunks read as prose and that no spacing is lost at the + seams.

Checklist

  • Linked issue exists and is referenced above
  • Tests added or updated for the behavior change: no behavior change. The assertions in ConfigKeyMetadataTest are untouched; only its messages and javadoc differ.
  • mvn verify passes locally
  • Docs updated (README.md, docs/rules/*.md) if user-facing behavior changed: CONTRIBUTING.md only. No rule doc or README claim is affected.
  • For a new/changed rule: false-positive rationale documented in docs/rules/: no rule changes.

ConfigKeyMetadataTest failed any rule key missing from the vendored index and
told the reader those rules "cannot fire on a real project and any finding they
produce is wrong." That inference only holds one way.

The metadata is authoritative for presence: a declared key is a real property.
It is not authoritative for absence. Boot binds properties it never declares,
management.endpoint.<id>.access among them, which #44 confirms by observation
on 3.5.16 rather than by reading the index.

The test still fails on absence. That is the right default and it earned its
place. What changes is what the failure claims: unconfirmed, not wrong, and a
prompt to check the key against the Boot source or a running app before
shipping it. The javadoc also stops taking credit the test has not earned:
metadata absence pointed at spring.web.cors.* and spring.security.debug, it did
not condemn them.

Also states the bar for an ACCEPTED_ABSENCES entry, which was documented only
as "a reason". Without a bar the map is a mute button, and the next contributor
to hit a red test will reach for it.

No rule, no key and no assertion changes. Suite unchanged at 59 passing.

Closes #44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[bug]: ConfigKeyMetadataTest treats absence from Spring's metadata as proof a property does not exist

1 participant