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
90 lines
6.9 KiB
Markdown
90 lines
6.9 KiB
Markdown
# 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`):
|
|
|
|
- **Bridge**: write the procedure as plain-English steps (**lingo**), equations written in LaTeX (**matho**), the notation that can completely specify any procedure (**pseudo**), or a specification you prove against (**speco**); the others follow as you type, and Mojo is generated from the pseudo, always labeled as generated.
|
|
- **Developer**: Mojo only. The checker's advice as you type, every step and every value in one Run view, a fuzzer that lists what it tried, and the real Mojo compiler's verdict.
|
|
- **Hardware**: the code beside a board you arrange: registers, memory, the stack, cache lines, the caches, virtual memory, the pipeline and the out-of-order core, with Mojo and its x86-64 as tabs, linked line by line.
|
|
|
|
A library of verified routines (statistics, numerics, sequence alignment, molecular simulation; `#/library`) comes with it, each one usable by name with `USE` and open to step through, and so does a catalog of worked problems, 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. 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
|
|
|
|
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
|
|
pixi run test # build, then every test
|
|
```
|
|
|
|
Without pixi, with Node 20 or later (and `python3` for the corpus pipeline's tests):
|
|
|
|
```bash
|
|
npm install && npm test
|
|
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. 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 site** | |
|
|
| `install` | Install TypeScript, the only npm dependency |
|
|
| `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 of the site |
|
|
| `check-pages <dir>` | Run every program embedded in the Quarto pages under a folder ([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) |
|
|
| **Ship** ([docs/deploy.md](docs/deploy.md)) | |
|
|
| `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 |
|
|
|
|
## Where things are
|
|
|
|
```
|
|
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, and the library
|
|
(pplus-library, its own submodule core/library) (core/README.md)
|
|
src/
|
|
main.ts the hash router
|
|
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 library, 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)
|
|
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/ (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
|
|
```
|
|
|
|
## Read next
|
|
|
|
| Document | For |
|
|
|---|---|
|
|
| [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/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 |
|