feat(ci,config): add comment coverage gate for reference.conf

[bladehan1]

What does this PR do?

Adds a comment-coverage CI gate for `reference.conf` and annotates all previously undocumented configuration keys.

Changes

1. `.github/scripts/check_reference_comments.py` (new, 358 lines, zero runtime dependencies)

   • Line-oriented Python 3 scanner — pyhocon is intentionally avoided because it discards comments.
   • Enforces that every key carries either an inline (`#` / `//`) comment or a non-blank comment on the immediately preceding line.
   • Array-element keys are deduplicated: only the first occurrence in a homogeneous array is checked (handles `rate.limiter` entries).
   • `--list` flag prints every key with its status (`commented` / `dedup` / `missing`) for local debugging.
   • On failure: human-readable violation list + GHA `::error` annotations with `line N: key`.
   • Docstring documents known HOCON edge-case limitations (quoted keys, `+=`, triple-quoted strings, bare URLs) and explains why each is low-risk for `reference.conf`.

2. `.github/workflows/pr-check.yml` (+6 lines)

   • New step runs immediately after the existing `check_reference_conf.py` (key-format / depth / port-uniqueness) gate.
   • Any non-zero exit code fails the step and blocks the job; no `continue-on-error`.

3. `common/src/main/resources/reference.conf`

   • All previously undocumented keys now carry inline comments. The `committee` block includes the `/wallet/getchainparameters` API key name and `ProposalType` ID for each governance parameter.

Why are these changes required?

`reference.conf` is the primary configuration reference for node operators. Before this change most keys had no explanation, forcing operators to read source code. There was no CI enforcement either, so new keys could be merged without documentation.

This PR has been tested by:

• Manual Testing: `python3 .github/scripts/check_reference_comments.py common/src/main/resources/reference.conf` → `OK` (exit 0)
• Manual Testing: `python3 .github/scripts/check_reference_conf.py common/src/main/resources/reference.conf` → `OK: 290 keys, all lowerCamelCase, depth <= 5, service ports unique` (exit 0)
• Manual Testing: `check_reference_comments.py --list` output verified: 252 commented, 118 dedup, 0 missing
• `committee` block comments cross-checked against live mainnet `/wallet/getchainparameters` API response and `ProposalUtil.ProposalType` enum in source — all 42 ProposalType IDs and API key names confirmed correct
• Unit Tests: local test suite `.helper/test_reference_conf/run.sh` — 41/41 passed (14 comment-coverage fixtures + 17 key-format fixtures + real `reference.conf` smoke tests)
• CI: PR Lint ✅, check-math ✅, Checkstyle ✅, System Test ✅, Build debian11 ✅, Build rockylinux ✅, Build macos26 ✅

Extra details

• HOCON comments (`#` / `//`) are fully transparent to Typesafe Config and pyhocon — no runtime behaviour is affected.
• The gate is intentionally a basic coverage check, not a full HOCON parser. Constructs not used in `reference.conf` (quoted keys, `+=`, triple-quoted strings) are documented as known limitations in the script docstring.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c48fd242-7cba-422c-b710-22ad1089695e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/ci_reference_comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

2 issues found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".github/scripts/check_reference_comments.py">

<violation number="1" location=".github/scripts/check_reference_comments.py:20">
P2: The key-line regex is too narrow for valid HOCON key syntax (e.g., hyphenated/quoted keys and `+=`), which can create false negatives in the coverage gate.</violation>

<violation number="2" location=".github/scripts/check_reference_comments.py:107">
P2: The genesis exemption misses equivalent nested HOCON syntax (`genesis { block { ... } }`), causing false comment-coverage failures for exempt keys.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>