Add ROADMAP, a documentation code-block checker, and fix the docs it found broken

[kthompson]

Adds a ROADMAP grounded in measurements, a tool that checks the documentation against the compiler, and the documentation fixes that tool demanded.

Why

The three stated goals — self-hosting, generics, usable sample programs — needed a plan based on what the compiler actually does rather than on estimates. Measuring that turned up more than expected, so this PR is the roadmap plus the first item burned down.

What changed

tools/doccheck/ — a new sbt project. Extracts every ```panther block from the markdown and runs it through the real pncs front end. Blocks take directives in an HTML comment above the fence (parse-only, expect-error, skip reason="..."), which renderers drop. A malformed directive is reported rather than ignored, so a typo cannot quietly disable checking. tools/doccheck/baseline.txt records known-broken blocks and is picked up automatically; the check fails both when a passing snippet breaks and when a baselined snippet starts passing, so the list cannot go stale. Wired in as a fourth CI job.

The documentation now compiles: 157 failing → 0.

200 blocks: 198 ok, 0 failing, 2 skipped

The baseline is empty, so CI enforces a clean run. Corrections were systematic, not scattered typos:

Docs said	Panther accepts
Array<Int>, Option<User>	Array[int], Option[User]
Int, String, Bool	int, string, bool
fun f(): T { return x }	def f(): T = x
for (item in items)	for (i <- 0 to n)
match (x) { 1 => .. }	x match { case 1 => .. }
"n: " + count	"n: " + string(count)

ROADMAP.md — every number is measured and every command reproduces it.

What the measurements found

Worth a reviewer's attention; these are the reason the roadmap is ordered the way it is.

• sbt pnc/compile reports 1058 diagnostics, and 685 mention an unsolved type variable — which is why generic inference leads the plan over everything else.
• Nothing is ever written to disk. Compilation.emit(output) ignores its argument and Emitter.emit() returns in-memory structures. The documented pncs output.pnb source.pn produces no file, there is no .pnb reader, and no CLI path to the working Compilation.exec(). This is what blocks sample programs.
• The compiler never exits non-zero — pnc/compile "succeeds" with 1058 errors.
• pnc/src/ast.pn and printer.pn are stale; transpile now emits Ast.pn/AstPrinter.pn instead. CI cannot see this because git diff --exit-code ignores untracked files. Accounts for 32 of the duplicate-definition diagnostics.
• in/out variance keywords are inverted in both the transpiler and the binder relative to Variance.scala's own comments. The two inversions cancel, so nothing breaks until someone hand-writes [out T].

Fixing the docs surfaced nine further gaps, all verified against the compiler:

• val is not enforced — val x = 10; x = 20 compiles with zero diagnostics. The docs promised an error that never happens; that prose is now corrected.
• break/continue crash the compiler — they parse, then boundErrorStatement calls panic().
• No return, no compound assignment, no pattern guards/alternation/tuples, no nested functions; decimal literals do not lex; block comments do not nest.

Reviewer notes

• functions/higher-order-functions.md was rewritten, not fixed. It was 275 lines teaching lambdas. Lambdas, function-typed parameters, and nested def all fail to parse, so higher-order functions do not exist in any form. It is now a short page that says so and shows the workarounds. Its two skip blocks are the only skips in the tree. This is a content decision worth a second opinion.
• guides/ still duplicates the topic directories. I fixed it in place rather than deleting it — that call is yours. Noted in the roadmap.
• A checker limitation shapes the docs today. Option, Result, List, and Dictionary are not builtins (only int, string, bool, char, unit, Array are), so a single-block compilation cannot mention Option. Blocks had to work around it. Compiling each block alongside the runtime .pn sources would fix it; it is the top item under ROADMAP §4.4 and deliberately not in this PR.
• Commits are meant to be read in order; the tool commit alone predates the doc fixes.
• No compiler source changed, so pnc/src/ needed no regeneration and the transpile-sync invariant is untouched.

Verification

• sbt test/test — 246/246
• sbt scalafmtCheckAll — clean
• sbt "doccheck/run docs/src/content/docs" — 0 failing
• check-primitives-map.mjs — 15 primitives, 4 invariants, all paths resolve
• Line endings preserved: 17 CRLF doc files unchanged

🤖 Generated with Claude Code

System recap — adds a new primitive (high risk)

Mode: recap · Base: main @ 1bdb118 · Head: a2b1309

Classification: adds — a new doc-check primitive (the doccheck sbt project and its CI job) plus a full rewrite of the language docs. No compiler source is touched, so no pipeline stage changes behaviour.

Primitives touched

Primitive	Group	Impact
doc-check	quality	adds — new sbt project, CLI, baseline, and CI job; new entry in primitives.yaml
language-docs	quality	extends — 16 pages rewritten; every block now compiles
visual-recap-tooling	quality	composes — taxonomy gains the doc-check entry
transpiler	tooling	composes — build.sbt gains the doccheck project; transpile/bootstrap tasks untouched

System map

A new checker compiles documentation snippets through the existing compiler front end; the docs are the input, CI is the gate, and no compiler stage is modified.

Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).

flowchart LR
	languageDocs["language-docs<br/>Panther language docs"]:::extended
	docCheck["doc-check<br/>Documentation code-block checker"]:::added
	lexer["lexer<br/>Lexer & tokens"]:::untouched
	parser["parser<br/>Parser & syntax tree"]:::untouched
	binder["binder<br/>Binder & type inference"]:::untouched
	transpiler["transpiler<br/>Build & sbt tasks"]:::touched
	languageDocs -->|"extracted panther blocks + check directives"| docCheck
	docCheck -->|"SourceFile per block"| lexer
	lexer -->|"token stream"| parser
	parser -->|"SyntaxTree via MakeSyntaxTree"| binder
	binder -->|"Diagnostics, rebased onto markdown line numbers"| docCheck
	transpiler -->|"new doccheck project + CI job"| docCheck
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Change flow

sequenceDiagram
	participant CI
	participant DC as DocCheck
	participant MS as MarkdownScanner
	participant BC as BlockChecker
	participant PC as pncs front end
	CI->>DC: doccheck/run docs/src/content/docs
	DC->>MS: scan each .md/.mdx
	MS-->>DC: DocBlock(id, code, directive)
	loop per block
		DC->>BC: check(block, Bind)
		BC->>PC: parseSourceFile + MakeCompilation.create
		PC-->>BC: Diagnostics (or a thrown panic)
		BC-->>DC: Ok / Failed / Crashed / Skipped
	end
	DC->>DC: compare against baseline.txt
	DC-->>CI: exit 0 (no new failures) or 1

Loading

Before / after

before:  215 blocks: 58 ok, 157 failing, 0 skipped   (4 crash the compiler)
after:   200 blocks: 198 ok, 0 failing, 2 skipped    (baseline.txt empty)

CI gains a fourth job:

Job	Command
docs (new)	sbt "doccheck/run docs/src/content/docs"

Invariants

• transpile-sync — not affected. No file under pncs/, runtime/, metadata/, or text/ changed, so pnc/src/ needed no regeneration.
• pncs-is-canonical — respected; pnc/src/ is untouched.
• diagnostics-not-exceptions — violations documented, not fixed. "text " + int and break/continue still panic() instead of reporting. The checker now reports these as CRASH rather than a plain failure; ROADMAP §4.2 tracks the fix.