feat(ci): enforce lowerCamelCase and max depth in reference.conf#6792
Closed
bladehan1 wants to merge 2 commits into
Closed
feat(ci): enforce lowerCamelCase and max depth in reference.conf#6792bladehan1 wants to merge 2 commits into
bladehan1 wants to merge 2 commits into
Conversation
Add a CI gate that scans common/src/main/resources/reference.conf and fails the build when any key violates lowerCamelCase (^[a-z][a-zA-Z0-9]*$ per dot-separated segment) or exceeds the maximum hierarchy depth (5). Array element keys are validated the same way; each array step counts as one depth level — e.g. an inner field at `rate.limiter.rpc[].component` is depth 5. Parsing is delegated to pyhocon, the reference Python HOCON implementation. It returns a fully-merged ConfigTree where dotted-form keys expand into nested objects — the same canonical key set Typesafe Config and ConfigBeanFactory see at runtime — and handles triple-strings, substitutions, includes, +=, and block comments without us re-implementing the grammar. Four legacy PBFT* keys are grandfathered via an in-script allowlist so the gate fails only on new violations. A consolidated GHA error annotation lists every offending key, and sys.exit(1) drives step failure. The script also accepts `--debug` to print every parsed key with its depth (trailing `/` marks namespace intermediates) for manual verification against the source file. Runs as a new step in the existing checkstyle job of pr-check.yml (setup-python + `pip install pyhocon`), so no extra runner spin-up.
bladehan1
force-pushed
the
ci/reference-conf-gate
branch
from
cd96b77 to
2b2fa79
Compare
warku123
reviewed
May 21, 2026
Pin pyhocon via .github/scripts/requirements.txt so the gate is not exposed to silent behavior changes in upstream releases, and enable actions/setup-python's pip cache (keyed off the requirements file) so subsequent CI runs skip the PyPI round-trip.
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
3 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.
What does this PR do?
Adds a CI gate that validates
common/src/main/resources/reference.confon every PR / push:^[a-z][a-zA-Z0-9]*$: starts with a lowercase ASCII letter, then ASCII letters/digits only. Acronym runs after position 1 (e.g.httpPBFTEnable,openHistoryQueryWhenLiteFN,allowShieldedTRC20Transaction) are accepted — only the first character is constrained, which matches whatjava.beans.Introspector/ConfigBeanFactoryactually require for bean-property auto-binding.MAX_DEPTHvia a reviewed change).node.shutdown.*).[]= +1 level); nested arrays (HOCON list-of-list) are supported.Implementation:
.github/scripts/check_reference_conf.pyusingpyhocon(pinned via.github/scripts/requirements.txt), wired into the existingcheckstylejob in.github/workflows/pr-check.yml.actions/setup-pythonenables pip caching keyed on the requirements file. Violations produce per-line stdout output plus one consolidated::error file=...,title=reference.conf::...GHA annotation so failures show up in the PR check summary.Why are these changes required?
reference.confis the single source of default values for every config key in java-tron, and key names must auto-bind toXxxConfig.javabean fields via Typesafe Config'sConfigBeanFactory. This gate is stricter than typical Java/Spring projects (Spring Boot'sBinder/ Quarkus / Micronaut tolerate kebab-case, snake_case, UPPER_CASE, and camelCase as equivalent forms) becauseConfigBeanFactoryusesjava.beans.Introspectorand requires the HOCON key to match the JavaBean property name exactly — no case normalization. Without a CI gate, non-conforming keys silently fail to bind and accumulate. Today the file has drifted: 4 PBFT keys violate the rule and the file header documents legacy exceptions handled via manual normalization.A depth ceiling also prevents deeply nested hierarchies from creeping in. The gate is set exactly at the current max (5) with no buffer: silent drift is unacceptable for a mature project, so any new key that needs to go deeper has to bump
MAX_DEPTHexplicitly and be reviewed.This PR has been tested by:
reference.conf— passes with 294 keys, max depth 5.::errorannotation; a single user-declared deep key produces exactly one depth violation line (leaf-only filtering).Follow up
config.conffiles).Class.getDeclaredFields()reflection vs Java-AST parsing; default-value comparison rules across types; what counts as a config bean) warrant a separate PR.Extra details
config.confcompatible:node.http.PBFTEnable,node.http.PBFTPort,node.rpc.PBFTEnable,node.rpc.PBFTPort, plusnode.shutdown.BlockTime/BlockHeight/BlockCount(PascalCase exceptions handled manually inNodeConfig.fromConfig; currently commented out inreference.conf— pre-listed so the gate stays green if ever uncommented with defaults).pyhoconover Typesafe Config because the gate runs before Gradle/JDK setup in CI (~3 steps: setup-python + pip install + invoke). Both implement the HOCON spec; outputs are equivalent.