From acf0b8e620adf734cf42d308f7f1d20f46f340b0 Mon Sep 17 00:00:00 2001 From: Alex Maldonado Date: Mon, 5 Oct 2026 03:46:04 +0000 Subject: [PATCH] Add docs/trust.md and a clean package task docs/trust.md lists every badge and verdict the app shows (where code came from, what a compiler said, what a proof, the fuzzer, a translation and the model machine say): what earns each one, what it means, and what it does not mean. New badges get a row there in the same commit. pixi run package zips the files git tracks, plus new files it does not ignore, into package/programming-plus-.zip (marked -dirty with uncommitted changes). The zip shared before this held .DS_Store files, __pycache__ folders and __MACOSX entries (3,661 files); the package holds none of them (1,694 files). Python standard library only. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ --- .gitignore | 1 + README.md | 2 ++ docs/trust.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++ pixi.toml | 1 + scripts/package.py | 43 ++++++++++++++++++++++++++++++++++++ 5 files changed, 102 insertions(+) create mode 100644 docs/trust.md create mode 100644 scripts/package.py diff --git a/.gitignore b/.gitignore index 4118958..50a7c3d 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ node_modules/ .DS_Store dist/ patches/ +package/ # pixi environments .pixi/* !.pixi/config.toml diff --git a/README.md b/README.md index d694073..b094b3c 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,7 @@ Every command is a pixi task (`pixi task list` shows them with their description | **Ship** ([docs/deploy.md](docs/deploy.md)) | | | `ci` | What CI runs: every test, and no program of ours failing | | `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/`, optionally over SSH | ## Where things are @@ -109,6 +110,7 @@ scratch/ ignored by git: a place for experiments |---|---| | [AGENTS.md](AGENTS.md) | Rules for anyone changing the code, 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/trust.md](docs/trust.md) | Every badge and verdict the app shows: what earns it, what it means, and what it does not mean | | [docs/sync-coverage.md](docs/sync-coverage.md) | What each translator can say, written by the tests: which programs translate fully, and why the rest do not | | [docs/exercises.md](docs/exercises.md) | Adding a catalog problem | | [docs/mojo-corpus.md](docs/mojo-corpus.md) | Writing Mojo of our own (probes, exercise programs, stress programs) and moving to a new Mojo version | diff --git a/docs/trust.md b/docs/trust.md new file mode 100644 index 0000000..89a2034 --- /dev/null +++ b/docs/trust.md @@ -0,0 +1,55 @@ +# What each badge and verdict means + +Programming+ is built for checking work that someone or something else produced, so every claim it shows names what answered it, and none claims more than that. This page lists each one: who earns it, what it means, and what it does not mean. When a new badge or verdict is added, it gets a row here in the same commit. + +## Where code came from + +| Shown | Earned by | Means | Does not mean | +|---|---|---|---| +| **Generated from pseudo** | The Bridge's Mojo tab, always (`mojoProvenance` in `src/core/provenance.ts`); Mojo copied from it with **Edit in Developer** | The translator wrote this Mojo from the pseudo, literally, with a header comment saying so | That anyone has read it, or that it is the Mojo a person would write | +| **Started from generated Mojo** | Generated Mojo edited in the Developer area (`mojoOrigin: 'generated-edited'`) | A person has changed generated Mojo | That the person reviewed the parts they did not change | +| (badge cleared) | **I've reviewed this**, in the Developer area only | The person says they reviewed it; the header comment goes too | That anything checked the review. Compiling and editing never clear the badge | + +## What a compiler said + +| Shown | Earned by | Means | Does not mean | +|---|---|---|---| +| **Compiled on godbolt** (ran, exit N / did not compile / timed out) | An answer from the compile backend (`src/services/compile-backend.ts`, godbolt.org with Mojo 1.1.0 by default) for this exact source, input and build level, made in this browser | The real compiler answered as shown | That the program is right. The badge is keyed by a hash, so any edit, other input or other level removes it, and a share link never carries it | +| **Edited since compile** | An edit after a compile | The compiler's answer is for an earlier text | Anything about the current text | +| **verified on Mojo 1.1.0** | An exercise's own program in `mojo/local/`, when godbolt's stored answer for that exact source passed the file's `# expect-stdout:` lines (`pixi run mojo-verify`) | The program printed what it should, on the real compiler | That the program is right on other inputs | +| A Mojo checker error, warning or note | Programming+'s own checker (`src/mojo/`) | The compiler would report this. The checker may never report an error on a program the compiler accepts (`tests/mojo-check.test.mjs`) | That a program without checker errors compiles. Only the compiler says that | +| A **best practices** note | The optional helper (`src/mojo/practices.ts`), off by default | A more idiomatic way to write a line, whose rewrite keeps the output the same where it offers one | An error. Notes never look like the compiler | +| Mojo output in the Run view and stepper | Programming+'s Mojo interpreter (`src/mojo/interp.ts`) | Exactly what godbolt printed for the same program, or the interpreter declines and says why (`tests/mojo-run.test.mjs`) | A prediction. The interpreter does not guess | + +## What a proof says + +The Prove tab reports every obligation in three statuses (`src/engines/pseudo/vcgen.ts`, `src/services/pseudo.ts`). + +| Shown | Earned by | Means | Does not mean | +|---|---|---|---| +| **Proved** | The built-in prover (`solver.ts`), on every path it examined, in a unit it examined completely | The claim follows from what is known, in the notation's number model: INTEGER as whole numbers of any size, FLOAT as finite numbers whose rounding is not seen into. The prover is sound (`tests/prover-soundness.test.mjs`) | That the Mojo made from the program has the same property. A 64-bit `Int` wraps and a `Float64` becomes `inf` or `nan`; the `int-model` and `float-model` notes say when a proof leans on the number model. A unit marked **partial** shows no claim as proved | +| **Broken** | A generated input (the fuzzer, seeded) or a run that breaks the claim at that place | There is an input for which the claim is false, and **Step through** shows it | Anything about other claims. A run outranks the prover: a proved obligation that an input breaks is shown as broken (and would be a soundness bug) | +| **Open** | Neither of the above | The checker could not finish the argument, usually because a loop needs an INVARIANT | That the claim is false | +| An invariant "the checker found on its own" | Inference in `vcgen.ts`, kept only at a fixed point | It holds on entry and survives every pass, and the proof used it | That it is the invariant a reader needs | + +## What testing says + +| Shown | Earned by | Means | Does not mean | +|---|---|---|---| +| A routine's cases in the Tests tab | The fuzzer (`src/core/fuzz.ts`), with the seed and input count shown | Every input listed was run and checked against each claim and limit | That untried inputs pass. "Held on 300 inputs" is evidence, not proof | +| A failure's smallest input | Shrinking in the fuzzer | The smallest input it found that fails the same way | The only failing input | + +## What a translation says + +| Shown | Earned by | Means | Does not mean | +|---|---|---|---| +| ⇄ in step (lingo, matho, speco) | The translator, which reads its own output back and holds it to the pseudo (`tests/sync-lingo.test.mjs`, `sync-matho.test.mjs`, `sync-speco.test.mjs`) | The two panes describe the same program, as far as the round trip checks | A proof that they are equivalent on every input | +| ⚠ not in step | A language that cannot say the program, or a pane that does not read | The pane keeps its last text and says why | That the pane is wrong | +| Generated Mojo agreeing with the pseudo | `tests/sync-mojo.test.mjs`, over every exercise and corpus program | On those programs, the Mojo prints what the pseudo prints | That the translator is verified. Where a line has no faithful Mojo, the translation stops with `not translated` rather than guess | + +## What the machine says + +| Shown | Earned by | Means | Does not mean | +|---|---|---|---| +| 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 | diff --git a/pixi.toml b/pixi.toml index 1140162..353dd94 100644 --- a/pixi.toml +++ b/pixi.toml @@ -62,4 +62,5 @@ mojo-update = { depends-on = ["mojo-harvest", "mojo-verify", "mojo-status", "tes # --- ship ------------------------------------------------------------------ ci = { depends-on = ["test", "mojo-status-strict"], description = "What CI runs: every test, and no program of ours failing" } site = { cmd = "scripts/assemble.sh", depends-on = ["test"], description = "Test, then assemble site/ for publishing" } +package = { cmd = "python scripts/package.py", description = "Zip the files git tracks (and new ones it does not ignore) into package/ for sharing" } deploy = { cmd = "scripts/deploy.sh {{ slug }} {{ target }}", args = [{ arg = "slug", default = "pplus" }, { arg = "target", default = "" }], depends-on = ["site"], description = "Publish site/ to /srv/www/, optionally on (user@host) over SSH (docs/deploy.md)" } diff --git a/scripts/package.py b/scripts/package.py new file mode 100644 index 0000000..9f57694 --- /dev/null +++ b/scripts/package.py @@ -0,0 +1,43 @@ +#!/usr/bin/env python3 +"""Zip the repository for sharing: the files git tracks, plus new files it does not ignore. + + pixi run package # writes package/programming-plus-.zip + +Nothing git ignores goes in: no .DS_Store, __pycache__, scratch/, dist/, site/, node_modules/ or +.pixi/. Files are stored under a top folder named programming-plus/, as the shared zips were. +Standard library only, like the corpus pipeline. +""" +import pathlib +import subprocess +import sys +import zipfile + +ROOT = pathlib.Path(__file__).resolve().parent.parent + + +def git(*args: str) -> str: + return subprocess.run(["git", *args], cwd=ROOT, check=True, capture_output=True, text=True).stdout + + +def main() -> int: + try: + commit = git("rev-parse", "--short", "HEAD").strip() + except (subprocess.CalledProcessError, FileNotFoundError): + print("package: this needs a git checkout (git init and commit first)", file=sys.stderr) + return 1 + dirty = bool(git("status", "--porcelain").strip()) + names = sorted(set(git("ls-files", "-z", "--cached", "--others", "--exclude-standard").split("\0")) - {""}) + names = [n for n in names if (ROOT / n).is_file()] + out_dir = ROOT / "package" + out_dir.mkdir(exist_ok=True) + out = out_dir / f"programming-plus-{commit}{'-dirty' if dirty else ''}.zip" + with zipfile.ZipFile(out, "w", compression=zipfile.ZIP_DEFLATED) as z: + for n in names: + z.write(ROOT / n, f"programming-plus/{n}") + size = out.stat().st_size / 1e6 + print(f"wrote {out.relative_to(ROOT)}: {len(names)} files, {size:.1f} MB{' (with uncommitted changes)' if dirty else ''}") + return 0 + + +if __name__ == "__main__": + sys.exit(main())