Executive Summary

The repository appears to be a small browser game prototype, but its main gameplay file has already accumulated enough concentrated logic to create a high maintainability burden. The dominant risks are one-file orchestration in src/game/game.js, repeated geometry and spawn builders, an archived monolith left in the active tree, and the absence of automated tests. The auditor's closing position is: High maintainability risk, low AI-slop confidence.

Background

The application appears to be a Three.js-based browser survival prototype bundled with Vite and deployed to GitHub Pages. README.md explicitly describes it as a "lightweight procedural survival prototype" and even lists splitting src/game/game.js as a future milestone, which materially strengthens the non-AI explanation for the current structure. The scoped audit covered the primary runtime entry, core game modules, manifest, deployment workflow, and manual playtest notes.

Methodology

Maintainability signals were investigated via static analysis and targeted source review. The engagement lead used specialist outputs for cyclomatic and cognitive complexity, structural duplication, dead abstraction checks, error-handling smells, test-signal review, and comment-intent review; candidate findings were filtered by agent-led triage and then validated against named paths and symbols. Confidence is mixed rather than uniform: measured branch and clone metrics were available for src/game/game.js, but the Java-oriented comment-density tooling did not apply to this JavaScript codebase, the exception-handling lane returned only a sampled non-finding, and the repository contains no automated tests from which assertion quality could be judged. Dynamic runtime behavior, browser profiling, and full-file body review outside the hotspot cluster were out of scope.

Findings

The evidence points to a localized but serious maintenance hotspot rather than uniform disorder across every file. src/game/game.js dominates the risk picture: indexed summaries place it at 2,081 lines, measured cyclomatic hotspots put init at 71 and animate at 58, and direct symbol review shows rendering bootstrap, shader definition, spawn management, UI mutation, combat input, save/load, and placement logic sharing one mutable state surface. A direct cognitive-complexity pass did not flag functions above 15, which suggests the pain comes more from breadth and coupling than from deeply nested logic.

The second hotspot is repeated construction logic. spawnTree, spawnRock, and spawnShrub repeat similar spawn-selection and scene-registration patterns; buildDoorwayMesh mirrors createDoorwayGhost, and buildDoorMesh mirrors createDoorGhost with parameter changes rather than a shared builder. loadGame extends the same pattern through a long type-dispatch reconstruction chain. These are maintenance risks because new geometry, placement, or persistence rules must be updated in multiple places.

The third risk is weak change-safety. package.json contains only dev, build, preview, and dev:vm scripts, with no test runner dependency or test script. docs/usernotes/playtest-notes.md shows manual playtesting in place of automated checks. In the same hotspot file, loadGame performs JSON.parse on persisted state without structured validation or recovery, and index.original.html remains in the root as a 2,406-line historical monolith that can confuse search and refactoring work.

Low-signal comments add a smaller but real readability tax. In src/game/game.js, the Boar constructor uses literal labels such as Body, Head, and Tusks over straightforward mesh creation, and many section dividers label obvious phases without explaining design constraints. The comments are mostly accurate, so this is a readability issue rather than a misleading-documentation issue.

Validated Non-Findings

Several checks did not produce material issues within the inspected sample. A direct cognitive-complexity pass across src/game/game.js, src/game/audio.js, and src/game/terrain.js found no function above the threshold of 15, which tempers the control-flow reading: the hotspot is broad and stateful, but not heavily nested everywhere.

The sampled support modules also held up well. src/game/audio.js:createAudioPlayer stayed compact, and src/game/terrain.js remained small and cohesive around hash, noise, fbm, and getElevation. The dead-abstraction lane also reviewed one-call helpers such as createAudioPlayer and createSpawnConfig; those looked like acceptable modular wrappers rather than harmful dead code.

The error-handling specialist found no exception-handling smells above threshold in the sampled set src/game/game.js, src/game/audio.js, src/game/terrain.js, src/game/data/config.js, and src/main.js. That result is scope-limited because that lane relied on hotspot orientation and did not establish a repository-wide body review. A targeted search also found no TODO, FIXME, HACK, or deprecated markers in sampled src/game/**/*.js.

Recommendations

The remediation plan should stay behavior-preserving and focus first on the concentrated hotspot rather than on wholesale rewriting.

• Finding 1 — Split src/game/game.js by runtime role: extract renderer/bootstrap, input handling, UI rendering, entity classes, placement/building, and save/load into separate modules with narrow exports.
• Finding 1 — Add characterization tests before large extractions, starting with deterministic logic in src/game/terrain.js, inventory/crafting state changes, and save/load round-trips around src/game/game.js:loadGame.
• Finding 1 — Add a JavaScript lint or CI budget for branchiness and size, such as review gates for cyclomatic complexity above 20 or large-file exceptions above an agreed LOC threshold. The policy should document expected false positives for dispatcher-style code.
• Finding 2 — Replace clone bundles in src/game/game.js with data-driven builders: one spawn factory for spawnTree / spawnRock / spawnShrub, and shared constructors for ghost versus solid door and doorway meshes.
• Finding 2 — Remove index.original.html from the active root once parity is confirmed, or clearly annotate and exclude it from everyday search and lint targets if temporary retention is required.
• Finding 3 — Add a test runner to package.json and begin with deterministic unit tests plus persisted-state schema validation; the current manual playtest notes in docs/usernotes/playtest-notes.md are useful operational notes but not a regression harness.
• Finding 4 — Reduce comment noise in src/game/game.js by deleting literal object-part labels and keeping only comments that explain non-obvious geometry, state constraints, or save/load invariants.

Conclusion

The repository shows evidence of real engineering effort: src/game/audio.js and src/game/terrain.js are restrained, purposeful modules, and several suspicious one-call abstractions proved harmless on review. Even so, the engagement closes with high maintainability risk because the main runtime file concentrates too many responsibilities, contains measured branch-heavy hotspots, duplicates builder logic, leaves a historical monolith in the active tree, and lacks automated test protection. The auditor's closing synthesis is: High maintainability risk, low AI-slop confidence.