Move the engine core into core/, a project of its own (pplus-core)
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
This commit is contained in:
1567 files changed
+3670
-981
No files matched your search
@@ -1,4 +1,4 @@
|
||||
# Programming+
|
||||
# Programming+ (pplus-web)
|
||||
|
||||
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`):
|
||||
|
||||
@@ -8,11 +8,11 @@ Programming+ takes a procedure **from an idea to Mojo to the machine**, built fo
|
||||
|
||||
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](https://godbolt.org).
|
||||
It is a static single-page app: TypeScript compiled by `tsc`, no bundler, no framework, no runtime dependencies. This repository is the site; what programs mean (the languages, the translators, the Mojo checker and interpreter, the prover, the fuzzer, the machine model, and the stored answers of the real tools) is **pplus-core**, a project of its own, kept here as the git submodule `core/` and imported as `#core/...` ([core/README.md](core/README.md)). Everything it says about Mojo is pinned to **Mojo 1.1.0** and checked against the real compiler on [Compiler Explorer](https://godbolt.org).
|
||||
|
||||
## Quick start
|
||||
|
||||
With [pixi](https://pixi.sh) (it brings the pinned Mojo, Node and Python):
|
||||
Clone with the submodule (`git clone --recurse-submodules`, or `git submodule update --init` in an existing clone). With [pixi](https://pixi.sh) (it brings the pinned Mojo, Node and Python):
|
||||
|
||||
```bash
|
||||
pixi run dev # build, then serve on http://localhost:4173
|
||||
@@ -28,48 +28,27 @@ 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.
|
||||
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. Core's own commands (the Mojo corpus, `play`, the CLI, the pinned Dafny) are in [core/README.md](core/README.md) and run with `pixi run --manifest-path core/pixi.toml <task>`.
|
||||
|
||||
| Task | What it does |
|
||||
|---|---|
|
||||
| **Build and test the app** | |
|
||||
| **Build and test the site** | |
|
||||
| `install` | Install TypeScript, the only npm dependency |
|
||||
| `build` | Compile `src/` to `dist/` |
|
||||
| `core-build` | Build pplus-core (`core/`) into `core/dist/`, which the site imports as `#core/` |
|
||||
| `core-test` | Run pplus-core's own tests |
|
||||
| `build` | Build core, then 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 |
|
||||
| `test` | Build, then run every test of the site |
|
||||
| `check-pages <dir>` | Run every program embedded in the Quarto pages under a folder ([quarto/README.md](quarto/README.md)) |
|
||||
| `engines-diff <static>` | Show what a course checkout has not taken yet from the engines and stylesheets ([docs/engines.md](docs/engines.md)) |
|
||||
| `engines-export <static>` | Copy the engines into a course checkout, TypeScript modules as built ([docs/engines.md](docs/engines.md)) |
|
||||
| **Write content** | |
|
||||
| `new-exercise <id>` | Start an exercise whose Mojo lives in `mojo/local/<id>.mojo` ([docs/exercises.md](docs/exercises.md)) |
|
||||
| `new-probe <name> <question>` | Start `mojo/probes/<name>.mojo`: one question about the compiler ([docs/mojo-corpus.md](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/README.md)) |
|
||||
| **Quarto** | |
|
||||
| `quarto-export <name> <dir>` | Copy a `core/mojo/local/` program, its x86-64 and setup beside a Quarto page, and print the shortcode |
|
||||
| `quarto-css` | Regenerate the extension's generated files (a test fails while they are out of date) |
|
||||
| `quarto-engine <dir>` | Copy a built Programming+ and core into a site's `_extensions/pplus/engine`, for the rendered views ([quarto/README.md](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](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](docs/deploy.md)) | |
|
||||
| `ci` | What CI runs: every test, and no program of ours failing |
|
||||
| `ci` | What CI runs: every test of the site, against the pinned core |
|
||||
| `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 |
|
||||
@@ -77,28 +56,21 @@ Every command is a pixi task (`pixi task list` shows them with their description
|
||||
## Where things are
|
||||
|
||||
```
|
||||
AGENTS.md rules for changing the code (read first)
|
||||
index.html, styles.css the page and the app's stylesheet
|
||||
AGENTS.md rules for changing the site (read first)
|
||||
index.html, styles.css the page (with the import map that points #core/ at core/dist/) and the app's stylesheet
|
||||
core/ pplus-core, a git submodule: languages, translators, prover, corpus (core/README.md)
|
||||
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
|
||||
core/ the app's state and its URL codec, the session (a core Workspace with storage, versions,
|
||||
compiles and the helper), the catalog with areas, the areas, saved versions, preferences
|
||||
ui/ the shell (one per area), the home page, the "With Quarto" gallery, the editor, the embeds, the views
|
||||
ui/hw/ the Hardware area's machine board, over the course's x86-64 views (from core)
|
||||
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)
|
||||
tests/ node --test against dist/ (and core/dist/)
|
||||
scripts/ the tasks above
|
||||
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
|
||||
@@ -108,13 +80,9 @@ scratch/ ignored by git: a place for experiments
|
||||
|
||||
| Document | For |
|
||||
|---|---|
|
||||
| [AGENTS.md](AGENTS.md) | Rules for anyone changing the code, coding agents included: the gate, what not to edit, conventions |
|
||||
| [AGENTS.md](AGENTS.md) | Rules for anyone changing the site, coding agents included: the gate, what not to edit, conventions |
|
||||
| [docs/app.md](docs/app.md) | What the app does: the three areas, translation between languages, its links, and how embeds behave |
|
||||
| [docs/trust.md](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](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](docs/exercises.md) | Adding a catalog problem |
|
||||
| [docs/mojo-corpus.md](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](docs/asm-coverage.md) | Which instructions compiled Mojo uses, against what the machine models |
|
||||
| [docs/engines.md](docs/engines.md) | The language engines this repository owns, their tests, and how the course takes them |
|
||||
| [docs/deploy.md](docs/deploy.md) | Building the site and publishing it to the droplet |
|
||||
| [quarto/README.md](quarto/README.md) | Embedding views in a Quarto site |
|
||||
| [core/README.md](core/README.md) | pplus-core: the engines, the prover, the Mojo corpus, the CLI, the pinned Dafny, and their docs |
|
||||
| [core/docs/trust.md](core/docs/trust.md) | Every badge and verdict the app shows: what earns it, what it means, and what it does not mean |
|
||||
Reference in new issue
Block a user