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
@@ -31,7 +31,11 @@ jobs:
|
||||
runs-on: quarto-deploy
|
||||
steps:
|
||||
# actions/checkout needs node on the host, which the job needs anyway.
|
||||
# core/ is pplus-core, a submodule pinned to one commit; the job's token
|
||||
# must be able to read that repository.
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
submodules: recursive
|
||||
|
||||
- name: Toolchain on the host
|
||||
run: |
|
||||
@@ -41,12 +45,17 @@ jobs:
|
||||
command -v rsync >/dev/null || echo "rsync missing: local deploys fall back to cp, SSH deploys need it"
|
||||
|
||||
- run: npm ci
|
||||
# Builds core (with this repository's TypeScript), then the site, then tests the site.
|
||||
- run: npm test
|
||||
# pplus-core's own tests, at the pinned commit (its CI runs them too; this catches a bad pin).
|
||||
- name: Core's tests
|
||||
run: node --test tests/*.test.mjs
|
||||
working-directory: core
|
||||
|
||||
# The same check as `pixi run mojo-status-strict`: offline, from the stored godbolt answers.
|
||||
# Core's mojo-status-strict task: offline, from the stored godbolt answers.
|
||||
- name: Our Mojo programs pass
|
||||
run: |
|
||||
if command -v python3 >/dev/null; then python3 scripts/mojo/corpus.py status --strict
|
||||
if command -v python3 >/dev/null; then python3 core/scripts/mojo/corpus.py status --strict
|
||||
else echo "python3 missing: corpus status skipped"; fi
|
||||
|
||||
- name: Assemble the site
|
||||
|
||||
@@ -4,37 +4,39 @@ Instructions for coding agents (and people) changing Programming+. Read this fir
|
||||
|
||||
## Build, test, and the gate
|
||||
|
||||
The engine core (the languages, translators, Mojo checker and interpreter, prover, fuzzer, machine model and the Mojo corpus) is **pplus-core**, the git submodule `core/`, with its own rules in [core/AGENTS.md](core/AGENTS.md). This file is for the site.
|
||||
|
||||
```bash
|
||||
pixi run test # build, then every test (node --test against dist/, the corpus pipeline's Python tests included)
|
||||
pixi run ci # the gate: every test, and no Mojo program of ours failing
|
||||
pixi run test # build core, then the site, then every test of the site
|
||||
pixi run core-test # core's own tests, at the pinned commit
|
||||
```
|
||||
|
||||
Without pixi (a sandbox with only Node and Python):
|
||||
|
||||
```bash
|
||||
tsc -p tsconfig.json && node --test tests/*.test.mjs
|
||||
python3 scripts/mojo/corpus.py status --strict
|
||||
npm install && npm test
|
||||
(cd core && node --test tests/*.test.mjs && python3 scripts/mojo/corpus.py status --strict)
|
||||
```
|
||||
|
||||
**Finish every change with the gate green.** The baseline passes completely; there is no known failure to work around. If a test fails, fix the cause or stop and report it. Do not skip, loosen, or delete a test to get green.
|
||||
**Finish every change with the gate green**, both commands. The baseline passes completely; there is no known failure to work around. If a test fails, fix the cause or stop and report it. Do not skip, loosen, or delete a test to get green.
|
||||
|
||||
The full suite takes about two minutes. While iterating, build and run one file: `tsc -p tsconfig.json && node --test tests/state.test.mjs`.
|
||||
The site's suite takes under a minute. While iterating, build and run one file: `npm run build && node --test tests/state.test.mjs`.
|
||||
|
||||
## Hard rules
|
||||
|
||||
1. **Do not edit generated files by hand.** `src/mojo/generated/*` and `quarto/_extensions/pplus/syntax/mojo.xml` come from the corpus pipeline (`pixi run mojo-emit`, `mojo-status`, `play`). `quarto/_extensions/pplus/pplus-views.css` comes from `styles.css`, and `pplus-hw.css` and `course/*.css` beside it from `styles/course/` (`pixi run quarto-css`; a test fails while they are out of date, so run it after changing a rule the views use). `mojo/corpus/` comes from `mojo-harvest`. `mojo/golden/` holds godbolt's answers and comes only from `mojo-verify`.
|
||||
2. **Do not edit a `.mojo` file's text unless the task needs it.** A stored godbolt answer is keyed by the whole source, header comments included, so any edit (even to a comment) makes the program unverified until it is asked again on the network. If you add or change one, say in your summary that it needs `pixi run mojo-verify-item '<corpus>/<name>'`.
|
||||
3. **Never claim Mojo compiles, runs, or prints something without the real compiler's answer.** Mojo is pinned to 1.1.0. The checker may never report an error on a program the compiler accepts, and the interpreter must print exactly what godbolt printed or decline; `tests/mojo-check.test.mjs` and `tests/mojo-run.test.mjs` hold them to that. Every Mojo construct you write into the app must pass `checkMojo`, and every standard-library name must exist in `src/mojo/generated/stdlib.ts` or `types.ts`.
|
||||
4. **No new dependencies.** TypeScript is the only npm package. There is no bundler, no framework, and no runtime dependency; the corpus pipeline is Python's standard library only. CodeMirror is vendored as one built module (`src/vendor/`), rebuilt only by `scripts/vendor/codemirror.sh`.
|
||||
5. **You have no network** in most sandboxes. Godbolt (`mojo-verify`, Compile & run) and GitHub (`mojo-harvest`, `mojo-fetch`) need one. Never fake their results; leave those steps to the owner and list them.
|
||||
6. **Never let the prover call something proved that a run breaks.** "Proved" in the app must be a proof. A change to `src/engines/pseudo/logic.ts`, `solver.ts` or `vcgen.ts` keeps `tests/prover-soundness.test.mjs` and `tests/engine-solver.test.mjs` green, and a fact the prover assumes must hold for every value a run can produce, or be guarded by an obligation. When you find a soundness bug, add the program that shows it to `tests/prover/` with a `// MUST-NOT-PROVE:` (or `// RUN-STOPS:`) header first, see the test fail, then fix the rule ([docs/engines.md](docs/engines.md#soundness)).
|
||||
1. **A change to what programs mean belongs in core.** A translator, the checker, the interpreter, the prover, the fuzzer, the machine model, the catalog's problems, the Mojo corpus: change them in pplus-core under its rules (its own commit, its own gate), then move the `core` pointer here in a commit that says what it brings. Never edit `core/` from a site change without that. The site imports core only as `#core/<path>.js` (the import map in `index.html`, `imports` in `package.json`), from its built `core/dist/`.
|
||||
2. **Do not edit generated files by hand.** `quarto/_extensions/pplus/pplus-views.css` comes from `styles.css`, `pplus-hw.css` and `course/*.css` beside it from `styles/course/`, and `syntax/mojo.xml` from core's `core/syntax/mojo.xml` (`pixi run quarto-css`; a test fails while they are out of date, so run it after changing a rule the views use). Core's generated files are listed in its AGENTS.md.
|
||||
3. **Never claim Mojo compiles, runs, or prints something without the real compiler's answer.** Mojo is pinned to 1.1.0 by core. What the app shows about Mojo comes from core's checker and interpreter and from godbolt's answers (stored in `core/mojo/golden/`, or asked live by Compile & run); the site never invents a verdict, and every Mojo construct written into the app must pass `checkMojo`.
|
||||
4. **Never show "proved" for something that is not a proof.** The badges and verdicts are in [core/docs/trust.md](core/docs/trust.md); the site shows what core decided and does not soften or upgrade it.
|
||||
5. **No new dependencies.** TypeScript is the only npm package. There is no bundler, no framework, and no runtime dependency. CodeMirror is vendored as one built module (`src/vendor/`), rebuilt only by `scripts/vendor/codemirror.sh`.
|
||||
6. **You have no network** in most sandboxes. Godbolt (Compile & run) needs one, and so do core's network tasks. Never fake their results; leave those steps to the owner and list them.
|
||||
7. **Keep the workspace working while you change it.** Code panes are always the CodeMirror editor (`Editor` in `src/ui/editor.ts`, over the vendored `src/vendor/codemirror.js`), never a `<textarea>`; `tests/editor.test.mjs` checks it. Keep the workspace's parts as they are unless the task changes them: the pane tabs over one editor, the stepper docked under the editor, the side column (the inspect panel, whose first tab is the Run view), and the dock; in the Hardware area, the code on the left and the arrangeable board on the right. Restyle or rearrange them only when asked, and after any UI change open the app (`pixi run dev`) and check that the editor has line numbers and highlighting, the stepper steps, and the styles loaded.
|
||||
|
||||
## Conventions
|
||||
|
||||
- **Commands are pixi tasks.** Name them as `pixi run <task>` in docs, comments, and messages. A new command is a task in `pixi.toml` with a `description` and a row in the README's Commands table; `tests/tasks.test.mjs` fails otherwise, and also fails on any `pixi run <name>` that names no task. `package.json` keeps only `build`, `watch`, `check`, `dev`, `test` (what CI uses).
|
||||
- **Docs.** The README is the front door: keep it short. Put behavior in [docs/app.md](docs/app.md), exercises in [docs/exercises.md](docs/exercises.md), Mojo of our own and the pipeline in [docs/mojo-corpus.md](docs/mojo-corpus.md), the engines and the prover's soundness in [docs/engines.md](docs/engines.md), deployment in [docs/deploy.md](docs/deploy.md), and the Quarto extension in [quarto/README.md](quarto/README.md). Update the document a change belongs in, in the same commit.
|
||||
- **Tests run against `dist/` with no DOM.** Put logic in DOM-free modules (`src/core/`, `src/services/`, `src/mojo/`, `src/quarto/`) and test it there. The views in `src/ui/views/` also run outside a browser, under the small document of `src/quarto/dom.ts`, when the Quarto extension renders them: a view may use the selectors that document knows (compound selectors and the descendant combinator) and must not need layout to produce its markup. When a test needs `localStorage`, install a fake on `globalThis` and remove it in `finally`, as `tests/state.test.mjs` does. For a UI change, write a short manual check list in the commit message.
|
||||
- **Docs.** The README is the front door: keep it short. Put behavior in [docs/app.md](docs/app.md), deployment in [docs/deploy.md](docs/deploy.md), and the Quarto extension in [quarto/README.md](quarto/README.md). Exercises, the Mojo corpus, the engines and the prover's soundness are core's documents (`core/docs/`). Update the document a change belongs in, in the same commit.
|
||||
- **Tests run against `dist/` with no DOM.** Logic about programs belongs in core; the site's own DOM-free logic (`src/core/`, `src/quarto/`) is tested here. A test that needs a piece of work uses a `Session` (`src/core/session.ts`), which extends core's `Workspace`. The views in `src/ui/views/` also run outside a browser, under the small document of `src/quarto/dom.ts`, when the Quarto extension renders them: a view may use the selectors that document knows (compound selectors and the descendant combinator) and must not need layout to produce its markup. When a test needs `localStorage`, install a fake on `globalThis` and remove it in `finally`, as `tests/state.test.mjs` does. For a UI change, write a short manual check list in the commit message.
|
||||
- **TypeScript.** Strict mode, ES modules, imports with the `.js` suffix (`from './state.js'`). Indent like the file you are editing (some files use two spaces, some four).
|
||||
- **Stable ids.** Diagnostic ids (`matho-refused`, `reserved-name`, ...) and reference section ids are asserted by tests and linked from guides. Change one only on purpose, and update every test and link that names it.
|
||||
- **Saved state.** `PlayState` in `src/core/state.ts` is what share links, `localStorage`, and `.pplus.json` files hold, and `normalize()` reads it. A new field goes into `normalize()`; a field the student edits goes into `EDITS` (it drives `editedFrom()` and `editsFingerprint()`).
|
||||
@@ -44,17 +46,12 @@ The full suite takes about two minutes. While iterating, build and run one file:
|
||||
|
||||
| To add | Do |
|
||||
|---|---|
|
||||
| A catalog problem | `pixi run new-exercise <id>` for one built around a Mojo program, or copy `src/exercises/_template.ts` ([docs/exercises.md](docs/exercises.md)) |
|
||||
| A question about the compiler | `pixi run new-probe <name> "<question>"` |
|
||||
| Realistic Mojo for the interpreter | `pixi run new-stress <name> "<what it exercises>"`, with the output you predict in `# expect-stdout:` lines |
|
||||
| A pseudo regression program | a file in `tests/corpus/` whose `// EXPECT:` lines are the output it must print |
|
||||
| A prover soundness regression | a file in `tests/prover/` whose `// MUST-NOT-PROVE: <kind>@<line>` names an obligation a run breaks, or `// RUN-STOPS: <kind>@<line>` where a run must stop |
|
||||
| A catalog problem, a probe, a stress program, a corpus or prover regression, a language | in core ([core/AGENTS.md](core/AGENTS.md#adding-things)), then move the `core` pointer here; a problem's area comes from `defaultAreaFor` in `src/core/catalog.ts` |
|
||||
| A command | a task in `pixi.toml` and a row in the README's Commands table |
|
||||
| A language | a `LanguageService` (`src/core/types.ts`) in `src/services/`, registered in `src/services/index.ts` |
|
||||
| A Quarto shortcode | a function in the table `quarto/_extensions/pplus/pplus.lua` returns, a row in `SHORTCODES` (`src/quarto/shortcodes.ts`) and in `scripts/check-pages.mjs`, a sample in the gallery (`src/ui/quarto.ts`) and a use in `quarto/example/`; a rendered view is a case of `renderStatic` (`src/quarto/render.ts`); a view of the machine is a name in `HW_NAMES` (`src/quarto/machine.ts`), `HW_VIEWS` in `pplus.lua` and `HW_VIEWS` in `scripts/check-pages.mjs` |
|
||||
|
||||
## Delivering work
|
||||
|
||||
- One logical change per commit, with a message that says what changed and why: the problem first, then what each part of the change does.
|
||||
- When the owner asks for patches, export them with `git format-patch -o patches/ <base>` (the `patches/` folder is ignored by git) and do not paste whole files into chat. If the tree you were given has no `.git`, run `git init` and commit it unchanged first, so the patches have a base.
|
||||
- End with a summary: what you changed, the gate's result, anything you could not verify (network steps, manual UI checks), and anything you noticed but left alone.
|
||||
- End with a summary: what you changed, the gate's result, the core commit the site is pinned to if it moved, anything you could not verify (network steps, manual UI checks), and anything you noticed but left alone.
|
||||
@@ -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 |
|
||||
@@ -0,0 +1,100 @@
|
||||
# EditorConfig: https://editorconfig.org
|
||||
# In VS Code, install the "EditorConfig for VS Code" extension (EditorConfig.EditorConfig).
|
||||
|
||||
root = true
|
||||
|
||||
# Defaults for every file
|
||||
[*]
|
||||
charset = utf-8
|
||||
end_of_line = lf
|
||||
indent_style = space
|
||||
indent_size = 4
|
||||
insert_final_newline = true
|
||||
trim_trailing_whitespace = true
|
||||
|
||||
# Python
|
||||
[*.{py,pyi}]
|
||||
indent_size = 4
|
||||
max_line_length = 88
|
||||
|
||||
# Mojo (`mojo format` is Black-style, 88 columns; the fire emoji extension is also valid)
|
||||
[*.{mojo,🔥}]
|
||||
indent_size = 4
|
||||
max_line_length = 88
|
||||
|
||||
# Rust (rustfmt defaults: 4 spaces, 100 columns)
|
||||
[*.rs]
|
||||
indent_size = 4
|
||||
max_line_length = 100
|
||||
|
||||
# Cargo manifests and rustfmt config
|
||||
[{Cargo.toml,Cargo.lock,rustfmt.toml,.rustfmt.toml,clippy.toml}]
|
||||
indent_size = 4
|
||||
|
||||
# Mojo project manifest
|
||||
[{mojoproject.toml,pixi.toml,pixi.lock}]
|
||||
indent_size = 4
|
||||
|
||||
# YAML
|
||||
[*.{yml,yaml}]
|
||||
indent_size = 2
|
||||
|
||||
# JSON and friends
|
||||
[*.{json,jsonc,json5}]
|
||||
indent_size = 2
|
||||
|
||||
# Web
|
||||
[*.{js,jsx,mjs,cjs,ts,tsx,css,scss,less,html,vue,svelte}]
|
||||
indent_size = 2
|
||||
|
||||
# Config formats
|
||||
[*.{toml,ini,cfg}]
|
||||
indent_size = 4
|
||||
|
||||
[*.xml]
|
||||
indent_size = 2
|
||||
|
||||
# Markdown: trailing spaces are significant (hard line breaks)
|
||||
[*.{md,markdown}]
|
||||
indent_size = 2
|
||||
trim_trailing_whitespace = false
|
||||
|
||||
# typst
|
||||
[*.{typ}]
|
||||
indent_size = 4
|
||||
trim_trailing_whitespace = false
|
||||
|
||||
# Shell scripts
|
||||
[*.{sh,bash,zsh}]
|
||||
indent_size = 2
|
||||
|
||||
# Makefiles require tabs
|
||||
[{Makefile,makefile,*.mk}]
|
||||
indent_style = tab
|
||||
|
||||
# Go uses tabs
|
||||
[*.go]
|
||||
indent_style = tab
|
||||
|
||||
# Windows-only scripts need CRLF
|
||||
[*.{bat,cmd,ps1}]
|
||||
end_of_line = crlf
|
||||
|
||||
# Dockerfiles
|
||||
[{Dockerfile,Dockerfile.*,*.dockerfile}]
|
||||
indent_size = 4
|
||||
|
||||
# Terraform
|
||||
[*.{tf,tfvars,hcl}]
|
||||
indent_size = 2
|
||||
|
||||
# Don't touch these
|
||||
[LICENSE*]
|
||||
insert_final_newline = false
|
||||
|
||||
[*.{diff,patch}]
|
||||
trim_trailing_whitespace = false
|
||||
|
||||
[*.min.{js,css}]
|
||||
insert_final_newline = unset
|
||||
trim_trailing_whitespace = unset
|
||||
@@ -0,0 +1,2 @@
|
||||
# SCM syntax highlighting & preventing 3-way merges
|
||||
pixi.lock merge=binary linguist-language=YAML linguist-generated=true -diff
|
||||
@@ -0,0 +1,25 @@
|
||||
# pplus-core on Gitea Actions, with a runner that has no container image: the act_runner runs jobs directly on the
|
||||
# host's shell ("host mode"; pplus-web's docs/deploy.md has the runner setup). Every push and pull request builds
|
||||
# and tests core, and checks that every Mojo program of ours still passes, offline, from godbolt's stored answers.
|
||||
name: Test
|
||||
on:
|
||||
push:
|
||||
pull_request:
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: quarto-deploy
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Toolchain on the host
|
||||
run: |
|
||||
node --version
|
||||
npm --version
|
||||
python3 --version || echo "python3 missing: the pipelines' tests are skipped"
|
||||
- run: npm ci
|
||||
- run: npm test
|
||||
- name: Our Mojo programs pass
|
||||
run: |
|
||||
if command -v python3 >/dev/null; then python3 scripts/mojo/corpus.py status --strict
|
||||
else echo "python3 missing: corpus status skipped"; fi
|
||||
@@ -0,0 +1,14 @@
|
||||
node_modules/
|
||||
dist/
|
||||
.DS_Store
|
||||
patches/
|
||||
package/
|
||||
# the pinned Dafny, fetched by `pixi run dafny-fetch` (scripts/dafny.py)
|
||||
.tools/
|
||||
# pixi environments
|
||||
.pixi/*
|
||||
!.pixi/config.toml
|
||||
|
||||
# Python
|
||||
__pycache__/
|
||||
*.pyc
|
||||
@@ -0,0 +1,59 @@
|
||||
# AGENTS.md
|
||||
|
||||
Instructions for coding agents (and people) changing pplus-core. Read this first, then the [README](README.md) for what core is and where things are. When this file and a task's instructions disagree, the task wins; say so in your summary.
|
||||
|
||||
## Build, test, and the gate
|
||||
|
||||
```bash
|
||||
pixi run test # build, then every test (node --test against dist/, the pipelines' Python tests included)
|
||||
pixi run ci # the gate: every test, and no Mojo program of ours failing
|
||||
```
|
||||
|
||||
Without pixi (a sandbox with only Node and Python):
|
||||
|
||||
```bash
|
||||
npx tsc -p tsconfig.json && node --test tests/*.test.mjs
|
||||
python3 scripts/mojo/corpus.py status --strict
|
||||
```
|
||||
|
||||
**Finish every change with the gate green.** The baseline passes completely; there is no known failure to work around. If a test fails, fix the cause or stop and report it. Do not skip, loosen, or delete a test to get green.
|
||||
|
||||
The full suite takes about two minutes. While iterating, build and run one file: `npx tsc -p tsconfig.json && node --test tests/sync-hub.test.mjs`.
|
||||
|
||||
## Hard rules
|
||||
|
||||
1. **Core has no DOM.** What a program means is decided without a browser. A library module never touches `document`, `window`, `localStorage` or `navigator`, never imports one of the course's page widgets, and never imports from outside `src/`; `tests/boundary.test.mjs` holds it to that. The widgets (listed in that test) live beside the engines only so the course and pplus-web take them from one place.
|
||||
2. **Do not edit generated files by hand.** `src/mojo/generated/*` and `syntax/mojo.xml` come from the corpus pipeline (`pixi run mojo-emit`, `mojo-status`, `play`). `mojo/corpus/` comes from `mojo-harvest`. `mojo/golden/` holds godbolt's answers and comes only from `mojo-verify`.
|
||||
3. **Do not edit a `.mojo` file's text unless the task needs it.** A stored godbolt answer is keyed by the whole source, header comments included, so any edit (even to a comment) makes the program unverified until it is asked again on the network. If you add or change one, say in your summary that it needs `pixi run mojo-verify-item '<corpus>/<name>'`.
|
||||
4. **Never claim Mojo compiles, runs, or prints something without the real compiler's answer.** Mojo is pinned to 1.1.0. The checker may never report an error on a program the compiler accepts, and the interpreter must print exactly what godbolt printed or decline; `tests/mojo-check.test.mjs` and `tests/mojo-run.test.mjs` hold them to that. Every Mojo construct you write into core must pass `checkMojo`, and every standard-library name must exist in `src/mojo/generated/stdlib.ts` or `types.ts`.
|
||||
5. **Never let the prover call something proved that a run breaks.** "Proved" must be a proof. A change to `src/engines/pseudo/logic.ts`, `solver.ts` or `vcgen.ts` keeps `tests/prover-soundness.test.mjs` and `tests/engine-solver.test.mjs` green, and a fact the prover assumes must hold for every value a run can produce, or be guarded by an obligation. When you find a soundness bug, add the program that shows it to `tests/prover/` with a `// MUST-NOT-PROVE:` (or `// RUN-STOPS:`) header first, see the test fail, then fix the rule ([docs/engines.md](docs/engines.md#soundness)).
|
||||
6. **No new dependencies.** TypeScript is the only npm package; there is no runtime dependency. The pipelines (the Mojo corpus, the Dafny pin) are Python's standard library only. Tools that are not npm packages are pinned: Mojo, Node and Python by pixi, Dafny by `scripts/dafny.py` (a version and a SHA-256 per platform).
|
||||
7. **You have no network** in most sandboxes. Godbolt (`mojo-verify`), GitHub (`mojo-harvest`, `mojo-fetch`, `dafny-fetch`) need one. Never fake their results; leave those steps to the owner and list them.
|
||||
8. **Core's exports are pplus-web's API.** pplus-web imports core's built modules as `#core/<path>` and builds against the declarations in `dist/`. Renaming or removing an export, or changing what a function returns, breaks the site; when you do it, say so in the summary so web is updated in the same release.
|
||||
|
||||
## Conventions
|
||||
|
||||
- **Commands are pixi tasks.** Name them as `pixi run <task>` in docs, comments, and messages. A new command is a task in `pixi.toml` with a `description` and a row in the README's Commands table; `tests/tasks.test.mjs` fails otherwise, and also fails on any `pixi run <name>` that names no task. `package.json` keeps only `build`, `watch`, `check`, `test` (what CI uses).
|
||||
- **Docs.** The README is the front door: keep it short. Put the engines, the prover and its soundness in [docs/engines.md](docs/engines.md), verdicts in [docs/trust.md](docs/trust.md), exercises in [docs/exercises.md](docs/exercises.md), and Mojo of our own and the pipeline in [docs/mojo-corpus.md](docs/mojo-corpus.md). Update the document a change belongs in, in the same commit.
|
||||
- **Tests run against `dist/` with no DOM.** A test that needs a piece of work uses a `Workspace` (`src/common/workspace.ts`) with `workForProblem` (`src/common/problems.ts`), not pplus-web's session.
|
||||
- **TypeScript.** Strict mode, ES modules, imports with the `.js` suffix (`from './workspace.js'`). Indent like the file you are editing (some files use two spaces, some four). A JavaScript module's exported function gets JSDoc for its optional parameters, so the declaration pplus-web builds against says so.
|
||||
- **Stable ids.** Diagnostic ids (`matho-refused`, `reserved-name`, ...) and obligation kinds (`index`, `argument`, ...) are asserted by tests and shown by pplus-web. Change one only on purpose, and update every test and link that names it.
|
||||
- **Writing.** User-facing copy is US English (color, behavior, optimized, labeled). Plain sentences; say what a thing does, not how good it is.
|
||||
|
||||
## Adding things
|
||||
|
||||
| To add | Do |
|
||||
|---|---|
|
||||
| A catalog problem | `pixi run new-exercise <id>` for one built around a Mojo program, or copy `src/exercises/_template.ts` ([docs/exercises.md](docs/exercises.md)) |
|
||||
| A question about the compiler | `pixi run new-probe <name> "<question>"` |
|
||||
| Realistic Mojo for the interpreter | `pixi run new-stress <name> "<what it exercises>"`, with the output you predict in `# expect-stdout:` lines |
|
||||
| A pseudo regression program | a file in `tests/corpus/` whose `// EXPECT:` lines are the output it must print |
|
||||
| A prover soundness regression | a file in `tests/prover/` whose `// MUST-NOT-PROVE: <kind>@<line>` names an obligation a run breaks, or `// RUN-STOPS: <kind>@<line>` where a run must stop |
|
||||
| A command | a task in `pixi.toml` and a row in the README's Commands table |
|
||||
| A language | a `LanguageService` (`src/common/types.ts`) in `src/services/`, registered in `src/services/index.ts` |
|
||||
|
||||
## Delivering work
|
||||
|
||||
- One logical change per commit, with a message that says what changed and why: the problem first, then what each part of the change does.
|
||||
- When the owner asks for patches, export them with `git format-patch -o patches/ <base>` (the `patches/` folder is ignored by git) and do not paste whole files into chat.
|
||||
- End with a summary: what you changed, the gate's result, anything you could not verify (network steps), anything that changes core's exports, and anything you noticed but left alone.
|
||||
+108
@@ -0,0 +1,108 @@
|
||||
# pplus-core
|
||||
|
||||
pplus-core is the part of Programming+ that has to be right: the languages, the translators between them, the Mojo checker and interpreter, the prover, the fuzzer, the x86-64 machine model, and the stored answers of the real tools that everything it says rests on. It has no DOM. pplus-web (the site, the editor, the views and the Quarto extension) and the course site use it as a pinned dependency.
|
||||
|
||||
- **Languages:** pseudo (parser, checker, interpreter, the English reader for lingo), matho (equations in LaTeX), speco (specifications), Mojo (a checker and an interpreter held to the real compiler), x86-64 on a model machine with caches, a pipeline and an out-of-order core.
|
||||
- **Translators:** pseudo to Mojo, lingo, matho and speco, with line maps and located refusals, and the hub that keeps the linked languages in step (`src/sync/`).
|
||||
- **Verification:** the prover (`src/engines/pseudo/logic.ts`, `solver.ts`, `vcgen.ts`), sound and held to it by tests; the fuzzer (`src/common/fuzz.ts`); and a pinned Dafny (`scripts/dafny.py`).
|
||||
- **Stored answers:** the Mojo corpus (`mojo/`): material harvested from Modular's repositories at pinned commits, our own probes and programs, and godbolt's answers for every one of them (`mojo/golden/`).
|
||||
- **A workspace:** `src/common/workspace.ts` is one piece of work and everything its sources mean. pplus-web's session extends it.
|
||||
- **A command line:** `pixi run cli check|run|prove|fuzz|translate <file>`.
|
||||
|
||||
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):
|
||||
|
||||
```bash
|
||||
pixi run test # build, then every test
|
||||
pixi run ci # the gate: every test, and no Mojo program of ours failing
|
||||
pixi run cli prove tests/corpus/27-quantifiers.pseudo
|
||||
pixi run dafny-fetch # once: the pinned Dafny, into .tools/
|
||||
```
|
||||
|
||||
Without pixi, with Node 20 or later (and `python3` for the pipelines' tests):
|
||||
|
||||
```bash
|
||||
npm install && npm test
|
||||
```
|
||||
|
||||
## 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** | |
|
||||
| `install` | Install TypeScript, the only npm dependency |
|
||||
| `build` | Compile `src/` to `dist/`, with type declarations for pplus-web |
|
||||
| `watch` | Rebuild `dist/` on every change |
|
||||
| `check` | Type-check only |
|
||||
| `test` | Build, then run every test, the pipelines' Python tests included |
|
||||
| `cli` | `pplus check\|run\|prove\|fuzz\|translate <file>`: core without a browser ([scripts/cli.mjs](scripts/cli.mjs)) |
|
||||
| `engines-diff <static>` | Show what a course checkout has not taken yet from the engines ([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)) |
|
||||
| **Dafny, pinned** ([scripts/dafny.py](scripts/dafny.py)) | |
|
||||
| `dafny-fetch` | Download the pinned Dafny into `.tools/`, checked by SHA-256 (network, once) |
|
||||
| `dafny` | Run the pinned Dafny with the arguments given, e.g. `pixi run dafny verify file.dfy` |
|
||||
| **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) |
|
||||
| **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/` and `syntax/mojo.xml` 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** | |
|
||||
| `ci` | What CI runs: every test, and no program of ours failing |
|
||||
| `package` | Zip what git tracks, and nothing it ignores, into `package/` for sharing |
|
||||
|
||||
## Where things are
|
||||
|
||||
```
|
||||
AGENTS.md rules for changing core (read first)
|
||||
src/
|
||||
common/ the workspace, the problem catalog, the fuzzer, the run view's data, the language
|
||||
reference, the machine presets, the shared types
|
||||
engines/pseudo/ the pseudo language and the prover (logic, solver, vcgen in TypeScript), and the course's
|
||||
page widgets for it (excluded from the build; see docs/engines.md)
|
||||
engines/asm86/ the x86-64 model machine, and the course's widgets that draw it (views, hwviews)
|
||||
engines/shared/ text helpers, and the course's DOM helpers
|
||||
services/ one adapter per language behind LanguageService; the compiler request and backend
|
||||
sync/ the translators and the hub that keeps the linked languages in step
|
||||
mojo/ the Mojo checker, interpreter, lifetimes, practices, AT&T-to-Intel; generated/ from the corpus
|
||||
exercises/ one file per catalog problem
|
||||
curriculum/ a lesson corpus kept as an interpreter fixture
|
||||
syntax/mojo.xml the Mojo words as a KDE syntax for Pandoc (generated; pplus-web copies it)
|
||||
tests/ node --test against dist/; corpus/ (pseudo programs), prover/ (soundness regressions)
|
||||
mojo/ the Mojo corpus: the pin and lock, harvested material, our programs, godbolt's answers
|
||||
scripts/ the tasks above; scripts/mojo/ is the corpus pipeline; dafny.py the Dafny pin; cli.mjs
|
||||
docs/ the documents below
|
||||
```
|
||||
|
||||
## Read next
|
||||
|
||||
| Document | For |
|
||||
|---|---|
|
||||
| [AGENTS.md](AGENTS.md) | Rules for anyone changing core, coding agents included: the gate, what not to edit, conventions |
|
||||
| [docs/engines.md](docs/engines.md) | The engines, the prover and its soundness, and how the course takes them |
|
||||
| [docs/trust.md](docs/trust.md) | Every verdict core produces: which tool earns it, what it means, and what it does not mean |
|
||||
| [docs/mojo-corpus.md](docs/mojo-corpus.md) | Writing Mojo of our own and moving to a new Mojo version |
|
||||
| [docs/exercises.md](docs/exercises.md) | Adding a catalog problem |
|
||||
| [docs/sync-coverage.md](docs/sync-coverage.md) | What each translator can say, written by the tests |
|
||||
| [docs/asm-coverage.md](docs/asm-coverage.md) | Which instructions compiled Mojo uses, against what the machine models |
|
||||
File renamed without changes.
@@ -1,15 +1,14 @@
|
||||
# The engines
|
||||
|
||||
Programming+ runs the language engines that the course site also runs, and draws the hardware views with the course's stylesheets, so a program behaves the same in the app as on a course page. **This repository owns the engines.** Changes are made and tested here, and the course copies them from here (`pixi run engines-export`). The engines started as a copy of the course's modules; the course no longer sends changes the other way.
|
||||
Programming+ runs the language engines that the course site also runs, so a program behaves the same in the app as on a course page. The course's widget stylesheets live in pplus-web (`styles/course/`), which compares them with the course's. **This repository owns the engines.** Changes are made and tested here, and the course copies them from here (`pixi run engines-export`). The engines started as a copy of the course's modules; the course no longer sends changes the other way.
|
||||
|
||||
| Here | The course receives it as | What it is |
|
||||
|---|---|---|
|
||||
| `src/engines/pseudo/` | `static/js/pseudo/` | The pseudo language: parser, checker, interpreter, the English (lingo) reader, the prover (`logic.ts`, `solver.ts`, `vcgen.ts`), translation |
|
||||
| `src/engines/asm86/` | `static/js/asm86/` | The x86-64 model machine, its caches, pipeline and out-of-order core, and the widgets that draw them |
|
||||
| `src/engines/shared/` | `static/js/shared/` | DOM helpers, URL state, text distance, charts |
|
||||
| `styles/course/` | `static/css/base/`, `static/css/widgets/` | The widget stylesheets ([styles/course/README.md](../styles/course/README.md)) |
|
||||
|
||||
The engines are wrapped behind one `LanguageService` interface (`src/core/types.ts`, adapters in `src/services/`). Modules the app does not use are excluded from the build in `tsconfig.json`. A change in `src/engines/` is a change to the course's language, so it needs a test here and goes to the course by export.
|
||||
The engines are wrapped behind one `LanguageService` interface (`src/common/types.ts`, adapters in `src/services/`). The course's page widgets (the pseudo views, the asm86 `views`/`hwviews`, the shared DOM helpers) sit beside the engines so the course and pplus-web take them from one place; the pseudo ones and a few others are excluded from core's build in `tsconfig.json`, and `tests/boundary.test.mjs` keeps core's library modules from importing any of them. A change in `src/engines/` is a change to the course's language, so it needs a test here and goes to the course by export.
|
||||
|
||||
## The prover
|
||||
|
||||
@@ -54,6 +53,6 @@ One addition to the pseudo language lives outside the engine, in app code: `DECL
|
||||
1. `pixi run engines-diff <course>/static` shows what the course has not taken yet: for each module, the file the course would receive (`src/engines/` as written, `dist/engines/` for a TypeScript module) against the course's copy, whitespace ignored, and the files only one side has.
|
||||
2. `pixi run engines-export <course>/static` builds and writes those files into the course's `static/js/`. A TypeScript module arrives as plain ES-module JavaScript, so the course's pages import it unchanged. Source maps are not copied.
|
||||
3. In the course repository, review the diff and run its pages before committing.
|
||||
4. For the stylesheets, follow [styles/course/README.md](../styles/course/README.md); they are still identical on both sides.
|
||||
4. The course's stylesheets are pplus-web's to compare (`styles/course/README.md` there).
|
||||
|
||||
A change someone makes in the course's copy is not picked up from there. Bring it here as a change with a test, then export.
|
||||
File renamed without changes.
@@ -81,7 +81,7 @@ The dialect markers in the pin are a cheap first look: `newer` patterns are synt
|
||||
| `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` |
|
||||
| `quarto/_extensions/pplus/syntax/mojo.xml` | The same words as a KDE syntax for Pandoc listings | `harvest`/`emit` |
|
||||
| `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.
|
||||
|
||||
File renamed without changes.
@@ -1,12 +1,14 @@
|
||||
# What each badge and verdict means
|
||||
|
||||
pplus-web shows the badges; the verdicts behind them come from pplus-core (the prover, the fuzzer, the translators, the compiler's stored and live answers, the model machine). This page is kept here, beside what produces them.
|
||||
|
||||
Programming+ is built for checking work that someone or something else produced, so every claim it shows names what answered it, and none claims more than that. This page lists each one: who earns it, what it means, and what it does not mean. When a new badge or verdict is added, it gets a row here in the same commit.
|
||||
|
||||
## Where code came from
|
||||
|
||||
| Shown | Earned by | Means | Does not mean |
|
||||
|---|---|---|---|
|
||||
| **Generated from pseudo** | The Bridge's Mojo tab, always (`mojoProvenance` in `src/core/provenance.ts`); Mojo copied from it with **Edit in Developer** | The translator wrote this Mojo from the pseudo, literally, with a header comment saying so | That anyone has read it, or that it is the Mojo a person would write |
|
||||
| **Generated from pseudo** | The Bridge's Mojo tab, always (`mojoProvenance` in pplus-web's `src/core/provenance.ts`); Mojo copied from it with **Edit in Developer** | The translator wrote this Mojo from the pseudo, literally, with a header comment saying so | That anyone has read it, or that it is the Mojo a person would write |
|
||||
| **Started from generated Mojo** | Generated Mojo edited in the Developer area (`mojoOrigin: 'generated-edited'`) | A person has changed generated Mojo | That the person reviewed the parts they did not change |
|
||||
| (badge cleared) | **I've reviewed this**, in the Developer area only | The person says they reviewed it; the header comment goes too | That anything checked the review. Compiling and editing never clear the badge |
|
||||
|
||||
@@ -36,7 +38,7 @@ The Prove tab reports every obligation in three statuses (`src/engines/pseudo/vc
|
||||
|
||||
| Shown | Earned by | Means | Does not mean |
|
||||
|---|---|---|---|
|
||||
| A routine's cases in the Tests tab | The fuzzer (`src/core/fuzz.ts`), with the seed and input count shown | Every input listed was run and checked against each claim and limit | That untried inputs pass. "Held on 300 inputs" is evidence, not proof |
|
||||
| A routine's cases in the Tests tab | The fuzzer (`src/common/fuzz.ts`), with the seed and input count shown | Every input listed was run and checked against each claim and limit | That untried inputs pass. "Held on 300 inputs" is evidence, not proof |
|
||||
| A failure's smallest input | Shrinking in the fuzzer | The smallest input it found that fails the same way | The only failing input |
|
||||
|
||||
## What a translation says
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
Loaded 100 of 1567 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user