nescript/compiler-bugs.md

// compiler-bugs.md — a running log of compiler issues surfaced
// while implementing the Pong example (examples/pong.ne et al).
//
// Format, one entry per bug:
//
// ## #N — one-line title
//
// **Status**: OPEN / WORKED-AROUND / FIXED
// **Phase**:   lexer / parser / analyzer / ir / optimizer / codegen / linker / runtime / asset
// **Surfaced in**: examples/pong/<file>.ne (brief context)
//
// ### Reproducer
// ```ne
// ... minimal .ne snippet that triggers the bad behaviour ...
// ```
//
// ### Expected vs actual
// What the user-visible behaviour should be; what the compiler actually does.
//
// ### Workaround (if applied)
// The current shape of the code in examples/pong/ that avoids the bug,
// and exactly what should be reverted once the fix lands. Every workaround
// in examples/pong/ MUST be tagged with `// BUG: compiler-bugs.md #N` so
// grep -r "BUG: compiler-bugs.md" finds every reverible workaround in one pass.
//
// ### Guess at the fix
// Which source file(s) and what kind of change is likely needed. Doesn't
// have to be right — it's a hint for the compiler-bug cleanup milestone.
//
// ---

(no bugs logged yet — pong development just started)
examples/pong: production-quality Pong game with powerups and multi-ball A complete, playable Pong game split across examples/pong/.ne files and pulled in from a top-level examples/pong.ne. Features: - Title screen* with a 3-option menu (CPU VS CPU / 1 PLAYER / 2 PLAYERS), a cursor sprite, blinking "PRESS A" prompt, brisk title march on pulse 2, and autopilot that auto-confirms CPU VS CPU after 45 frames of no input so the headless jsnes golden harness reaches gameplay by frame 180. - Ball physics with signed-magnitude velocity (u8 magnitude + sign bit per axis), wall bounce at top/bottom, paddle AABB collision with push-out, and score-out detection at left/right exits. - Multi-ball via parallel ball_* arrays (MAX_BALLS = 3). Each ball scores a point independently; the round continues until the last ball exits the playfield. - CPU AI that tracks the nearest active ball heading toward its side with a per-frame step, 4 px dead zone, and CPU_SPEED = 1 so rallies can end naturally. - Three powerup types that spawn every ~4 seconds, bounce off all four walls, and are caught by paddle AABB overlap: 1. LONG — extends the catching paddle from 24 → 40 px for 5 hits 2. FAST — doubles ball x-velocity on the catcher's next hit 3. MULTI — spawns two extra balls on the catcher's next hit - Victory at first-to-7 with a "PLAYER N WINS" banner and the builtin fanfare, auto-returning to Title. - Audio: 5 user-declared sfx (WallBounce, PaddleHit, Score, PowerSpawn, PowerCatch) plus a title march and the builtin fanfare for victory. Source layout mirrors examples/war: examples/pong.ne top-level game shell examples/pong/PLAN.md living design doc examples/pong/constants.ne layout + gameplay constants examples/pong/assets.ne 45-tile Tileset (paddles, ball, alphabet, digits, cursor, center-line, powerup icons) examples/pong/audio.ne sfx + music declarations examples/pong/state.ne all mutable globals examples/pong/rng.ne 8-bit Galois LFSR examples/pong/render.ne draw helpers examples/pong/input.ne paddle step (human + CPU AI) examples/pong/ball.ne multi-ball physics + paddle collision examples/pong/powerup.ne powerup entity (spawn, bounce, catch, apply) examples/pong/title_state.ne state Title + menu examples/pong/play_state.ne state Playing (P_SERVE/P_PLAY/P_POINT) examples/pong/victory_state.ne state Victory Verification: - 616 compiler unit tests pass (cargo test --all-targets) - cargo fmt / cargo clippy --all-targets -- -D warnings clean - 33/33 emulator harness goldens match - examples/pong.nes builds byte-identically from source https://claude.ai/code/session_0134F5uwDEVTes2Ee9S7JeXy 2026-04-16 01:25:29 +00:00			`// compiler-bugs.md — a running log of compiler issues surfaced`
			`// while implementing the Pong example (examples/pong.ne et al).`
			`//`
			`// Format, one entry per bug:`
			`//`
			`// ## #N — one-line title`
			`//`
			`// Status: OPEN / WORKED-AROUND / FIXED`
			`// Phase: lexer / parser / analyzer / ir / optimizer / codegen / linker / runtime / asset`
			`// Surfaced in: examples/pong/<file>.ne (brief context)`
			`//`
			`// ### Reproducer`
			// ```ne
			`// ... minimal .ne snippet that triggers the bad behaviour ...`
			// ```
			`//`
			`// ### Expected vs actual`
			`// What the user-visible behaviour should be; what the compiler actually does.`
			`//`
			`// ### Workaround (if applied)`
			`// The current shape of the code in examples/pong/ that avoids the bug,`
			`// and exactly what should be reverted once the fix lands. Every workaround`
			// in examples/pong/ MUST be tagged with `// BUG: compiler-bugs.md #N` so
			`// grep -r "BUG: compiler-bugs.md" finds every reverible workaround in one pass.`
			`//`
			`// ### Guess at the fix`
			`// Which source file(s) and what kind of change is likely needed. Doesn't`
			`// have to be right — it's a hint for the compiler-bug cleanup milestone.`
			`//`
			`// ---`

			`(no bugs logged yet — pong development just started)`