# Development Commands
Development commands and validation steps for the repository.
Agents must run appropriate checks after modifying code.
---
## Contents
- [Core Workflow](#core-workflow)
- [Validation Command Selection](#validation-command-selection)
- [Justfile Usage](#justfile-usage)
- [Formatting](#formatting)
- [Linting](#linting)
- [Documentation Validation](#documentation-validation)
- [Full CI Validation](#full-ci-validation)
- [Benchmark Profiles](#benchmark-profiles)
- [Examples](#examples)
- [Spell Checking](#spell-checking)
- [Notebook Validation](#notebook-validation)
- [Markdown Checks](#markdown-checks)
- [TOML Checks](#toml-checks)
- [YAML Checks](#yaml-checks)
- [Shell Script Validation](#shell-script-validation)
- [JSON Validation](#json-validation)
- [Paper Build](#paper-build)
- [CITATION.cff Validation](#citationcff-validation)
- [GitHub Actions Validation](#github-actions-validation)
- [Recommended Command Matrix](#recommended-command-matrix)
- [CI Expectations](#ci-expectations)
- [Changelog](#changelog)
---
## Core Workflow
Typical development loop:
```bash
just check
just check-fast
just fix
just test
just ci
```
These commands ensure:
- formatting
- linting
- static analysis
- tests
Treat this as a menu, not a required sequence. The validation matrix below is
the handoff source of truth.
## Validation Command Selection
Use the smallest non-mutating validator that covers the files you changed while
iterating. For final handoff validation, match commands to the changed file
surfaces instead of defaulting all edits to full CI.
Core Rust code means production Rust or manifest changes that can affect library
behavior, public API, features, examples, benchmarks, or downstream users. It
does not include Rust doctest-only, unit-test-only, integration-test-only,
benchmark-only, or example-only edits when the focused validator covers the
changed surface.
| Markdown documentation (`*.md`) | `just markdown-check` | `just check-docs` |
| Python under `scripts/` | Targeted pytest or `just test-python`; add `just python-check` for logic/style | `just python-check` and `just test-python` |
| Jupyter notebooks (`notebooks/**/*.ipynb`) | `just notebook-check` | `just notebook-check` |
| Paper sources and figures (`papers/**/*`, paper notebooks) | `just paper-check` | `just papers` |
| Configuration only (JSON, TOML, YAML, CFF, workflows) | Matching config validator | `just check-config` |
| Rust unit tests only (`#[cfg(test)]` in `src/**`) | Targeted `cargo test --lib <filter>` or `just test-unit` | `just test-unit` |
| Rust doctests only (`///` examples or crate docs) | Targeted `cargo test --doc --release <filter>` or `just test-doc` | `just test-doc` |
| Rust integration tests only (`tests/**`) | Targeted `cargo nextest run --test <name>` or `just test-integration-fast` | `just test-integration` |
| Rust benchmark files only (`benches/**`) | Targeted benchmark command or `just bench-smoke` | Matching benchmark validator |
| Rust examples only (`examples/**`) | Targeted `cargo run --example <name>` or `just examples` | `just examples` |
| Core Rust code | Focused checks or targeted tests while iterating | `just ci` |
| Mixed focused surfaces without core Rust | Run each matching focused validator once | Run each matching focused validator once |
| Mixed core Rust plus tests/benches/examples/docs/config | Focused checks while iterating | `just ci` |
Do not run `just ci` merely because documentation, configuration, Python,
notebook, or test-only Rust files changed. Do not run `just test` when a single
focused test bucket covers the change unless you intentionally want the full
default test suite. When a diff touches multiple focused test surfaces, compose
the matching recipes once each; for example, run `just test-doc` and
`just test-integration` for doctest plus integration-test changes. Broad Rust
correctness workflows compose `just test-unit`, `just test-integration`,
`just test-cli`, and `just test-doc` through `just test-rust`.
During fast code-writing cycles, start with the smallest changed test or
doctest rather than the whole focused bucket. For single-item rustdoc edits, run
`cargo test --doc --release <item-or-module-filter>`; for unit-test edits, run
`cargo test --lib <test-or-module-filter>`; for integration-test crate edits,
run the changed crate with `cargo nextest run --test <crate>`. Cargo's built-in
test-name filter accepts one filter per invocation, so run separate filtered
commands for unrelated changed tests or choose one shared module/name prefix
that covers the intended small group. Use `just test-doc`, `just test-unit`, or
`just test-integration` for final bucket validation or broad changes.
Focused validators own one target class. Avoid adding a compile-only smoke
recipe before a recipe that already compiles and runs the same target class.
For benchmark-only changes, run the changed benchmark with
`cargo bench --profile perf --bench <name>` when the change affects measured
behavior. Use `just bench-smoke` for harness-only edits, and `just bench` for
broad benchmark-suite changes.
## Justfile Usage
This repository standardizes development tasks through the `justfile`.
Run bare `just` for the curated workflow guide and `just --list` for the
complete grouped command reference. Public recipes are documented, grouped,
and kept in lexicographic source order so both views are easy to scan. Each
public recipe owns one distinct operation; broader workflows compose those
recipes instead of repeating their commands. Shared private guards and
parameterized implementation helpers live in `just/helpers.just`.
Tool-version variables in the root `justfile` are the source of truth for both
local setup and GitHub Actions. `just setup-tools` installs or synchronizes the
repository toolchain, while 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.
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.
---
## Full CI Validation
Before core Rust changes, broad API-affecting changes, release-style
validation, or explicit maintainer requests, run the full CI command:
```bash
just ci
```
This runs:
- formatting checks
- justfile formatting checks
- GitHub Actions checks
- Markdown checks
- release-version reference synchronization
- `Cargo.toml`/`Cargo.lock` synchronization
- JSON/TOML/YAML/CFF checks
- Python lint/typecheck
- notebook hygiene and extracted-code checks
- shell script formatting and lint checks
- Rust core lint, documentation, and Semgrep checks
- benchmark harness compile checks
- Rust lib unit tests
- Rust doctests
- Rust release integration tests
- Python tests
- example builds
---
## Benchmark Profiles
For performance-sensitive code changes, follow
[`perf-tuning.md`](perf-tuning.md): benchmark before editing, add a benchmark
when none covers the hot path, benchmark after editing, and preserve
scientific invariants throughout. Benchmark output is only evidence when the
measured workflow maintains its triangulation, predicate, topology, and
diagnostic invariants.
`just ci` is the comprehensive error-catching validation path used by GitHub
Actions. It composes `just check`, `just test`, `just bench-compile`, and
`just examples`. The target classes remain orthogonal: `rust-core-check` covers
formatting, all-targets Clippy, rustdoc, and Semgrep; `unused-deps` checks direct
Cargo dependency hygiene; `test-rust` composes unit, integration, CLI, and
doctest buckets; `notebook-check` validates notebooks without executing them.
Routine notebook checks are lint-only. Execute one notebook deliberately with
`just notebook-execute` or use its named artifact-refresh recipe. There is no
aggregate recipe that executes every notebook.
`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 gives slower debug
geometry paths a finite 60-second watchdog. `test-integration` runs a focused
release-profile nextest bucket. `test-cli` owns the feature-gated CLI tests,
and `test-rust` composes every Rust test class once.
```bash
just ci
just test
just rust-core-check
just test-rust
just notebook-check
just bench-compile
```
Commands that run benchmarks and produce performance data use the `perf`
profile:
```bash
just bench
just bench-ci
just bench-latest
just bench-latest-vs-last
just bench-compare
just bench-save-baseline v0.7.8
just perf-local
just perf-github-assets
just perf-release
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 `delaunay` CLI. The
dimension-specific `just pachner-stress-3d` and `just pachner-stress-4d` recipes
default to 100 attempted moves with progress every 10 attempts, 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 CLI supports
`round-trip` and `random-walk` modes; `round-trip` is the default. Pass explicit
`attempts`, `vertices`, and `validate_every` arguments for soak runs. 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. It runs
`ci_performance_suite`, `circumsphere_containment`, `cold_path_predicates`,
and `locate`, leaving `target/criterion/new` data suitable for
`just bench-compare`. The manual `topology_guarantee_construction` suite remains
available through `just bench-save-baseline <tag> topology` and
`uv run benchmark-utils perf-local --suite topology`. 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 perf-local` when you want the tool to manage isolated
baseline/current worktrees.
```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 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 perf-local` for an isolated temp-worktree comparison of the
current package version against the latest stable published release. It writes
`target/bench-reports/performance.md` and runs local benchmarks. Use
`just perf-github-assets` when you want to compare stored GitHub Release
benchmark assets without local Cargo benchmark runs. Use `just perf-release`
in release PRs to promote one curated comparison into
`docs/PERFORMANCE.md`, archiving the previous curated report under
`docs/archive/performance/`. The GitHub-asset and release-promotion recipes also
accept explicit `<current-tag> <baseline-tag>` pairs for repair paths.
Temp-worktree release commands apply tracked checkout changes by default;
untracked files must be added to git before they affect the generated report.
Before pushing Rust or benchmark changes, run:
```bash
just ci
just perf-large-scale-smoke
```
For performance-sensitive changes and PR-ready work, also run:
```bash
just perf-no-regressions
```
## Slow Correctness Tests
The routine correctness suite has two buckets:
- `just test` runs default tests that should stay under roughly 10 seconds per
test.
- `just test-slow` runs tests gated by the `slow-tests` feature when a
deterministic correctness or regression case exceeds that budget.
`just test-slow` runs in release mode with the repository's `slow` nextest
profile. Debug-mode exact-predicate arithmetic can make high-dimensional tests
look like hangs, so slow correctness timing should be measured with the release
recipe. Deterministic slow tests should use `#[cfg(feature = "slow-tests")]`,
not `#[ignore]`.
`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 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 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 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 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`. Ordinary notebook validation does
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. 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.
Reviewer-facing validation diagrams under `docs/assets/validation/` use the
same deterministic notebook with a separate explicit output switch:
```bash
just validation-doc-figures
```
Routine notebook checks keep writing only under `target/`; neither tracked
documentation nor paper figures are refreshed implicitly.
---
## Markdown Checks
Markdown files are checked with rumdl and spell-checking for handoff. Keep the
non-mutating check before the mutating fixer in user-facing command examples.
Commands:
```bash
just markdown-check
just markdown-fix
```
---
## TOML Checks
TOML files should parse cleanly, pass Taplo linting, and match Taplo
formatting.
Commands:
```bash
just toml-check
just toml-lint
just toml-fmt-check
just toml-fix
```
---
## YAML Checks
YAML and `CITATION.cff` files should match the dprint/pretty_yaml formatting
configuration and pass yamllint.
Commands:
```bash
just yaml-check
just yaml-fix
```
`just yaml-check` runs both `just yaml-fmt-check` and `just yaml-lint`; use
`just yaml-fix` for the mutating dprint formatter.
---
## Shell Script Validation
Shell scripts must pass:
```text
shfmt
shellcheck
```
Run the focused non-mutating validator with:
```bash
just shell-check
```
`just shell-check` composes the focused `just shell-lint` and
`just shell-fmt-check` leaves, and `just ci` includes the aggregate check.
---
## JSON Validation
JSON files should be validated after edits.
Run:
```bash
just json-check
```
---
## CITATION.cff Validation
Citation metadata should pass both YAML style linting and CFF schema
validation.
Run:
```bash
just citation-check
```
---
## GitHub Actions Validation
Workflows must pass `actionlint`.
Run with:
```bash
just action-lint
```
---
## Recommended Command Matrix
| Run lints | `just check` |
| Fast compile check | `just check-fast` |
| Check formatting | `just fmt-check` |
| Check justfile formatting | `just justfile-fmt-check` |
| Apply formatters/auto-fixes | `just fix` |
| Validate Markdown-only changes | `just check-docs` |
| Validate release-version references | `just docs-version-check` |
| Validate `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` |
| 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 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` |
| Run full GitHub-equivalent CI | `just ci` |
| Run perf-profile benchmarks | `just bench` |
---
## CI Expectations
CI enforces:
- GitHub Actions checks
- Markdown, JSON, TOML, YAML, CFF, and spell checks
- release-version reference synchronization
- `Cargo.toml`/`Cargo.lock` synchronization
- Python lint, type checks, and tests
- notebook hygiene and extracted-code checks
- shell script formatting and lint checks
- core Rust formatting, Clippy, rustdoc, and Semgrep checks
- Rust unit, doctest, and integration tests
- benchmark harness compilation
- examples
The default portability contract runs the same `just ci` recipe on Linux,
macOS, and Windows. Optimize bootstrap and caching without silently reducing
that platform coverage; a narrower matrix requires an explicit replacement for
each lost portability check.
The root `justfile` owns managed tool-version pins. After bootstrapping `just`
through `.github/actions/setup-just`, workflows resolve those pins with
`just --evaluate` instead of repeating version literals. Rust workflow caches
must keep `cache-bin: false`: restoring `${CARGO_HOME}/bin` can replace
rustup-managed Cargo shims with stale or host-incompatible binaries.
`.codacy.yml` owns Codacy engine and path policy. Keep Codacy feedback aligned
with repository validators rather than establishing an independent style or
static-analysis regime.
Rust warnings are denied by the manifest lint policy and Clippy warnings are
denied by `just clippy`. Keep any
intentional warning-level exceptions explicit in `Cargo.toml`.
Agents must ensure changes pass the appropriate local validator before
proposing patches. Use the validation matrix above for final handoff: core
Rust/Cargo changes require `just ci`, while documentation, configuration,
Python, test-only, benchmark-only, and example-only changes use their focused
validators and compose them once each when multiple surfaces changed.
---
## Changelog
The changelog is **auto-generated**.
Never edit manually.
Regenerate with:
```bash
just changelog
```
This runs `git-cliff`, applies the Python postprocessor, archives completed
minor release series under `docs/archive/changelog/`, and applies `rumdl`
formatting to the generated changelog files.
For release PRs, generate the changelog for a version before the final tag
exists with:
```bash
just changelog-unreleased vX.Y.Z
```
Create annotated release tags from the generated changelog after the release PR
is merged with:
```bash
just tag vX.Y.Z
```