Skip to content

docs: correct six stale comments found by a fact-check pass - #164

Merged
mcdope merged 2 commits into
masterfrom
fix/stale-doc-comments
Aug 26, 2026
Merged

mcdope merged 2 commits into
masterfrom
fix/stale-doc-comments

Conversation

@mcdope

@mcdope mcdope commented Aug 26, 2026

Copy link
Copy Markdown
Owner

Six comments that describe the code as it was rather than as it is. No behaviour changes — comments, one doc paragraph, and one config comment.

They surfaced because three independent agents fact-checked a draft of some launch copy against the repo. Nobody goes looking for stale comments; they turn up when something forces a close read.

What was wrong

Where Claimed Actually
lore.ts:21-23 HP_PER_COMPLEXITY is 25 35
enemies.ts:412-415 room total is 25 * complexity, Edge Case roll is 10-15 35, and 25-35
mapGenerator.ts:263 Edge Cases are never in a normal room set in three places since 2026-08-20
main.ts:327 third tab is "GitHub" it is "Repo", and takes GitLab/Codeberg too
decisions.md assertAllRoomsReachable is a "dev-time assertion" runs in production, and logs rather than throws
vitest.config.ts:100 coverage is 99.94/99.79/99.62/99.97% 99.9083/99.5225/99.84/99.99%

Notes on the fixes

The two HP comments now name the constants instead of restating their values, so this particular drift cannot recur. The two deliberate historical references to 25 — in weapons.ts and combatConstants.ts, both describing the 25 → 35 change itself — are left alone.

mapGenerator.ts kept the half that is still true. spawnEdgeCaseEnemies does populate the corridor features exclusively and is the only thing that populates them; it is the converse ("and normal enemies never spawn in one") that stopped holding. types.ts already carried the corrected wording and is now cross-referenced.

The coverage figures are restated in units rather than percentages, because that is the part worth knowing: statements are at 13,073/13,085 and branches at 5,627/5,654, so each can afford exactly one more uncovered unit before the gate fails. The thresholds no longer "sit just below" what is measured — statements is essentially on the line, and that is worth a reader knowing before they wonder why an unrelated PR went red.

That last number is itself a correction: the first draft said "a single new uncovered statement fails the gate", from a measurement taken on a branch that carried extra code. The arithmetic says two.

Also in here

One unrelated commit, acd3acf, adds pr/ to .gitignore — a local scratch directory for launch copy and screenshots. It has to be ignored rather than merely untracked, because run-balancing-capture.mjs refuses to start on any non-empty git status --porcelain.

Verification

  • npm run build — clean, bundle hygiene clean
  • npx vitest run --dir src — 3,682 tests, 135 files, all passing
  • npx vitest run scripts/lib/docPins.test.mjs — 70 passing
  • Coverage re-measured on this branch: 99.9/99.52/99.84/99.99, all four gates clear

🤖 Generated with Claude Code

https://claude.ai/code/session_017ncJfux8GDacSTeLDcqrhr

mcdope and others added 2 commits August 26, 2026 22:07
`pr/` holds ready-to-post launch copy for seven platforms plus the images each
one needs. It is drafts and captured screenshots: the durable artifacts are the
posts themselves, wherever they end up published, not a snapshot of what was
pasted. Same rule the docs-audit/ and level_maps/ entries already follow.

Ignored rather than merely untracked because run-balancing-capture.mjs refuses to
start on any non-empty `git status --porcelain`, untracked files included — so an
unignored scratch directory would block a capture while a kit is being written.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
None of these change behaviour; all six describe the code as it was, not as it
is. They surfaced while three independent agents fact-checked a launch-copy
draft against the repo, which is the only reason anyone read them closely.

- lore.ts / enemies.ts still gave `HP_PER_COMPLEXITY` as 25; it has been 35
  since the enemy-health pass. The enemies.ts comment was wrong twice over — it
  also called the Edge Case roll "10-15", which is now 25-35. Both are fixed by
  naming the constants instead of restating their values, so the same drift
  cannot recur; the two *deliberate* historical references to 25 (weapons.ts,
  combatConstants.ts, both describing the 25 -> 35 change itself) are untouched.

- mapGenerator.ts claimed Edge Cases are "never a normal room, and normal
  enemies never spawn in one". The converse half stopped being true on
  2026-08-20: `edgeCase` is now set in three places, and `types.ts` already
  carries the corrected wording. What remains true, and is what the comment was
  reaching for, is that `spawnEdgeCaseEnemies` populates the corridor features
  exclusively and is the only thing that populates them.

- main.ts headed the launch tabs "Local / Continue / GitHub / Demo level". The
  tab is called Repo and takes GitLab and Codeberg too. Its elements were
  renamed with it; only the `LaunchTab` key is still `github`, so the comment
  now says so rather than leaving a reader to wonder which name is wrong.

- decisions.md called `assertAllRoomsReachable` "a permanent dev-time BFS
  assertion". It is deliberately not gated behind `import.meta.env.DEV` — the
  source says so, and says why: a shipped build is exactly where nothing else
  would catch an unreachable room. It also `console.error`s rather than throws,
  so "assertion" was the wrong word.

- vitest.config.ts advertised coverage of 99.94/99.79/99.62/99.97%. Measured on
  master today it is 99.9083/99.5225/99.84/99.99. Restated in units rather than
  percentages because that is the part worth knowing: statements sit at
  13,073/13,085 and branches at 5,627/5,654, so each can afford exactly one more
  uncovered unit before the gate fails.

That last figure is itself a correction of a first draft of this commit, which
said "a single new uncovered statement fails" from a measurement taken on a
branch carrying extra code. The arithmetic says two.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mcdope
mcdope merged commit bbed706 into master Aug 26, 2026
21 checks passed
@mcdope
mcdope deleted the fix/stale-doc-comments branch August 26, 2026 20:51
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