feat(ci): enforce lowerCamelCase and max depth in reference.conf

[bladehan1]

What does this PR do?

Adds a CI gate that validates common/src/main/resources/reference.conf on every PR / push:

• Every dot-separated segment of every key must match ^[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 what java.beans.Introspector / ConfigBeanFactory actually require for bean-property auto-binding.
• Total path depth must be ≤ 5 (set exactly at the current max in tree — no buffer; new deeper keys must explicitly bump MAX_DEPTH via a reviewed change).
• Seven legacy keys are grandfathered via an explicit ALLOWLIST (4 PBFT + 3 node.shutdown.*).
• Array steps count toward depth (each [] = +1 level); nested arrays (HOCON list-of-list) are supported.

Implementation: .github/scripts/check_reference_conf.py using pyhocon (pinned via .github/scripts/requirements.txt), wired into the existing checkstyle job in .github/workflows/pr-check.yml. actions/setup-python enables 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.conf is the single source of default values for every config key in java-tron, and key names must auto-bind to XxxConfig.java bean fields via Typesafe Config's ConfigBeanFactory. This gate is stricter than typical Java/Spring projects (Spring Boot's Binder / Quarkus / Micronaut tolerate kebab-case, snake_case, UPPER_CASE, and camelCase as equivalent forms) because ConfigBeanFactory uses java.beans.Introspector and 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.

A depth ceiling also prevents deeply nested hierarchies from creeping in. The gate is set exactly at the current max with no buffer: silent drift is unacceptable for a mature project, so any new key that needs to go deeper has to bump MAX_DEPTH explicitly and be reviewed.

This PR is the release_v4.8.2 counterpart of #6792 (which targets develop), so the same gate runs on hotfix PRs against the release branch.

This PR has been tested by:

• Manual Testing: ran the script against release_v4.8.2's reference.conf — passes with all keys, max depth 5.
• Local fixture suite (not committed) covering: empty / simple / dotted-form / at-max-depth / object array / scalar array / allowlist / format violations (Pascal / snake / digit / array-internal / non-allowlisted acronym) / depth violations (dotted + in-array) / combined + dedup invariant / env errors (parse failure, missing file). All assertions PASS.
• Verified: parse failure (invalid HOCON) and missing file both exit 2 with ::error annotation; a single user-declared deep key produces exactly one depth violation line (leaf-only filtering).

Follow up

• Sunset legacy ALLOWLIST entries via a rename + deprecation cycle (out of scope here — would break existing user config.conf files).
• Bean-field ↔ key parity + default-value drift gate (Gate 2) is the highest-leverage follow-up — would have caught the dead keys removed in refactor(config): remove unused storage index and json parsing config #6794 and the default drift fixed in fix(config): optimizes config binding for node  #6755 / refactor(config): overhaul config docs, fix defaults, remove dead params #6790. Scope and implementation (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

• Allowlist exempts 7 legacy keys to keep user config.conf compatible: node.http.PBFTEnable, node.http.PBFTPort, node.rpc.PBFTEnable, node.rpc.PBFTPort, plus node.shutdown.BlockTime/BlockHeight/BlockCount (PascalCase exceptions handled manually in NodeConfig.fromConfig; currently commented out in reference.conf — pre-listed so the gate stays green if ever uncommented with defaults).
• Library choice: pyhocon over 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.

[barbatos2011]

Solid CI gate, with two small items to address in this PR plus a recommendation on how to land the broader gate strategy.

Two issues to address in this PR

1. node.shutdown.BlockTime / BlockHeight / BlockCount should be in ALLOWLIST

PR #6790's docs/configuration-conventions.md explicitly lists these as a third documented PascalCase exception (alongside the PBFT* family and isOpenFullTcpDisconnect), handled via manual reads in NodeConfig.fromConfig. They pass the gate today only because they're commented out in reference.conf. If anyone ever uncomments them with default values (e.g. a future "graceful shutdown defaults" PR), CI rejects a legitimate documented exception.

Suggested addition:

ALLOWLIST = {
    "node.http.PBFTEnable",
    "node.http.PBFTPort",
    "node.rpc.PBFTEnable",
    "node.rpc.PBFTPort",
    # node.shutdown.BlockTime/BlockHeight/BlockCount: PascalCase exceptions
    # documented in configuration-conventions.md, read manually in
    # NodeConfig.fromConfig. Currently commented out in reference.conf;
    # listed here to prevent CI breakage if ever uncommented with defaults.
    "node.shutdown.BlockTime",
    "node.shutdown.BlockHeight",
    "node.shutdown.BlockCount",
}

2. Regex description vs actual behavior

The regex ^[a-z][a-zA-Z0-9]*$ is described as enforcing "lowerCamelCase," but it actually accepts acronym runs anywhere after position 1 — e.g. httpPBFTEnable, pBFTExpireNum, openHistoryQueryWhenLiteFN, allowShieldedTRC20Transaction all pass (and all exist in current reference.conf).

This is a conscious choice — those names work with ConfigBeanFactory because they start lowercase, which is the actual constraint — but the script docstring / PR description should be precise so reviewers don't later challenge them as violations. Suggested wording:

"Each segment must start with a lowercase ASCII letter and contain only ASCII letters/digits. Acronym runs after position 1 (e.g. httpPBFTEnable) are accepted: this matches what java.beans.Introspector tolerates, which is what ConfigBeanFactory actually needs."

Context: why a strict gate is justified

The lowerCamelCase + depth-limit approach is stricter than typical Java/Spring projects, which usually rely on bean binding to catch silent failures plus relaxed name matching (Spring Boot's Binder / ConfigurationPropertyName API tolerates kebab-case, snake_case, UPPER_CASE, and camelCase as equivalent forms; Quarkus and Micronaut behave similarly). The aggressive gate here is justified because java-tron uses Typesafe Config's ConfigBeanFactory, which uses java.beans.Introspector and 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.

One sentence in the PR description acknowledging "stricter than typical Java projects, but necessary because ConfigBeanFactory does no case normalization" would help future contributors understand the choice.

Recommendation: extend this PR with Gates 2–5 as separate commits

Think of this PR as Gate 1. A new config key being "reasonable" actually has 5–6 independent dimensions. Suggest landing all of them in this PR with one commit per gate (rather than as follow-up PRs):

Gate	Goal	Catches	Implementation
1 (this commit)	Naming + depth	Foo, some_key, depth > 5	Python + pyhocon
2	Bean ↔ key parity + default drift	key has no bean field, field has no key, Java default ≠ reference.conf default	Python + javalang or Gradle JUnit using Class.getDeclaredFields() + ConfigFactory.defaultReference()
3	Binding chain completeness	bean field exists but applyXxxConfig doesn't assign to PARAMETER, or no production consumer reads getXxx()	Java AST or Gradle JUnit reflection
4	Inline comment coverage	Leaf keys without #/// documentation	Python + pyhocon + raw text scan (carry-forward inline comments)
5	XxxConfigTest coverage	Bean field present but no test assertion references it	Gradle JUnit (reflection on test bytecode)

(Gate 6 — deprecation policy via git history scan — is qualitatively different and lower priority; defer.)

Why one PR + multi-commit rather than 5 follow-up PRs:

1. Shared infrastructure — Gates 1/2/4 all use pyhocon, share GHA annotation emission, live in .github/scripts/. Keeping them together avoids cross-PR refactoring.
2. Coherent design surface — reviewer can spot rules that interact (e.g. comment-coverage gate's line-attribution must match how naming gate walks segments).
3. Avoids the "follow-up never happens" trap — multi-PR roadmaps in OSS projects often stall after Gate 1 lands.
4. Independent rollback preserved — git revert <gate-N-commit-sha> is as clean as reverting a standalone PR.
5. Project velocity context — the config series (refactor(config): simplify applyEventConfig (follow-up to #6615) #6735, fix(config): optimizes config binding for node  #6755, refactor(config): merge test config files #6788, refactor(config): overhaul config docs, fix defaults, remove dead params #6790, refactor(config): remove unused storage index and json parsing config #6794, this PR) is concentrated in a few contributors; one focused PR avoids ×5 scoping/CI/review overhead.

Why Gate 2 is the highest-leverage follow-up: it's exactly the gate that would have caught the recent class of issues this series has been fixing manually:

• refactor(config): remove unused storage index and json parsing config #6794 removed receiveTcpMinDataLength, maxNestingDepth, maxTokenCount, storage.index.directory/switch — all dead config keys discovered by manual grep. Parity gate would have flagged them.
• fix(config): optimizes config binding for node  #6755 / refactor(config): overhaul config docs, fix defaults, remove dead params #6790 needed to fix several allowShieldedTransactionApi / dns defaults inconsistencies between Java field initializers and reference.conf. Drift gate would have caught them.

Suggested commit layout:

1. feat(ci): add reference.conf naming + depth gate           ← current PR content
2. feat(ci): add bean ↔ key parity + default drift gate       ← Gate 2 (highest ROI)
3. feat(ci): add config binding chain completeness gate
4. feat(ci): add inline comment coverage gate
5. feat(ci): add XxxConfigTest field coverage gate

For Gate 2 implementation, Gradle JUnit using Java reflection is likely simpler than Python + AST parsing — Class.getDeclaredFields() walks bean fields naturally, no Java AST parser needed. ~4–6 hr starting cost.

TL;DR

• ✅ Approve in principle — Gate 1 is solid, regex/depth logic verified empirically (296 keys, max depth 5)
• 🟠 Fix 2 small items before merge — add shutdown.BlockTime/Height/Count to ALLOWLIST; tighten regex description in script
• 📋 Suggest extending to all 5 gates in this PR as separate commits, rather than 5 follow-up PRs — shared infrastructure, coherent design surface, avoids the "follow-up never happens" trap

[bladehan1]

Two changes have been implemented.
Agreed that Gate 2 is the highest ROI going forward, but this PR should not be merged. The scope of Gate 2 (which packages count as config beans, cross-type default value comparison, Args.java boundary, toolchain selection) is substantial enough for its own PR.

Gates 3/4/5 overlap with Gate 2.Gate 2's scope must be clarified first before we can determine whether 3/4/5 still stand independently

[317787106]

Good gate — the naming-convention and depth ceiling cover two of the most common drift vectors. A few additional constraints worth considering for this script or follow-up PRs, roughly in order of implementation cost:

1. Duplicate-key detection

HOCON silently keeps the last value when the same key appears twice, making typo-overwrites invisible. A text-level scan (before ConfigFactory.parse_file) can surface these cheaply without pyhocon involvement:

import collections
seen = collections.Counter()
for line in path.read_text().splitlines():
    m = re.match(r'^\s*([\w.]+)\s*[={]', line)
    if m:
        seen[m.group(1)] += 1
duplicates = [k for k, c in seen.items() if c > 1]

2. Port-uniqueness check

reference.conf currently defines 10+ default ports. Two services sharing a port is a hard startup failure with a confusing error message. Extracting all *[Pp]ort leaf values and asserting they are distinct costs ~5 lines and
would prevent port-collision regressions from landing silently.

3. No non-empty default for sensitive keys

Keys whose path contains password, secret, privateKey, or token should default to "" or be absent. A regex scan over leaf values would catch any accidental weak-credential default before it reaches a release tag.

4. Numeric-range sanity

Many leaf types have well-known valid ranges implied by their names:

┌────────────────────────────────┬────────────────┐
│            Pattern             │ Expected range │
├────────────────────────────────┼────────────────┤
│ *[Pp]ort                       │ 1024–65535     │
├────────────────────────────────┼────────────────┤
│ *[Tt]imeout / *[Ii]nterval     │ > 0            │
├────────────────────────────────┼────────────────┤
│ *[Ss]ize / *[Cc]ount / *[Nn]um │ ≥ 0            │
└────────────────────────────────┴────────────────┘

These can be checked with a small name→constraint dispatch table using isinstance(value, int) after pyhocon parsing.

5. Bean-field ↔ key parity (the "Gate 2" mentioned in the PR description)

This is the highest-leverage follow-up: reflect each *Config class to enumerate declared fields and cross-check against reference.conf keys in both directions — orphan keys (in conf, no field) and unbound fields (field
exists, no default in conf). This is what would have caught indexDirectory and maxNestingDepth at PR time rather than requiring a manual audit like #6794. The implementation is more involved (needs javap or AST parsing), but
the --list-keys output from this script is a natural input for it — worth adding a --list-keys flag now to keep the two gates composable.

[bladehan1]

Thanks for the thorough list. Status by item:

1 Duplicate-key detection — declined.

Duplicate keys in a well-formatted reference.conf are visible in code review (the file has section ordering, and the header documents it). pyhocon exposes no API for it, so the only path is a hand-rolled text scanner — exactly the trap this PR paid for once already: the original homemade scanner mis-handled key = { ... } blocks and under-counted by 17 keys / 1 depth level, which is why we switched to pyhocon. The proposed regex would also stumble on dotted-form keys inside {} blocks, += appends, // line comments, and triple-quoted strings — silent false-positive or miss in each case. Maintaining a second parallel scanner doesn't pay for a class of bug already visible to reviewers.

2 Port-uniqueness check — implemented in this PR.

Added as rule 4 in check_reference_conf.py: leaves whose last segment is port or ends in Port must bind distinct integer values. Sentinels 0 (disabled) and -1 (auto/unset) are exempt. Paths containing [] are excluded — per-record fields (e.g. genesis-witness ports), not local-process bindings. Uses pyhocon's parsed tree, no extra deps.

3 Sensitive-default scan — not a fit for CI.

This is policy-shaped ("what counts as sensitive", "warn vs fail", "where the empty-placeholder allowlist lives"), not a config-grammar check. The decisions are release-engineering and business, not syntactic. CI gates work when the rule is deterministic from the file alone; this one isn't, and pushing it into CI just moves the policy decision into a regex with an ever-growing exemption list.

4 Numeric-range sanity — not a fit for CI either.

Range constraints belong with the bean that owns the value (e.g. fromConfig-side validation in *Config.java, or JSR-303-style annotations on the field), not with a regex over reference.conf. The file lists values; the bean knows their meaning. A pattern-dispatch table in CI separates the constraint from its owner and accumulates per-pattern exemptions (*[Pp]ort legitimately admits 0 / -1; *[Ss]ize may be normalized from bytes; etc.) until the gate's signal-to-noise is worse than a code review.

5 Bean-field ↔ key parity (Gate 2) — declined as a CI gate; replaced with a convention comment in reference.conf.

This is the part worth laying out carefully.

The gate would catch two distinct silent-miss cases:

• (A) HOCON key with no Java reader — dead config (e.g. storage.index.directory in refactor(config): remove unused storage index and json parsing config #6794).
• (B) Java field with no HOCON default — ConfigBeanFactory binds nothing and the field keeps its Java-side initializer, silent if that initializer happens to be acceptable.

The surface is real. The question is what tool catches it.

The proposed CI shape (javap or AST parse) is expensive and grows over time:

• Lombok @Setter / @Getter are pre-compile annotations. A source-level AST sees @Setter, not setFoo(). The gate either re-implements Lombok semantics or runs post-compilation against .class files — both are substantial first build-outs.
• The script already documents three manual-bind exceptions (pBFTExpireNum, isOpenFullTcpDisconnect, BlockTime/Height/Count) that a naive parity check would flag. The gate needs an allowlist for these.
• A fourth category must also be allowlisted: pre-normalization paths that deliberately bypass ConfigBeanFactory. NodeConfig.parseMaxMessageSize parses node.rpc.maxMessageSize via Config.getMemorySize(...).toBytes() and writes the int back before bean creation, so a naive parity check flags this as a violation.

The gate would land at ~100 LOC with a growing allowlist that turns it into noise within a few cycles.

The class of bug is qualitative, not syntactic:

• "Is the new key's value compatible with the bean field's primitive type?"
• "Does the new field actually need a default in reference.conf, or is the Java-side initializer fine?"
• "Should this key be a raw int, or are we tempted to add a pre-normalization helper for a human-readable form?"

These are convention questions. Documentation answers them more reliably than a parser.

What I did instead — extended the rules block at the top of reference.conf. It already covered camelCase auto-binding and the three manual-bind exceptions; it now also documents:

• The value-type rule: literals must match the Java field's primitive type. ConfigBeanFactory does no coercion; long won't bind "4m".
• The pre-normalization stance: NodeConfig.parseMaxMessageSize is in the existing code as the antipattern the convention warns against — it makes one key parse differently from every other in the file, for an ergonomic gain that doesn't outweigh the consistency cost. New keys must not add similar pre-normalization helpers; use the raw int and keep every key homogeneous.
• CI scope: the script validates SYNTAX (camelCase, depth, port uniqueness). Value-type / parity mismatches surface as ConfigBeanFactory exceptions at startup, not in CI.

For the dead-key case (#6794's failure mode): periodic manual audits remain the cheapest catch-net. Running one every few months is less work than maintaining the AST/reflection gate, and it's the same shape of work #6794 already does.

The trade-off is real — comments are easier to ignore than a red check. But for a class of bug whose fixes are qualitative, and where the gate would carry a growing exception list, the cost equation doesn't favor the gate.