GeezerVison

Clean-code review

I audited the diff with the clean-code-principles checklist.

Fixed:

• [core-dry] Code.of(receiver) was repeated about ten times in StateHints. It is now one field, shownReceiver; only the static decidingArgument marks it inline.
• [solid-srp] Marking (Code.of) and rendering (Code.render) sit in one small class. Producers only mark, and only LJDiagnostic.toString renders, so no producer knows about ANSI.
• [testability] Code.render(message, colour) takes the colour flag as a package-visible overload, so CodeTest covers colour on and off without depending on the console.

Declined:

• [solid-ocp] Structured segments instead of backticks. The PM chose backticks in the string (rustc style), which keeps plain-text clients working unchanged.
• [core-dry] SourceReference.message repeats the note text. It is what ties a reference to its line for a client, and each reference carries exactly one line, so I kept it rather than index into getMessageNotes() (where RefinementError puts alias lines first).
• [func-few-arguments] SourceReference has 5 components. They are the minimum a client needs to find the words and open the place.

Codex review, round 1

codex exec review:

[P2] Preserve whitespace inside code spans. Code.render(Code.of(" x "), true) shows x: the trim can't tell Code.of's padding from the code's own spaces.

Soundness prompt. It found three issues:

1. Unmarked code in not-found errors: Alias 'Positiv' could not be found, Did you mean 'Positive'?.
2. Code.render edge cases:
   • " a " loses its spaces;
   • multi-line code and empty code stay fenced;
   • two spans written back to back ( `ab` ``) are read as one;
   • backticked prose outside Code.of is coloured.
3. A reference's words occurring twice: Origin: line 18, d.lock("line 18") makes ….

Fixed in "Keep the spaces of code, name where a reference starts, mark names not found":

• render strips the padding only when Code.of added it, that is when the inner code starts or ends with a backtick. " a " keeps its spaces. Spans now match across line breaks.
• SourceReference gains start, the index of text in message. The deciding-argument hint computes it from how the message is built, so a call whose code holds line 20 cannot mislead a client. Origin notes start their reference right after Origin: .
• NotFoundError marks the missing name and the suggestion.
• Tests: CodeTest covers spaces and line breaks, and both reference checks assert start.

Declined:

• Empty code. No message builds an empty code span.
• Two spans back to back, and backticks in prose. Code.of never puts two spans side by side without words between them, and none of the verifier's message text has backticks of its own.

The study tasks are byte-identical to the previous commit. Tests: 740 run, 0 failures.

Codex review, round 2

codex exec review: "I found no actionable regressions in the changed code."

Soundness prompt. It found no verifier program with code left unmarked, prose marked, or a wrong reference. It reported three direct Code strings:

1. **" ":** Code.ofgave ``` `` `` ```, and render dropped the code's own spaces. The padding rule was ambiguous for code that starts and ends with a space and also holds a backtick.
2. Code.of("a") + Code.of("b"): two spans with nothing between them read as one.
3. Code.of(""): empty code stays fenced.

Fixed (1) in "Pad code that holds a backtick or ends with a space, so render keeps it exact". Code.of pads with one space on each side whenever the code holds a backtick or starts or ends with a space, and render strips exactly one space on each side when both are there. The round trip is now exact for every non-empty code; " ", " x "and" x "are checked, andCodeTestcovers" ".

Declined (2) and (3). No message builds an empty span or puts two spans side by side without words between them: every template separates its spans with prose or , . Supporting them would need a real lexer for a case that cannot occur.

The study tasks are byte-identical. Tests: 740 run, 0 failures.

Codex review, round 3

codex exec review: "I found no actionable regressions in the diff."

Soundness prompt: it found no Code.render mismatch and no wrong SourceReference. It found unmarked code in three spec-declaration diagnostics built in TypeChecker:

• State set name 'Door' must be an identifier that starts with a lowercase letter;
• State 'ready' is in two state sets of DuplicateState: phase and access;
• State set name 'undo' is also the name of a method of SetMethodCollision, so undo(x) == ready reads like a call to undo()… (warning).

Declined for this PR, as a follow-up. #532 lists headlines, hints, origin notes, the gloss and counterexamples, the messages a participant reads when a call or value is wrong. These three report mistakes in the specification itself. They go through CustomError/CustomWarning, whose text LJDiagnostic.toString already renders, so marking them later is a change to their strings only. I'll list them, with the other error kinds (state conflicts, syntax), as a follow-up for the PM.

This ends the Codex loop for this PR: nothing relevant to #532's scope is left.