# 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)
- [Local CodeRabbit Review](#local-coderabbit-review)
- [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
Available development commands:
```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 source of truth for iteration and PR readiness.
## Validation Command Selection
Use `just check` during iterative review and fixes, alongside the smallest
targeted tests that exercise changed behavior. Focused validators provide
quicker feedback on individual surfaces, and `just check-fast` is available
for compile-only feedback.
Reserve `just ci` for final validation once those iterations are complete,
when preparing core Rust/Cargo or public-behavior changes for PR readiness or
push. Release validation and explicit maintainer requests may also require
full CI. An intermediate local handoff records the checks run during iteration;
it does not by itself trigger `just ci`. For non-core changes, compose the
matching focused validators once each.
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 sources and fixtures | Targeted pytest and `just python-check` | `just python-check`, `just python-fixture-lint`, 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 | `just check` and targeted tests | `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 | `just check` and targeted tests | `just ci` |
For Semgrep fixture changes, also run `just semgrep-test` to preserve the
deliberate positive and negative cases.
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.
## Local CodeRabbit Review
CodeRabbit review is opt-in. Agents may run `just review` or
`just review-uncommitted` only when the maintainer explicitly requests that
command or gives permission for the CodeRabbit review. A general request to
review, fix, validate, or prepare a PR does not authorize sending the diff to
this external service. Without authorization, continue local review and the
applicable validators; CodeRabbit is not a PR-readiness requirement. Do not
interrupt routine work to request a CodeRabbit review.
When authorized, run the review after substantive changes settle and fast
checks pass. Assess each finding against the repository's contracts, fix valid
issues, and run the affected checks.
```bash
just review # Complete branch diff against local main
just review origin/main # Use a different locally available PR base
just review-uncommitted # Only staged, unstaged, and new files
```
`just review [base]` includes committed branch changes and local edits;
`just review-uncommitted` excludes already committed changes. Both include
non-ignored untracked files and pass `AGENTS.md` and `.coderabbit.yml` as
additional review instructions. Inspect the intended diff before invoking
either recipe. The base defaults to local `main`; choose the actual PR base
and ensure it is current. These commands do not fetch or change Git state.
The recipes use CodeRabbit's `--agent` output so agents can read structured
findings. Install the [CodeRabbit CLI](https://docs.coderabbit.ai/cli) separately
and authenticate with `coderabbit auth login` before the first review. The
required scope flags are supported by CLI 0.7.6; consult
`coderabbit review --help` when using another version. CodeRabbit is an
external prerequisite, separate from the tools managed by `just setup-tools`.
CodeRabbit review is separate from `just check` and `just ci`: it uses a remote
service, authentication, and review allowances. CLI failures propagate through
the recipes. If an authorized review cannot run because of authentication,
service errors, exhausted allowances, or another access limitation, report it
as unavailable, never as a clean result. Report the scope, completion status,
actionable findings, fixes, and any remaining issues in the handoff. A review
that was not requested is simply not run; it does not block local validation
or handoff.
Reuse a completed review of the same diff. Any rerun must be covered by the
maintainer's explicit authorization and warranted by substantial fixes or new
changes. After fixes, run `just ci` for core Rust/Cargo or public
behavior changes, or the focused final validators in the matrix above for
other changes. Keep the GitHub PR review: its broader context can produce
different findings from the local CLI review.
## 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 stable `X.Y.Z` 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` and stable-uv
preflights before either dependency updater can change declarations or
lockfiles. Direct `just update-dependencies`, `just update-python-dependencies`,
and `just update-cargo-tools` also check stable uv before their updates.
These entry points reuse the pin reconciler's version parser without requiring
uv to match the tracked pin. This check uses an already installed Python
interpreter with dependency syncing and Python downloads disabled; invalid uv
output fails before updates begin.
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
Once iterative review and fixes are complete, core Rust/Cargo or public-behavior
changes must pass the full CI command before a PR is ready or the changes are
pushed. Also run it for release validation or an explicit maintainer request:
```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 formatting, full-policy lint, and type checks across tracked and new sources
- direct Python Semgrep fixture lint
- 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
[`TUNING-PERFORMANCE.md`](TUNING-PERFORMANCE.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 python-fixture-lint`, `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 bounded randomized 6D intersection agreement check and
randomized 5D full-report agreement check have 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.
The compact `T^3` builder case that validates topology and Delaunay has a
1,800-second override; the reversed-input and orientation-reversing-map cases
retain their 1,200-second overrides for 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-preflight
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.
`just bench-preflight [bench_timeout]` executes fixture setup and one operation
for every case in every curated target using Criterion `--test`, without
sampling, saved baselines, or measurement sidecars. Its default and maximum
per-target ceiling is 600 seconds including compilation. `bench-latest` and
other callers of the release plan complete all preflights before sampling the
first target. Fatal benchmark errors always print to stderr without requiring
`bench-logging` or an enabled tracing subscriber.
The GitHub release baseline workflow is dispatched explicitly with a stable
tag after creating its mutable draft release. It validates the target before
benchmarking, uploads and verifies the archive, then publishes. It refuses
existing baseline assets and published releases; see the recovery sequence in
[`../RELEASING.md`](../RELEASING.md).
Manual `just bench-latest` runs use a 30-minute timeout for each target unless
an override is supplied. The local `performance-release` workflow uses a
two-hour sampling ceiling plus a ten-minute preflight ceiling per target and
derives its outer ceiling from all five curated targets (up to ten hours and
fifty minutes). The hosted draft workflow has a 150-minute job ceiling and a
one-hour sampling ceiling per target. 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/`.
The corrected benchmark contract starts with v0.8.2. For that initial release,
the no-argument `just performance-release` instead runs fresh, strict absolute
measurements into `benches/PERFORMANCE_RESULTS.md`, using the same summary path
as `just bench-perf-summary`. It requires no previous release or tag fetch.
Skip `performance-doc` and `performance-readme` for v0.8.2. Comparisons across
the v0.8.2 contract boundary are rejected before measurement or acquisition;
historical reports retain their original release labels.
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 core Rust/Cargo or public-behavior changes, complete final
comprehensive validation:
```bash
just ci
```
Before pushing Rust or benchmark changes, also run the performance smoke guard:
```bash
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
```
`just zizmor` uses the repository's pinned scanner with the `regular` persona.
It takes a token from `ZIZMOR_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN`, in
that order, then tries `gh auth token` for `GH_HOST` (default `github.com`).
Tokens are passed through the environment without being printed. With
authentication, online audits include action SHA/version-comment checks;
without it, the recipe reports that it is running offline. Explicit zizmor
environment settings such as `ZIZMOR_OFFLINE` still apply.
The `zizmor.yml` SARIF workflow reads `zizmor_version` from `justfile` and
explicitly enables online audits with the same persona. Zizmor resolves action
SHAs against release tags; repository Semgrep rules require an explicit scanner
version and disabled setup-uv caching in release workflows without duplicating
that remote resolution.
---
## Recommended Command Matrix
| Run lints | `just check` |
| Fast compile check | `just check-fast` |
| CodeRabbit review of a branch and local edits, when explicitly authorized | `just review [base]` |
| CodeRabbit review of only local edits and new files, when explicitly authorized | `just review-uncommitted` |
| 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 formatting, full-policy lint, type checks, and tests
- direct Python Semgrep fixture lint
- 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 native targets are `x86_64-unknown-linux-gnu`, `aarch64-apple-darwin`, and
`x86_64-pc-windows-msvc`, respectively. CI checks the compiler host against the
matrix before running recipes; installing a target alone does not prove that
Cargo built or tested it. Intel macOS is not a separate native CI cell.
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 use `just check` and targeted tests during iterative review and fixes.
For final PR readiness or push, core Rust/Cargo or public-behavior changes
require `just ci`. Documentation, configuration, Python, notebook, test-only,
benchmark-only, and example-only changes use the focused validators in the
matrix above; compose each affected surface once.
---
## 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
```