Repository navigation
Contributing
How to work on enumeratio: the toolchain, the names, where things go, and what a change has to pass before it lands. For parallel work across several sessions, see Lanes; for what to work on, see Roadmap.
The repo is a pnpm monorepo on Vite+, whose CLI is vp.
vp <name> runs a built-in command; vp run <name> runs a package.json script or a
vite.config.ts task.
vp install
pnpm -r --filter "./packages/**" --filter "./upstream/**" run build
vp check
vp test- Build the library packages before
vp checkor the tests: type-aware lint and the tests resolve sibling packages through theirdist/. If a sibling's dist is missing on the first pass, run the build again. Keep both filters; a barepnpm -r run buildalso builds the site, which takes more than 2 GB. - The site is VitePress in
web/:pnpm --filter @enumeratio/web run build, orvitepress devfor the dev server. - If setup or package-manager behaviour looks wrong,
vp env doctorsays why.
-
enumeratio is the mathematics: the symbol definitions (collections, statistics and
maps, the special functions, the algebras) and their evaluation, built on
@cortex-js/compute-engineand written in its language, Epsil. -
notatio is the interface: the notebook, the
<notatio-*>elements, the plots and glyphs, the CLI and REPL, the format registry, the docs site, and the vdom (the component form of an expression). notatio is not a syntax: the text is Epsil. - The line runs by what the word governs. enumeratio owns meaning ("a head", "defined
as", "evaluates to"); notatio owns writing and showing ("written as", "prints as",
InputForm, the
*Formheads). See Syntax and Formats. - In the reference data, an example's retypeable text form is keyed
epsil, andnotatiokeys its component serialisation, the vdom as Vue/React markup (Examples as Data §2). - Symbol names are spelled out, not abbreviated. Package names haven't all caught up; don't rename them in passing (see Component Naming for how renames wait).
-
Design writing goes on this wiki, not in the repo: settled design under Design, open design under Speculative design.
-
Upstream candidates. A head or fix compute-engine would plausibly take (Wolfram or mpmath has it, or it fixes or widens a native head) is written as a patch in
upstream/compute-engine/, not in a symbol package, even before anything is proposed. Its code is laid out as in compute-engine; its reference entries stay inpackages/reference/entries/and never go upstream. See Upstreaming §10. -
Reference entries. Each head's record is a folder,
reference/<Head>/, in the package that declares it (packages/reference/entries/for compute-engine's own heads):-
index.md: front matter (summary, signatures, bindings, references…), with the details as a markdown list below it. -
examples.tsv: one hand-written row per example, in page order. Each row has a stableid(lowercase words joined by-),exprandexpectedas MathJSON, and each system's hand classification. An example whose value is known from outside our evaluation also carriesknown, itssource(DLMF 25.6.1,OEIS A000110…) and optionally atolerance. Never "fix" a failing known check by rewritingexpected. -
examples.values.<system>.tsv: generated, one per system: our own forms and each oracle's answers.
Read and write records through
@enumeratio/entry/node, never by hand-parsing their files. After editing, runnode packages/reference/scripts/format-records.ts. After adding or changing an example (or a printer or transpiler), runUPDATE_FORMS=1 node packages/frontend/scripts/collect-forms.ts; the forms test says when that's needed. Add a head by adding its folder. -
-
Golden data, not snapshots, in
packages/. Assert against a committed golden JSON file (expect(actual).toEqual(golden[id])), regenerated behind anUPDATE_*flag, because it's plain data you can review and reuse. A guard test enforces this. -
Patches in
upstream/test the way their upstream does, snapshots included, so a test can go upstream with its code. -
Long sweeps run nightly. A test that samples or enumerates takes a small budget by
default and its full one under
DEEP_TESTS=1. Keep the important cases in the standard run as fixed examples, not left to the sample. Don't just raise a test timeout.
- Work on a branch or worktree, never directly on
main. Land through a pull request:mainrequires its status checks, so a direct push skips them. Never force-pushmain. -
Never commit conflict markers. After resolving any merge, and before committing:
git grep -nE '^(<{7}|>{7})' $(git rev-parse --show-toplevel)must be empty. A marked file landing onmainbreaks the dev server and every checkout. - Commits and PRs are authored as the project (
enumeratio), not as a person. -
No attribution markers in commits, PR descriptions or comments: no
Co-Authored-Byor other trailers, no "generated with" line, no session links, no footers. This holds for any tool or agent that writes on the project's behalf. When merging a squash, give the message explicitly, since the default adds co-author trailers.
-
The gate (
ci.yml, every push and PR): build the library packages, thenvp check, the per-package tests and the site build. -
Production (
enumeratio.dev) ships from GitHub Pages on merge tomain. -
Previews. Every build of every commit also goes up as a Cloudflare Pages preview at
<sha7>.enumeratio.pages.dev. The PR's sticky preview comment carries the URL; review links go below its first two lines, which each push rewrites. Previews are cleaned up nightly: a closed PR's a day after it closes, untagged ones after 30 days. -
Advisory sweeps, never required checks:
-
plausible.ymlsamples the collection kernels on every push that touches them, and deeply each night (Plausible). -
nightly.ymlrescans the oracle lanes against the committed values nightly: Python (mpmath, SymPy), Julia (Nemo, Combinatorics.jl) and Rust. Each lane also runs the oracle Plausible, which resamples the documented examples toward the edges of each domain. Weekly, it rescans Oscar, Mathlib, Sage and Wolfram the same way. - A lane fails when an answered row changes verdict, classification or input, not on a float's printed digits.
- Failures file rolling issues labelled
nightly-fixup. A nightly routine reads them and opens fix PRs, but never merges.
-