62 lines
8.8 KiB
Markdown
62 lines
8.8 KiB
Markdown
# AGENTS.md
|
|
|
|
Instructions for coding agents (and people) changing pplus-core. Programming+ takes a procedure from an idea to Mojo to the machine. Core decides what a program means in each of its notations: lingo (steps in plain English), matho (equations written in LaTeX), pseudo (pseudocode precise enough to run, prove and translate), speco (a specification to prove against) and Mojo (Modular's programming language, pinned to version 1.2.0). 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 # what CI runs: every test, no Mojo program we wrote failing by godbolt's stored answers, library-check, mojo-local, a short fuzz (docs/ci.md)
|
|
```
|
|
|
|
Without pixi (a sandbox with only Node and Python):
|
|
|
|
```bash
|
|
npx tsc -p tsconfig.json && node --test --test-concurrency=8 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 under a minute (25 s on the machine this was last measured on). It runs eight files at a time: Node's default is one fewer than the processor count, and on a 24-core machine the 41 files at once (each 60 to 490 MB at its peak) passed a 3 GB memory cap on some runs and were OOM-killed on others; eight at a time peaked at 1.9 GB in the same 22 s. 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 a 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 a course's site and pplus-web take them from one place.
|
|
2. **Do not edit generated files by hand.** `src/mojo/generated/*` and `library/syntax/mojo.xml` come from the corpus pipeline (`pixi run mojo-emit`, `mojo-status`, `play`). `src/library/generated.ts` comes from `library/` (`pixi run library-emit`), and the library's `status.json`, `STATUS.md` and `golden/` from `pixi run library-check` and `library-verify-mojo`. `library/mojo/corpus/` comes from `mojo-harvest`. `library/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.2.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 from godbolt's stored answers, and `pixi run mojo-local` and `pixi run mojo-fuzz` hold them, and the Mojo the translator writes, to the pinned compiler on your machine. Run `mojo-local` after any change to `src/mojo/` or `src/sync/pseudo-to-mojo.ts`. 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 `library/pseudo/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.
|
|
9. **Data lives in pplus-library, code lives here.** Programs, corpora, pins, fixtures and stored answers belong in `library/` (its own AGENTS.md has its rules); scripts, engines and tests that read them stay in core. A change under `library/` is committed and pushed in pplus-library first, then committed here with the new submodule pointer (`git add library`) and whatever core regenerated from it.
|
|
|
|
## 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 `library/pseudo/programs/` whose `// EXPECT:` lines are the output it must print |
|
|
| A prover soundness regression | a file in `library/pseudo/prover/` whose `// MUST-NOT-PROVE: <kind>@<line>` names an obligation a run breaks, or `// RUN-STOPS: <kind>@<line>` where a run must stop |
|
|
| A verified routine others can USE | in pplus-library (`library/`), under its AGENTS.md; then `pixi run library-check` and `library-emit` here ([docs/library.md](docs/library.md)) |
|
|
| 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.
|