What programs mean (the languages, translators, Mojo checker and
interpreter, prover, fuzzer, machine model, catalog problems and the Mojo
corpus with godbolt's stored answers) was mixed into the site's tree, so a
change to the prover and a change to a button went through the same gate
and the same docs. This moves all of it under core/, laid out as its own
repository, ready to be extracted with its history and pinned here as a
git submodule.
- core/: src/{engines,services,sync,mojo,exercises,curriculum,common},
mojo/, syntax/mojo.xml, its tests (with Workspace and workForProblem in
place of the site's Session), scripts (corpus pipeline, play, the
exercise and probe starters, engines export/diff), and its docs
(engines, trust, mojo-corpus, exercises, coverage). Its own pixi.toml,
package.json, README, AGENTS.md and CI workflow.
- core/tests/boundary.test.mjs: library modules use no DOM, import no
page widget, and import nothing outside src/.
- core/scripts/cli.mjs: pixi run cli check|run|prove|fuzz|translate.
- core/scripts/dafny.py: Dafny 4.11.0 pinned by version and SHA-256 per
platform, fetched into .tools/ (pixi run dafny-fetch, pixi run dafny).
- The site imports core only as #core/<path>.js: an import map in
index.html, "imports" in package.json for node, core's declarations for
tsc. The site's TypeScript builds core first (npm run build).
- assemble.sh, the Quarto engine copy, the render cache key, check-pages,
quarto-export and quarto-css read core/dist and core/mojo; quarto-css
copies core's syntax/mojo.xml into the extension.
- Site tests that covered engines moved to core; the rest keep Session.
- README, AGENTS.md, docs/app.md, docs/deploy.md and the CI workflow
describe the split (checkout with submodules; core's tests and corpus
status run against the pinned commit).
Gate: site 110 pass; core 307 pass; corpus status --strict passes.
Manual check: the assembled site opens Bridge (count-base-proved),
Developer and Hardware (count-base) with the editor, the stepper and the
board, and no module errors.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
3.0 KiB
Adding an exercise
An exercise is a catalog problem: one file in src/exercises/, listed in src/exercises/index.ts. The home page, the problem menu, share links, embeds, and the tests pick it up from there. pixi run test checks every exercise: its pseudo parses, its call runs, its answer matches expect, and its Mojo program (if it names one) exists and prints what it should.
There are two ways to start one.
An exercise around a Mojo program
pixi run new-exercise rolling-sum # 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.
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.
With # mode: both and # args: -O0 --debug-level=line-tables in the header, godbolt also returns the listing, and play turns it into the exercise's x86-64 pane (see "The assembly" in mojo-corpus.md).
An exercise in lingo, pseudo, matho or speco
Copy src/exercises/_template.ts to <id>.ts, fill it in, import it in src/exercises/index.ts, and add it to the list (before blank, the demo playground, which stays last). Then pixi run test.
The fields
| Field | Means |
|---|---|
id |
The URL (#/<area>/p/<id>): lowercase words joined by hyphens |
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 |
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 |
area |
The area it opens in: bridge, dev or hw. Absent: Hardware for asm-* ids, Developer for a problem that is only a Mojo program, Bridge otherwise |
src/exercises/types.ts documents each field in full.