infra/paperspec
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: documents and session tokens
check / check (default, macos-latest) (push) Canceled after 0s
Details
check / check (default, ubuntu-latest) (push) Canceled after 0s
Details
check / check (py310, macos-latest) (push) Canceled after 0s
Details
check / check (py310, ubuntu-latest) (push) Canceled after 0s
Details

Browse Source
This commit is contained in:
alexm committed 2026-10-12 01:07:50 -04:00
1 parent 62f54ed869
commit 8b2df58266
39 files changed
+1523 -199
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

tools/README.md
+19 -6
View File
@@ -1,11 +1,24 @@
# Tools
Non-normative, standard library only, licensed Apache-2.0.
Small programs that build and check the repository, and one for loading packages into SQLite.
They use only the Python standard library and are licensed Apache-2.0.
| Tool | Does |
| Program | Does |
| --- | --- |
| `oracle/` | A compact implementation of every rule, used to compute and check the vectors and fixtures. It is not a library; implementations conform to the chapters, and `scienting-core` is the reference implementation. |
| `build.py` | Builds `fixtures/` (except `src/`) and `vectors/` from `fixtures/src/` and the cases it defines. Deterministic; `--out DIR` builds elsewhere. |
| `check.py` | Checks the whole repository; `--quick` skips the determinism rebuild. Uses `jsonschema` as a second validator when installed. |
| `check.py` | Checks everything: schemas, records, packages, the broken packages, every vector, a byte-for-byte rebuild, the SQL round trip and the prose. `--quick` skips the rebuild. |
| `build.py` | Builds `fixtures/` and `vectors/` from the hand-written sources in `fixtures/src/` and the cases it defines. `--out DIR` builds into another folder. |
| `load.py` | Loads packages into a SQLite database with the tables of `sql/`: `python3 tools/load.py --sqlite lab.db PACKAGE…`. |
| `oracle/` | A compact implementation of every rule, which `build.py` uses to compute expected values and `check.py` uses to recompute them. |
The oracle's JSON Schema validator supports exactly the keyword subset of [spec/22-conformance.md](../spec/22-conformance.md#223-schemas) and refuses schemas that use anything else.
## When to run what
Each program is also a pixi task, so `pixi run check`, `pixi run quick`, `pixi run build` and `pixi run load` work from anywhere in the repository; `pixi run check` lints the Markdown first.
Run `pixi run check` before every commit.
Run `pixi run build` after changing a fixture source, a rule in `oracle/`, or a case in `build.py`, then commit the regenerated files with the change; the check fails if they are out of date.
## About the oracle
The oracle exists so that no expected value in this repository is typed by hand.
It favors clarity over speed, its Ed25519 is the slow reference code of RFC 8032, and it is not a library to build on: implementations follow the [specification](../spec/README.md) and test themselves against the [vectors](../vectors/README.md).
Its JSON Schema validator supports exactly the keyword subset the schemas use, and refuses any schema that uses more.