Files
pplus-web/AGENTS.md
T
alexmandClaude bd51349967 Add the library page, and pin core with sized types and the library
core 477dffe brings pseudo's sized types (INT8..UINT64, FLOAT32), exact
numerical built-ins, USE IEEE, and USE for pplus-library, its new
submodule: 16 routines checked at every level.

- #/library (src/ui/library.ts): every routine by module with a count
  of how its checks ended; a routine's page shows its pseudo, cases and
  results, every check with its detail, each reference implementation
  with its note, tolerance and source, the Dafny proof and the sources.
- Open in the Bridge: a routine opens as the problem lib:<id>
  (src/core/library.ts), its first case as the call, so it can be
  stepped through; the problem menu names it.
- Library in the site nav; README, docs/app.md and AGENTS.md updated.
- Two Quarto examples expected "X_BAR returned 3" for a FLOAT result;
  core now prints it in its type, 3.0.

Gate: site 113 pass; core 332 pass; library-check no failing check.
Manual check: #/library lists 16 routines with chips; a routine's page
shows numbered pseudo, cases, checks; Open in the Bridge steps through
NeedlemanWunschScore; no console errors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
2026-10-05 12:19:08 +00:00

58 lines
7.7 KiB
Markdown

# AGENTS.md
Instructions for coding agents (and people) changing Programming+. Read this first, then the [README](README.md) for what the app 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
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 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
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**, 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 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. **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), 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()`).
- **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, a probe, a stress program, a corpus or prover regression, a language, a library routine | in core (a library routine in pplus-library, core's submodule `library/`) ([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 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, 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.