Add USE and pin pplus-library: routines verified once, used by name
Routines that many programs need (a mean, a gap penalty, the Lennard-Jones potential, the minimum image convention) were rewritten and re-verified each time, and there was no way to open one and see exactly what it does. They now live in pplus-library, pinned here as the submodule library/, and a program brings them in with USE. - USE module / USE module.Routine (pseudo-study resolveUses): each routine is studied once in its own file (its own USE lines resolved the same way, cycles refused) and handed to the checker as a library routine; unknown-library, unknown-routine, library-clash, use-place. - A run steps over a library routine (one step at the call, one at the return, none of its lines); a broken contract is reported at the call, naming the routine. The prover uses its REQUIRE and ENSURE at the call and does not prove it again; it is not a unit of the program. - pseudo-to-mojo writes each library routine the program calls once, dependencies first, labeled as coming from the library. - src/library: the registry USE reads, generated from library/ (scripts/library.mjs emit), so the site needs no files at run time. - scripts/library.mjs check: every routine at every level: structure, cases, prover, fuzzer, generated Mojo, each reference implementation (CPython; cc at -O0 and -O2; core's Mojo interpreter; the pinned compiler's stored answer) held to the pseudo's results, and the Dafny proof with the pinned Dafny. Writes library/status.json and STATUS.md. scripts/library_godbolt.py stores the compiler's answers (network). - pixi tasks library-check, library-emit, library-verify-mojo, library-harness; CI checks out the submodule and runs library-check. - Tests: tests/library.test.mjs, corpus 53-library; docs/library.md and a library section in trust.md. Gate: 332 pass; library-check: no failing check (16 routines; the Mojo references are unverified until library-verify-mojo runs on the network). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
This commit is contained in:
21 files changed
+2654
-20
No files matched your search
@@ -11,7 +11,10 @@ jobs:
|
||||
test:
|
||||
runs-on: quarto-deploy
|
||||
steps:
|
||||
# library/ is pplus-library, a submodule; tests/library.test.mjs needs it checked out
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
submodules: recursive
|
||||
- name: Toolchain on the host
|
||||
run: |
|
||||
node --version
|
||||
@@ -23,3 +26,6 @@ jobs:
|
||||
run: |
|
||||
if command -v python3 >/dev/null; then python3 scripts/mojo/corpus.py status --strict
|
||||
else echo "python3 missing: corpus status skipped"; fi
|
||||
# every library routine at every level the host has tools for (python3, cc); nothing may fail
|
||||
- name: Library routines pass
|
||||
run: node scripts/library.mjs check
|
||||
@@ -0,0 +1,4 @@
|
||||
[submodule "library"]
|
||||
path = library
|
||||
url = ../pplus-library.git
|
||||
branch = main
|
||||
@@ -23,7 +23,7 @@ The full suite takes about two minutes. While iterating, build and run one file:
|
||||
## 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 `syntax/mojo.xml` come from the corpus pipeline (`pixi run mojo-emit`, `mojo-status`, `play`). `mojo/corpus/` comes from `mojo-harvest`. `mojo/golden/` holds godbolt's answers and comes only from `mojo-verify`.
|
||||
2. **Do not edit generated files by hand.** `src/mojo/generated/*` and `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`. `mojo/corpus/` comes from `mojo-harvest`. `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 `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)).
|
||||
@@ -49,6 +49,7 @@ The full suite takes about two minutes. While iterating, build and run one file:
|
||||
| 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 `tests/corpus/` whose `// EXPECT:` lines are the output it must print |
|
||||
| A prover soundness regression | a file in `tests/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` |
|
||||
|
||||
|
||||
@@ -7,13 +7,14 @@ pplus-core is the part of Programming+ that has to be right: the languages, the
|
||||
- **Verification:** the prover (`src/engines/pseudo/logic.ts`, `solver.ts`, `vcgen.ts`), sound and held to it by tests; the fuzzer (`src/common/fuzz.ts`); and a pinned Dafny (`scripts/dafny.py`).
|
||||
- **Stored answers:** the Mojo corpus (`mojo/`): material harvested from Modular's repositories at pinned commits, our own probes and programs, and godbolt's answers for every one of them (`mojo/golden/`).
|
||||
- **A workspace:** `src/common/workspace.ts` is one piece of work and everything its sources mean. pplus-web's session extends it.
|
||||
- **A library:** pplus-library, the submodule `library/`: verified routines (statistics, numerics, alignment, molecular simulation, sequences) that a program brings in with `USE`, each checked at every level ([docs/library.md](docs/library.md)).
|
||||
- **A command line:** `pixi run cli check|run|prove|fuzz|translate <file>`.
|
||||
|
||||
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
|
||||
|
||||
With [pixi](https://pixi.sh) (it brings the pinned Mojo, Node and Python):
|
||||
Clone with the library 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 test # build, then every test
|
||||
@@ -46,6 +47,11 @@ Every command is a pixi task (`pixi task list` shows them with their description
|
||||
| **Dafny, pinned** ([scripts/dafny.py](scripts/dafny.py)) | |
|
||||
| `dafny-fetch` | Download the pinned Dafny into `.tools/`, checked by SHA-256 (network, once) |
|
||||
| `dafny` | Run the pinned Dafny with the arguments given, e.g. `pixi run dafny verify file.dfy` |
|
||||
| **The library** ([docs/library.md](docs/library.md)) | |
|
||||
| `library-check` | Check every library routine at every level; writes `library/status.json` and `STATUS.md` |
|
||||
| `library-emit` | Regenerate `src/library/generated.ts`, the registry `USE` reads, from `library/` |
|
||||
| `library-verify-mojo` | Ask the pinned Mojo compiler about every Mojo reference of the library (network) |
|
||||
| `library-harness <id> <lang> <level>` | Print the program a reference implementation is run as |
|
||||
| **Write content** | |
|
||||
| `new-exercise <id>` | Start an exercise whose Mojo lives in `mojo/local/<id>.mojo` ([docs/exercises.md](docs/exercises.md)) |
|
||||
| `new-probe <name> <question>` | Start `mojo/probes/<name>.mojo`: one question about the compiler ([docs/mojo-corpus.md](docs/mojo-corpus.md)) |
|
||||
@@ -79,6 +85,7 @@ AGENTS.md rules for changing core (read first)
|
||||
src/
|
||||
common/ the workspace, the problem catalog, the fuzzer, the run view's data, the language
|
||||
reference, the machine presets, the shared types
|
||||
library/ the registry USE reads (generated from library/), and its types
|
||||
engines/pseudo/ the pseudo language and the prover (logic, solver, vcgen in TypeScript), and the course's
|
||||
page widgets for it (excluded from the build; see docs/engines.md)
|
||||
engines/asm86/ the x86-64 model machine, and the course's widgets that draw it (views, hwviews)
|
||||
@@ -89,6 +96,7 @@ src/
|
||||
exercises/ one file per catalog problem
|
||||
curriculum/ a lesson corpus kept as an interpreter fixture
|
||||
syntax/mojo.xml the Mojo words as a KDE syntax for Pandoc (generated; pplus-web copies it)
|
||||
library/ pplus-library, a git submodule: verified routines that programs bring in with USE
|
||||
tests/ node --test against dist/; corpus/ (pseudo programs), prover/ (soundness regressions)
|
||||
mojo/ the Mojo corpus: the pin and lock, harvested material, our programs, godbolt's answers
|
||||
scripts/ the tasks above; scripts/mojo/ is the corpus pipeline; dafny.py the Dafny pin; cli.mjs
|
||||
@@ -103,6 +111,7 @@ docs/ the documents below
|
||||
| [docs/engines.md](docs/engines.md) | The engines, the prover and its soundness, and how the course takes them |
|
||||
| [docs/trust.md](docs/trust.md) | Every verdict core produces: which tool earns it, what it means, and what it does not mean |
|
||||
| [docs/mojo-corpus.md](docs/mojo-corpus.md) | Writing Mojo of our own and moving to a new Mojo version |
|
||||
| [docs/library.md](docs/library.md) | The library: USE, what each check of a routine means, and changing it |
|
||||
| [docs/exercises.md](docs/exercises.md) | Adding a catalog problem |
|
||||
| [docs/sync-coverage.md](docs/sync-coverage.md) | What each translator can say, written by the tests |
|
||||
| [docs/asm-coverage.md](docs/asm-coverage.md) | Which instructions compiled Mojo uses, against what the machine models |
|
||||
@@ -0,0 +1,43 @@
|
||||
# The library
|
||||
|
||||
pplus-library (the submodule `library/`) holds routines written once in pseudo and checked at every level, so a program can use them by name instead of rewriting and re-verifying them, and a learner can open any of them to see exactly what it does. Core reads it through a generated registry (`src/library/generated.ts`, `pixi run library-emit`), so the site needs no files at run time.
|
||||
|
||||
## Using a routine
|
||||
|
||||
```
|
||||
USE md // every routine of the module
|
||||
USE align.MatchScore // one routine
|
||||
```
|
||||
|
||||
USE lines go at the top of a program. From then on a routine is called like the program's own:
|
||||
|
||||
- **The checker** types each call against the routine's parameters. A program may not define a routine of the same name (`library-clash`); an unknown module or routine is an error at the USE line, with the names that exist (`unknown-library`, `unknown-routine`).
|
||||
- **A run** steps over a routine: one step where it is called, one where it hands back, and none of its own lines (they belong to another file). Its contracts are still checked; a broken REQUIRE is reported at the call, naming the routine. To step through a routine, open it in the library.
|
||||
- **The prover** uses the routine's REQUIRE as an obligation at each call and its ENSURE as a fact afterwards, the way it treats the program's own routines. It does not prove the routine again: the library did.
|
||||
- **The Mojo translator** writes each routine the program uses once, before the program's own code, dependencies first, labeled as coming from the library.
|
||||
|
||||
A routine file (`routine.pseudo`) holds USE lines and exactly one FUNCTION or PROCEDURE. A routine that calls another brings it in with USE, so every function in the library is checked on its own.
|
||||
|
||||
## What "verified" means for a routine
|
||||
|
||||
`pixi run library-check` runs every check and records what it found in `library/status.json` and `library/STATUS.md`:
|
||||
|
||||
| Check | Passes when | Recorded as |
|
||||
|---|---|---|
|
||||
| structure | `routine.pseudo` defines exactly the routine `routine.json` names, and nothing else | pass, fail |
|
||||
| pseudo | every case runs; its result is recorded and is what the references are held to | pass, fail |
|
||||
| prover | every obligation of the routine is proved | pass; open (some not proved, none broken); fail (one broken) |
|
||||
| fuzz | 300 generated inputs break no contract and stop no run | pass, fail, skipped |
|
||||
| mojo | the Mojo generated from the pseudo checks, runs in core's interpreter and prints what the pseudo prints | pass, fail, skipped (a construct the interpreter declines) |
|
||||
| a reference, per runner | `cpython`, `cc -O0`, `cc -O2`, core's Mojo `interpreter`, or the pinned compiler on `godbolt` prints the pseudo's results on every case, exactly or within the tolerance `routine.json` states | pass, fail, skipped (the tool is missing), unverified (no stored compiler answer for this exact program) |
|
||||
| proof | the pinned Dafny verifies the proof file, or its stored verdict matches this exact text | pass, fail, unverified |
|
||||
|
||||
A reference implementation is the function alone; the tool writes the program it runs as (the function plus a main that prints each case), and `pixi run library-harness <id> <lang> <level>` prints it. A Mojo reference's answer from the compiler is stored in the routine's `golden/mojo-<level>.json`, keyed by the SHA-256 of that program, by `pixi run library-verify-mojo` (network). A Dafny verdict is stored in `golden/dafny.json`, keyed by the proof's text and the Dafny version.
|
||||
|
||||
What each check does not say is in [trust.md](trust.md#library-routines).
|
||||
|
||||
## Changing the library
|
||||
|
||||
1. Change pplus-library under its [AGENTS.md](../library/AGENTS.md): one routine per file, cases, references with their notes and tolerances, a Dafny proof where one says something.
|
||||
2. In core: `pixi run library-check` (no check may fail), then `pixi run library-emit`.
|
||||
3. Commit pplus-library; commit core with the new `library` pointer and the regenerated registry. `tests/library.test.mjs` fails while the registry is out of date with the checkout.
|
||||
@@ -2,13 +2,13 @@
|
||||
|
||||
<!-- Written by tests/sync-coverage.test.mjs. Do not edit; rerun `npm test` to refresh. -->
|
||||
|
||||
Each translator in `src/sync/` is run over every exercise with pseudo (17), every program in `tests/corpus/` (52), and 17 one-construct fixtures (`tests/helpers/sync-programs.mjs`). 3 of the 86 have pseudo that does not read, by design (they teach the notation's error messages), and are left out below. That leaves **83 programs**.
|
||||
Each translator in `src/sync/` is run over every exercise with pseudo (17), every program in `tests/corpus/` (53), and 17 one-construct fixtures (`tests/helpers/sync-programs.mjs`). 3 of the 87 have pseudo that does not read, by design (they teach the notation's error messages), and are left out below. That leaves **84 programs**.
|
||||
|
||||
| From pseudo to | Says it completely | Says it with a gap or a checker error | Cannot say it |
|
||||
| --- | ---: | ---: | ---: |
|
||||
| Mojo | 80 | 3 | 0 |
|
||||
| lingo | 31 | 0 | 52 |
|
||||
| matho | 3 | 0 | 80 |
|
||||
| Mojo | 81 | 3 | 0 |
|
||||
| lingo | 31 | 0 | 53 |
|
||||
| matho | 3 | 0 | 81 |
|
||||
|
||||
Mojo is a program-for-program translation that always produces something: a line with no faithful spelling becomes a visible `raise Error("not translated: pseudo line N")` and a warning. Lingo and matho must read back as the same program, so what they cannot say exactly they refuse, with the construct and its line, and the pane keeps its last good text.
|
||||
|
||||
@@ -32,7 +32,7 @@ English is read by `readSteps`, whose grammar has no sentence for these.
|
||||
|
||||
| What it has no form for | Programs | Which |
|
||||
| --- | ---: | --- |
|
||||
| steps outside a routine (every English step belongs to a routine) | 50 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 46 more |
|
||||
| steps outside a routine (every English step belongs to a routine) | 51 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 47 more |
|
||||
| a fixed-length ARRAY | 4 | ex:edit-distance, 05-primes-sieve.pseudo, 11-matrix-multiply.pseudo, 15-game-of-life.pseudo |
|
||||
| a BYREF parameter | 3 | 06-fibonacci-memo.pseudo, 10-insertion-sort.pseudo, 26-swap-byref.pseudo |
|
||||
| a HASHMAP whose values are not counts | 3 | ex:translate-codons, 13-stack-brackets.pseudo, 39-constants-codons.pseudo |
|
||||
@@ -64,7 +64,7 @@ An equation lowers to one `FUNCTION` that returns a value; a program with output
|
||||
|
||||
| What it has no form for | Programs | Which |
|
||||
| --- | ---: | --- |
|
||||
| steps outside a function (an equation is a function) | 46 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 42 more |
|
||||
| steps outside a function (an equation is a function) | 47 | 01-arithmetic.pseudo, 02-temperature.pseudo, 03-compound-interest.pseudo, 04-gcd-recursion.pseudo, and 43 more |
|
||||
| a function that answers LIST (equations answer numbers) | 5 | ex:match, ex:match-proved, ex:match-off-by-one, ex:match-reset, and 1 more |
|
||||
| a function that answers STRING (equations answer numbers) | 5 | ex:revcomp, fixture:string-build, fixture:slice, fixture:case, and 1 more |
|
||||
| a function that answers BOOL (equations answer numbers) | 3 | ex:binary-search, fixture:early-return, fixture:forall |
|
||||
|
||||
@@ -55,3 +55,17 @@ The Prove tab reports every obligation in three statuses (`src/engines/pseudo/vc
|
||||
|---|---|---|---|
|
||||
| Registers, caches, pipeline and counters in the Hardware area | The model machine (`src/engines/asm86/`), on the preset machine named in Setup | What that model does with these instructions | A measurement of a real processor. Cycle counts are a teaching model; compare a run with itself across edits |
|
||||
| "stopped: … standard library, not on the model machine" | A call into a function the model does not have | The real program would enter the library here | That the library call does anything in particular |
|
||||
|
||||
## Library routines
|
||||
|
||||
A routine of pplus-library (`USE md`) carries the record of `pixi run library-check` ([library.md](library.md)).
|
||||
|
||||
| Shown | Earned by | Means | Does not mean |
|
||||
|---|---|---|---|
|
||||
| **Cases pass** | Running the pseudo on the cases in `routine.json` | The routine gives those results; they are what every reference is held to | That the results are right for other inputs |
|
||||
| **Prover: pass** | Every obligation of the routine proved, as for any pseudo | Its contracts hold for every input that meets its REQUIRE, in the notation's number model | Anything about the value of FLOAT arithmetic beyond what the contracts say |
|
||||
| **Prover: open** | Some obligation not proved, none broken | The routine's comment says which and why (usually FLOAT rounding, which is opaque to the prover) | That it is wrong |
|
||||
| **A reference agrees** | Python, C at -O0 and -O2, core's Mojo interpreter, or the pinned compiler, run on the cases | That implementation, at that level, prints the pseudo's results exactly, or within the stated tolerance | That it agrees on other inputs, or at other optimization flags |
|
||||
| **Mojo: unverified** | No stored answer from the pinned compiler for that exact program | Not yet asked (`pixi run library-verify-mojo`) | That it fails |
|
||||
| **Proof: pass** | The pinned Dafny verified the proof file (or its stored verdict for this exact text) | The method is correct over exact numbers, as the proof states it | That the FLOAT version computes the same digits: rounding is outside the proof |
|
||||
|
||||
Submodule
+1
Submodule library added at df12b2a008.
@@ -34,6 +34,12 @@ engines-export = { cmd = "node scripts/engines-export.mjs {{ static }}", args =
|
||||
dafny-fetch = { cmd = "python scripts/dafny.py fetch", description = "Download the pinned Dafny into .tools/, checked by SHA-256 (network, once)" }
|
||||
dafny = { cmd = "python scripts/dafny.py", description = "Run the pinned Dafny with the arguments given, e.g. pixi run dafny verify file.dfy (fetches it first if missing)" }
|
||||
|
||||
# --- the library (library/, the pplus-library submodule; docs/library.md) ---
|
||||
library-check = { cmd = "node scripts/library.mjs check", depends-on = ["build"], description = "Check every library routine at every level (cases, prover, fuzzer, generated Mojo, every reference, the Dafny proof); writes library/status.json and STATUS.md" }
|
||||
library-emit = { cmd = "node scripts/library.mjs emit", depends-on = ["build"], description = "Regenerate src/library/generated.ts, the registry USE reads, from library/" }
|
||||
library-verify-mojo = { cmd = "node scripts/library.mjs mojo-sources | python scripts/library_godbolt.py", depends-on = ["build"], description = "Ask the pinned Mojo compiler about every Mojo reference of the library and store the answers (network)" }
|
||||
library-harness = { cmd = "node scripts/library.mjs harness {{ id }} {{ lang }} {{ level }}", args = ["id", "lang", "level"], depends-on = ["build"], description = "Print the program a reference implementation is run as, e.g. pixi run library-harness md.LennardJones c multiply" }
|
||||
|
||||
# --- write content ---------------------------------------------------------
|
||||
new-exercise = { cmd = "node scripts/new-exercise.mjs {{ id }}", args = ["id"], description = "Start an exercise: mojo/local/<id>.mojo and src/exercises/<id>.ts, registered in index.ts" }
|
||||
new-probe = { cmd = "node scripts/mojo/new-program.mjs probe {{ name }} \"{{ question }}\"", args = ["name", "question"], description = "Start mojo/probes/<name>.mojo: one question about the pinned compiler" }
|
||||
@@ -59,5 +65,5 @@ mojo-probes-local = { cmd = "for f in mojo/probes/*.mojo; do echo \"== $f\"; moj
|
||||
mojo-update = { depends-on = ["mojo-harvest", "mojo-verify", "mojo-status", "test"], description = "After editing mojo/pin.json: harvest, verify, status, test" }
|
||||
|
||||
# --- ship ------------------------------------------------------------------
|
||||
ci = { depends-on = ["test", "mojo-status-strict"], description = "What CI runs: every test, and no program of ours failing" }
|
||||
ci = { depends-on = ["test", "mojo-status-strict"], description = "What CI runs: every test (the library's registry up to date among them), and no program of ours failing" }
|
||||
package = { cmd = "python scripts/package.py", description = "Zip the files git tracks (and new ones it does not ignore) into package/ for sharing" }
|
||||
@@ -0,0 +1,460 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* The library's tools: check every routine of pplus-library (the submodule library/) at every level, record
|
||||
* what was found in the library, and generate core's registry from it.
|
||||
*
|
||||
* node scripts/library.mjs check [--dir library] [--only stats.Mean] every check; writes status.json, STATUS.md, goldens
|
||||
* node scripts/library.mjs emit [--check] library/ -> src/library/generated.ts
|
||||
* node scripts/library.mjs harness <id> <lang> <level> print the program a reference is run as
|
||||
* node scripts/library.mjs mojo-sources [--out dir] write each Mojo reference's harness, for godbolt
|
||||
*
|
||||
* The checks of one routine:
|
||||
* structure routine.pseudo defines exactly the routine routine.json names, and nothing else (USE lines aside)
|
||||
* pseudo every case runs; its result is recorded and becomes what the references are held to
|
||||
* prover every obligation of the routine: pass when all are proved, open when some are not, fail when broken
|
||||
* fuzz the fuzzer finds no input that breaks a contract or stops the run
|
||||
* mojo the Mojo generated from the pseudo checks, runs in core's interpreter and prints what the pseudo prints
|
||||
* and for each reference implementation, per way of running it:
|
||||
* cpython python3 runs it on every case cc -O0, cc -O2 cc compiles and runs it on every case
|
||||
* interpreter core's Mojo interpreter runs it godbolt the stored answer of the pinned compiler
|
||||
* and the proof, if there is one: the pinned Dafny verifies it (or its stored verdict for this exact text).
|
||||
*
|
||||
* Needs a build (dist/). Python and a C compiler are used when they are on the PATH; without them those checks
|
||||
* are recorded as skipped, never as passed.
|
||||
*/
|
||||
import fs from 'node:fs';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
import crypto from 'node:crypto';
|
||||
import { execFileSync, spawnSync } from 'node:child_process';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const CORE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
||||
const args = process.argv.slice(2);
|
||||
const cmd = args[0];
|
||||
const opt = (name, dflt = null) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : dflt; };
|
||||
const flag = (name) => args.includes(`--${name}`);
|
||||
const LIB = path.resolve(opt('dir', path.join(CORE, 'library')));
|
||||
const GENERATED = path.join(CORE, 'src', 'library', 'generated.ts');
|
||||
|
||||
const sha256 = (s) => crypto.createHash('sha256').update(s).digest('hex');
|
||||
const readJson = (p) => JSON.parse(fs.readFileSync(p, 'utf8'));
|
||||
const writeIfChanged = (p, text) => { if (!fs.existsSync(p) || fs.readFileSync(p, 'utf8') !== text) { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, text); return true; } return false; };
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Reading the library */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
/** Every module and routine on disk, with its sources, and the status last recorded for it. */
|
||||
export function load(dir = LIB) {
|
||||
if (!fs.existsSync(path.join(dir, 'modules'))) throw new Error(`no library at ${dir}: check out the submodule (git submodule update --init) or pass --dir`);
|
||||
const status = fs.existsSync(path.join(dir, 'status.json')) ? readJson(path.join(dir, 'status.json')).routines || {} : {};
|
||||
const modules = [];
|
||||
for (const m of fs.readdirSync(path.join(dir, 'modules')).sort()) {
|
||||
const mdir = path.join(dir, 'modules', m);
|
||||
if (!fs.existsSync(path.join(mdir, 'module.json'))) continue;
|
||||
const meta = readJson(path.join(mdir, 'module.json'));
|
||||
const routines = [];
|
||||
for (const r of fs.readdirSync(mdir).sort()) {
|
||||
const rdir = path.join(mdir, r);
|
||||
if (!fs.existsSync(path.join(rdir, 'routine.json'))) continue;
|
||||
const rm = readJson(path.join(rdir, 'routine.json'));
|
||||
const id = `${meta.name}.${rm.name}`;
|
||||
const st = status[id] || {};
|
||||
routines.push({
|
||||
id, module: meta.name, name: rm.name, dir: path.relative(dir, rdir).split(path.sep).join('/'),
|
||||
summary: rm.summary || '', tags: rm.tags || [], sources: rm.sources || [],
|
||||
source: fs.readFileSync(path.join(rdir, 'routine.pseudo'), 'utf8'),
|
||||
cases: (rm.cases || []).map((c, i) => ({ ...c, ...(st.cases?.[i]?.call === c.call ? { result: st.cases[i].result } : {}) })),
|
||||
references: (rm.references || []).map((ref) => ({
|
||||
lang: ref.lang, level: ref.level, file: ref.file, note: ref.note || '',
|
||||
...(ref.rel !== undefined ? { rel: ref.rel } : {}), ...(ref.abs !== undefined ? { abs: ref.abs } : {}),
|
||||
source: fs.readFileSync(path.join(rdir, ref.file), 'utf8'),
|
||||
checks: st.references?.[`${ref.lang}/${ref.level}`] || {},
|
||||
})),
|
||||
...(rm.proof ? { proof: { lang: rm.proof.lang, file: rm.proof.file, note: rm.proof.note || '', source: fs.readFileSync(path.join(rdir, rm.proof.file), 'utf8'), check: st.proof || { status: 'unverified', detail: 'not checked yet' } } } : {}),
|
||||
checks: st.checks || {},
|
||||
});
|
||||
}
|
||||
modules.push({ name: meta.name, title: meta.title, summary: meta.summary, routines });
|
||||
}
|
||||
return modules;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Values in other languages */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
const floatText = (v) => { const s = String(v); return /[.e]/.test(s) || !Number.isFinite(v) ? s : `${s}.0`; };
|
||||
const items = (v) => (Array.isArray(v) ? v : v?.data ? v.data : []);
|
||||
|
||||
function pyLiteral(v, t) {
|
||||
switch (t?.k) {
|
||||
case 'FLOAT': return floatText(v).replace('e+', 'e');
|
||||
case 'INTEGER': return String(v);
|
||||
case 'BOOL': return v ? 'True' : 'False';
|
||||
case 'CHAR': case 'STRING': return JSON.stringify(v);
|
||||
case 'LIST': case 'ARRAY': return `[${items(v).map((x) => pyLiteral(x, t.of)).join(', ')}]`;
|
||||
default: throw new Error(`no Python literal for ${t?.k}`);
|
||||
}
|
||||
}
|
||||
|
||||
function mojoType(t) {
|
||||
switch (t?.k) {
|
||||
case 'FLOAT': return t.bits === 32 ? 'Float32' : 'Float64';
|
||||
case 'INTEGER': return t.bits ? `${t.signed ? 'Int' : 'UInt'}${t.bits}` : 'Int';
|
||||
case 'BOOL': return 'Bool';
|
||||
case 'CHAR': case 'STRING': return 'String';
|
||||
case 'LIST': case 'ARRAY': return `List[${mojoType(t.of)}]`;
|
||||
default: throw new Error(`no Mojo type for ${t?.k}`);
|
||||
}
|
||||
}
|
||||
|
||||
function mojoLiteral(v, t) {
|
||||
switch (t?.k) {
|
||||
case 'FLOAT': return floatText(v).replace('e+', 'e');
|
||||
case 'INTEGER': return String(v);
|
||||
case 'BOOL': return v ? 'True' : 'False';
|
||||
case 'CHAR': case 'STRING': return JSON.stringify(v);
|
||||
case 'LIST': case 'ARRAY': return `${mojoType(t)}(${items(v).map((x) => mojoLiteral(x, t.of)).join(', ')})`;
|
||||
default: throw new Error(`no Mojo literal for ${t?.k}`);
|
||||
}
|
||||
}
|
||||
|
||||
/** A C argument list for one call, with the declarations it needs first: a list becomes (array, length). */
|
||||
function cArgs(vals, params, tag) {
|
||||
const decls = []; const out = [];
|
||||
vals.forEach((v, i) => {
|
||||
const t = params[i].type;
|
||||
switch (t?.k) {
|
||||
case 'FLOAT': out.push(floatText(v)); break;
|
||||
case 'INTEGER': out.push(`${v}L`); break;
|
||||
case 'BOOL': out.push(v ? '1' : '0'); break;
|
||||
case 'CHAR': out.push(`'${v.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`); break;
|
||||
case 'STRING': out.push(JSON.stringify(v)); break;
|
||||
case 'LIST': case 'ARRAY': {
|
||||
const xs = items(v);
|
||||
if (t.of?.k !== 'FLOAT' && t.of?.k !== 'INTEGER') throw new Error('C lists hold numbers only');
|
||||
const ct = t.of.k === 'FLOAT' ? 'double' : 'long';
|
||||
const name = `a${tag}_${i}`;
|
||||
decls.push(`${ct} ${name}[${Math.max(1, xs.length)}] = {${xs.length ? xs.map((x) => (t.of.k === 'FLOAT' ? floatText(x) : `${x}L`)).join(', ') : '0'}};`);
|
||||
out.push(name, `${xs.length}L`);
|
||||
break;
|
||||
}
|
||||
default: throw new Error(`no C argument for ${t?.k}`);
|
||||
}
|
||||
});
|
||||
return { decls, args: out };
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* The checks */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
const ok = (detail) => ({ status: 'pass', detail });
|
||||
const bad = (detail) => ({ status: 'fail', detail });
|
||||
const skip = (detail) => ({ status: 'skipped', detail });
|
||||
const open = (detail) => ({ status: 'open', detail });
|
||||
const unverified = (detail) => ({ status: 'unverified', detail });
|
||||
|
||||
function have(cmdName) { return spawnSync(cmdName, ['--version'], { encoding: 'utf8' }).status === 0; }
|
||||
|
||||
/** Does a printed value agree with the pseudo's, within the reference's tolerance? */
|
||||
function agrees(printed, want, t, rel = 0, abs = 0) {
|
||||
const s = String(printed).trim();
|
||||
if (t?.k === 'FLOAT' || t?.k === 'INTEGER') {
|
||||
const got = Number(s.replace(/^inf$/i, 'Infinity').replace(/^-inf$/i, '-Infinity').replace(/^nan$/i, 'NaN'));
|
||||
if (Number.isNaN(got) && Number.isNaN(want)) return true;
|
||||
if (Number.isNaN(got)) return false;
|
||||
if (got === want) return true;
|
||||
return Math.abs(got - want) <= Math.max(rel * Math.max(Math.abs(got), Math.abs(want)), abs);
|
||||
}
|
||||
if (t?.k === 'BOOL') return ['true', '1'].includes(s.toLowerCase()) === Boolean(want);
|
||||
return s === String(want);
|
||||
}
|
||||
|
||||
function compareLines(stdout, wants, t, rel, abs) {
|
||||
const got = stdout.replace(/\n$/, '').split('\n');
|
||||
if (got.length !== wants.length) return `printed ${got.length} line(s) for ${wants.length} case(s)`;
|
||||
for (let i = 0; i < wants.length; i++) if (!agrees(got[i], wants[i].value, t, rel, abs)) return `case ${i + 1} (${wants[i].call}) printed ${got[i]}, and the pseudo gives ${wants[i].text}`;
|
||||
return null;
|
||||
}
|
||||
|
||||
/** The program a reference implementation is run as: its source, plus a main that prints each case. */
|
||||
function harness(lang, ref, fname, sub, calls) {
|
||||
const params = sub.params;
|
||||
if (lang === 'python') {
|
||||
return `import importlib.util\nspec = importlib.util.spec_from_file_location("ref", __REF__)\nref = importlib.util.module_from_spec(spec)\nspec.loader.exec_module(ref)\n${calls.map((c) => `print(repr(ref.${fname}(${c.args.map((v, i) => pyLiteral(v, params[i].type)).join(', ')})))`).join('\n')}\n`;
|
||||
}
|
||||
if (lang === 'mojo') {
|
||||
return `${ref.source.replace(/\s+$/, '')}\n\n\ndef main() raises:\n${calls.map((c) => ` print(${fname}(${c.args.map((v, i) => mojoLiteral(v, params[i].type)).join(', ')}))`).join('\n')}\n`;
|
||||
}
|
||||
if (lang === 'c') {
|
||||
const fmt = sub.returns?.k === 'FLOAT' ? '%.17g' : '%ld';
|
||||
const body = calls.map((c, k) => { const a = cArgs(c.args, params, k); return ` { ${a.decls.join(' ')} printf("${fmt}\\n", ${fname}(${a.args.join(', ')})); }`; }).join('\n');
|
||||
return `#include <stdio.h>\n\n${ref.source.replace(/\s+$/, '')}\n\nint main(void) {\n${body}\n return 0;\n}\n`;
|
||||
}
|
||||
throw new Error(`no harness for ${lang}`);
|
||||
}
|
||||
|
||||
export async function checkLibrary(dir = LIB, only = null) {
|
||||
const { setLibrary } = await import(path.join(CORE, 'dist/library/registry.js'));
|
||||
const svc = await import(path.join(CORE, 'dist/services/pseudo.js'));
|
||||
const { parseExpression } = await import(path.join(CORE, 'dist/engines/pseudo/parse.js'));
|
||||
const { evaluateConstant } = await import(path.join(CORE, 'dist/engines/pseudo/interp.js'));
|
||||
const { formatValue } = await import(path.join(CORE, 'dist/engines/pseudo/lang.js'));
|
||||
const { pseudoToMojo, snake } = await import(path.join(CORE, 'dist/sync/pseudo-to-mojo.js'));
|
||||
const { checkMojo } = await import(path.join(CORE, 'dist/mojo/check.js'));
|
||||
const { runMojo } = await import(path.join(CORE, 'dist/mojo/interp.js'));
|
||||
const { sameOutput } = await import(path.join(CORE, 'dist/sync/compare.js'));
|
||||
|
||||
const modules = load(dir);
|
||||
setLibrary(modules);
|
||||
const pin = readJson(path.join(CORE, 'mojo', 'pin.json'));
|
||||
const dafny = (() => { try { const p = execFileSync('python3', [path.join(CORE, 'scripts', 'dafny.py'), 'path'], { encoding: 'utf8' }).trim(); return fs.existsSync(p) ? p : null; } catch { return null; } })();
|
||||
const dafnyVersion = (() => { try { return readJson(path.join(CORE, 'scripts', 'dafny.json')).version; } catch { return null; } })() || (() => { const m = /VERSION = "([^"]+)"/.exec(fs.readFileSync(path.join(CORE, 'scripts', 'dafny.py'), 'utf8')); return m ? m[1] : 'unknown'; })();
|
||||
const python = have('python3');
|
||||
const cc = have('cc');
|
||||
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pplus-library-'));
|
||||
const out = {};
|
||||
for (const m of modules) {
|
||||
for (const r of m.routines) {
|
||||
if (only && r.id !== only) { continue; }
|
||||
const rdir = path.join(dir, r.dir);
|
||||
const rec = { checks: {}, cases: [], references: {}, proof: undefined };
|
||||
out[r.id] = rec;
|
||||
const st = svc.studyOf(r.source);
|
||||
const program = st.program?.program;
|
||||
// structure
|
||||
const subs = program ? [...program.subs.values()] : [];
|
||||
if (!st.ok) { rec.checks.structure = bad(`the pseudo does not check: ${st.diagnostics.filter((d) => d.severity === 'error').map((d) => `line ${d.line}: ${d.message}`).join('; ')}`); continue; }
|
||||
if (subs.length !== 1 || subs[0].name.toUpperCase() !== r.name.toUpperCase()) { rec.checks.structure = bad(`routine.pseudo defines ${subs.map((s) => s.name).join(', ') || 'nothing'}; it must define exactly ${r.name} (helpers are routines of their own, brought in with USE)`); continue; }
|
||||
if (program.main.body.length) { rec.checks.structure = bad(`routine.pseudo has lines outside ${r.name} (line ${program.main.body[0].line}); a routine file holds USE lines and the routine only`); continue; }
|
||||
const sub = subs[0];
|
||||
rec.checks.structure = ok(`defines ${sub.kind === 'Function' ? 'FUNCTION' : 'PROCEDURE'} ${sub.name}${program.libs?.size ? `, using ${[...program.libs.values()].map((x) => x.lib.id).join(', ')}` : ''}`);
|
||||
// pseudo: every case
|
||||
const calls = [];
|
||||
let caseFail = null;
|
||||
for (const c of r.cases) {
|
||||
const p = parseExpression(c.call);
|
||||
let entry = { call: c.call };
|
||||
try {
|
||||
if (p.diags.some((d) => d.severity === 'error') || p.expr.kind !== 'CallExpr' || p.expr.name.toUpperCase() !== r.name.toUpperCase()) throw new Error(`"${c.call}" is not a call of ${r.name}`);
|
||||
const vals = p.expr.args.map((a) => evaluateConstant(program, a));
|
||||
const tr = svc.runPseudo(st, { call: c.call, maxSteps: 2000000 });
|
||||
if (tr.error) throw new Error(`${c.call} stops: ${tr.error.message}`);
|
||||
const result = tr.raw.result;
|
||||
entry = { call: c.call, result: formatValue(result, sub.returns, { max: 1000 }) };
|
||||
calls.push({ call: c.call, args: vals, value: result, text: entry.result });
|
||||
} catch (e) { caseFail = caseFail || e.message; }
|
||||
rec.cases.push(entry);
|
||||
}
|
||||
rec.checks.pseudo = caseFail ? bad(caseFail) : ok(`${calls.length} case(s) run`);
|
||||
// prover
|
||||
const pr = svc.provePseudo(st);
|
||||
const obs = pr.units.flatMap((u) => u.obligations);
|
||||
const broken = obs.filter((o) => o.status === 'broken');
|
||||
const notProved = obs.filter((o) => o.status !== 'proved');
|
||||
rec.checks.prover = broken.length ? bad(`${broken.length} obligation(s) broken: ${broken.map((o) => `${o.kind}@${o.line} (${o.label})`).join('; ')}`)
|
||||
: notProved.length ? open(`${obs.length - notProved.length} of ${obs.length} obligation(s) proved; open: ${notProved.map((o) => `${o.kind}@${o.line} (${o.label})`).join('; ')}`)
|
||||
: ok(`all ${obs.length} obligation(s) proved`);
|
||||
// fuzz
|
||||
const props = svc.propertiesPseudo(st, r.name)[0];
|
||||
rec.checks.fuzz = !props ? skip('no routine to fuzz') : props.problem ? skip(`the fuzzer cannot generate inputs: ${props.problem}`)
|
||||
: props.failures.length ? bad(`${props.failures.length} failing input(s), first: ${props.failures[0].call}: ${props.failures[0].message}`)
|
||||
: ok(`no failure in ${props.checked} generated input(s)`);
|
||||
// the Mojo generated from the pseudo, on every case
|
||||
if (calls.length) {
|
||||
const prog = `USE ${r.module}.${r.name}\n${calls.map((c) => `OUTPUT ${c.call}`).join('\n')}\n`;
|
||||
const want = svc.runPseudo(svc.studyOf(prog), {}).output.join('\n');
|
||||
const mj = pseudoToMojo(prog);
|
||||
if ('unsupported' in mj) rec.checks.mojo = bad(`the translator refused: ${mj.unsupported.map((d) => d.message).join('; ')}`);
|
||||
else {
|
||||
const gaps = mj.notes.filter((n) => n.id === 'translate-gap');
|
||||
const ck = checkMojo(mj.source);
|
||||
const errs = ck.diagnostics.filter((d) => d.severity === 'error');
|
||||
if (gaps.length) rec.checks.mojo = skip(`the translator has no Mojo for: ${gaps.map((g) => g.message.replace(/^.*?\(|\)\..*$/g, '')).join('; ')}`);
|
||||
else if (errs.length) rec.checks.mojo = bad(`the generated Mojo has checker errors: ${errs.map((d) => `L${d.line} ${d.message}`).join(' | ')}`);
|
||||
else {
|
||||
const run = runMojo(ck.module, mj.source, { maxSteps: 4000000 });
|
||||
rec.checks.mojo = run.refused ? skip(`core's Mojo interpreter declines ${run.refused}; the compiler's answer is needed`)
|
||||
: run.exitCode !== 0 ? bad(`the generated Mojo stopped (exit ${run.exitCode})`)
|
||||
: sameOutput(want, run.stdout) ? ok('the generated Mojo prints what the pseudo prints on every case, in core\'s interpreter') : bad(`the generated Mojo printed ${JSON.stringify(run.stdout.slice(0, 120))}; the pseudo printed ${JSON.stringify(want.slice(0, 120))}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
// references
|
||||
const fname = snake(r.name);
|
||||
for (const ref of r.references) {
|
||||
const checks = {};
|
||||
rec.references[`${ref.lang}/${ref.level}`] = checks;
|
||||
if (!calls.length) { checks.cases = skip('no case ran in pseudo, so there is nothing to hold it to'); continue; }
|
||||
const rel = ref.rel ?? 0; const abs = ref.abs ?? 0;
|
||||
const tol = rel || abs ? ` (within rel ${rel}, abs ${abs})` : ' (exactly)';
|
||||
try {
|
||||
if (ref.lang === 'python') {
|
||||
if (!python) { checks.cpython = skip('python3 is not on the PATH'); continue; }
|
||||
const h = harness('python', ref, fname, sub, calls).replace('__REF__', JSON.stringify(path.join(rdir, ref.file)));
|
||||
const p = spawnSync('python3', ['-c', h], { encoding: 'utf8', timeout: 60000 });
|
||||
if (p.status !== 0) { checks.cpython = bad(`python3 stopped: ${(p.stderr || '').trim().split('\n').pop()}`); continue; }
|
||||
const diff = compareLines(p.stdout, calls, sub.returns, rel, abs);
|
||||
checks.cpython = diff ? bad(diff) : ok(`agrees with the pseudo on ${calls.length} case(s)${tol}`);
|
||||
} else if (ref.lang === 'c') {
|
||||
if (!cc) { checks['cc -O0'] = skip('no C compiler (cc) on the PATH'); continue; }
|
||||
const src = harness('c', ref, fname, sub, calls);
|
||||
const file = path.join(tmp, `${fname}-${ref.level}.c`);
|
||||
fs.writeFileSync(file, src);
|
||||
for (const level of ['-O0', '-O2']) {
|
||||
const bin = path.join(tmp, `${fname}-${ref.level}${level}`);
|
||||
const c = spawnSync('cc', ['-std=c11', level, '-o', bin, file, '-lm'], { encoding: 'utf8' });
|
||||
if (c.status !== 0) { checks[`cc ${level}`] = bad(`cc ${level} failed: ${(c.stderr || '').trim().split('\n')[0]}`); continue; }
|
||||
const p = spawnSync(bin, [], { encoding: 'utf8', timeout: 60000 });
|
||||
const diff = p.status !== 0 ? `exited ${p.status}` : compareLines(p.stdout, calls, sub.returns, rel, abs);
|
||||
checks[`cc ${level}`] = diff ? bad(diff) : ok(`agrees with the pseudo on ${calls.length} case(s)${tol}`);
|
||||
}
|
||||
} else if (ref.lang === 'mojo') {
|
||||
const src = harness('mojo', ref, fname, sub, calls);
|
||||
const ck = checkMojo(src);
|
||||
const errs = ck.diagnostics.filter((d) => d.severity === 'error');
|
||||
if (errs.length) checks.interpreter = bad(`core's Mojo checker reports: ${errs.map((d) => `L${d.line} ${d.message}`).join(' | ')}`);
|
||||
else {
|
||||
const run = runMojo(ck.module, src, { maxSteps: 4000000 });
|
||||
const diff = run.refused ? null : run.exitCode !== 0 ? `stopped (exit ${run.exitCode})` : compareLines(run.stdout, calls, sub.returns, rel, abs);
|
||||
checks.interpreter = run.refused ? skip(`core's Mojo interpreter declines ${run.refused}`) : diff ? bad(diff) : ok(`agrees with the pseudo on ${calls.length} case(s) in core's interpreter${tol}`);
|
||||
}
|
||||
// the compiler's stored answer for this exact program
|
||||
const gfile = path.join(rdir, 'golden', `mojo-${ref.level}.json`);
|
||||
const g = fs.existsSync(gfile) ? readJson(gfile) : null;
|
||||
if (!g || g.source_sha256 !== sha256(src) || g.compiler !== pin.godbolt.compiler) checks.godbolt = unverified(`no stored answer from ${pin.godbolt.compiler} for this program: pixi run library-verify-mojo`);
|
||||
else if (!g.result?.compiled) checks.godbolt = bad(`${pin.godbolt.compiler} did not compile it: ${(g.result?.buildStderr || '').split('\n')[0]}`);
|
||||
else {
|
||||
const diff = g.result.exitCode !== 0 ? `exited ${g.result.exitCode}` : compareLines(g.result.stdout, calls, sub.returns, rel, abs);
|
||||
checks.godbolt = diff ? bad(diff) : ok(`${pin.godbolt.compiler} agrees with the pseudo on ${calls.length} case(s)${tol}`);
|
||||
}
|
||||
} else checks.cases = skip(`no runner for ${ref.lang} yet`);
|
||||
} catch (e) {
|
||||
checks.harness = bad(`could not build the harness: ${e.message}`);
|
||||
}
|
||||
}
|
||||
// proof
|
||||
if (r.proof) {
|
||||
const gfile = path.join(rdir, 'golden', 'dafny.json');
|
||||
const src = r.proof.source;
|
||||
const flags = ['verify', '--resource-limit', '20000000'];
|
||||
if (dafny) {
|
||||
const p = spawnSync(dafny, [...flags, path.join(rdir, r.proof.file)], { encoding: 'utf8', timeout: 600000 });
|
||||
const summary = /Dafny program verifier finished with (.*)/.exec(p.stdout || '')?.[1] || (p.stdout || p.stderr || '').trim().split('\n').pop();
|
||||
const pass = p.status === 0 && / 0 errors/.test(summary);
|
||||
rec.proof = pass ? ok(`Dafny ${dafnyVersion}: ${summary}`) : bad(`Dafny ${dafnyVersion}: ${summary}`);
|
||||
writeIfChanged(gfile, `${JSON.stringify({ tool: 'dafny', version: dafnyVersion, flags, source_sha256: sha256(src), verdict: pass ? 'verified' : 'failed', summary }, null, 2)}\n`);
|
||||
} else {
|
||||
const g = fs.existsSync(gfile) ? readJson(gfile) : null;
|
||||
rec.proof = g && g.source_sha256 === sha256(src) ? (g.verdict === 'verified' ? ok(`Dafny ${g.version} (stored answer): ${g.summary}`) : bad(`Dafny ${g.version} (stored answer): ${g.summary}`))
|
||||
: unverified('the pinned Dafny is not fetched (pixi run dafny-fetch) and there is no stored verdict for this text');
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
fs.rmSync(tmp, { recursive: true, force: true });
|
||||
return { modules, results: out };
|
||||
}
|
||||
|
||||
const ORDER = ['structure', 'pseudo', 'prover', 'fuzz', 'mojo'];
|
||||
|
||||
function statusMarkdown(modules, results) {
|
||||
const mark = (c) => (!c ? '·' : { pass: 'pass', fail: '**fail**', open: 'open', skipped: 'skipped', unverified: 'unverified' }[c.status] || c.status);
|
||||
const lines = ['# Library status', '', '<!-- Written by `pixi run library-check` in pplus-core. Do not edit. -->', '',
|
||||
'Each routine, at each level. *pass*: checked and agrees; *open*: the prover could not finish every obligation (nothing is wrong, nothing is proved); *skipped*: the tool is not available here, or it declines the construct; *unverified*: no stored answer for this exact text yet.', ''];
|
||||
for (const m of modules) {
|
||||
lines.push(`## ${m.title} (\`${m.name}\`)`, '', '| Routine | Cases | Prover | Fuzz | Generated Mojo | References | Proof |', '| --- | --- | --- | --- | --- | --- | --- |');
|
||||
for (const r of m.routines) {
|
||||
const res = results[r.id];
|
||||
if (!res) continue;
|
||||
const refs = Object.entries(res.references).map(([k, checks]) => `${k}: ${Object.entries(checks).map(([how, c]) => `${how} ${mark(c)}`).join(', ')}`).join('<br>');
|
||||
lines.push(`| \`${r.id}\` | ${mark(res.checks.pseudo)} | ${mark(res.checks.prover)} | ${mark(res.checks.fuzz)} | ${mark(res.checks.mojo)} | ${refs || '·'} | ${res.proof ? `dafny ${mark(res.proof)}` : '·'} |`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
lines.push('## Details', '');
|
||||
for (const m of modules) for (const r of m.routines) {
|
||||
const res = results[r.id];
|
||||
if (!res) continue;
|
||||
lines.push(`### ${r.id}`, '');
|
||||
for (const k of ORDER) if (res.checks[k]) lines.push(`- ${k}: ${res.checks[k].status}. ${res.checks[k].detail}`);
|
||||
for (const [k, checks] of Object.entries(res.references)) for (const [how, c] of Object.entries(checks)) lines.push(`- ${k}, ${how}: ${c.status}. ${c.detail}`);
|
||||
if (res.proof) lines.push(`- proof: ${res.proof.status}. ${res.proof.detail}`);
|
||||
lines.push('');
|
||||
}
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Emitting core's registry */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
function emitText(dir = LIB) {
|
||||
const modules = load(dir);
|
||||
let commit = '';
|
||||
try { commit = execFileSync('git', ['-C', dir, 'rev-parse', '--short=12', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { /* not a checkout */ }
|
||||
return `// Generated by scripts/library.mjs emit from library/ (pplus-library). Do not edit; run pixi run library-emit.\nimport type { LibraryModule } from './types.js';\n\nexport const LIBRARY_COMMIT = ${JSON.stringify(commit)};\nexport const LIBRARY_MODULES: LibraryModule[] = ${JSON.stringify(modules, null, 2)};\n`;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Command line */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
||||
if (cmd === 'check') {
|
||||
const only = opt('only');
|
||||
const { modules, results } = await checkLibrary(LIB, only);
|
||||
const prior = fs.existsSync(path.join(LIB, 'status.json')) ? readJson(path.join(LIB, 'status.json')).routines || {} : {};
|
||||
const merged = only ? { ...prior, ...results } : results;
|
||||
const sorted = Object.fromEntries(Object.keys(merged).sort().map((k) => [k, merged[k]]));
|
||||
writeIfChanged(path.join(LIB, 'status.json'), `${JSON.stringify({ comment: 'Written by pixi run library-check in pplus-core. Do not edit.', routines: sorted }, null, 2)}\n`);
|
||||
writeIfChanged(path.join(LIB, 'STATUS.md'), `${statusMarkdown(modules, sorted)}\n`);
|
||||
let failed = 0;
|
||||
for (const [id, res] of Object.entries(results)) {
|
||||
const all = [...Object.entries(res.checks), ...Object.entries(res.references).flatMap(([k, c]) => Object.entries(c).map(([h, v]) => [`${k} ${h}`, v])), ...(res.proof ? [['proof', res.proof]] : [])];
|
||||
for (const [k, c] of all) if (c.status === 'fail') { failed++; console.log(`FAIL ${id} ${k}: ${c.detail}`); }
|
||||
console.log(`${id}: ${all.map(([k, c]) => `${k}=${c.status}`).join(' ')}`);
|
||||
}
|
||||
console.log(failed ? `${failed} failing check(s)` : 'no failing check');
|
||||
process.exit(failed ? 1 : 0);
|
||||
} else if (cmd === 'emit') {
|
||||
const text = emitText(LIB);
|
||||
if (flag('check')) {
|
||||
const cur = fs.existsSync(GENERATED) ? fs.readFileSync(GENERATED, 'utf8') : '';
|
||||
if (cur !== text) { console.error('src/library/generated.ts is out of date with library/: run pixi run library-emit'); process.exit(1); }
|
||||
console.log('src/library/generated.ts is up to date');
|
||||
} else console.log(writeIfChanged(GENERATED, text) ? 'wrote src/library/generated.ts' : 'src/library/generated.ts unchanged');
|
||||
} else if (cmd === 'harness' || cmd === 'mojo-sources') {
|
||||
const svc = await import(path.join(CORE, 'dist/services/pseudo.js'));
|
||||
const { setLibrary } = await import(path.join(CORE, 'dist/library/registry.js'));
|
||||
const { parseExpression } = await import(path.join(CORE, 'dist/engines/pseudo/parse.js'));
|
||||
const { evaluateConstant } = await import(path.join(CORE, 'dist/engines/pseudo/interp.js'));
|
||||
const { snake } = await import(path.join(CORE, 'dist/sync/pseudo-to-mojo.js'));
|
||||
const modules = load(LIB);
|
||||
setLibrary(modules);
|
||||
const programs = [];
|
||||
for (const m of modules) for (const r of m.routines) {
|
||||
const st = svc.studyOf(r.source);
|
||||
if (!st.ok) continue;
|
||||
const sub = [...st.program.program.subs.values()][0];
|
||||
const calls = r.cases.map((c) => ({ args: parseExpression(c.call).expr.args.map((a) => evaluateConstant(st.program.program, a)) }));
|
||||
for (const ref of r.references) programs.push({ id: r.id, ref, dir: path.join(LIB, r.dir), make: () => harness(ref.lang, ref, snake(r.name), sub, calls) });
|
||||
}
|
||||
if (cmd === 'harness') {
|
||||
const [id, lang, level] = args.slice(1);
|
||||
const p = programs.find((x) => x.id === id && x.ref.lang === lang && x.ref.level === level);
|
||||
if (!p) { console.error(`no reference ${lang}/${level} for ${id}`); process.exit(2); }
|
||||
process.stdout.write(p.make());
|
||||
} else {
|
||||
// one JSON line per Mojo reference: what scripts/library_godbolt.py sends, and where its answer goes
|
||||
const list = programs.filter((p) => p.ref.lang === 'mojo').map((p) => ({ id: `${p.id} mojo/${p.ref.level}`, source: p.make(), golden: path.join(p.dir, 'golden', `mojo-${p.ref.level}.json`) }));
|
||||
process.stdout.write(`${JSON.stringify(list, null, 2)}\n`);
|
||||
}
|
||||
} else {
|
||||
console.error('usage: node scripts/library.mjs check [--only id] | emit [--check] | harness <id> <lang> <level> | mojo-sources');
|
||||
process.exit(2);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,58 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Ask the pinned Mojo compiler (on Compiler Explorer) about every Mojo reference implementation of the library,
|
||||
and store each answer beside the routine, in golden/mojo-<level>.json. Network; standard library only.
|
||||
|
||||
node scripts/library.mjs mojo-sources | python3 scripts/library_godbolt.py [--force] [--dry-run]
|
||||
|
||||
Each program is the reference's source with a main that prints every case (scripts/library.mjs builds it). An
|
||||
answer is keyed by the SHA-256 of that exact program and the compiler id, so editing a reference or a case makes
|
||||
it unverified until it is asked again; an answer already stored for the same program is not asked again unless
|
||||
--force. pixi run library-check then compares the stored output with the pseudo's results.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import sys
|
||||
from datetime import date
|
||||
from pathlib import Path
|
||||
|
||||
CORE = Path(__file__).resolve().parent.parent
|
||||
sys.path.insert(0, str(CORE / "scripts" / "mojo"))
|
||||
from mojocorpus import godbolt # noqa: E402
|
||||
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
force = "--force" in argv
|
||||
dry = "--dry-run" in argv
|
||||
pin = json.loads((CORE / "mojo" / "pin.json").read_text())
|
||||
base, compiler = pin["godbolt"]["base"], pin["godbolt"]["compiler"]
|
||||
timeout = int(pin["godbolt"].get("timeoutSeconds", 90))
|
||||
items = json.load(sys.stdin)
|
||||
asked = 0
|
||||
for it in items:
|
||||
src = it["source"]
|
||||
sha = hashlib.sha256(src.encode("utf-8")).hexdigest()
|
||||
out = Path(it["golden"])
|
||||
if out.exists() and not force:
|
||||
old = json.loads(out.read_text())
|
||||
if old.get("source_sha256") == sha and old.get("compiler") == compiler:
|
||||
print(f"[library] {it['id']}: stored answer is current")
|
||||
continue
|
||||
if dry:
|
||||
print(f"[library] {it['id']}: would ask {base} ({compiler}), {len(src)} bytes")
|
||||
continue
|
||||
data = godbolt.post(base, compiler, godbolt.request_body(src, "run"), timeout=timeout)
|
||||
result = godbolt.normalise("run", data)
|
||||
out.parent.mkdir(parents=True, exist_ok=True)
|
||||
out.write_text(json.dumps({"tool": "godbolt", "compiler": compiler, "mojoVersion": pin["mojo"]["version"],
|
||||
"source_sha256": sha, "asked": date.today().isoformat(), "result": result},
|
||||
indent=2, ensure_ascii=False) + "\n")
|
||||
asked += 1
|
||||
print(f"[library] {it['id']}: compiled={result['compiled']} exit={result['exitCode']}")
|
||||
print(f"[library] asked {asked} program(s)")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv[1:]))
|
||||
@@ -177,7 +177,10 @@ class Checker {
|
||||
if (s.name.startsWith('<')) this.subs.set(`${up(s.name)}#${s.line}`, { name: s.name, kind: s.kind, node: s, params: [], returns: null, requires: [], ensures: [], decreases: null });
|
||||
else if (this.subs.has(up(s.name))) this.error('duplicate', s, `${s.name} is already defined on line ${this.subs.get(up(s.name)).node.line}.`);
|
||||
else if ((BUILTINS[up(s.name)] && !SOFT_BUILTINS.has(up(s.name))) || SIZED[up(s.name)]) this.error('builtin-name', s, `${up(s.name)} is a built-in, so a ${s.kind.toUpperCase()} cannot take its name.`);
|
||||
else if (this.libs.has(up(s.name))) this.error('library-clash', s, `${s.name} also comes from the library (USE ${this.libOrigin.get(up(s.name))?.module} on line ${this.libOrigin.get(up(s.name))?.line}). Rename this one, or bring in only the routines you need: USE ${this.libOrigin.get(up(s.name))?.module}.<Name>.`, { guide: 'libraries' });
|
||||
else if (this.libs.has(up(s.name))) {
|
||||
this.error('library-clash', s, `${s.name} also comes from the library (USE ${this.libOrigin.get(up(s.name))?.module} on line ${this.libOrigin.get(up(s.name))?.line}). Rename this one, or bring in only the routines you need: USE ${this.libOrigin.get(up(s.name))?.module}.<Name>.`, { guide: 'libraries' });
|
||||
this.subs.set(up(s.name), { name: s.name, kind: s.kind, node: s, params: [], returns: null, requires: [], ensures: [], decreases: null });
|
||||
}
|
||||
else this.subs.set(up(s.name), { name: s.name, kind: s.kind, node: s, params: [], returns: null, requires: [], ensures: [], decreases: null });
|
||||
}
|
||||
}
|
||||
|
||||
@@ -289,7 +289,7 @@ class Interpreter {
|
||||
|
||||
runCall(name, args) {
|
||||
this.start();
|
||||
const sub = this.program.subs.get(up(name));
|
||||
const sub = this.program.subs.get(up(name)) || this.program.libs?.get(up(name));
|
||||
if (!sub) throw new PseudoError('value', `No FUNCTION or PROCEDURE is called ${name}.`, null);
|
||||
if (args.length !== sub.params.length) throw new PseudoError('value', `${sub.name} takes ${plural(sub.params.length, 'value')}, and ${args.length} ${args.length === 1 ? 'was' : 'were'} given.`, sub.node);
|
||||
sub.params.forEach((p, i) => {
|
||||
@@ -1221,8 +1221,8 @@ class Interpreter {
|
||||
if (old && n.kind === 'Name' && old.has(up(n.name))) return old.get(up(n.name));
|
||||
return this.evaluate(n);
|
||||
}
|
||||
if (e.sub || this.program.subs.get(up(e.name))) {
|
||||
const sub = e.sub || this.program.subs.get(up(e.name));
|
||||
if (e.sub || this.program.subs.get(up(e.name)) || this.program.libs?.get(up(e.name))) {
|
||||
const sub = e.sub || this.program.subs.get(up(e.name)) || this.program.libs.get(up(e.name));
|
||||
const slots = this.argSlots(sub, e.args);
|
||||
return this.invoke(sub, slots, e, false);
|
||||
}
|
||||
@@ -1536,7 +1536,7 @@ export function run(program, options = {}) {
|
||||
throw e;
|
||||
}
|
||||
}
|
||||
const sub = options.call ? program.subs.get(up(options.call.name)) : null;
|
||||
const sub = options.call ? (program.subs.get(up(options.call.name)) || program.libs?.get(up(options.call.name))) : null;
|
||||
return {
|
||||
program,
|
||||
steps: it.steps,
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,40 @@
|
||||
/**
|
||||
* The library as core sees it: modules of verified routines that a program brings in with USE.
|
||||
*
|
||||
* The data comes from the generated module (scripts/library.mjs emit, from the library/ submodule), so the
|
||||
* site needs no files at run time. The library's own tools read the routines from disk instead and install
|
||||
* them here with setLibrary() before checking them.
|
||||
*/
|
||||
import { LIBRARY_MODULES } from './generated.js';
|
||||
import type { LibraryModule, LibraryRoutine } from './types.js';
|
||||
|
||||
export type { LibraryModule, LibraryRoutine } from './types.js';
|
||||
|
||||
let modules: LibraryModule[] = LIBRARY_MODULES;
|
||||
let byModule = index(modules);
|
||||
|
||||
function index(mods: LibraryModule[]): Map<string, LibraryModule> {
|
||||
return new Map(mods.map((m) => [m.name.toUpperCase(), m]));
|
||||
}
|
||||
|
||||
/** Replace the library (the library's own tools, and tests). Returns the one it replaced. */
|
||||
export function setLibrary(mods: LibraryModule[]): LibraryModule[] {
|
||||
const old = modules;
|
||||
modules = mods;
|
||||
byModule = index(mods);
|
||||
generation++;
|
||||
return old;
|
||||
}
|
||||
|
||||
/** Bumped by setLibrary, so a cache of studied routines knows to start again. */
|
||||
export let generation = 0;
|
||||
|
||||
export function libraryModules(): LibraryModule[] { return modules; }
|
||||
|
||||
export function libraryModule(name: string): LibraryModule | undefined { return byModule.get(String(name).toUpperCase()); }
|
||||
|
||||
/** A routine by its id (stats.Mean), or by module and name. Names ignore case, as in pseudo. */
|
||||
export function libraryRoutine(module: string, name?: string): LibraryRoutine | undefined {
|
||||
if (name === undefined) { const i = module.indexOf('.'); if (i < 0) return undefined; name = module.slice(i + 1); module = module.slice(0, i); }
|
||||
return libraryModule(module)?.routines.find((r) => r.name.toUpperCase() === String(name).toUpperCase());
|
||||
}
|
||||
@@ -0,0 +1,70 @@
|
||||
/**
|
||||
* The shapes of the library (pplus-library, the submodule library/): modules of verified pseudo routines, each
|
||||
* with its cases, its reference implementations in other languages, an optional proof, and the status of every
|
||||
* check, as `pixi run library-check` last recorded it.
|
||||
*/
|
||||
|
||||
/** One check of one routine: what it found, and when the stored answer was made. */
|
||||
export interface LibraryCheck {
|
||||
/**
|
||||
* 'pass'; 'fail'; 'open' (the prover could not finish every obligation: nothing is wrong, nothing is proved);
|
||||
* 'unverified' (no stored answer for this exact text); 'skipped' (the tool is not available, or declines).
|
||||
*/
|
||||
status: 'pass' | 'fail' | 'open' | 'unverified' | 'skipped';
|
||||
/** One line: what was checked and what it found. */
|
||||
detail: string;
|
||||
}
|
||||
|
||||
export interface LibraryReference {
|
||||
/** 'python', 'mojo', 'c', ... */
|
||||
lang: string;
|
||||
/** 'plain', 'unrolled', 'fsum', ...: one implementation of the routine, at one level of care or optimization. */
|
||||
level: string;
|
||||
/** The file, relative to the routine's folder. */
|
||||
file: string;
|
||||
/** What this level does differently, in a sentence, and why it needs a tolerance if it has one. */
|
||||
note: string;
|
||||
/** The tolerance this level is held to against the pseudo, relative and absolute; exact when absent. */
|
||||
rel?: number;
|
||||
abs?: number;
|
||||
source: string;
|
||||
/** Per way of running it: 'interpreter' (core's Mojo interpreter), 'godbolt', 'cpython', 'cc -O0', 'cc -O2'. */
|
||||
checks: Record<string, LibraryCheck>;
|
||||
}
|
||||
|
||||
export interface LibraryCase {
|
||||
/** A call in pseudo, such as Mean([1.0, 2.0, 3.0]). */
|
||||
call: string;
|
||||
/** What the pseudo returns, written as pseudo writes values; filled in by library-check from a run. */
|
||||
result?: string;
|
||||
/** The tolerance a reference implementation is held to, relative and absolute; 0 for exact. */
|
||||
rel?: number;
|
||||
abs?: number;
|
||||
}
|
||||
|
||||
export interface LibraryRoutine {
|
||||
/** module.Name, as USE writes it: stats.Mean. */
|
||||
id: string;
|
||||
module: string;
|
||||
name: string;
|
||||
/** The routine's folder in pplus-library, such as modules/stats/mean. */
|
||||
dir: string;
|
||||
summary: string;
|
||||
tags: string[];
|
||||
/** Where the method comes from: a paper, a textbook section, a manual page. */
|
||||
sources: Array<{ title: string; url?: string }>;
|
||||
/** The routine file, routine.pseudo: one FUNCTION or PROCEDURE with its contracts, and USE lines for what it calls. */
|
||||
source: string;
|
||||
cases: LibraryCase[];
|
||||
references: LibraryReference[];
|
||||
proof?: { lang: string; file: string; note: string; source: string; check: LibraryCheck };
|
||||
/** pseudo (cases run), prover, fuzz, mojo (the generated Mojo), each a LibraryCheck. */
|
||||
checks: Record<string, LibraryCheck>;
|
||||
}
|
||||
|
||||
export interface LibraryModule {
|
||||
name: string;
|
||||
title: string;
|
||||
summary: string;
|
||||
routines: LibraryRoutine[];
|
||||
}
|
||||
@@ -22,6 +22,8 @@ import { parse, parseExpression } from '../engines/pseudo/parse.js';
|
||||
import { check } from '../engines/pseudo/check.js';
|
||||
import { analyze } from '../engines/pseudo/analyze.js';
|
||||
import { coach } from '../engines/pseudo/coach.js';
|
||||
import { libraryModule, libraryModules, generation as libraryGeneration } from '../library/registry.js';
|
||||
import type { LibraryRoutine } from '../library/registry.js';
|
||||
|
||||
const RANK: Record<string, number> = { error: 0, warning: 1, note: 2 };
|
||||
|
||||
@@ -118,7 +120,66 @@ const diag = (severity: string, code: string, line: number, col: number, message
|
||||
* `source` is the source as written; `parsed` is the engine's parse of the blanked source, with the assignments
|
||||
* put in.
|
||||
*/
|
||||
export function studyPseudo(source: string, options: { coach?: boolean; strict?: boolean } = {}): any {
|
||||
/** Studied library routines, by generation, id and source, so a routine is checked once however many programs use it. */
|
||||
const routineCache = new Map<string, any>();
|
||||
|
||||
/** A library routine, studied as a program of its own (its own USE lines resolved the same way). */
|
||||
function studyRoutine(r: LibraryRoutine, stack: string[]): any {
|
||||
const key = `${libraryGeneration}\u0000${r.id}\u0000${r.source}`;
|
||||
let st = routineCache.get(key);
|
||||
if (!st) {
|
||||
st = studyPseudo(r.source, { coach: false, libraryStack: [...stack, r.id] });
|
||||
routineCache.set(key, st);
|
||||
}
|
||||
return st;
|
||||
}
|
||||
|
||||
/**
|
||||
* The routines a program's USE lines bring in: UPPER name -> the checked routine (its own program's FUNCTION or
|
||||
* PROCEDURE, marked with `lib`), where each came from, and what could not be found.
|
||||
*/
|
||||
export function resolveUses(body: any[], stack: string[] = []): { libs: Map<string, any>; origin: Map<string, { module: string; line: number }>; diags: any[] } {
|
||||
const libs = new Map<string, any>();
|
||||
const origin = new Map<string, { module: string; line: number }>();
|
||||
const diags: any[] = [];
|
||||
for (const u of body) {
|
||||
if (u?.kind !== 'Use' || u.ieee) continue;
|
||||
const m = libraryModule(u.module);
|
||||
if (!m) {
|
||||
const names = libraryModules().map((x) => x.name);
|
||||
diags.push(diag('error', 'unknown-library', u.line, u.moduleCol ?? u.col, `No module of the library is called ${u.module}.${names.length ? ` The modules are ${names.join(', ')}.` : ' The library has no modules in this build.'}`, { guide: 'libraries' }));
|
||||
continue;
|
||||
}
|
||||
let routines = m.routines;
|
||||
if (u.routine) {
|
||||
const r = m.routines.find((x) => x.name.toUpperCase() === String(u.routine).toUpperCase());
|
||||
if (!r) { diags.push(diag('error', 'unknown-routine', u.line, u.routineCol ?? u.col, `The module ${m.name} has no routine called ${u.routine}. Its routines are ${m.routines.map((x) => x.name).join(', ')}.`, { guide: 'libraries' })); continue; }
|
||||
routines = [r];
|
||||
}
|
||||
for (const r of routines) {
|
||||
if (stack.includes(r.id)) { diags.push(diag('error', 'library-cycle', u.line, u.col, `${r.id} is already being brought in by ${stack[stack.length - 1]}, so the routines would use each other in a circle.`, { guide: 'libraries' })); continue; }
|
||||
const st = studyRoutine(r, stack);
|
||||
const sub = st.ok ? st.program.subs.get(r.name.toUpperCase()) : null;
|
||||
if (!sub) {
|
||||
const why = st.errors?.[0] ? `line ${st.errors[0].line}: ${st.errors[0].message}` : `it defines no routine called ${r.name}`;
|
||||
diags.push(diag('error', 'library-broken', u.line, u.col, `The library routine ${r.id} does not check (${why}). That is a fault in the library, not in this program.`, { guide: 'libraries' }));
|
||||
continue;
|
||||
}
|
||||
sub.lib = { module: m.name, id: r.id, program: st.program, source: r.source };
|
||||
const k = r.name.toUpperCase();
|
||||
const prior = origin.get(k);
|
||||
if (prior && prior.module.toUpperCase() !== m.name.toUpperCase()) {
|
||||
diags.push(diag('error', 'library-clash', u.line, u.col, `${r.name} comes from both ${prior.module} (line ${prior.line}) and ${m.name}. Bring in only the one you mean: USE ${m.name}.<Name>.`, { guide: 'libraries' }));
|
||||
continue;
|
||||
}
|
||||
libs.set(k, sub);
|
||||
origin.set(k, { module: m.name, line: u.line });
|
||||
}
|
||||
}
|
||||
return { libs, origin, diags };
|
||||
}
|
||||
|
||||
export function studyPseudo(source: string, options: { coach?: boolean; strict?: boolean; libraryStack?: string[] } = {}): any {
|
||||
const original = String(source ?? '');
|
||||
const { source: blanked, inits } = splitDeclareInits(original);
|
||||
const parsed: any = parse(blanked);
|
||||
@@ -149,8 +210,12 @@ export function studyPseudo(source: string, options: { coach?: boolean; strict?:
|
||||
}
|
||||
if (extra.length) parsed.diags = [...parsed.diags, ...extra].sort((a: any, b: any) => a.line - b.line || a.col - b.col);
|
||||
|
||||
// from here on, exactly what study() does (src/engines/pseudo/study.js)
|
||||
const { program, diags } = check(parsed);
|
||||
// the routines USE brings in, checked in their own files first
|
||||
const uses = resolveUses(parsed.ast.body, options.libraryStack || []);
|
||||
if (uses.diags.length) parsed.diags = [...parsed.diags, ...uses.diags].sort((a: any, b: any) => a.line - b.line || a.col - b.col);
|
||||
|
||||
// from here on, what study() does (src/engines/pseudo/study.js), with the library's routines in scope
|
||||
const { program, diags } = check(parsed, { libs: uses.libs, libOrigin: uses.origin });
|
||||
const errors = diags.filter((d: any) => d.severity === 'error');
|
||||
let analysis = null;
|
||||
let coached: any[] = [];
|
||||
|
||||
@@ -47,7 +47,7 @@ export function studyOf(source: string): Parsed<Study> {
|
||||
function resolveCall(program: any, call: string) {
|
||||
const p = parseExpression(call);
|
||||
if (p.diags.some((d: any) => d.severity === 'error') || p.expr.kind !== 'CallExpr') throw new Error(`"${call}" is not a call. Write the subroutine's name and its arguments, as in COUNT_BASE('A', "GATTACA").`);
|
||||
const sub = program.subs.get(p.expr.name.toUpperCase());
|
||||
const sub = program.subs.get(p.expr.name.toUpperCase()) || program.libs?.get(p.expr.name.toUpperCase());
|
||||
if (!sub) throw new Error(`The program has no FUNCTION or PROCEDURE called ${p.expr.name}.`);
|
||||
if (p.expr.args.length !== sub.params.length) throw new Error(`${sub.name} takes ${sub.params.length} value(s), and the call gives ${p.expr.args.length}.`);
|
||||
const args = p.expr.args.map((a: any, i: number) => {
|
||||
|
||||
@@ -39,6 +39,10 @@ export { GENERATED_HEADER };
|
||||
export interface MojoOptions {
|
||||
/** The call to run, such as COUNT_BASE('A', "GATTACA"); becomes the body of `main` when the pseudo has no lines of its own. */
|
||||
call?: string | null;
|
||||
/** Internal: write the definitions only, no imports and no main (a library routine). */
|
||||
defsOnly?: boolean;
|
||||
/** Internal: the library routines' Mojo, written before the program's own definitions. */
|
||||
libraryBlocks?: Array<{ id: string; lines: string[]; imports: string[] }>;
|
||||
}
|
||||
|
||||
export interface MojoResult { source: string; map: LineMap; notes: Diagnostic[] }
|
||||
@@ -183,7 +187,7 @@ class Gen {
|
||||
constructor(private program: any, private source: string, private raising: Set<string>, private opts: MojoOptions) {
|
||||
for (const c of program.comments || []) this.commentsByLine.set(c.line, c);
|
||||
this.srcLines = source.split('\n');
|
||||
for (const sub of program.subs.values()) {
|
||||
for (const sub of [...program.subs.values(), ...(program.libs?.values() ?? [])]) {
|
||||
const changed = this.changedIn(sub.node.body);
|
||||
const assigned = this.assignedIn(sub.node.body);
|
||||
this.varParams.set(key(sub.name), sub.params.map((p: any) => p.mode !== 'BYREF' && ((changed.has(up(p.name)) && isCollection(p.type)) || assigned.has(up(p.name)))));
|
||||
@@ -344,7 +348,15 @@ class Gen {
|
||||
this.emit(0, '', null);
|
||||
this.emit(0, '', null);
|
||||
}
|
||||
for (const b of this.opts.libraryBlocks || []) {
|
||||
this.emit(0, `# From the Programming+ library: ${b.id} (verified in pplus-library; generated from its pseudo)`, null);
|
||||
for (const l of b.lines) this.emit(0, l, null);
|
||||
for (const n of b.imports) this.imports.add(n);
|
||||
this.emit(0, '', null);
|
||||
this.emit(0, '', null);
|
||||
}
|
||||
for (const sub of p.subs.values()) { this.subroutine(sub); this.emit(0, '', null); this.emit(0, '', null); }
|
||||
if (this.opts.defsOnly) return this.assemble();
|
||||
this.mainFunction();
|
||||
this.leadingComments(Infinity, 0);
|
||||
return this.assemble();
|
||||
@@ -997,10 +1009,24 @@ export function pseudoToMojo(pseudo: string, opts: MojoOptions = {}): MojoResult
|
||||
return { unsupported: errors.length ? errors : [{ lang: 'pseudo', severity: 'error', id: 'translate-no-program', line: 1, message: 'The pseudo does not read yet, so there is nothing to translate.' }] };
|
||||
}
|
||||
const program = st.program;
|
||||
// the library routines the program uses, each once, the ones they use first
|
||||
const libs = libraryOrder(program);
|
||||
const libRaising = new Set<string>();
|
||||
const libraryBlocks: Array<{ id: string; lines: string[]; imports: string[] }> = [];
|
||||
for (const lib of libs) {
|
||||
const raising = inferRaising(lib.program, libRaising);
|
||||
const gen = new Gen(lib.program, lib.source, raising, { defsOnly: true });
|
||||
gen.run();
|
||||
for (const sub of lib.program.subs.values()) if (raising.has(up(sub.name))) libRaising.add(up(sub.name));
|
||||
const lines = gen.out.map((l) => l.text);
|
||||
while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
|
||||
libraryBlocks.push({ id: lib.id, lines, imports: [...gen.imports] });
|
||||
}
|
||||
opts = { ...opts, libraryBlocks };
|
||||
const callText = (opts.call || '').trim();
|
||||
const callName = callText ? /^\s*([A-Za-z_][A-Za-z0-9_]*)/.exec(callText)?.[1] : null;
|
||||
// Inference, then translation; a line that could not be translated becomes a raise, so its routine raises too, and the pass is run again.
|
||||
const extra = new Set<string>();
|
||||
const extra = new Set<string>(libRaising);
|
||||
for (let pass = 0; ; pass++) {
|
||||
const raising = inferRaising(program, extra);
|
||||
if (bodyRaises(program.main.body, raising)) raising.add('MAIN');
|
||||
@@ -1014,6 +1040,34 @@ export function pseudoToMojo(pseudo: string, opts: MojoOptions = {}): MojoResult
|
||||
}
|
||||
}
|
||||
|
||||
/** The names of every routine a program calls, anywhere in it. */
|
||||
function calledNames(program: any): Set<string> {
|
||||
const out = new Set<string>();
|
||||
const seen = new Set<any>();
|
||||
const visit = (x: any): void => {
|
||||
if (!x || typeof x !== 'object' || seen.has(x)) return;
|
||||
seen.add(x);
|
||||
if (Array.isArray(x)) { for (const y of x) visit(y); return; }
|
||||
if ((x.kind === 'CallExpr' || x.kind === 'Call') && x.name) out.add(up(x.name));
|
||||
for (const [k, v] of Object.entries(x)) if (k !== 'sub' && k !== 'sym' && k !== 'type' && k !== 'resolved' && v && typeof v === 'object') visit(v);
|
||||
};
|
||||
visit(program.main?.body);
|
||||
for (const s of program.subs.values()) { visit(s.node.body); visit(s.requires); visit(s.ensures); }
|
||||
return out;
|
||||
}
|
||||
|
||||
/** Every library routine a program calls, directly or through another routine, dependencies first, each once. */
|
||||
function libraryOrder(program: any, out: Map<string, any> = new Map()): any[] {
|
||||
const called = calledNames(program);
|
||||
for (const sub of program.libs?.values() ?? []) {
|
||||
if (!called.has(up(sub.name))) continue;
|
||||
if (out.has(sub.lib.id)) continue;
|
||||
libraryOrder(sub.lib.program, out);
|
||||
out.set(sub.lib.id, sub.lib);
|
||||
}
|
||||
return [...out.values()];
|
||||
}
|
||||
|
||||
/** The set of names a generated source may use from the standard library, for the grounding test. */
|
||||
export function stdlibNamesUsed(): string[] { return Object.keys(USED_STDLIB); }
|
||||
export const STD_INDEX = MOJO_STD_EXPORTS;
|
||||
@@ -0,0 +1,12 @@
|
||||
// Routines from the library, called like the program's own: a run steps over each one, and the
|
||||
// prover uses each one's REQUIRE and ENSURE at the call.
|
||||
// EXPECT: 5.0 4.571428571428571
|
||||
// EXPECT: 0.0 -0.0615234375
|
||||
// EXPECT: 0
|
||||
USE stats
|
||||
USE md.LennardJones
|
||||
USE align.NeedlemanWunschScore
|
||||
DECLARE Samples : LIST OF FLOAT <- [2.0, 4.0, 4.0, 4.0, 5.0, 5.0, 7.0, 9.0]
|
||||
OUTPUT Mean(Samples), " ", Variance(Samples)
|
||||
OUTPUT LennardJones(1.0, 1.0, 1.0), " ", LennardJones(2.0, 1.0, 1.0)
|
||||
OUTPUT NeedlemanWunschScore("GATTACA", "GCATGCU", 1, -1, -1)
|
||||
@@ -0,0 +1,85 @@
|
||||
// The library (library/, pplus-library): the registry core builds from it is current, every routine checks and
|
||||
// runs as its record says, and USE behaves as docs/library.md describes: names resolve, runs step over the
|
||||
// routines, the prover uses their contracts, and the Mojo translator writes each routine once.
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import fs from 'node:fs';
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import { libraryModules, libraryRoutine } from '../dist/library/registry.js';
|
||||
import { studyOf, runPseudo, provePseudo } from '../dist/services/pseudo.js';
|
||||
import { pseudoToMojo } from '../dist/sync/pseudo-to-mojo.js';
|
||||
import { checkMojo } from '../dist/mojo/check.js';
|
||||
import { runMojo } from '../dist/mojo/interp.js';
|
||||
|
||||
test('the registry is generated from the library checkout and is up to date', () => {
|
||||
assert.ok(fs.existsSync('library/modules'), 'library/ is not checked out: git submodule update --init');
|
||||
const r = spawnSync(process.execPath, ['scripts/library.mjs', 'emit', '--check'], { encoding: 'utf8' });
|
||||
assert.equal(r.status, 0, r.stderr || r.stdout);
|
||||
});
|
||||
|
||||
test('every routine: one routine per file, its cases run, and its record is current and has no failing check', () => {
|
||||
const mods = libraryModules();
|
||||
assert.ok(mods.length >= 6, `only ${mods.length} modules`);
|
||||
let routines = 0;
|
||||
for (const m of mods) {
|
||||
for (const r of m.routines) {
|
||||
routines++;
|
||||
const st = studyOf(r.source);
|
||||
assert.ok(st.ok, `${r.id}: ${st.diagnostics.filter((d) => d.severity === 'error').map((d) => d.message).join('; ')}`);
|
||||
const subs = [...st.program.program.subs.values()];
|
||||
assert.deepEqual(subs.map((s) => s.name), [r.name], `${r.id} defines ${subs.map((s) => s.name)}`);
|
||||
assert.ok(r.cases.length >= 2, `${r.id} has fewer than two cases`);
|
||||
for (const c of r.cases) {
|
||||
const tr = runPseudo(st, { call: c.call, maxSteps: 2000000 });
|
||||
assert.equal(tr.error, null, `${r.id}: ${c.call}: ${tr.error?.message}`);
|
||||
assert.ok(c.result !== undefined, `${r.id}: ${c.call} has no recorded result: run pixi run library-check`);
|
||||
}
|
||||
const all = [...Object.entries(r.checks), ...r.references.flatMap((x) => Object.entries(x.checks).map(([k, v]) => [`${x.lang}/${x.level} ${k}`, v])), ...(r.proof ? [['proof', r.proof.check]] : [])];
|
||||
for (const [k, c] of all) assert.notEqual(c.status, 'fail', `${r.id} ${k}: ${c.detail}`);
|
||||
for (const k of ['structure', 'pseudo', 'prover', 'fuzz']) assert.ok(r.checks[k], `${r.id} has no ${k} check recorded: run pixi run library-check`);
|
||||
}
|
||||
}
|
||||
assert.ok(routines >= 16, `only ${routines} routines`);
|
||||
});
|
||||
|
||||
test('USE: a module or one routine; unknown names are errors at the USE line', () => {
|
||||
assert.ok(libraryRoutine('md.LennardJones'));
|
||||
assert.ok(libraryRoutine('MD', 'lennardjones'), 'names ignore case');
|
||||
const ids = (src) => studyOf(src).diagnostics.filter((d) => d.severity === 'error').map((d) => `${d.id}@${d.line}`);
|
||||
assert.deepEqual(ids('USE nosuchmodule\n'), ['unknown-library@1']);
|
||||
assert.deepEqual(ids('USE md.NoSuchRoutine\n'), ['unknown-routine@1']);
|
||||
assert.deepEqual(ids('USE md.MinimumImage\nFUNCTION MinimumImage(X : FLOAT) RETURNS FLOAT\n RETURN X\nENDFUNCTION\n'), ['library-clash@2']);
|
||||
assert.deepEqual(ids('USE align.MatchScore\nOUTPUT LinearGapPenalty(2, -1)\n'), ['unknown-function@2'], 'USE of one routine brings in only that one');
|
||||
assert.deepEqual(ids('IF TRUE THEN\n USE md\nENDIF\n'), ['use-place@2']);
|
||||
});
|
||||
|
||||
test('a run steps over a library routine, and a broken REQUIRE is reported at the call', () => {
|
||||
const st = studyOf('USE md\nOUTPUT MinimumImage(2.3, 1.0)\nOUTPUT MinimumImage(1.0, 0.0)\n');
|
||||
const tr = runPseudo(st, {});
|
||||
assert.equal(tr.output[0], '0.2999999999999998');
|
||||
assert.ok(tr.steps.every((s) => s.line === null || s.line <= 3), 'a step carries a line of the library file');
|
||||
assert.ok(tr.steps.some((s) => s.kind === 'call' && /from the library \(md\.MinimumImage\)/.test(s.text)));
|
||||
assert.equal(tr.error?.kind, 'require');
|
||||
assert.equal(tr.error.line, 3);
|
||||
assert.match(tr.error.message, /In the library routine md\.MinimumImage/);
|
||||
});
|
||||
|
||||
test('the prover uses a routine\'s REQUIRE at the call and its ENSURE afterwards, without proving it again', () => {
|
||||
const r = provePseudo(studyOf('USE seq.HammingDistance\nFUNCTION F(S : STRING) RETURNS INTEGER\n ENSURE RESULT <= LENGTH(S)\n RETURN HammingDistance(S, S)\nENDFUNCTION\n'));
|
||||
assert.deepEqual(r.units.map((u) => u.name), ['F'], 'library routines are not units of the program');
|
||||
const obs = r.units[0].obligations;
|
||||
assert.equal(obs.find((o) => o.kind === 'require').status, 'proved');
|
||||
assert.equal(obs.find((o) => o.kind === 'ensure').status, 'proved', 'the ENSURE of HammingDistance is a fact after the call');
|
||||
});
|
||||
|
||||
test('the Mojo made from a program that uses the library holds each routine once, dependencies first, and agrees', () => {
|
||||
const src = 'USE align\nOUTPUT NeedlemanWunschScore("GATTACA", "GCATGCU", 1, -1, -1), " ", MatchScore(\'A\', \'A\', 2, -1)\n';
|
||||
const mj = pseudoToMojo(src);
|
||||
const defs = [...mj.source.matchAll(/^def (\w+)/gm)].map((m) => m[1]);
|
||||
assert.deepEqual(defs, ['match_score', 'linear_gap_penalty', 'needleman_wunsch_score', 'main']);
|
||||
assert.match(mj.source, /# From the Programming\+ library: align\.MatchScore/);
|
||||
const ck = checkMojo(mj.source);
|
||||
assert.deepEqual(ck.diagnostics.filter((d) => d.severity === 'error'), []);
|
||||
const run = runMojo(ck.module, mj.source, { maxSteps: 4000000 });
|
||||
assert.equal(run.stdout.trim(), runPseudo(studyOf(src), {}).output.join('\n'));
|
||||
});
|
||||
Reference in new issue
Block a user