62 lines
7.8 KiB
Markdown
62 lines
7.8 KiB
Markdown
# 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 `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.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 `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.
|