diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml index a131a04..cb3cd82 100644 --- a/.gitea/workflows/deploy.yml +++ b/.gitea/workflows/deploy.yml @@ -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 diff --git a/AGENTS.md b/AGENTS.md index 53bc170..4cf4c50 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 '/'`. -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/.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 `