fix: improve error context with unified logging and error return traces (#276)

[MichaelFisher1997]

Summary

Closes #276

• Enhanced log.zig: Added errWithTrace() method that logs an error and automatically dumps the error return trace stack via @errorReturnTrace(), giving full stack traces at error sites
• Unified logging: Migrated all 139 std.log.* calls across 27 files to the custom log.log.* logger for consistent formatting and a single source of truth
• Error return traces at critical catch sites: Upgraded 30+ error catch blocks to use errWithTrace() in mesh building, GPU recovery, resource recreation, shader loading, and more
• Contextual init logging: Added descriptive log messages at each subsystem initialization step in App.init(), World.initGen(), and RenderSystem.init()
• Bug fix: Added missing errdefer in World.initGen() that leaked the WorldStreamer if WorldRenderer init failed

Changes

src/engine/core/log.zig

• Added errWithTrace() method for error logging with automatic stack trace dumps
• Updated module-level documentation with usage examples

Logging Migration (27 files, 139 call sites)

• src/world/*.zig (6 files): world.zig, chunk_mesh.zig, chunk_allocator.zig, world_renderer.zig, world_streamer.zig, lod_upload_queue.zig, registry.zig
• src/engine/graphics/*.zig + vulkan/*.zig (17 files): rhi_vulkan.zig, vulkan_device.zig, lpv_system.zig, and all vulkan/ sub-modules
• src/game/*.zig (4 files): session.zig, settings/persistence.zig, settings/json_presets.zig

Error Return Trace Sites (30+ locations)

• Mesh build failures (world_streamer, chunk_mesh x3, lod_manager, lod_renderer)
• GPU operations (rhi_vulkan, rhi_frame_orchestration x12, rhi_pass_orchestration x4)
• Rendering failures (render_graph sky/cloud passes)
• Shader loading (lpv_system)
• World generation (overworld_generator block light)
• Settings persistence (app.zig)

Init Context Logging

• App.init(): logs before SettingsManager, WindowManager, RenderSystem, AudioSystemManager, UISystemManager
• World.initGen(): logs before WorldStreamer and WorldRenderer init
• RenderSystem.init(): logs before RHI device init, resource packs, texture atlas, AtmosphereSystem, MaterialSystem, LPVSystem

Acceptance Criteria (from #276)

• Critical initialization paths have detailed error logging
• Error messages include file and line information (via @errorReturnTrace())
• Debug builds include full stack traces (via errWithTrace())
• Document error handling strategy (module-level docs in log.zig)
• Tests still pass

[opencode-agent]

Now I have all the information needed for a comprehensive review.

📋 Summary

This PR Closes #276 - Improving error context with unified logging and error return traces.

Purpose: Standardizes all logging through a custom log.zig module and adds automatic error return traces at critical failure sites for better debugging.

Scope: 35 files changed, 204 insertions(+), 148 deletions(-). All 139 std.log.* calls migrated to the custom logger, 30+ error catch blocks upgraded to use errWithTrace(), plus contextual init logging and a memory leak bug fix.

Overall Quality: Good - The PR successfully addresses all acceptance criteria from #276. Tests pass, the code follows Zig conventions, and the changes improve observability without adding runtime overhead in release builds.

---

🔴 Critical Issues (Must Fix - Blocks Merge)

None identified.

---

⚠️ High Priority Issues (Should Fix)

None identified.

---

💡 Medium Priority Issues (Nice to Fix)

None identified.

---

ℹ️ Low Priority Suggestions (Optional)

None identified.

---

📊 SOLID Principles Score

Principle	Score	Notes
Single Responsibility	9	log.zig has single responsibility for logging; migration doesn't mix concerns
Open/Closed	8	Logger is extensible via LogLevel enum; new levels can be added without modifying consumers
Liskov Substitution	10	No inheritance hierarchies affected; pure struct-based design
Interface Segregation	9	Logger provides focused API (trace/debug/info/warn/err/errWithTrace/fatal)
Dependency Inversion	8	All modules now depend on log.zig abstraction instead of std.log directly
Average	8.8	Strong adherence to SOLID principles

---

🎯 Final Assessment

Overall Confidence Score: 92%

How to interpret:

• 0-30%: Major concerns, do not merge without significant rework
• 31-60%: Moderate concerns, several issues need addressing
• 61-80%: Minor concerns, mostly ready with some fixes
• 81-100%: High confidence, ready to merge or with trivial fixes

Confidence Breakdown:

• Code Quality: 95% (Clean implementation following Zig idioms, consistent patterns)
• Completeness: 90% (All acceptance criteria from [MED] Improve error context - Add file:line information and descriptive error messages #276 met, tests pass)
• Risk Level: 90% (Low risk - logging changes are additive, errdefer fix is correct)
• Test Coverage: 95% (All existing tests pass, shader validation included)

Merge Readiness:

• All critical issues resolved
• SOLID average score >= 6.0
• Overall confidence >= 60%
• No security concerns
• Tests present and passing (if applicable)

Verdict:

MERGE

This PR successfully implements comprehensive error logging improvements, unifies 139 logging calls across 27 files, adds contextual stack traces at 30+ error sites, and fixes a resource leak bug. All tests pass and the code follows project conventions.

opencode session  |  github run