# Development Commands
Development commands and validation steps for the repository.
Agents must run appropriate checks after modifying code.
---
## Contents
- [Core Workflow](#core-workflow)
- [Validation Command Selection](#validation-command-selection)
- [Justfile Usage](#justfile-usage)
- [Formatting](#formatting)
- [Linting](#linting)
- [Documentation Validation](#documentation-validation)
- [Full CI Validation](#full-ci-validation)
- [Benchmark Profiles](#benchmark-profiles)
- [Examples](#examples)
- [Spell Checking](#spell-checking)
- [Notebook Validation](#notebook-validation)
- [Markdown Checks](#markdown-checks)
- [TOML Checks](#toml-checks)
- [YAML Checks](#yaml-checks)
- [Shell Script Validation](#shell-script-validation)
- [JSON Validation](#json-validation)
- [Paper Build](#paper-build)
- [CITATION.cff Validation](#citationcff-validation)
- [GitHub Actions Validation](#github-actions-validation)
- [Recommended Command Matrix](#recommended-command-matrix)
- [CI Expectations](#ci-expectations)
- [Changelog](#changelog)
---
## Core Workflow
Typical development loop:
```bash
just check
just check-fast
just fix
just test
just ci
```
These commands ensure:
- formatting
- linting
- static analysis
- tests
Treat this as a menu, not a required sequence. The validation matrix below is
the handoff source of truth.
## Validation Command Selection
Use the smallest non-mutating validator that covers the files you changed while
iterating. For final handoff validation, match commands to the changed file
surfaces instead of defaulting all edits to full CI.
Core Rust code means production Rust or manifest changes that can affect library
behavior, public API, features, examples, benchmarks, or downstream users. It
does not include Rust doctest-only, unit-test-only, integration-test-only,
benchmark-only, or example-only edits when the focused validator covers the
changed surface.
| Markdown documentation (`*.md`) | `just markdown-check` | `just check-docs` |
| Python under `scripts/` | Targeted pytest or `just test-python`; add `just python-check` for logic/style | `just python-check` and `just test-python` |
| Jupyter notebooks (`notebooks/**/*.ipynb`) | `just notebook-check` | `just notebook-check` |
| Paper sources and figures (`papers/**/*`, paper notebooks) | `just paper-check` | `just papers` |
| Configuration only (JSON, TOML, YAML, CFF, workflows) | Matching config validator | `just check-config` |
| Rust unit tests only (`#[cfg(test)]` in `src/**`) | Targeted `cargo test --lib <filter>` or `just test-unit` | `just test-unit` |
| Rust doctests only (`///` examples or crate docs) | Targeted `cargo test --doc --release <filter>` or `just test-doc` | `just test-doc` |
| Rust integration tests only (`tests/**`) | Targeted `cargo nextest run --test <name>` or `just test-integration-fast` | `just test-integration` |
| Rust benchmark files only (`benches/**`) | Targeted benchmark command or `just bench-smoke` | Matching benchmark validator |
| Rust examples only (`examples/**`) | Targeted `cargo run --example <name>` or `just examples` | `just examples` |
| Core Rust code | Focused checks or targeted tests while iterating | `just ci` |
| Mixed focused surfaces without core Rust | Run each matching focused validator once | Run each matching focused validator once |
| Mixed core Rust plus tests/benches/examples/docs/config | Focused checks while iterating | `just ci` |
Do not run `just ci` merely because documentation, configuration, Python,
notebook, or test-only Rust files changed. Do not run `just test` when a single
focused test bucket covers the change unless you intentionally want the full
default test suite. When a diff touches multiple focused test surfaces, compose
the matching recipes once each; for example, run `just test-doc` and
`just test-integration` for doctest plus integration-test changes. Broad Rust
correctness workflows compose `just test-unit`, `just test-integration`,
`just test-cli`, and `just test-doc` through `just test-rust`.
During fast code-writing cycles, start with the smallest changed test or
doctest rather than the whole focused bucket. For single-item rustdoc edits, run
`cargo test --doc --release <item-or-module-filter>`; for unit-test edits, run
`cargo test --lib <test-or-module-filter>`; for integration-test crate edits,
run the changed crate with `cargo nextest run --test <crate>`. Cargo's built-in
test-name filter accepts one filter per invocation, so run separate filtered
commands for unrelated changed tests or choose one shared module/name prefix
that covers the intended small group. Use `just test-doc`, `just test-unit`, or
`just test-integration` for final bucket validation or broad changes.
Focused validators own one target class. Avoid adding a compile-only smoke
recipe before a recipe that already compiles and runs the same target class.
For benchmark-only changes, run the changed benchmark with
`cargo bench --profile perf --bench <name>` when the change affects measured
behavior. Use `just bench-smoke` for harness-only edits, and `just bench` for
broad benchmark-suite changes.
## Justfile Usage
This repository standardizes development tasks through the `justfile`.
Run bare `just` for the curated workflow guide and `just --list` for the
complete grouped command reference. Public recipes are documented, grouped,
and kept in lexicographic source order so both views are easy to scan. Each
public recipe owns one distinct operation; broader workflows compose those
recipes instead of repeating their commands. Shared private guards and
parameterized implementation helpers live in `just/helpers.just`.
Tool-version variables in the root `justfile` are the source of truth for both
local setup and GitHub Actions. Before the first `just` invocation, run
`bash scripts/bootstrap_just.sh`; it installs the pinned Just release only when
that exact version is not already available. `just setup-tools` then installs
or synchronizes the repository toolchain. It requires `uv`, `gh`, `jq`,
`rustup`, Cargo, and `chktex` on `PATH`, installs the pinned Rust CLI tools, and
provisions the unpinned `cargo-update` bootstrap package that supplies
`cargo-install-update`. Its final inventory verifies both `gh` and
`cargo-install-update`. Private `_ensure-*` dependencies fail fast when a
required tool or pinned version is unavailable during an individual recipe.
`just setup` composes `setup-tools` with the development build.
Use `just update` for deliberate dependency and tool maintenance. It composes
`just update-dependencies`, which advances compatible and incompatible Cargo
requirements and lockfiles for both the root package and the isolated
`tests/fixtures/checkpoint_no_float_roundtrip/` resolution root, resolves any
exact direct pins under
`[dependency-groups].dev` as one universal set for the supported Python
version, then upgrades `uv.lock`, with
`just update-cargo-tools`, which upgrades only the locally installed Cargo CLI
packages owned by `setup-tools` and atomically reconciles their root `justfile`
pins plus the active uv version after every requested package updates
successfully. uv remains an external prerequisite managed outside this
repository; the update workflow accepts its active version long enough to
record the new pin but does not replace the uv installation. Ordinary uv-backed
recipes continue to require the exact reconciled pin. The Cargo tool updater
requires `cargo-install-update` from the `cargo-update` package and does not
touch other Cargo-installed executables or uv's user-global tool environments.
`setup-tools` and CI consume the reconciled declarations. The exact-pin step
leaves ranged development requirements, project/runtime dependencies, optional
dependencies, build requirements, and intentional uv overrides unchanged.
The aggregate `just update` runs its `cargo-install-update` preflight before
either dependency updater can change declarations or lockfiles.
Agents should **prefer running `just` commands instead of invoking the
underlying tools directly**. The justfile ensures the correct flags,
configuration, and tool ordering are used.
Examples:
- prefer `just check` instead of running `cargo clippy` directly
- prefer `just fix` instead of running `cargo fmt` directly
- prefer `just ci` instead of manually running multiple validation steps when
full CI is the right validation level
Direct tool invocation should only be used when a corresponding `just`
command does not exist.
---
## Formatting
Rust and justfile formatting checks are non-mutating:
```bash
just fmt-check
just justfile-fmt-check
```
Apply formatting through:
```bash
just fix
```
Run checks before mutating fixers; formatting drift should be understood before
`just fix` rewrites files. The focused mutating recipes are `just fmt` for Rust
and `just justfile-fmt` for the root and helper justfiles.
---
## Linting
Lint checks include:
```bash
cargo clippy
```
Repository warnings are denied through the manifest lint policy in
`Cargo.toml`; explicitly configured lint exceptions remain warnings. Clippy
invocations also deny warnings.
Run via:
```bash
just check
```
`just check` is the non-mutating lint/validator bundle. It does not run tests,
examples, or benchmarks.
`just check-fast` is the cheapest compile-only check:
```bash
just check-fast
```
`rust-core-check` runs all-targets Clippy in the default and all-features
configurations. This intentionally includes the all-targets, all-features
surface uploaded by the PR Clippy SARIF workflow, so `just ci` fails locally on
the same warning classes that would become GitHub code-scanning annotations.
---
## Documentation Validation
Documentation must build successfully.
Verify with:
```bash
just doc-check
```
or
```bash
cargo doc
```
Release-facing version references are checked separately:
```bash
just docs-version-check
```
This compares the Cargo package version against `Cargo.lock`, `pyproject.toml`,
`uv.lock`, `CITATION.cff`, release-pinned README links, active documentation
dependency and `cargo add` snippets, and current-tag benchmark workflow
examples.
After generating a release changelog, run the strict final release gate:
```bash
just release-version-check
```
It invokes `check-docs-version-sync --final-release`, requiring exactly one
current-version changelog heading whose date matches `CITATION.cff`.
---
## Full CI Validation
Before core Rust changes, broad API-affecting changes, release-style
validation, or explicit maintainer requests, run the full CI command:
```bash
just ci
```
This runs:
- formatting checks
- justfile formatting checks
- GitHub Actions checks
- Markdown checks
- release-version reference synchronization
- `Cargo.toml`/`Cargo.lock` synchronization
- JSON/TOML/YAML/CFF checks
- Python lint/typecheck
- notebook hygiene and extracted-code checks
- canonical validation-figure currentness on macOS
- shell script formatting and lint checks
- Rust core lint, documentation, and Semgrep checks
- benchmark harness compile checks
- Rust lib unit tests
- Rust doctests
- Rust release integration tests
- Python tests
- example builds
---
## Benchmark Profiles
For performance-sensitive code changes, follow
[`perf-tuning.md`](perf-tuning.md): benchmark before editing, add a benchmark
when none covers the hot path, benchmark after editing, and preserve
scientific invariants throughout. Benchmark output is only evidence when the
measured workflow maintains its triangulation, predicate, topology, and
diagnostic invariants.
`just ci` is the comprehensive error-catching validation path used by GitHub
Actions. It composes `just check`, `just test`, `just bench-compile`, and
`just examples`. The target classes remain orthogonal: `rust-core-check` covers
formatting, all-targets Clippy, rustdoc, and Semgrep; `unused-deps` checks direct
Cargo dependency hygiene; `test-rust` composes unit, integration, CLI, and
doctest buckets; `notebook-check` validates notebooks without executing them.
Routine notebook checks are lint-only. On macOS, `just ci` also executes only
the validation notebook through `validation-doc-figures-check`, regenerating
under `target/` and failing when tracked canonical figures are stale. Execute
other notebooks deliberately with `just notebook-execute` or use a named
artifact-refresh recipe. There is no aggregate recipe that executes every
notebook.
`just semgrep` scans repository-owned Rust under `src/`, `examples/`, and
`benches/`. Because Semgrep's default ignore policy excludes test directories,
the shared target enumerator also supplies tracked Python and Rust tests to
both local validation and the hosted SARIF workflow. Deliberate violations
under `tests/semgrep/` remain excluded from repository scans and are exercised
only by `just semgrep-test`.
`just test` is tests-only. `test-integration-compile` is an explicit no-run
smoke recipe for cases where a compile-only check is the desired validator; do
not run it before `test-integration` unless you intentionally want a separate
compile-only pass. `test-unit` runs lib unit
tests in both debug and release profiles so debug assertions and default
overflow checks remain covered. The nextest `debug` profile preserves the
default 10-second watchdog, with 60-second overrides for the two periodic
builder cases whose debug exact-geometry cost is platform-sensitive and the
optimized 5D intersection agreement checks, which can reach that boundary on
hosted runners. The randomized 5D full-report agreement check has the same
focused override across platforms. The translated 5D and complete 6D exact
SoS expansion checks, including the D=6 adaptive-kernel checks that repeat the
complete expansion, also have a focused 60-second override because their
irreducible cold-path work can cross the default boundary on hosted runners.
`test-integration` runs a focused release-profile nextest bucket. Selected 4D
property families retain that default coverage with a Windows-only 60-second
override because their release runtimes sit at the 10-second boundary on
Windows runners. The 5D local-neighbor repair guardrail has the same focused
Windows-only override. The cospherical 3D `OnSuspicion` sequence property has
a focused cross-platform 60-second override for the same hosted-runner boundary.
The isolated downstream checkpoint fixture has a focused 120-second override
because it compiles a standalone crate in a separate target directory to prove
that Cargo feature unification does not supply `serde_json/float_roundtrip`.
The deterministic 5D SoS in-sphere property has a cross-platform 60-second
override because its two complete exact expansions per generated case can also
cross that boundary on hosted runners. Unaffected tests keep the normal budget.
`test-cli` owns the feature-gated binary unit and CLI integration tests, and
`test-rust` composes every Rust test class once.
The LLVM-instrumented coverage profile retains its 300-second default watchdog
and grants a 1,200-second override only to the three compact `T^3` builder cases
that exercise periodic-image construction.
```bash
just ci
just test
just rust-core-check
just test-rust
just notebook-check
just bench-compile
```
Performance workflows use the following command surface. Commands that perform
measurements use the `perf` profile; `performance-doc` and
`performance-readme` only consume retained evidence:
```bash
just bench
just bench-ci
just bench-latest
just bench-latest-vs-last
just bench-compare [baseline] [suite] [scope]
just bench-save-baseline v0.7.8
just performance-local
just performance-github-assets
just performance-release
just performance-doc
just performance-readme
just perf-baseline
just perf-compare
just perf-vs-ref
just perf-no-regressions
just bench-perf-summary
just bench-pachner-stress
cargo bench --profile perf --bench ci_performance_suite
```
The `perf` profile inherits from release and restores ThinLTO with one codegen
unit. Use it for measured benchmark output; `just ci` does not need it to catch
compile, lint, test, documentation, example, or benchmark-harness build errors.
Use `just bench-smoke` only for quick harness validation with minimal samples;
do not treat smoke output as performance data.
Workspace-wide benchmark recipes (`just bench`, `just bench-smoke`,
`just bench-compile`, and the benchmark compile step inside `just ci`) enable
`--features bench` so feature-gated benchmark fixtures and benchmark-only
dependencies are compiled.
Use `just pachner-stress [attempts] [validate_every] [mode]` for the manual 3D+4D
direct Pachner diagnostic run through the opt-in `pachner-stress` binary. This
aggregate recipe accepts only those three parameters and fixes the 3D and 4D
workloads at 9,000 and 1,000 vertices, respectively. To change a vertex count,
use the dimension-specific `just pachner-stress-3d [attempts] [vertices]
[validate_every] [output_dir] [mode]` or `just pachner-stress-4d [attempts]
[vertices] [validate_every] [output_dir] [mode]` recipe; their `vertices`
parameters default to 9,000 and 1,000, respectively. All three recipes default
to 100 workload steps with progress every 10 steps, write progress CSV plus
summary JSON under `target/pachner_stress/`, and keep parseable stdout
stage/report/progress lines so long workloads can be diagnosed without making
the workflow part of routine CI. These direct stress recipes currently validate
topology scope only (Levels 1-3); the large Level 4 realization overlap scan is
deferred to the dedicated realization-validation work. The `pachner-stress`
binary supports `round-trip` and `random-walk` modes; `round-trip` is the
default. The existing `--attempts` flag counts forward/inverse pairs in
`round-trip` mode and candidate/proposal cycles in `random-walk` mode. Schema
version 2 reports configured/completed steps separately from actual proposal
attempts and accepted mutations, and computes interim acceptance over completed
proposals. Use
`just bench-pachner-stress` when Criterion timing statistics for stable 4D move
and inverse fixtures are needed.
Some repair benchmarks need feature-gated fixtures that deliberately construct
invalid-but-structurally-coherent topology. Run those harnesses with
`--features bench`; the `bench` feature exists only for benchmark fixtures and
benchmark-only dependencies, and must not expose normal construction escape
hatches:
```bash
cargo bench --profile perf --features bench --bench pl_manifold_repair -- --noplot
```
Use `just perf-large-scale-smoke [max_secs]` for a coarse local wall-clock guard
over the release-mode large-scale debug harness. It runs the same 2D-5D defaults
as `just debug-large-scale-{2,3,4,5}d`, caps each test runtime at 60 seconds by
default, and reports all failing dimensions before exiting. It does not compare
against a baseline and should not be treated as benchmark data. Run it before
pushing Rust or benchmark changes to catch obvious local performance drift early.
Use `just bench-perf-summary` from the release PR branch after version and
documentation updates. It runs fresh perf-profile summary benchmarks, records
the current Criterion construction metadata and generated simplex counts, and
regenerates `benches/PERFORMANCE_RESULTS.md`.
Use `just bench-latest` when you need the curated release-signal Criterion
suite for local saved-baseline comparisons. The recipe executes the immutable
target/section/group plan in `scripts/benchmark_utils.py`, leaving
`target/criterion/new` data suitable for `just bench-compare`; release CI and
strict summary generation consume that same plan. The manual
`topology_guarantee_construction` suite remains
available through `just bench-save-baseline <tag> topology` and
`cargo bench --locked --profile perf --bench topology_guarantee_construction`. Save the previous release
signal as `last` with `just bench-save-baseline last` from the baseline
checkout, or save an explicit baseline name with the same recipe. Use
`just performance-local` when you want the tool to manage isolated
baseline/current worktrees.
Manual `just bench-latest` runs use a 30-minute timeout for each target unless
an override is supplied. The release workflow uses a two-hour failure ceiling
per target and derives its outer ceiling from all five curated targets
(currently up to ten hours). A target timeout invalidates the measurement; rerun
the complete release workflow rather than treating partial Criterion output as
release evidence.
```bash
# In the baseline checkout, usually the previous release:
just bench-save-baseline last
# In the current checkout:
just bench-latest-vs-last
just bench-compare last
```
If you saved the baseline with an explicit release tag instead, pass that tag
to the report step, for example `just bench-compare v0.7.8`.
Use lower-level `uv run --locked benchmark-utils bench-compare --scope all-benches` only
when you explicitly want an exploratory report over every Criterion result
already present under `target/criterion/`.
Use `just performance-local` for an isolated temp-worktree comparison of the
current package version against the latest stable published release. It runs
local benchmarks and retains adjacent Markdown, versioned CSV, and provenance
JSON under `target/bench-reports/` without changing tracked docs. Use
`just performance-github-assets` to retain a provenance-validated bundle from
stored GitHub Release benchmark assets without local Cargo runs. Supported
archives carry versioned source, command, toolchain, completed-target,
measurement-plan, per-run host, sample, and content-digest metadata bound to
the requested clean tag. Existing legacy archives remain loadable as
provenance-limited absolute timing evidence. GitHub-asset ratios are always
suppressed because the archives came from separate measurement sessions. Use
`just performance-release` in release PRs to measure, retain, reload-validate, and
promote one curated comparison into `docs/PERFORMANCE.md`, archiving the
previous report and exact promoted CSV/provenance bytes under
`docs/archive/performance/`.
Use `just performance-doc` to retry rendering or promotion from an existing
retained CSV/provenance pair. It runs no Cargo benchmarks or measurement
worktrees and rejects incomplete, invalid, stale, same-version, or
scientifically non-comparable pairs. Promotion uses per-file atomic replacement
with rollback for caught failures; after a hard interruption, inspect the
destinations and rerun the idempotent command. The GitHub
asset and release-promotion recipes accept explicit `<current-tag>
<baseline-tag>` pairs for repair paths, but both tags must be supplied together
before any fetch or benchmark side effect. Temp-worktree release commands apply
tracked checkout changes by default; untracked files must be added to git before
they affect the generated report.
Use `just performance-readme` after `performance-release` to validate that the
retained bundle exactly matches the promoted durable evidence, then publish a
compact group-level README table and the canonical CSV/provenance pair under
`docs/assets/bench/`. It runs no benchmarks, updates tag-pinned evidence links,
and rolls back every README-owned destination on caught failures.
Scratch Markdown identifies the adjacent CSV/provenance pair under
`target/bench-reports/`. A promoted report instead identifies the exact durable
pair copied under `docs/archive/performance/data/`. Broad configuration digests
remain recorded provenance; cross-release comparability uses the normalized
measurement plan, harness identity, toolchain, completed targets, host, and
confidence level.
CSV is canonical because the comparison is a small, deterministic, diffable
audit record. Notebooks may derive disposable Parquet caches from it for larger
analyses, but `performance-doc` accepts only the validated CSV and provenance
JSON pair. Raw Criterion data remains in the release `.tar.gz` assets.
Before pushing Rust or benchmark changes, run:
```bash
just ci
just perf-large-scale-smoke
```
For performance-sensitive changes and PR-ready work, also run:
```bash
just perf-no-regressions
```
## Slow Correctness Tests
The routine correctness suite has two buckets:
- `just test` runs default tests that should stay under roughly 10 seconds per
test.
- `just test-slow` runs tests gated by the `slow-tests` feature when a
deterministic correctness or regression case exceeds that budget.
`just test-slow` runs in release mode with the repository's `slow` nextest
profile. Debug-mode exact-predicate arithmetic can make high-dimensional tests
look like hangs, so slow correctness timing should be measured with the release
recipe. Deterministic slow tests should use `#[cfg(feature = "slow-tests")]`,
not `#[ignore]`. The recipe is the maintained execution path for every test
hidden by that feature and includes feature-gated doctests after the nextest
run. When adding or removing a gate, compare nextest discovery with and without
`--features slow-tests` so the slow-only case is demonstrably owned by this
lane.
`just perf-no-regressions` is the fuller local PR guard. It runs
`ci_performance_suite` with the shared dev-mode Criterion arguments against a
same-machine baseline generated from the current GitHub `main` ref. The guard
reuses a local cache under `baseline-artifacts/perf-no-regressions/` keyed by
the resolved `origin/main` commit and local Rust compiler version, and refreshes
that baseline when `main` or the compiler changes, or when the cached artifact
does not match the benchmark contract. The current worktree benchmark still runs
fresh each time so repeated comparisons can catch local performance drift.
The comparison report is written to
`benches/worktree_vs_main_compare_results.txt` by default so it is visibly a
branch/PR-vs-main check. The local guard exits nonzero only when benchmark
execution fails or total matched benchmark mean time regresses beyond the
threshold; individual benchmark regressions are warnings in the report. The
report also lists total, geomean, median, top regressions, and top improvements,
and the command prints a short terminal status with the report path.
`just clean` removes Criterion data under `target/`, but it does not remove this
local baseline cache.
```bash
just perf-no-regressions
```
To compare the current branch against a specific local release/ref baseline,
use `just perf-vs-ref`:
```bash
just perf-vs-ref v0.7.8
```
It uses the same cached same-machine baseline flow as `just perf-no-regressions`
but resolves and caches the requested ref, writes a
`benches/worktree_vs_<ref>_compare_results.txt` report, and treats overall total
matched-time regressions as failures while keeping individual benchmark
regressions as report warnings.
`just perf-baseline` is optional and intentionally persistent: use it only when
you want to create or refresh `baseline-artifact/baseline_results.txt` for later
manual same-machine comparisons. `baseline-artifact/` and
`baseline-artifacts/` are ignored by git so local timing records stay local. CI
regression checks now download the latest stable GitHub Release asset,
`delaunay-vX.Y.Z-criterion-baseline.tar.gz`, and compare the current
`ubuntu-latest` GitHub Actions run against that released-version Ubuntu
baseline.
`just perf-compare <file>` still writes
`benches/main_vs_release_compare_results.txt` by default. It follows the same
terminal-status convention, but remains stricter: individual benchmark
regressions still make release-style comparisons fail.
For lower-level workflows, `uv run --locked benchmark-utils ensure-ref-baseline --ref
<ref> --dev` prints the cached/generated same-machine baseline path for a branch
or version tag, and `uv run --locked benchmark-utils fetch-baseline --ref <ref>` downloads
the manual compatibility GitHub Actions artifact instead. Use the generated
local baseline for same-machine regression checks; use the downloaded artifact
only when you explicitly want CI-runner parity. `uv run --locked benchmark-utils
compare-ref --ref <ref>` writes
`benches/worktree_vs_<ref>_compare_results.txt` unless `--output` is supplied.
To generate a scratch baseline without replacing the default artifact, write it
somewhere else and compare directly:
```bash
just perf-baseline-to /tmp/delaunay-main-baseline
just perf-compare /tmp/delaunay-main-baseline/baseline_results.txt
```
---
## Examples
Example programs live in:
```text
examples/
```
Validate with:
```bash
just examples
```
Examples must:
- compile
- run successfully
- demonstrate correct API usage
---
## Spell Checking
Documentation and comments are spell‑checked.
`just spell-check` scans every tracked file plus unignored files that are new in
the working tree, so the same recipe covers clean CI checkouts and local work.
Run:
```bash
just spell-check
```
If a legitimate technical word fails:
Add it to:
```text
typos.toml
```
under:
```toml
[default.extend-words]
```
Allowlist the exact acronym or domain term rather than a shorter fragment.
`typos` can split some plural capitalized acronyms unexpectedly; prefer wording
such as “PNG files” over allowlisting the shorter fragment reported by the
diagnostic.
---
## Notebook Validation
Notebook policy for cell identity, source hygiene, deliberate execution, and
tracked artifacts lives in [`notebooks.md`](notebooks.md). Notebook code is
extracted and checked with Ruff and ty so `.ipynb` cells follow the same Python
standards as repository scripts.
Commands:
```bash
just notebook-check
just notebook-execute notebooks/00_quickstart.ipynb
just notebook-clear-outputs-all
just notebook-reset-from-git
```
`notebook-check` runs notebook hygiene and extracted-code checks without
executing notebooks. Explicit notebook execution writes the executed notebook
and generated artifacts under `target/notebooks/<notebook-stem>/` while leaving
the source notebook unchanged. The
quickstart Euclidean hero preview also defaults to
`target/notebooks/00_quickstart/delaunay_3d_readme.png` and is not a tracked
artifact. The tracked spherical README hero is generated separately with
`just spherical-readme-hero`. Notebook names do not encode expected runtime
because execution cost depends on chosen parameters.
`just notebook-reset-from-git` discards edits to tracked source notebooks by
restoring tracked `.ipynb` files under `notebooks/` from the Git index, removes
`target/notebooks/`, and deletes Jupyter checkpoint directories. Pass an
explicit source when needed, for example `just notebook-reset-from-git HEAD`, to
restore notebooks from a committed tree instead of the current index.
These recipes keep the CI shape stable as notebooks are added or split. The
repository intentionally has no aggregate recipe that executes every notebook.
`just spherical-readme-hero` is the deliberate, potentially long-running
refresh path for `docs/assets/readme/delaunay_spherical_readme.png`. It executes
`notebooks/02_spherical_hero.ipynb` with the perf-profile Rust CLI;
routine notebook checks do not regenerate the tracked hero.
---
## Paper Build
Publication-facing TeX lives under `papers/`. The source `.tex` file and the
compiled reviewer `.pdf` live side by side, while LaTeX auxiliary files are
ignored and build under `target/papers/`.
Commands:
```bash
just paper-cli
just validation-doc-figures
just validation-doc-figures-check
just paper-tex-fmt-check
just paper-tex-lint
just paper-build
just paper-pdf-check
just paper-check
just paper-artifact-check
just paper-refresh
just papers
```
`just paper-cli` builds the local `delaunay` binary used by paper notebooks
before nbconvert starts its execution timeout. `just validation-doc-figures`
refreshes the canonical PNG files under `docs/assets/validation/`, which are
reused directly by `papers/validation.tex`. It validates the complete six-file
set in staging and publishes it transactionally, preserving the prior complete
set if rendering or publication fails. `just validation-doc-figures-check`
uses the same generator under `target/` and compares the complete set without
modifying tracked files. `just ci` composes that check on macOS, the canonical
paper-artifact platform. Ordinary notebook validation and direct interactive
execution do not refresh tracked figures. `just paper-tex-fmt-check` runs `tex-fmt --check`,
and `just paper-tex-lint` runs `chktex` over `papers/*.tex`. `just paper-build`
compiles
`papers/validation.tex` with Tectonic in `target/papers/validation/` without
changing tracked files. `just paper-pdf-check` uses the uv-managed
`paper-pdf-check` helper to verify that target-built PDF opens, has pages,
includes expected title/reference text, and does not contain the literal
`\today`. `just paper-check` lints, builds, and sanity-checks a paper without
refreshing tracked artifacts. `just paper-artifact-check` additionally compares
the rebuilt and tracked reviewer PDFs page by page using extracted text and page
geometry, avoiding a false requirement that platform-native PDF internals be
byte-identical. `just paper-refresh` runs the basic check before copying the
target-built PDF to `papers/validation.pdf`. `just papers` refreshes the
canonical figures and reviewer PDF through those named artifact owners.
Tectonic and `tex-fmt` are pinned Cargo-installed tools. `chktex` comes from a
TeX distribution or system package manager. Local macOS installations provided
by MacTeX place commands under `/Library/TeX/texbin`; if a non-interactive shell
does not load that directory, run paper recipes with
`PATH=/Library/TeX/texbin:/opt/homebrew/bin:$PATH`. Installing or upgrading
Tectonic from Cargo also requires a `pkg-config` implementation and development
headers for its externally resolved native bridge libraries. macOS requires
FreeType, Graphite2, ICU, libpng, and zlib, but not fontconfig. Non-Apple
platforms additionally require fontconfig and OpenSSL. The pinned default build vendors
HarfBuzz. When the pinned Tectonic version is absent, `just setup-tools`
requires `pkg-config` (commonly installed as `pkgconf`) and checks the
platform-specific external native dependency set. On macOS it auto-detects
common Homebrew metadata
directories, including the active SDK metadata used for system compression
libraries, before it asks for a manual `PKG_CONFIG_PATH`. An already-correct
Tectonic installation does not require those native build prerequisites. Paper
CI installs the platform native package set explicitly, caches Tectonic's
versioned user bundle directory, and warms a cold bundle cache with bounded
download retries before starting the paper build.
Reviewer-facing validation diagrams under `docs/assets/validation/` use the
same deterministic notebook with a separate explicit output switch:
```bash
just validation-doc-figures
just validation-doc-figures-check
```
Routine notebook checks and the non-mutating currentness check write only under
`target/`; neither tracked documentation nor paper figures are refreshed
implicitly.
---
## Markdown Checks
Markdown files are checked with rumdl and spell-checking for handoff. Keep the
non-mutating check before the mutating fixer in user-facing command examples.
Commands:
```bash
just markdown-check
just markdown-fix
```
---
## TOML Checks
TOML files should parse cleanly, pass Taplo linting, and match Taplo
formatting.
Commands:
```bash
just toml-check
just toml-lint
just toml-fmt-check
just toml-fix
```
---
## YAML Checks
YAML and `CITATION.cff` files should match the dprint/pretty_yaml formatting
configuration and pass yamllint.
Commands:
```bash
just yaml-check
just yaml-fix
```
`just yaml-check` runs both `just yaml-fmt-check` and `just yaml-lint`; use
`just yaml-fix` for the mutating dprint formatter.
---
## Shell Script Validation
Shell scripts must pass:
```text
shfmt
shellcheck
```
Run the focused non-mutating validator with:
```bash
just shell-check
```
`just shell-check` composes the focused `just shell-lint` and
`just shell-fmt-check` leaves, and `just ci` includes the aggregate check.
---
## JSON Validation
JSON files should be validated after edits.
Run:
```bash
just json-check
```
---
## CITATION.cff Validation
Citation metadata should pass both YAML style linting and CFF schema
validation.
Run:
```bash
just citation-check
```
---
## GitHub Actions Validation
Workflows must pass `actionlint`.
Run with:
```bash
just action-lint
```
---
## Recommended Command Matrix
| Run lints | `just check` |
| Fast compile check | `just check-fast` |
| Check formatting | `just fmt-check` |
| Check justfile formatting | `just justfile-fmt-check` |
| Apply formatters/auto-fixes | `just fix` |
| Validate Markdown-only changes | `just check-docs` |
| Validate release-version references | `just docs-version-check` |
| Validate final release changelog/citation synchronization | `just release-version-check` |
| Validate `Cargo.toml`/`Cargo.lock` synchronization | `just cargo-lock-check` |
| Validate configuration-only changes | `just check-config` |
| Validate Python scripts/tests | `just python-check` and `just test-python` |
| Validate notebook changes | `just notebook-check` |
| Verify tracked validation figures are current | `just validation-doc-figures-check` |
| Validate shell script changes | `just shell-check` |
| Validate core Rust checks | `just rust-core-check` |
| Run all default test buckets | `just test` |
| Run Rust tests only | `just test-rust` |
| Run CLI-feature binary unit and integration tests | `just test-cli` |
| Run Rust lib unit tests only | `just test-unit` |
| Run doctests only | `just test-doc` |
| Run integration tests | `just test-integration` |
| Compile benchmark harnesses | `just bench-compile` |
| Compile release integration tests without running | `just test-integration-compile` |
| Run examples | `just examples` |
| Update dependency declarations, locks, and repo-owned Cargo tools | `just update` |
| Update Cargo declarations and Cargo/Python dependency locks | `just update-dependencies` |
| Update release metadata with the current UTC date | `just update-version vX.Y.Z` |
| Validate crates.io metadata and dry-run the package | `just publish-check` |
| Run full GitHub-equivalent CI | `just ci` |
| Run perf-profile benchmarks | `just bench` |
---
## CI Expectations
CI enforces:
- GitHub Actions checks
- Markdown, JSON, TOML, YAML, CFF, and spell checks
- release-version reference synchronization
- `Cargo.toml`/`Cargo.lock` synchronization
- Python lint, type checks, and tests
- notebook hygiene and extracted-code checks
- shell script formatting and lint checks
- core Rust formatting, Clippy, rustdoc, and Semgrep checks
- Rust unit, doctest, and integration tests
- benchmark harness compilation
- examples
The default portability contract runs the same `just ci` recipe on Linux,
macOS, and Windows. Optimize bootstrap and caching without silently reducing
that platform coverage; a narrower matrix requires an explicit replacement for
each lost portability check.
The root `justfile` owns managed tool-version pins. After bootstrapping `just`
through `.github/actions/setup-just`, workflows resolve those pins with
`just --evaluate` instead of repeating version literals. Rust workflow caches
must keep `cache-bin: false`: restoring `${CARGO_HOME}/bin` can replace
rustup-managed Cargo shims with stale or host-incompatible binaries.
`.codacy.yml` owns Codacy engine and path policy. Keep Codacy feedback aligned
with repository validators rather than establishing an independent style or
static-analysis regime.
Rust warnings are denied by the manifest lint policy and Clippy warnings are
denied by `just clippy`. Keep any
intentional warning-level exceptions explicit in `Cargo.toml`.
Agents must ensure changes pass the appropriate local validator before
proposing patches. Use the validation matrix above for final handoff: core
Rust/Cargo changes require `just ci`, while documentation, configuration,
Python, test-only, benchmark-only, and example-only changes use their focused
validators and compose them once each when multiple surfaces changed.
---
## Changelog
The changelog is **auto-generated**.
Never edit manually.
Regenerate with:
```bash
just changelog
```
This runs `git-cliff`, applies the Python postprocessor, archives completed
minor release series under `docs/archive/changelog/`, and applies `rumdl`
formatting to the generated changelog files.
For release PRs, generate the changelog for a version before the final tag
exists with:
```bash
just changelog-unreleased vX.Y.Z
```
First set release metadata; the updater records the current UTC date:
```bash
just update-version vX.Y.Z
```
Same-day retries are content-idempotent; a retry after UTC midnight updates
`CITATION.cff` and any existing target changelog heading together.
`changelog-unreleased` first rejects a non-stable tag or a tag that differs
from Cargo metadata, before `git-cliff` writes the changelog, then synchronizes
the generated heading from `CITATION.cff`. Finish with
`just release-version-check` and `just publish-check` before merge or
publication.
Create annotated release tags from the generated changelog after the release PR
is merged with:
```bash
just tag vX.Y.Z
```