feat: move corpus to library
Test / test (push) Failing after 1m38s

This commit is contained in:
alexm committed 2026-10-06 10:27:46 -04:00
1 parent 5b8b079165
commit cae5cff55a
1350 files changed
+197 -941995

No files matched your search

+1 -1
View File
@@ -1,6 +1,6 @@
# The model machine against compiled Mojo
"Open in Hardware" puts a function from the real compiler's listing on the model machine (`src/engines/asm86`), translated from godbolt's AT&T syntax by `src/mojo/att.ts`. The machine implements a teaching subset of x86-64, so the question is how much of what the Mojo compiler actually emits it can take. This is the census: every function in every listing the corpus holds (`mojo/golden/*.json` answered with `asm`), sent exactly as the button sends it, and what the assembler said. `node scripts/asm-census.mjs` reruns it (add `--ops` for every mnemonic); `tests/asm-coverage.test.mjs` holds the numbers as a ratchet, so a new corpus item that brings a new instruction fails the build rather than a student's session.
"Open in Hardware" puts a function from the real compiler's listing on the model machine (`src/engines/asm86`), translated from godbolt's AT&T syntax by `src/mojo/att.ts`. The machine implements a teaching subset of x86-64, so the question is how much of what the Mojo compiler actually emits it can take. This is the census: every function in every listing the corpus holds (`library/mojo/golden/*.json` answered with `asm`), sent exactly as the button sends it, and what the assembler said. `node scripts/asm-census.mjs` reruns it (add `--ops` for every mnemonic); `tests/asm-coverage.test.mjs` holds the numbers as a ratchet, so a new corpus item that brings a new instruction fails the build rather than a student's session.
## Where it stands
+2 -2
View File
@@ -43,10 +43,10 @@ The numerical built-ins (`HYPOT`, `EXPM1`, `LOG1P`, `FMA`, `ULP`, `NEXT_AFTER`,
A "proved" must be a proof. Two test files hold the prover to that, and a change to `logic.ts`, `solver.ts` or `vcgen.ts` must keep both green:
- `tests/prover-soundness.test.mjs`: every regression program in `tests/prover/` names, in a `// MUST-NOT-PROVE: <kind>@<line>` header, an obligation that a run breaks and that an unsound rule once proved; it may never be proved again, and the program must still break it. A program whose fix was to the language names where its run now stops, `// RUN-STOPS: <kind>@<line>`. Across every exercise, corpus program, lesson solution and example, nothing marked proved may be broken by the fuzzer or by running the program, and `ASSERT 1 == 2` appended to a program that runs to its end may never be proved.
- `tests/prover-soundness.test.mjs`: every regression program in `library/pseudo/prover/` names, in a `// MUST-NOT-PROVE: <kind>@<line>` header, an obligation that a run breaks and that an unsound rule once proved; it may never be proved again, and the program must still break it. A program whose fix was to the language names where its run now stops, `// RUN-STOPS: <kind>@<line>`. Across every exercise, corpus program, lesson solution and example, nothing marked proved may be broken by the fuzzer or by running the program, and `ASSERT 1 == 2` appended to a program that runs to its end may never be proved.
- `tests/engine-solver.test.mjs`: a table of goals the solver must prove and goals it must leave unknown, 400 random linear integer formulas checked against every small assignment, and obligations from small programs.
When a soundness bug is found, add the program that shows it to `tests/prover/` first, watch the test fail, then fix the rule. The bugs found so far, each with its program:
When a soundness bug is found, add the program that shows it to `library/pseudo/prover/` first, watch the test fail, then fix the rule. The bugs found so far, each with its program:
| Program | Rule | Fix |
|---|---|---|
+3 -3
View File
@@ -7,11 +7,11 @@ There are two ways to start one.
## An exercise around a Mojo program
```bash
pixi run new-exercise rolling-sum # mojo/local/rolling-sum.mojo, src/exercises/rolling-sum.ts, registered
pixi run new-exercise rolling-sum # library/mojo/local/rolling-sum.mojo, src/exercises/rolling-sum.ts, registered
pixi run play rolling-sum # after each edit: run, verify on godbolt, build, list the assembly, test
```
For a title or a home-page section other than the defaults, run the script directly: `node scripts/new-exercise.mjs rolling-sum --title "Rolling sum" --group "Loop forms"`. If `mojo/local/rolling-sum.mojo` already exists, it is kept as written and only the exercise is made.
For a title or a home-page section other than the defaults, run the script directly: `node scripts/new-exercise.mjs rolling-sum --title "Rolling sum" --group "Loop forms"`. If `library/mojo/local/rolling-sum.mojo` already exists, it is kept as written and only the exercise is made.
The exercise names its program (`mojoProgram: 'rolling-sum'`) instead of carrying the source. The Mojo pane shows the file without its header comments, and badges it "verified on Mojo 1.1.0" only when godbolt's answer for that exact source passed the file's own `# expect-stdout:` lines. Editing the file changes its key, so it reads as unverified until `play` (or `mojo-verify`) asks again. The header keys are in [mojo-corpus.md](mojo-corpus.md#mojo-of-our-own).
@@ -29,7 +29,7 @@ Copy `src/exercises/_template.ts` to `<id>.ts`, fill it in, import it in `src/ex
| `title`, `group`, `blurb` | The name, the home-page section it files under (a new name makes a new section), and one or two sentences on what the student does |
| `meta` | Optional: `lecture`, `level` (`intro`, `core`, `advanced`), `tags`, `concepts`, `minutes`, `page` (where it is taught) |
| `sources` | Any of `lingo`, `pseudo`, `matho`, `speco`, `asm`. Pseudo is derived from lingo (or matho, written in LaTeX) when absent, and speco from the pseudo's inline contracts |
| `mojoProgram` | The name of a program in `mojo/local/`, shown in the Mojo pane |
| `mojoProgram` | The name of a program in `library/mojo/local/`, shown in the Mojo pane |
| `call`, `expect` | The call to run, and what it should return; the tests compare them |
| `setup`, `machine` | For assembly: the setup block (registers and memory before the run) and the machine model preset |
| `lang` | The pane that opens first |
+1 -1
View File
@@ -1,6 +1,6 @@
# The library
pplus-library (the submodule `library/`) holds routines written once in pseudo and checked at every level, so a program can use them by name instead of rewriting and re-verifying them, and a learner can open any of them to see exactly what it does. Core reads it through a generated registry (`src/library/generated.ts`, `pixi run library-emit`), so the site needs no files at run time.
pplus-library (the submodule `library/`) is the ground truth of Programming+: besides the routines this document is about, it holds the Mojo corpus (`library/mojo/`, see [mojo-corpus.md](mojo-corpus.md)) and the pseudo regression and soundness programs (`library/pseudo/`). Its routines are written once in pseudo and checked at every level, so a program can use them by name instead of rewriting and re-verifying them, and a learner can open any of them to see exactly what it does. Core reads it through a generated registry (`src/library/generated.ts`, `pixi run library-emit`), so the site needs no files at run time.
## Using a routine
+21 -19
View File
@@ -4,21 +4,23 @@ Programming+ teaches what Mojo does when it runs, so everything it says about Mo
Every command below is a pixi task; the [README](../README.md#commands) lists them all.
The corpus itself (the pin, the harvested material, our programs and godbolt's answers) lives in pplus-library, the submodule `library/`, under `library/mojo/`; the pipeline that builds and checks it (`scripts/mojo/`) and what it generates for the app (`src/mojo/generated/`) live here. A task that changes the corpus leaves changes in both repositories: commit and push `library/` first, then commit core with the new pointer (`git add library`) and the regenerated files.
## Mojo of our own
There are three kinds of Mojo program we write, and each has a folder, a task to start one, and a job:
| Kind | Folder | Start one | Its job | Shipped in the app |
|---|---|---|---|---|
| probe | `mojo/probes/` | `pixi run new-probe <name> "<question>"` | Ask the pinned compiler one question (what does `//` do on a negative Int?). Godbolt's answer is the point; it is recorded, not judged. | no, but the checker and interpreter are held to the answers |
| exercise program | `mojo/local/` | `pixi run new-exercise <id>` | The Mojo of a catalog problem. It must pass its own `# expect-stdout:` lines. | yes, in `src/mojo/generated/programs.ts`, badged verified when it passed |
| stress program | `mojo/stress/` | `pixi run new-stress <name> "<what it exercises>"` | Realistic Mojo that stresses the interpreter. Its `# expect-stdout:` lines are the interpreter's prediction; godbolt confirms or refutes it. | no |
| probe | `library/mojo/probes/` | `pixi run new-probe <name> "<question>"` | Ask the pinned compiler one question (what does `//` do on a negative Int?). Godbolt's answer is the point; it is recorded, not judged. | no, but the checker and interpreter are held to the answers |
| exercise program | `library/mojo/local/` | `pixi run new-exercise <id>` | The Mojo of a catalog problem. It must pass its own `# expect-stdout:` lines. | yes, in `src/mojo/generated/programs.ts`, badged verified when it passed |
| stress program | `library/mojo/stress/` | `pixi run new-stress <name> "<what it exercises>"` | Realistic Mojo that stresses the interpreter. Its `# expect-stdout:` lines are the interpreter's prediction; godbolt confirms or refutes it. | no |
The loop is the same for all three:
```bash
pixi run new-probe int-floordiv-negative "does // floor toward negative infinity on Int?"
# edit mojo/probes/int-floordiv-negative.mojo
# edit library/mojo/probes/int-floordiv-negative.mojo
pixi run mojo-verify-item 'probes/int-floordiv-negative' # ask godbolt (network)
pixi run test # the checker and interpreter scoreboards read the new answer
```
@@ -59,7 +61,7 @@ Header lines (`# probe:`, `# mode:`, …) are for `verify`; only those keys are
## Reading the status
`pixi run mojo-status` judges every item from the stored answers, offline, and writes `mojo/golden/STATUS.md` (a table per corpus, every failure with its reason, and every probe's question and verdict) and `status.json` (`git diff mojo/golden/status.json` shows exactly what changed).
`pixi run mojo-status` judges every item from the stored answers, offline, and writes `library/mojo/golden/STATUS.md` (a table per corpus, every failure with its reason, and every probe's question and verdict) and `status.json` (`git -C library diff mojo/golden/status.json` shows exactly what changed).
Each item says what the pinned compiler should do with it: `pass` (compiles, runs, exits 0, and prints what it should or contains the idiom it should), `fail` (that check must not hold: a starter), `compile-error` (must be rejected, with each expected error at its line), `observe` (a probe: the answer is the point), or `skip` (with a reason: newer syntax than the pin, no `main`, not reproducible on public godbolt). Verdicts are `pass`, `fail`, `observed`, `skipped`, and `unverified` (no golden yet).
@@ -71,17 +73,17 @@ The dialect markers in the pin are a cheap first look: `newer` patterns are synt
| Path | What it is | Who writes it |
|---|---|---|
| `mojo/pin.json` | The Mojo version, the godbolt compiler id, each source repository and the ref to use, and the dialect markers | You |
| `mojo/mojo.lock.json` | What each ref resolved to: commit, zip sha256, and the directory inside the zip | `fetch`/`harvest` |
| `mojo/corpus/` | Processed material, one directory per processor, each item with its provenance | `harvest` |
| `mojo/corpus/SOURCES.md` | Which commit and license everything came from, what each processor found, every warning | `harvest` |
| `mojo/probes/` | Our questions about the pinned compiler's behavior, one small program each | You (`new-probe`) |
| `mojo/local/` | Exercise programs, shipped in the app | You (`new-exercise`) |
| `mojo/stress/` | Realistic programs that test the interpreter, not shipped | You (`new-stress`) |
| `mojo/golden/<key>.json` | Godbolt's answer for one program, keyed by compiler, mode, arguments, stdin and source | `verify` |
| `mojo/golden/STATUS.md` | Every item's verdict against the goldens | `status` (also `harvest`, `verify`) |
| `src/mojo/generated/` | What the app reads at run time: `pin.ts` (version, compiler), `tokens.ts` (the words, removed words and the compiler's messages for them), `editor.ts` (comment and indentation rules), `programs.ts` (`mojo/local/` programs with their verdicts), `stdlib.ts` and `types.ts` (which package exports each name, which types are copyable), and `listings.ts` (exercise listings, written by `scripts/mojo/listings.mjs` during `play`) | `harvest`/`emit`; `verify` and `status` refresh `programs.ts` |
| `syntax/mojo.xml` | The same words as a KDE syntax for Pandoc listings (pplus-web copies it into its Quarto extension with its quarto-css task) | `harvest`/`emit` |
| `library/mojo/pin.json` | The Mojo version, the godbolt compiler id, each source repository and the ref to use, and the dialect markers | You |
| `library/mojo/mojo.lock.json` | What each ref resolved to: commit, zip sha256, and the directory inside the zip | `fetch`/`harvest` |
| `library/mojo/corpus/` | Processed material, one directory per processor, each item with its provenance | `harvest` |
| `library/mojo/corpus/SOURCES.md` | Which commit and license everything came from, what each processor found, every warning | `harvest` |
| `library/mojo/probes/` | Our questions about the pinned compiler's behavior, one small program each | You (`new-probe`) |
| `library/mojo/local/` | Exercise programs, shipped in the app | You (`new-exercise`) |
| `library/mojo/stress/` | Realistic programs that test the interpreter, not shipped | You (`new-stress`) |
| `library/mojo/golden/<key>.json` | Godbolt's answer for one program, keyed by compiler, mode, arguments, stdin and source | `verify` |
| `library/mojo/golden/STATUS.md` | Every item's verdict against the goldens | `status` (also `harvest`, `verify`) |
| `src/mojo/generated/` | What the app reads at run time: `pin.ts` (version, compiler), `tokens.ts` (the words, removed words and the compiler's messages for them), `editor.ts` (comment and indentation rules), `programs.ts` (`library/mojo/local/` programs with their verdicts), `stdlib.ts` and `types.ts` (which package exports each name, which types are copyable), and `listings.ts` (exercise listings, written by `scripts/mojo/listings.mjs` during `play`) | `harvest`/`emit`; `verify` and `status` refresh `programs.ts` |
| `library/syntax/mojo.xml` | The same words as a KDE syntax for Pandoc listings (pplus-web copies it into its Quarto extension with its quarto-css task) | `harvest`/`emit` |
Commit all of it. The stored answers are what make `pixi run test` and `mojo-status` work offline.
@@ -116,11 +118,11 @@ A processor whose input files are missing at the pinned ref is skipped with a wa
## Moving to a new Mojo version
1. Find the release. Mojo releases are tagged `mojo/vX.Y.Z` in `modular/modular` (the platform's own tags are `modular/vX.Y`). Find godbolt's compiler id for it, `mojo_X_Y_Z`, in `https://godbolt.org/api/compilers/mojo`.
2. Edit `mojo/pin.json`: `mojo.version`, `godbolt.compiler`, and `sources.modular.ref`. Move the other refs to the commits that match: Mojo Quest's commit whose `src/lib/compile.ts` names the new compiler id; the vscode-mojo, mojo-syntax and skills commits released alongside it.
2. Edit `library/mojo/pin.json`: `mojo.version`, `godbolt.compiler`, and `sources.modular.ref`. Move the other refs to the commits that match: Mojo Quest's commit whose `src/lib/compile.ts` names the new compiler id; the vscode-mojo, mojo-syntax and skills commits released alongside it.
3. Review the dialect markers against the new release notes. Anything in the notes' **Removed** or **Language changes** sections belongs in `older`; anything in `newer` that this release now includes comes out. (`newer` matters only when harvesting a snapshot past a release.)
4. `pixi run mojo-harvest`, then read `mojo/corpus/SOURCES.md`: every warning is something to look at, and a `release` line saying `snapshot newer` means the ref is not the release tag.
4. `pixi run mojo-harvest`, then read `library/mojo/corpus/SOURCES.md`: every warning is something to look at, and a `release` line saying `snapshot newer` means the ref is not the release tag.
5. `pixi run mojo-verify`. A new compiler id changes every key, so every item is asked again: about 440 requests, two at a time. Run it once, not in a loop; the public server is shared.
6. `pixi run mojo-status`, then read `mojo/golden/STATUS.md`. `git diff mojo/golden/status.json` shows exactly which verdicts and probe answers changed between versions. A changed probe answer is a change Programming+'s Mojo engine has to make; a failing Mojo Quest solution or manual sample usually means a language change the markers should know about.
6. `pixi run mojo-status`, then read `library/mojo/golden/STATUS.md`. `git -C library diff mojo/golden/status.json` shows exactly which verdicts and probe answers changed between versions. A changed probe answer is a change Programming+'s Mojo engine has to make; a failing Mojo Quest solution or manual sample usually means a language change the markers should know about.
7. `pixi run test`, then commit the pin, the lock, the corpus, the goldens, and `src/mojo/generated/` together.
## Licenses and provenance
+1 -1
View File
@@ -2,7 +2,7 @@
<!-- Written by tests/sync-coverage.test.mjs. Do not edit; rerun `npm test` to refresh. -->
Each translator in `src/sync/` is run over every exercise with pseudo (17), every program in `tests/corpus/` (53), and 17 one-construct fixtures (`tests/helpers/sync-programs.mjs`). 3 of the 87 have pseudo that does not read, by design (they teach the notation's error messages), and are left out below. That leaves **84 programs**.
Each translator in `src/sync/` is run over every exercise with pseudo (17), every program in `library/pseudo/programs/` (53), and 17 one-construct fixtures (`tests/helpers/sync-programs.mjs`). 3 of the 87 have pseudo that does not read, by design (they teach the notation's error messages), and are left out below. That leaves **84 programs**.
| From pseudo to | Says it completely | Says it with a gap or a checker error | Cannot say it |
| --- | ---: | ---: | ---: |
+1 -1
View File
@@ -18,7 +18,7 @@ Programming+ is built for checking work that someone or something else produced,
|---|---|---|---|
| **Compiled on godbolt** (ran, exit N / did not compile / timed out) | An answer from the compile backend (`src/services/compile-backend.ts`, godbolt.org with Mojo 1.1.0 by default) for this exact source, input and build level, made in this browser | The real compiler answered as shown | That the program is right. The badge is keyed by a hash, so any edit, other input or other level removes it, and a share link never carries it |
| **Edited since compile** | An edit after a compile | The compiler's answer is for an earlier text | Anything about the current text |
| **verified on Mojo 1.1.0** | An exercise's own program in `mojo/local/`, when godbolt's stored answer for that exact source passed the file's `# expect-stdout:` lines (`pixi run mojo-verify`) | The program printed what it should, on the real compiler | That the program is right on other inputs |
| **verified on Mojo 1.1.0** | An exercise's own program in `library/mojo/local/`, when godbolt's stored answer for that exact source passed the file's `# expect-stdout:` lines (`pixi run mojo-verify`) | The program printed what it should, on the real compiler | That the program is right on other inputs |
| A Mojo checker error, warning or note | Programming+'s own checker (`src/mojo/`) | The compiler would report this. The checker may never report an error on a program the compiler accepts (`tests/mojo-check.test.mjs`) | That a program without checker errors compiles. Only the compiler says that |
| A **best practices** note | The optional helper (`src/mojo/practices.ts`), off by default | A more idiomatic way to write a line, whose rewrite keeps the output the same where it offers one | An error. Notes never look like the compiler |
| Mojo output in the Run view and stepper | Programming+'s Mojo interpreter (`src/mojo/interp.ts`) | Exactly what godbolt printed for the same program, or the interpreter declines and says why (`tests/mojo-run.test.mjs`) | A prediction. The interpreter does not guess |