[R2-11][P4] Fix AGENTS.md function-casing rule + normalize 4 mixed-style files

[MichaelFisher1997]

Part of #839 — [Audit][Round 2] A++ umbrella.
Phase: P4 · Finding: R2-11 · Scope: doc + trivial code normalization

Problem

AGENTS.md mandates snake_case for functions (init_renderer), but the codebase is 99.3% camelCase (initRenderer) — following Zig stdlib convention. The literal rule is unfollowable. Additionally, 4 files mix styles within themselves, which is the only real readability bug.

Evidence

AGENTS.md vs code contradiction

From AGENTS.md → "Code Style" → "Naming Conventions":

Functions/Variables: snake_case (init_renderer, mesh_queue, chunk_x)

Across 409 Zig files (excluding vendored libs/):

• camelCase functions: 2,814 (99.3%)
• snake_case functions: 19 (0.7%)

The Zig stdlib itself uses camelCase for functions (std.mem.Allocator, std.ArrayList.append). The AGENTS.md rule contradicts both the code and Zig idiom.

4 files mix styles within themselves (the real bug)

File	camelCase fns	snake_case fns
modules/world-lod/src/lod_renderer.zig	99	2
modules/world-lod/src/lod_geometry.zig	85	7
modules/engine-graphics/src/vulkan/culling_system.zig	16	3
modules/game-core/src/benchmark.zig	15	1

Example from lod_geometry.zig (verified in audit):

pub fn is_lod_water_cell_for_lod(...)    // snake_case, next to:
pub fn quantizedCellTerrainHeightForLOD(...) // camelCase

Other naming notes (out of scope, just context)

• Types/constants/files/imports: 100% compliant with AGENTS.md
• One intentional global violates SCREAMING_SNAKE: pub var log in engine-core/src/log.zig:175 — intentional for API ergonomics (log.log.info(...))

Fix

Step 1 — fix AGENTS.md (one-line change)

Change the Functions row in the Naming Conventions table to:

Functions: camelCase following Zig stdlib convention (initRenderer, meshQueue, chunkX)

Keep Variables: snake_case as-is (Zig idiom for locals).

Update any examples in AGENTS.md / CONTRIBUTING.md that show snake_case function names.

Step 2 — normalize the 4 mixed files

Rename the ~13 snake_case functions to camelCase. Use grep -rE + manual rename (Zig has no built-in rename refactoring; this is mechanical).

Sites to rename (approximate — verify each before editing):

• modules/world-lod/src/lod_renderer.zig — 2 fns
• modules/world-lod/src/lod_geometry.zig — 7 fns (e.g. is_lod_water_cell_for_lod → isLODWaterCellForLOD, cell_color_for_lod → cellColorForLOD, water_coverage_stats → waterCoverageStats)
• modules/engine-graphics/src/vulkan/culling_system.zig — 3 fns (e.g. update_aabb_data → updateAABBData, read_visible_count → readVisibleCount, read_visible_indices → readVisibleIndices)
• modules/game-core/src/benchmark.zig — 1 fn

Update all call sites (grep for each old name across modules/ and src/).

Verification

• nix develop --command zig build test (catches any missed call site)
• nix develop --command zig fmt src/ modules/ (formatting check)
• grep -rE 'pub fn [a-z][a-z0-9_]*_[a-z]' modules/ src/ | grep -v '_tests.zig' | grep -vE 'pub fn (deinit|main)' should return zero matches after normalization
  • (exceptions: deinit, main, and test helper fns are conventional snake_case in some Zig projects — verify before flagging)

Constraints

• Pure rename, no behavior change. No codepath alterations.
• Single PR per file (4 PRs) or one PR for all renames + AGENTS.md update — either is fine.
• Conventional commit: docs: fix AGENTS.md function casing rule, refactor(world-lod): normalize function casing in lod_geometry.
• All call sites must be updated in the same PR — no broken builds on dev.

Notes

• This is the lowest-risk issue in Round 2, but it removes the only documented rule that the codebase uniformly violates — improves AGENTS.md credibility.
• If the team prefers snake_case for functions after all (e.g. for consistency with a sibling project), invert the fix: rename 2,814 camelCase → snake_case. That's a much larger PR and not recommended.

Tracking: #839

[github-actions]

Posted analysis on issue #842. Summary:

• Classification: Doc-fix (P4) + Refactor (P4); AGENTS.md rule contradicting code is the real maintainability bug.
• Key correction: Audit listed 4 files but actually 5 files contain snake_case pub fn — modules/engine-rhi/src/culling.zig was missed and declares the 3 interface methods that vulkan/culling_system.zig implements. Renaming without the RHI interface would break the type contract.
• Recommendation: Single PR (not 4) because the interface/implementor pair forces atomicity, and the rename set is small (~14 file edits).
• Scope: Too small to warrant sub-issue splitting.
• Doc edit: Provided exact AGENTS.md:110 and CONTRIBUTING.md:223 text replacement.
• Renames: Enumerated all 13 sites; flagged that deinit/main/_test should be excluded from any final grep gate.

opencode session  |  github run