feat(coordinator): add checkCoordinatorConfigDocs validator#3567
Closed
gauravahuja wants to merge 1 commit into
Closed
feat(coordinator): add checkCoordinatorConfigDocs validator#3567gauravahuja wants to merge 1 commit into
gauravahuja wants to merge 1 commit into
Conversation
Add ConfigDocValidator (pure over the walked ConfigKey list) enforcing: every leaf carries @ConfigDoc and every section @ConfigSection, and the description is non-blank. A replacement is optional even for deprecated items (a plain removal is valid). It emits a deterministic, path-sorted violation report. Wire it behind a ConfigDocCheckMain entrypoint and a standalone checkCoordinatorConfigDocs Gradle task that walks the five root config classes and fails on any violation. The task is intentionally NOT wired into 'check' yet: the real config classes are annotated in a later phase, so running it now reports the currently-undocumented keys. Wiring into check/CI happens once every key is documented. Signed-off-by: Gaurav Ahuja <gauravahuja9@gmail.com>
gauravahuja
requested a deployment
to
docker-build-and-e2e
July 15, 2026 03:52 — with 
GitHub Actions
Waiting
GitHub Actions
Waiting
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
This was referenced Jul 15, 2026
| * validates that every key is documented, prints any violations, and exits non-zero on failure | ||
| * so the Gradle task (and CI) fails. | ||
| */ | ||
| object ConfigDocCheckMain { |
Contributor
There was a problem hiding this comment.
Is this going to the final production Jar?
If so, it should not. It's bad practice to mix build/analysis tool code into production code.
Have you considered making a Gradle plugin inside gradleSrc? If too complex as gradleSrc, then we shall create a Gradle module inside jvm-libs (e.g jvm-libs/linea/config-validator) and add it here as compile only dependency.
This piece of work (documentation validation and generation) must be replicated to Maru. The way it is done atm it's not possible :(
gauravahuja
added a commit
that referenced
this pull request
Jul 21, 2026
Add ConfigDocsRunner (walk+validate+report exit code; generate+writeIfChanged idempotently) plus generic ConfigDocsCheckMain/ConfigDocsGenerateMain entry points and a ConfigDocsSpec interface. Apps declare a single ConfigDocsSpec object (roots, section detector, output paths, title) and name it from build.gradle; the generic mains load it by class name, so apps need no check/generate entry-point code and the Gradle plugin stays zero-logic. Refs: #3567 Signed-off-by: Gaurav Ahuja <gauravahuja9@gmail.com>
gauravahuja
added a commit
that referenced
this pull request
Jul 23, 2026
Add ConfigDocsRunner (walk+validate+report exit code; generate+writeIfChanged idempotently) plus generic ConfigDocsCheckMain/ConfigDocsGenerateMain entry points and a ConfigDocsSpec interface. Apps declare a single ConfigDocsSpec object (roots, section detector, output paths, title) and name it from build.gradle; the generic mains load it by class name, so apps need no check/generate entry-point code and the Gradle plugin stays zero-logic. Refs: #3567 Signed-off-by: Gaurav Ahuja <gauravahuja9@gmail.com>
Contributor
Author
|
Closing in favor of #3606 |
gauravahuja
added a commit
that referenced
this pull request
Jul 23, 2026
…figSection Annotate every Coordinator TOML config class with @ConfigDoc (leaf values) and @ConfigSection (nested tables), covering all 450 config keys across: top-level sections, defaults, database, request retries, prover, traces, conflation, L1 submission, L2 network gas pricing, message anchoring, forced transactions, protocol, signer, state manager, type-2 state proof, L1 finalization monitor, and API. Annotations are imported from the jvm-libs:linea:config-docs module and depended on via compileOnly, so the tooling stays out of the production jar. checkConfigDocs now reports 450/450 keys documented. Refs: #3567 Signed-off-by: Gaurav Ahuja <gauravahuja9@gmail.com>
gauravahuja
added a commit
that referenced
this pull request
Jul 23, 2026
…figSection Annotate every Coordinator TOML config class with @ConfigDoc (leaf values) and @ConfigSection (nested tables), covering all 450 config keys across: top-level sections, defaults, database, request retries, prover, traces, conflation, L1 submission, L2 network gas pricing, message anchoring, forced transactions, protocol, signer, state manager, type-2 state proof, L1 finalization monitor, and API. Annotations are imported from the jvm-libs:linea:config-docs module and depended on via compileOnly, so the tooling stays out of the production jar. checkConfigDocs now reports 450/450 keys documented. Refs: #3567 Signed-off-by: Gaurav Ahuja <gauravahuja9@gmail.com>
gauravahuja
added a commit
that referenced
this pull request
Jul 23, 2026
…tive spec
Add a reusable 'linea.config-docs' buildSrc convention plugin that creates a
'configDocs' source set (compiled against main + the config-docs engine, kept
out of the production jar) and registers checkConfigDocs / generateConfigDocs
tasks. The tasks run the engine's generic entry points against the app's
ConfigDocsSpec, whose fully-qualified name is declared in build.gradle
(configDocs { spec = ... }) - no per-app entry-point code and no
META-INF/services file.
Coordinator applies the plugin and provides CoordinatorConfigDocsSpec (roots,
section detector, output paths) in the configDocs source set. checkConfigDocs
currently reports the undocumented keys; the config classes are annotated in
the next PR. Generated artifacts are committed in a later PR.
Refs: #3567
Signed-off-by: Gaurav Ahuja <gauravahuja9@gmail.com>
gauravahuja
added a commit
that referenced
this pull request
Jul 23, 2026
…figSection Annotate every Coordinator TOML config class with @ConfigDoc (leaf values) and @ConfigSection (nested tables), covering all 450 config keys across: top-level sections, defaults, database, request retries, prover, traces, conflation, L1 submission, L2 network gas pricing, message anchoring, forced transactions, protocol, signer, state manager, type-2 state proof, L1 finalization monitor, and API. Annotations are imported from the jvm-libs:linea:config-docs module and depended on via compileOnly, so the tooling stays out of the production jar. checkConfigDocs now reports 450/450 keys documented. Refs: #3567 Signed-off-by: Gaurav Ahuja <gauravahuja9@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add ConfigDocValidator (pure over the walked ConfigKey list) enforcing: every leaf carries @ConfigDoc and every section @ConfigSection, and the description is non-blank. A replacement is optional even for deprecated items (a plain removal is valid). It emits a deterministic, path-sorted violation report.
Wire it behind a ConfigDocCheckMain entrypoint and a standalone checkCoordinatorConfigDocs Gradle task that walks the five root config classes and fails on any violation.
The task is intentionally NOT wired into 'check' yet: the real config classes are annotated in a later phase, so running it now reports the currently-undocumented keys. Wiring into check/CI happens once every key is documented.
This PR implements issue(s) #2978
Checklist
PR.
Note
Low Risk
Verification-only tooling and tests; no runtime coordinator behavior or config parsing changes.
Overview
Adds documentation enforcement for Coordinator v2 TOML config: a pure
ConfigDocValidatorover walkedConfigKeys requires@ConfigDocon leaves,@ConfigSectionon nested tables, and non-blank descriptions (deprecated keys/sections may omit a replacement).ConfigDocCheckMainruns the existing schema walker across the five root config file classes and exits non-zero with a path-sorted report on failure. A standalone Gradle taskcheckCoordinatorConfigDocsinvokes that main class; it is not hooked intocheck/CI yet so builds stay green until annotations land on the real config classes.Unit tests cover validator rules and report formatting; an integration test exercises walker + validator on sample TOML data classes.
Reviewed by Cursor Bugbot for commit bdbe166. Bugbot is set up for automated code reviews on this repo. Configure here.