2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00

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> Show what a course checkout has not taken yet from the engines and stylesheets (docs/engines.md)
engines-export <static> Copy the engines into a course checkout, TypeScript modules as built (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/
package Zip what git tracks, and nothing it ignores, into package/ for sharing
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 language engines this repository owns and the course copies (docs/engines.md)
  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
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/trust.md Every badge and verdict the app shows: what earns it, what it means, and what it does not mean
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 language engines this repository owns, their tests, and how the course takes them
docs/deploy.md Building the site and publishing it to the droplet
quarto/README.md Embedding views in a Quarto site
Languages
TypeScript 48.6%
JavaScript 24.8%
CSS 22%
Lua 3.6%
Shell 0.3%
Other 0.6%