Skip to content

chore(module): make comments readable without the issue tracker - #412

Merged
Mathih13 merged 3 commits into
mainfrom
chore/module-comment-tracker-refs
Sep 3, 2026
Merged

Mathih13 merged 3 commits into
mainfrom
chore/module-comment-tracker-refs

Conversation

@Mathih13

@Mathih13 Mathih13 commented Sep 3, 2026 •

Copy link
Copy Markdown
Contributor

Comments under module/src pointed at the issue tracker about 830 times: (#119), Issue #237: …, #120's opener, pre-#22 order. A reader without tracker access cannot follow any of them, and CODING_STANDARDS.md forbids the practice. A second group of allow(dead_code) attributes claimed a caller was coming "with the Trade Session work" or kept a core "for a future gw_* twin". Those callers either already exist or never will.

What changed

Comments keep their explanation and lose the reference token. (#119) disappears, #120's opener becomes the opener, MERGE ORDER (#19 × #20) becomes The merge order, and a sentence that carried nothing but a pointer is gone. A script did the mechanical pass; every changed line was then read and about 60 sentences were repaired by hand where the removal broke the grammar. No explanation was shortened. String literals, attributes and test names were not touched.

Dead-code allowances:

  • helpers.rs: deleted three. trade.rs already calls player_interaction_gate, PlayerInteractionDenied and the range constant.
  • talent.rs: deleted two. gw_reset_talents exists and calls do_reset_talents.
  • instance.rs, items/inventory.rs: five became cfg_attr(not(feature = "debug_reducers"), allow(dead_code)) with a one-line note naming the sole caller. No gw_reset_instance or gw_split_item reducer exists; debug_reset_instance and debug_split_item are what reach these cores. This is the idiom nine other sites in the crate already use, and unlike a hard cfg it keeps the unit tests for those gates compiling in a default cargo test.
  • spell/stacking.rs: deleted DR_CAT_CHARM, DR_CAT_SLEEP and DR_CAT_DISORIENT. No mechanic maps to them, nothing reads them, and the numbering is internal rather than a wire contract.

Five unconditional allowances remain: RULE_STACKS (the wildcard fallback, read only by a test), EquipStat::Spirit (an item-template stat column with a live match arm and no constructor yet), and three taxonomy bindings. _RESERVED_NON_KIND_TAXONOMY now holds 18 residual values, including P_SPELLMOD_OP. A source tripwire pins the unconditional count at five; conditional cfg_attr allowances do not count.

Keeping it clean

tripwires::issue_reference_tripwire lexes Rust source before it checks comments. It detects full-line and trailing // comments, nested block comments, and forms such as pre-#22; it ignores code, ordinary escaped strings, raw strings, byte raw strings, and character literals. Build, opcode, patch, and revision numbers are not tracker references. Those five exception words match ASCII case-insensitively.

The only allow-listed file is spell/cast/targeting.rs, with exactly six references. A lower count, a higher count, or an absent allow-listed file fails. Direct fixtures cover the comment and literal forms, both stale-count directions, and the missing-file condition.

Verification

  • cargo test -p lyracore-module --lib --features=debug_reducers: 1467 passed.
  • cargo clippy -p lyracore-module --features=debug_reducers -- -D warnings stops on 31 existing errors in unrelated files. No error is in the scanner, taxonomy, or EventAI change.
  • cargo check --target wasm32-unknown-unknown -p lyracore-module --features=debug_reducers completes cleanly.

Written by Claude Fable 5.1 in Claude Code.

Review fixes by GPT-5.6 through the Codex harness in T3 Code.

Mathih13 and others added 3 commits September 3, 2026 19:29
…lowances

Comments in module/src carried ~830 issue-number references. A reader with no
tracker access cannot follow them, and CODING_STANDARDS forbids them.

Strip the reference tokens only, keeping the surrounding explanation. Delete
five stale `allow(dead_code)` attributes whose callers have since landed, mark
the three split/reset cores that only a debug reducer reaches with
`cfg_attr(not(feature = "debug_reducers"), allow(dead_code))`, and delete the
three DR category constants that no code reads.

Add `tripwires::issue_reference_tripwire`, a ratchet that fails when a comment
under module/src carries a tracker reference again.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@Mathih13
Mathih13 merged commit 2d52aec into main Sep 3, 2026
1 check passed
@Mathih13
Mathih13 deleted the chore/module-comment-tracker-refs branch September 3, 2026 20:28
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.

1 participant