# 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)
- [Dependency and Secret Scanning](#dependency-and-secret-scanning)
- [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` |
| 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`, `just test-doc`, and `just test-features` through `just test-rust`.
For changes confined to optional-feature tests, use `just test-unit-features`
or `just test-doc-features` for the affected target class.
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 public API harness-only edits, and
`just bench all` for broad diagnostic benchmark-suite changes. Explicit user
restrictions on benchmark execution take precedence; report compile-only or
mocked validation separately from measured evidence.
## 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 # Branch and local changes against verified origin/main
just review main # Explicit local base override
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 default `origin/main` must match the live remote at invocation.
The shared CLI checks with `git ls-remote`, then compares the local cached ref.
Missing, stale, or unreachable remote bases fail before CodeRabbit starts. Refresh
stale refs yourself with `git fetch origin`, then retry when authorized. Explicit
local bases and uncommitted-only reviews skip remote freshness checks. The wrapper
never fetches or changes Git state.
Both recipes call the locked shared CLI and stream CodeRabbit's structured
`--agent` output. Instruction discovery requires root `AGENTS.md` and exactly
one of `.coderabbit.yml` or `.coderabbit.yaml`. Install the
[CodeRabbit CLI](https://docs.coderabbit.ai/cli) separately and authenticate with
`coderabbit auth login`. It remains an external prerequisite; setup does not
install or authenticate it, enable paid credits, or retry reviews.
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` or `just --list` for the same complete grouped command reference,
generated by Just with arguments and descriptions. The explicit private default
recipe lists commands without running validators. Public recipes are documented,
grouped, and kept in lexicographic source order. 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 declarations live in their authoritative consumer files: exact uv and Cargo
tool pins in `pyproject.toml`, Python in `.python-version`, and Rust plus components
in `rust-toolchain.toml`. `tooling` pins `research-repo-tools==0.2.3` from PyPI
and is included by `dev`. Before the first Just invocation, run:
```bash
uv run --locked --managed-python --only-group tooling research-repo-tools setup
```
Provision Git, a POSIX shell, and platform compiler/linker prerequisites first.
Shared setup installs and verifies declared versions,
installs Just through its pinned `rust-just` dependency, configures shell PATH,
and synchronizes dev with managed Rust available. Open a new terminal if PATH
changed. `just setup-tools` repeats that setup. GitHub CLI, jq, and CodeRabbit remain system prerequisites for
the recipes that need them. No sibling checkout, local wheel override, generated
launcher, or editable shared-package install is used.
The uv setup command works in Bash and PowerShell. Delaunay setup and CI require
no TeX tools; manuscript production belongs to
[acgetchell/Papers](https://github.com/acgetchell/Papers/tree/main/delaunay-validation).
Managed Rust, Cargo tools, and release binaries live in the shared package's versioned cache.
Recipes select them with `toolchain run`, which verifies versions and fails when
an installation is incomplete; an ambient executable cannot satisfy a managed
pin. `just tools-check` inspects without syncing or downloading Python.
`just tools-export` exports verified paths to GitHub Actions.
`just tools-python-check` checks inherited Ruff, ty and pytest pins explicitly.
`just tools-sync-binaries` repairs only declared release binaries, including
prebuilt dprint and rumdl. `just tools-clean` previews obsolete managed installs;
include other consumers with `--keep-root PATH`, and use `--apply` only after
reviewing the plan. The separate `just clean` retains its build-artifact cleanup.
Retention roots must pass the installed shared release's Python-baseline checks.
`just update-cargo-tools --dry-run` and `just update-uv --dry-run` preview upgrades.
`just update` runs `update-tools` before `update-dependencies`, stopping on the
first failure. Completed package-manager steps remain applied. uv upgrades through
its installation owner; managed Cargo upgrades publish verified exact TOML pins.
Just follows the shared package pin and is not upgraded independently through
Cargo. These policies replace cargo-update and the legacy Just-variable reconciler.
An unsupported uv installation owner produces a diagnostic; update through that
owner and reconcile `tool.uv.required-version` before retrying.
`update-dependencies` composes Cargo and Python updates while retaining tool pins.
The Cargo override advances requirements and lockfiles for the root and isolated
`tests/fixtures/checkpoint_no_float_roundtrip/` resolution roots. Python updates
use shared `deps update-python --all-projects` to advance exact direct dev pins,
preserve included tooling constraints and intentional ranges, refresh the entire
`uv.lock`, and explicitly sync dev with managed Rust available, including when
`default-groups = []`. Additional independent uv projects must be declared under
`tool.research-repo-tools.deps.python-projects`; none are currently needed here.
`update-tools` preserves dependency requirements and
locks. Change the shared package version explicitly through uv, refresh the lock,
review its release notes, and rerun setup. `deps update-tools` is the separate
legacy interface for user-installed tools; this repository uses managed TOML pins.
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.
For occasional shared operations, `just files`, `just templates`,
`just validate`, and `just performance` forward explicit arguments to the public
CLI. Declarative performance commands require a consumer-owned configuration;
the established Delaunay performance recipes retain their scientific policy.
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.
Configuration, documentation, Python, notebook, shell, and unused-dependency
checks run before Clippy and Rustdoc so their failures surface before expensive
Rust analysis. Each recipe retains its setup prerequisites; Just runs shared
dependencies with the same arguments only once per invocation.
`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 `research-repo-tools release check --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 native notebook 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, doctest,
and feature-only 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 explicit repository rule scopes, including Rust, Python,
workflow YAML, documentation, notebooks and paper sources. Shared enumeration
keeps tracked Python and Rust tests visible to both local validation and the
hosted SARIF workflow. The paired reports require complete selected-input
coverage and matching active findings. Deliberate violations
under `tests/semgrep/` remain excluded from repository scans and are exercised
only by `just semgrep-test`. Focused Rustdoc import tests use the shared,
line-preserving `rust_blocks` extractor. The optional aggregate `--rust-docs`
scan failed paired-report completeness with this repository's rule scopes on
v0.2.3, so the scan and prose-fixture gates retain their validated native mode.
`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.
`test-features` composes `test-unit-features` and `test-doc-features` with
`diagnostics,count-allocations,bench`. The unit lane uses a focused nextest
filter in debug and release modes; the doctest lane selects allocation
measurement and diagnostics examples. These selections exclude default tests
and leave `slow-tests` in its existing bucket. Adding or moving feature-gated
tests requires checking nextest discovery with and without these features and
updating `_feature_unit_filter` to cover the difference. Likewise, update the
doctest filters when adding feature-only examples. The native CI matrix reaches
both lanes through `just ci` → `just test` → `just test-rust`.
The LLVM-instrumented coverage profile retains its 300-second default watchdog.
The exact 20-point 4D exterior-insertion regression has a 900-second override
after reaching that watchdog in the parallel Linux coverage suite; its complete
input and per-prefix realization and empty-sphere assertions remain enabled.
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 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` for the public API fixture preflight without statistical
sampling; it produces no performance data.
The explicit slow suite (`just bench all`), `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-latest` from the release PR branch after measured inputs change,
then `just bench-perf-summary` to regenerate `benches/PERFORMANCE_RESULTS.md`.
The summary recipe only renders retained, validated measurements, including
their source, host, completion time, construction metadata and simplex counts.
It fails on missing or incompatible evidence without starting benchmarks.
Repeated rendering of the same evidence produces the same report.
`just bench`, `just bench-ci`, and `just bench-latest` select the same public API
plan: `ci_performance_suite`, `circumsphere_containment`, and `locate`. Routine
and release CI use that plan. Internal predicate-path, realization-component,
repair, allocation, and large-scale diagnostics are opt-in through a selected
benchmark target or `just bench all`. The profiling workflow is manual-only,
with one timing or allocation run per dispatch. Normal correctness tests remain
independent of this benchmark selection.
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 `tooling/python/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.
Saved baseline names must start with an ASCII letter or digit and contain only
ASCII letters, digits, dots, underscores, or hyphens. Names must be distinct
without regard to case across the saved samples; `new`, `base`, `change`, and
`report` are reserved. Conflicting existing names are rejected before discovery
or sampling with a rename diagnostic, leaving the previous output unchanged.
`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 leaves the draft for
maintainer review and `just release-publish TAG`. 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. Fresh runs use a private output tree and publish to
`target/criterion` after validation, preserving named baselines. Discovery and scientific
preflight precede sampling, and saved baselines are checked against the fresh
raw files before evidence is retained. The local `performance-release` workflow uses
separate two-hour discovery and sampling ceilings per target, plus a ten-minute
preflight ceiling per target. The sampling child also has an aggregate limit of
two hours times the selected target count for each revision; discovery and preflight
run before that child. There is no combined local workflow deadline.
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, shared comparison JSON, and evidence 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 comparison JSON/evidence bytes under
`docs/archive/performance/`.
Fresh comparisons use the recorded harness and measurement plan to establish workload
identity, including comparisons across older release labels. Failed scientific fixtures
invalidate a run; incompatible harnesses suppress ratios. When no comparable baseline
exists, use `just bench-latest` followed by `just bench-perf-summary` for absolute
results and skip comparison publication.
Historical reports retain their original release labels.
Use `just performance-doc` to retry rendering or promotion from an existing
retained comparison JSON/evidence 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
the shared exact snapshot by default, including nonignored new files and their
permissions. Snapshot application requires the captured checkout revision.
Promotion commands require every input and output, including retained scratch
reports, to be inside the project root. External promotion paths fail before
measurements or publication. Standalone `performance-local` and
`performance-github-assets` reports may use external output paths.
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 comparison JSON/evidence 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 comparison JSON/evidence 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.
The canonical timing payload is the shared `research-repo-tools/criterion-comparison/v1`
JSON, paired with its digest-bound evidence envelope. Delaunay's context records
coverage and scientific eligibility. Ratios require matching measured harnesses,
plans, toolchains, confidence levels, and hosts. Timing changes are descriptive;
marginal timing intervals are not ratio intervals or significance tests.
Historical CSV/text files stay unchanged as records. Their readers and writers
are retired. New reports use `.comparison.json` and `.evidence.json`; old files
cannot be passed to the new promotion commands.
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 performance-local
```
## 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 performance-local` measures the current checkout and the latest published stable
release freshly on this machine, retaining evidence under `target/bench-reports/`.
The CI performance job uses the same command and retains the same JSON pair. It
fails on execution or invalid evidence, and reports descriptive timing changes without
an arbitrary regression threshold. It suppresses ratios for differing harnesses,
measurement plans, toolchains, confidence levels, or host identities.
The text-baseline, cached-ref, artifact-polling and threshold commands are retired.
For a chosen saved Criterion baseline, use `just bench-save-baseline <name>` and
`just bench-compare <name>`; review workload identity before interpreting those
lower-level diagnostic comparisons.
---
## 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
checked directly by 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 native notebook code checks without
executing notebooks. Shared lint/advice enforces the configured cell-ID pattern.
`just notebook` launches JupyterLab with caches under `target/notebooks/jupyter`;
additional arguments pass to the shared launch command. Reset is explicit:
`just notebook-reset-from-git` applies the configured index restore and scratch
cleanup; pass `HEAD` to restore that revision instead. Explicit notebook execution writes the executed notebook
under `target/notebooks/notebooks/<notebook-stem>.ipynb` with an adjacent
`.report.json`. Generated figures/data stay under
`target/notebooks/<notebook-stem>/`, 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
The active validation manuscript and its build instructions live in
[Papers/delaunay-validation](https://github.com/acgetchell/Papers/tree/main/delaunay-validation).
Paper dependencies, TeX tools, and paper CI are maintained there.
Shared validation notebooks and canonical figures remain documentation-owned.
`just notebook-cli` builds their Rust CLI; `just validation-doc-figures-check`
regenerates figures under `target/` and compares them without publication.
Normal macOS CI retains this documentation check and requires no TeX tools.
Only `just validation-doc-figures` explicitly refreshes the canonical figure set.
---
## 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 update-actions --dry-run` previews exact SHA and version-comment updates
for workflow identities in `.github/action-updates.toml`. `--check` detects available updates without writing;
omit the flag to apply them deliberately. This stage stays separate from
`just update`. The publishing authentication action and privileged Dependabot
workflow retain their dedicated review and are excluded from automatic updates.
The upstream updater accepts workflow YAML only. setup-uv remains on the
Dependabot path so its workflow and setup-composite references stay coupled.
CodeQL uses an explicit action-release target because its latest GitHub release
is a bundle tag that the shared updater rejects as a semantic version.
The shared strict Actions allowlist checker requires identity entries ending
in `@*`. The existing selected-actions policy restricts the publishing action
to an exact commit, so the repository retains that policy and its local Semgrep
allowlist rather than loosening the publishing restriction.
`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 runs the pinned shared CLI directly with online
audits required and the same configured persona. It uploads the resulting SARIF;
scanner failures remain failures. Local `just zizmor` uses the same implementation
with the documented unauthenticated offline fallback.
---
## Dependency and Secret Scanning
`just security` composes `just audit` and `just security-secrets`, using the
published shared scanner commands. Exact Gitleaks and OSV-Scanner versions live
in `tool.research-repo-tools.toolchain.binaries`; `just setup-tools` installs and
verifies them. These network/full-history gates run separately from `just check`
and the platform `just ci` matrix.
`just audit` scans `uv.lock`, `Cargo.lock`, and
`tests/fixtures/checkpoint_no_float_roundtrip/Cargo.lock`. Advisory queries need
network access. Go/Rust call analysis is disabled, so the audit does not execute
dependency build code. The existing Cargo audit workflow checks RustSec
advisories separately.
`just security-secrets` scans all reachable Git history plus tracked/nonignored
working files, including new files. Full history is required. Shared defaults
exclude environment/build directories; ignored untracked files, unreachable
objects, binary blobs, archives, and nested repositories are outside the scan.
The shared command redacts secret values and adjacent match text and disables
inline and ambient-ignore bypasses.
The `osv.yml` and `gitleaks.yml` workflows call these same recipes on pull
requests, pushes to `main`, weekly schedules, and manual dispatch. Gitleaks
checks out full history with `fetch-depth: 0`. Both workflows use read-only
repository permissions, fail on findings or incomplete scans, and retain
JSON/SARIF reports from `target/security/` for seven days, including on findings.
---
## Recommended Command Matrix
| Run lints | `just check` |
| Audit dependencies and scan for secrets | `just security` |
| Audit maintained Python and Rust lockfiles | `just audit` |
| Scan Git history and current files for secrets | `just security-secrets` |
| 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` |
| Lint deliberate static-analysis Python fixtures | `just python-fixture-lint` |
| 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 feature-only library tests and doctests | `just test-features` |
| 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` |
| Summarize retained Cobertura coverage by file | `just coverage-report [ARGS...]` |
| Inspect notebook cells without execution | `just notebook-inspect PATH [ARGS...]` |
| Preview notebook restoration and cleanup | `just notebook-reset [ARGS...]` |
| Preview obsolete managed installations | `just tools-clean [--keep-root PATH]` |
| Preview selected Actions pin updates | `just update-actions --dry-run` |
---
## 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 native notebook 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 composite `.github/actions/setup-just` installs uv from the consumer TOML
pin, installs the locked PyPI package, provisions native libraries, synchronizes
managed tools, and exports verified paths. Tool caches are keyed by host and
consumer declarations, and restored versions are rechecked. Rust workflow caches
keep `cache-bin: false` to avoid restoring stale Cargo shims.
`.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
```
The shared operation generates with its packaged git-cliff policy, normalizes
history, and rotates completed minor series into `docs/archives/changelog/`.
`just changelog-preview` performs the same preparation without publishing files.
`just changelog-archive` repairs rotation/navigation without regenerating commits.
`just release-notes TAG` reads retained root or archived notes.
Prepare metadata separately, then generate using its declared citation date:
```bash
just update-version vX.Y.Z --date YYYY-MM-DD --previous-release vA.B.C
just changelog-release vX.Y.Z
just release-version-check
just publish-check
```
Metadata updates default to the current UTC date and discover published stable
GitHub history when the predecessor is omitted. The `declared` date policy
permits tagging on a later day without rewriting the preparation date. If that
declared date is deliberately advanced, repeat metadata preparation and
generation. The optional ISO date in `changelog-release TAG [DATE]` overrides
the citation default.
`changelog-preview --tag TAG` uses that default without writing files and also
accepts `--date YYYY-MM-DD`. Final validation requires matching target
heading and citation dates. Create an annotated local tag only after the release
PR is merged:
```bash
just tag vX.Y.Z
```
Trusted main-push CI uses `just release-package` to verify clean default and
all-feature Cargo packages without upload credentials, then `just release-artifact
create OUTPUT` retains the archive and source/run/tool manifest for 30 days.
`just release-evidence [IDENTITY]` validates the retained archive for the clean
checkout without Cargo or a published release event; an optional identity must
match the previous selection. `release-publish` requires this evidence before
making the GitHub release immutable.
The release workflow uses `just release-artifact verify` to retrieve the exact
main artifact and require byte-identical repackaging without rebuilding. After
deployment approval, it revalidates the same frozen selection before requesting
an upload token. `just publish-check`
remains the local metadata/package preview that permits uncommitted edits.
`just release-gate TAG` requires the immutable published event, reviewed commit,
native CI checks and benchmark asset; `just release-publish TAG` approves a
reviewed draft through a human GitHub CLI session, and `just release-verify TAG`
checks the release and exact registry version with bounded visibility polling.
Follow [Releasing](../RELEASING.md) for account setup, sequence, and recovery.