C64-dev/newLang/planning/claims/E02-S04.md

---

story: E02-S04 owner: e02_diagnostics status: done started: 2026-11-07 depends-on: [E01-S03, E00-S02]

E02-S04 Claim

Intended change

Add the stable diagnostic catalog (src/common/diagcat.inc, one line per diagnostic, included as constants and as messages), src/common/errors.inc, and src/compiler/diagnostics.s, which prints the 40-column screen form and writes NAME.ERR, with a default limit of 20 errors. Extend diskio.s with output-file and DOS-command wrappers.

File area

• src/common/diagcat.inc, src/common/errors.inc, src/common/diskio.inc
• src/compiler/diagnostics.s, src/compiler/diskio.s
• tests/diag/
• scripts/build-diag-test.ps1, scripts/verify-diag-test.ps1, scripts/lib/Nova128Test.psm1
• docs/diagnostics.md (generated from the catalog), docs/architecture.md
• planning/claims/E02-S04.md
• generated files under build/

Acceptance evidence

• Lexical, syntax, type, access, interface, disk, and resource categories have stable IDs: 33 diagnostics in src/common/diagcat.inc across nine category ranges; the build rejects out-of-range, duplicate, or reused numbers and any grammar .expect symbol missing from the catalog.
• Screen form fits 40 columns for representative diagnostics: x128 screen RAM shows each diagnostic as a header row and a message row, all at most 39 characters, including the longest message, a clipped two-argument message, and the widest header (E023 DIAG.N8 65535 255).
• ERR output contains source, line, column, code, and message: diag.err read back from the D81 equals the expected six lines exactly; a stale diag.err was replaced and a stale clean.err was scratched when no diagnostics occurred.
• Error limiting defaults to 20 and terminates cleanly: 25 reports give carry 0 x20 then 1 x5; limit.err holds 20 errors plus E221; no files are left open after any phase. An unwritable ERR name (DOS 33) shows E201 once and leaves no file. A mutation that stops counting is caught.

Coordination notes

The grammar fixtures’ symbolic .expect names become catalog symbols unchanged. Later stories append diagnostics within their category range.

Work log

• The first x128 run showed garbage before every message: find_message clobbered X, the formatter's buffer index. Fixed; found by dumping screen RAM and the format buffer.
• c1541 -read needs name,s for SEQ files.
• The ERR width check uses spec limits (15-character source name, line <= 599, column <= 81), so the longest ERR line is 77 characters.

Completion

• Tests run: scripts/verify-diag-test.ps1 (pass plus counting mutation).
• Results: result block, 19 screen rows, diag.err, limit.err, and the directory all match expectations.
• Files changed: src/common/diagcat.inc, src/common/errors.inc, src/common/diskio.inc, src/common/c128.inc (CHKOUT), src/compiler/diagnostics.s, src/compiler/diskio.s, tests/diag/, scripts/build-diag-test.ps1, scripts/verify-diag-test.ps1, docs/diagnostics.md, docs/architecture.md, tests/grammar/README.md, this claim.
• Remaining risks: later stories will append diagnostics, and their wording should be reviewed by the user; the 80-column display path was not exercised here (E01-S04 covers KERNAL output in both modes); a disk that fills up while NAME.ERR is being written is not tested.