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

.github/workflows/ci.yml

@@ -45,6 +45,27 @@ jobs:
           sbt pncs/transpile
           git diff --exit-code || (echo "Transpilation produced changes, please commit them." && exit 1)
 
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup JDK
+        uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+
+      - name: Setup SBT
+        uses: sbt/setup-sbt@v1
+
+      # Picks up tools/doccheck/baseline.txt automatically, so this fails only
+      # when a doc snippet that used to compile stops compiling, or when a
+      # baselined snippet starts compiling and the baseline needs shortening.
+      - name: doc code blocks
+        run: sbt "doccheck/run docs/src/content/docs"
+
   lint:
     runs-on: ubuntu-latest
     steps:

CONTRIBUTING.md

@@ -95,6 +95,32 @@ Suites are organized by pipeline stage: `LexerTests`, `ParserTests`,
 new cases to the suite for the stage you changed, and add a test for every bug
 you fix.
 
+## Documentation code blocks
+
+Every ` ```panther ` block under `docs/` is compiled by
+[`doccheck`](tools/doccheck/README.md):
+
+```bash
+sbt "doccheck/run docs/src/content/docs"
+```
+
+Every block currently compiles, and `tools/doccheck/baseline.txt` — the list of
+blocks known not to compile — is empty. Keep it that way: a snippet you add or
+change has to pass.
+
+The check fails in two directions — a snippet that used to compile breaking,
+*and* a baselined snippet starting to compile — so if you ever do need to
+baseline something, regenerate it in the same commit:
+
+```bash
+sbt "doccheck/run --update-baseline docs/src/content/docs"
+```
+
+A snippet that should not be compiled as written gets a directive on the line
+above its fence — `parse-only`, `expect-error`, or `skip reason="..."`. Prefer
+fixing the snippet; see [ROADMAP.md](ROADMAP.md#4-documentation-that-is-checked)
+for the plan to empty the baseline.
+
 ## Commits
 
 Commit messages follow a Conventional-Commits style, with an optional scope
@@ -126,15 +152,20 @@ sbt pncs/transpile
 sbt pncs/compile && sbt test/test && sbt scalafmtCheckAll
 ```
 
+```bash
+sbt "doccheck/run docs/src/content/docs"
+```
+
 Then **commit the regenerated `.pn` files** along with your Scala changes.
 
-The [`ci`](.github/workflows/ci.yml) workflow runs three jobs on every pull
+The [`ci`](.github/workflows/ci.yml) workflow runs four jobs on every pull
 request, all of which must pass:
 
 1. `sbt pncs/compile`, then `sbt test/test`
 2. `sbt pncs/transpile`, then `git diff --exit-code` — this fails if the
    transpiled output in `pnc/src/` is out of sync with the Scala sources
-3. `sbt scalafmtCheckAll`
+3. `doccheck` against its baseline
+4. `sbt scalafmtCheckAll`
 
 For the pull request itself:
 

README.md

@@ -55,6 +55,10 @@ sbt "pncs/run --help"
 sbt "pncs/run output.pnb source.pn"
 ```
 
+Note that the output path is not honoured yet: the emitter builds the chunk and
+metadata in memory and nothing is written to disk, so no `output.pnb` appears.
+See [ROADMAP.md](ROADMAP.md#31-write-and-read-pnb).
+
 ### Regenerating the Panther sources
 
 Any change to the Scala sources must be transpiled and the result committed —
@@ -64,14 +68,18 @@ CI checks that `pnc/src/` is in sync.
 sbt pncs/transpile
 ```
 
-### Commands that are expected to fail
+### Commands that do not work yet
 
-Self-hosting is not finished yet, so these do not currently succeed:
+Self-hosting is not finished, so these do not produce a working compiler:
 
-- `sbt compile` (fails in the `pnc/compile` step — use `sbt pncs/compile`)
-- `sbt pnc/compile`
+- `sbt compile` (use `sbt pncs/compile`)
+- `sbt pnc/compile` — reports 1058 diagnostics against the generated `.pn`
+  sources. It still *exits zero*, because the compiler does not set a failure
+  exit code; read the diagnostic count, not the exit status.
 - `sbt pncs/bootstrap`
 
+[ROADMAP.md](ROADMAP.md#1-self-hosting) tracks what is left.
+
 ### Scripts
 
 `scripts/` holds cross-platform PowerShell wrappers around the same sbt tasks:
@@ -89,6 +97,7 @@ Self-hosting is not finished yet, so these do not currently succeed:
 | `text/`     | Text processing library                                                     |
 | `test/`     | ScalaTest suites plus shared helpers                                        |
 | `docs/`     | Astro/Starlight documentation site                                          |
+| `tools/`    | Development tooling — currently `doccheck`, the doc code-block checker      |
 | `scripts/`  | Cross-platform PowerShell wrappers around the sbt tasks                     |
 
 Entry points: [`pncs/src/main/scala/Program.scala`](pncs/src/main/scala/Program.scala)
@@ -106,6 +115,22 @@ pnpm --dir docs install && pnpm --dir docs dev
 `docs_old/` is the previous mdbook-based site, kept for reference. New
 documentation goes in `docs/`.
 
+Every ` ```panther ` block in the docs is checked against the compiler by
+[`doccheck`](tools/doccheck/README.md):
+
+```sh
+sbt "doccheck/run docs/src/content/docs"
+```
+
+Every block currently compiles, and `tools/doccheck/baseline.txt` — the list of
+known-broken blocks — is empty, so CI fails if that stops being true.
+
+## Roadmap
+
+[ROADMAP.md](ROADMAP.md) covers the three things being worked toward —
+self-hosting, generics, and runnable sample programs — with the current
+measurements for each.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the development loop, the invariants