The engines had no tests of their own in the course repository; this repository now owns them, so a change to solver.js or vcgen.js needs something to answer to besides the end-to-end tests. tests/engine-solver.test.mjs holds: - a table of goals the solver must prove (transitivity, integer tightening, case splits, congruence on positions, DIV and MOD by a constant, lengths at least 0) and goals it must leave unknown (a false step, FLOAT tightening, products of unknowns, rounded FLOAT addition, different positions); one known gap, 2X == 1 not seen as impossible, is recorded so an improvement shows up; - 400 random linear integer formulas with DIV, MOD, if-then-else and boolean structure; every one the solver proves is checked against all 729 assignments of X, Y, Z in [-4, 4]; - programs whose obligations must come out proved or not: a counting loop with its invariant, an index one past the end, a division that needs a REQUIRE, FILL and RANDINT arguments, and the int-model note. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
Programming+
Programming+ takes a procedure from an idea to Mojo to the machine, built for a world where writing code is easy and knowing what it does is the job. It has three areas (src/core/areas.ts):
- Bridge: write the procedure as plain-English steps (lingo), equations written in LaTeX (matho), the notation that can completely specify any procedure (pseudo), or a specification you prove against (speco); the others follow as you type, and Mojo is generated from the pseudo, always labeled as generated.
- Developer: Mojo only. The checker's advice as you type, every step and every value in one Run view, a fuzzer that lists what it tried, and the real Mojo compiler's verdict.
- Hardware: the code beside a board you arrange: registers, memory, the stack, cache lines, the caches, virtual memory, the pipeline and the out-of-order core, with Mojo and its x86-64 as tabs, linked line by line.
A catalog of worked problems comes with it, each opening in every area it has something to show in, and any view can be shared as a link or embedded in a page. With Quarto, a page can also run a program kept beside it while the page renders, and show the run, a stepper, the flowchart, the proof and the rest without an iframe, down to the machine itself (registers, caches, the pipeline, the core, stepped). The With Quarto page (#/quarto) is a gallery of every shortcode.
It is a static single-page app: TypeScript compiled by tsc, no bundler, no framework, no runtime dependencies. Everything it says about Mojo is pinned to Mojo 1.1.0 and checked against the real compiler on Compiler Explorer.
Quick start
With pixi (it brings the pinned Mojo, Node and Python):
pixi run dev # build, then serve on http://localhost:4173
pixi run test # build, then every test
Without pixi, with Node 20 or later (and python3 for the corpus pipeline's tests):
npm install && npm test
npm run dev
Commands
Every command is a pixi task (pixi task list shows them with their descriptions). tests/tasks.test.mjs fails if this table and pixi.toml disagree.
| Task | What it does |
|---|---|
| Build and test the app | |
install |
Install TypeScript, the only npm dependency |
build |
Compile src/ to dist/ |
watch |
Rebuild dist/ on every change |
check |
Type-check only |
dev |
Build, then serve on http://localhost:4173 |
test |
Build, then run every test, the corpus pipeline's Python tests included |
check-pages <dir> |
Run every program embedded in the Quarto pages under a folder (quarto/README.md) |
engines-diff <static> |
Compare the vendored course code with a course checkout (docs/engines.md) |
| Write content | |
new-exercise <id> |
Start an exercise whose Mojo lives in mojo/local/<id>.mojo (docs/exercises.md) |
new-probe <name> <question> |
Start mojo/probes/<name>.mojo: one question about the compiler (docs/mojo-corpus.md) |
new-stress <name> <about> |
Start mojo/stress/<name>.mojo: realistic Mojo that tests the interpreter |
play <name> |
For mojo/local/<name>.mojo: run, verify on godbolt, build, list the assembly, test |
play-watch <name> |
The same, again on every save (tests off) |
quarto-export <name> <dir> |
Copy a mojo/local/ program, its x86-64 and setup beside a Quarto page, and print the shortcode |
quarto-css |
Regenerate the extension's pplus-views.css from styles.css (a test fails while it is out of date) |
quarto-engine <dir> |
Copy a built Programming+ into a site's _extensions/pplus/engine, for the rendered views (quarto/README.md) |
quarto-example |
Render the example site in quarto/example, every shortcode on real pages (needs Quarto) |
| The Mojo corpus (docs/mojo-corpus.md) | |
mojo-verify |
Ask godbolt about every program with no answer yet (network) |
mojo-verify-item <id> |
Ask again about one item, e.g. 'probes/life-*' (network) |
mojo-verify-dry |
Show what mojo-verify would send; send nothing |
mojo-verify-diagnostics |
Also check the compiler's own diagnostic tests (opt-in; network) |
mojo-status |
Judge every item from the stored answers, offline; writes mojo/golden/STATUS.md |
mojo-status-strict |
The same, and fail if a program we wrote fails |
mojo-harvest |
After editing mojo/pin.json: fetch Modular's sources, process, regenerate (network) |
mojo-harvest-local [dir] |
Harvest, with zips standing in for sources the pin leaves unresolved |
mojo-harvest-offline [dir] |
Harvest from zips only, no network |
mojo-fetch |
Re-resolve every ref in the pin and rewrite the lock (network) |
mojo-emit |
Regenerate src/mojo/generated/ from the pin and corpus, offline |
mojo-test |
The corpus pipeline's own tests |
mojo-run <file> |
Run one Mojo file on the pinned local compiler |
mojo-probes-local |
Run every probe on the local compiler (a quick look) |
mojo-update |
After editing the pin: harvest, verify, status, test |
| Ship (docs/deploy.md) | |
ci |
What CI runs: every test, and no program of ours failing |
site |
Test, then assemble site/ |
deploy [slug] [target] |
Publish site/ to /srv/www/<slug>, optionally over SSH |
Where things are
AGENTS.md rules for changing the code (read first)
index.html, styles.css the page and the app's stylesheet
src/
main.ts the hash router
core/ state and its URL codec, the session, the catalog, the areas, the language reference
sync/ the translators between the languages and the hub that keeps the Bridge's panes in step
services/ one adapter per language behind LanguageService (lingo, matho, pseudo, speco, mojo, asm), godbolt.ts
mojo/ the Mojo checker, interpreter, lifetimes, and AT&T-to-Intel listing translator
mojo/generated/ generated from mojo/pin.json and the corpus; do not edit
ui/ the shell (one per area), the home page, the "With Quarto" gallery, the editor, the embeds, the views
quarto/ the Quarto extension's rendered views: a program run and drawn by the views, as HTML (render.ts),
the small document they draw into outside a browser (dom.ts), the shortcode list (shortcodes.ts)
ui/hw/ the Hardware area's machine board, over the course's x86-64 views
exercises/ one file per catalog problem
curriculum/ a lesson corpus kept as an interpreter fixture (tests/curriculum.test.mjs); no UI
engines/ the course site's language engines (docs/engines.md); do not edit here
vendor/ CodeMirror 6 as one built module; scripts/vendor/ rebuilds it
styles/course/ the course site's widget stylesheets, copied unchanged (and bridge.css, ours)
tests/ node --test against dist/; tests/corpus/ holds pseudo regression programs
mojo/ the Mojo corpus: the pin and lock, harvested material, our probes, local and
stress programs, and godbolt's answers (golden/)
scripts/ the tasks above; scripts/mojo/ is the corpus pipeline (Python, standard library only)
quarto/ the Quarto extension (_extensions/pplus) and an example site using every shortcode (example/)
docs/ the documents below, and the Caddy site block
scratch/ ignored by git: a place for experiments
Read next
| Document | For |
|---|---|
| AGENTS.md | Rules for anyone changing the code, coding agents included: the gate, what not to edit, conventions |
| docs/app.md | What the app does: the three areas, translation between languages, its links, and how embeds behave |
| docs/sync-coverage.md | What each translator can say, written by the tests: which programs translate fully, and why the rest do not |
| docs/exercises.md | Adding a catalog problem |
| docs/mojo-corpus.md | Writing Mojo of our own (probes, exercise programs, stress programs) and moving to a new Mojo version |
| docs/asm-coverage.md | Which instructions compiled Mojo uses, against what the machine models |
| docs/engines.md | The vendored course engines and stylesheets, and how they differ from the course |
| docs/deploy.md | Building the site and publishing it to the droplet |
| quarto/README.md | Embedding views in a Quarto site |