Makefile

MDLINT ?= markdownlint-cli2
# `make fmt` and `make check-fmt` call mdtablefix directly. `--git` selects the
# Markdown files Git tracks and `--include-untracked` adds the untracked files
# Git does not ignore, so a new document is formatted before it is staged.
# Both modes need mdtablefix 0.6.0 or later; CI pins the version at the
# install-mdtablefix step.
MDTABLEFIX ?= mdtablefix
MDTABLEFIX_SELECT = --git --include-untracked
MDTABLEFIX_EXTENSIONS = --md-exts md,markdown,mdx
MDTABLEFIX_RULES = --wrap --renumber --breaks --ellipsis --fences
MARKDOWN_GLOBS = '*.md' '*.markdown' '*.mdx'
NIXIE ?= nixie
YAMLLINT ?= yamllint
ACTIONLINT ?= actionlint
TOOLS = $(MDLINT) $(YAMLLINT) $(ACTIONLINT) uv
VENV_TOOLS = pytest ruff
RUST_DIR ?= rust
CARGO ?= cargo
# Rust 1.85.0 remains Cuprum's published compatibility toolchain. This
# separately pinned nightly is selected only for compatible Linux debug work.
MSRV_TOOLCHAIN ?= 1.85.0
DEV_FAST_TOOLCHAIN ?= nightly-2026-08-23
DEV_FAST_CRANELIFT_COMPONENT ?= rustc-codegen-cranelift
# Clippy is a separate rustup component from the backend, but `rust-lint` runs
# it through this same nightly, so the prerequisite gate must require both.
DEV_FAST_LINT_COMPONENT ?= clippy
DEV_FAST_REQUIRED_COMPONENTS ?= $(DEV_FAST_CRANELIFT_COMPONENT) $(DEV_FAST_LINT_COMPONENT)
# The selected Cargo fragment is repository-fixed state, not a caller input.
# `override` is load-bearing, not decoration: a plain or `?=` definition still
# yields to an ordinary environment variable, and any non-override definition
# yields to a command-line variable. With either, `make dev-build
# DEV_FAST_RUST_CONFIG=/tmp/other.toml` would run the accelerated route under a
# configuration the project never approved while `dev-fast-check` still passed.
# Both names need it: the second because a caller could otherwise replace the
# derived value directly. Anything needing a different Cargo configuration is
# outside this route and does not use it.
override DEV_FAST_CONFIG_RELATIVE := tools/dev-fast/config.toml
override DEV_FAST_RUST_CONFIG := ../$(DEV_FAST_CONFIG_RELATIVE)
DEV_FAST_MOLD_VERSION_FILE ?= tools/mold/VERSION
DEV_FAST_MOLD_VERSION := $(strip $(shell tr -d '\r\n' < $(DEV_FAST_MOLD_VERSION_FILE)))
DEV_FAST_MOLD_VERSION_PATTERN = $(subst .,\.,$(DEV_FAST_MOLD_VERSION))
DEV_FAST_CARGO_BRIDGE ?= tools/dev-fast/cargo
DEV_FAST_HOST_IS_LINUX := $(if $(filter Linux,$(shell uname -s)),yes)
# `CARGO` remains a caller-injectable single executable. Maturin can select
# that executable but cannot pass Cargo's configuration-file `--config` form.
DEV_FAST_CARGO_COMMAND = RUSTUP_TOOLCHAIN=$(DEV_FAST_TOOLCHAIN) $(CARGO) --config $(DEV_FAST_RUST_CONFIG)
MSRV_CARGO_COMMAND = RUSTUP_TOOLCHAIN=$(MSRV_TOOLCHAIN) $(CARGO)
RUST_DEBUG_CARGO = $(if $(DEV_FAST_HOST_IS_LINUX),$(DEV_FAST_CARGO_COMMAND),$(CARGO))
RUST_DEBUG_PREREQUISITE = $(if $(DEV_FAST_HOST_IS_LINUX),dev-fast-check)
# Parse release spellings without re-parsing caller-provided flags in a shell.
maturin_release_profile = $(strip $(if $(1),$(if $(and $(filter --profile,$(firstword $(1))),$(filter release,$(word 2,$(1)))),yes,$(call maturin_release_profile,$(wordlist 2,$(words $(1)),$(1))))))
MATURIN_DEVELOP_IS_RELEASE := $(strip $(filter --release -r --profile=release,$(MATURIN_DEVELOP_FLAGS)) $(call maturin_release_profile,$(MATURIN_DEVELOP_FLAGS)))
DEVELOP_DEV_FAST_ENABLED := $(if $(DEV_FAST_HOST_IS_LINUX),$(if $(MATURIN_DEVELOP_IS_RELEASE),,yes))
DEVELOP_DEV_FAST_PREREQUISITE = $(if $(DEVELOP_DEV_FAST_ENABLED),dev-fast-check)
DEVELOP_DEV_FAST_ENV = $(if $(DEVELOP_DEV_FAST_ENABLED),RUSTUP_TOOLCHAIN=$(DEV_FAST_TOOLCHAIN) DEV_FAST_CARGO=$(CARGO) CARGO=$(DEV_FAST_CARGO_BRIDGE))
DEV_FAST_CHECK_COMMAND = test "$(DEV_FAST_HOST_IS_LINUX)" = yes || { printf '%s\n' 'dev-fast is supported only on Linux; use the stable backend on this host' >&2; exit 1; }; test -f "$(DEV_FAST_CONFIG_RELATIVE)" || { printf 'dev-fast configuration is missing: %s\n' "$(DEV_FAST_CONFIG_RELATIVE)" >&2; exit 1; }; command -v mold >/dev/null 2>&1 || { printf 'mold %s is required for Linux dev-fast builds\n' "$(DEV_FAST_MOLD_VERSION)" >&2; exit 1; }; mold --version | grep -q '^mold $(DEV_FAST_MOLD_VERSION_PATTERN)\($$\|[[:space:]]\)' || { printf 'mold %s is required for Linux dev-fast builds\n' "$(DEV_FAST_MOLD_VERSION)" >&2; exit 1; }; components="$$(rustup component list --installed --toolchain "$(DEV_FAST_TOOLCHAIN)")" || { printf 'cannot inspect the components installed for %s\n' "$(DEV_FAST_TOOLCHAIN)" >&2; exit 1; }; for component in $(DEV_FAST_REQUIRED_COMPONENTS); do printf '%s\n' "$$components" | grep -q "^$$component" || { printf 'install %s for %s before using dev-fast\n' "$$component" "$(DEV_FAST_TOOLCHAIN)" >&2; exit 1; }; done
DEV_FAST_TEST_RUSTFLAGS = $(TEST_RUSTFLAGS) $(if $(DEV_FAST_HOST_IS_LINUX),-Clink-arg=-fuse-ld=mold)
DEV_FAST_TEST_COMMAND = if $(LOCAL_TOOL_ENV) command -v cargo-nextest >/dev/null 2>&1; then $(LOCAL_TOOL_ENV) cargo-nextest --version | head -1 | $(NEXTEST_VERSION_OK) || { $(NEXTEST_FLOOR_MESSAGE); }; cd $(RUST_DIR) && $(LOCAL_TOOL_ENV) RUSTFLAGS="$(DEV_FAST_TEST_RUSTFLAGS)" $(DEV_FAST_CARGO_COMMAND) nextest run $(NEXTEST_FLAGS) $(BUILD_JOBS); else echo "cargo-nextest not found; falling back to cargo test." >&2; cd $(RUST_DIR) && RUSTFLAGS="$(DEV_FAST_TEST_RUSTFLAGS)" $(DEV_FAST_CARGO_COMMAND) test $(TEST_FLAGS) $(BUILD_JOBS) -- --test-threads=$(TEST_JOBS); fi
RUSTFMT_TOOLCHAIN ?= nightly-2026-05-28
RUSTFMT_CARGO ?= $(CARGO) +$(RUSTFMT_TOOLCHAIN)
WHITAKER ?= whitaker
BUILD_JOBS ?=
RUST_FLAGS ?= -D warnings
RUSTDOC_FLAGS ?= --cfg docsrs -D warnings
DOCTEST_RUSTDOC_FLAGS = $(RUSTDOC_FLAGS) $(if $(DEV_FAST_HOST_IS_LINUX),-Zunstable-options --display-doctest-warnings --doctest-build-arg=-D --doctest-build-arg=warnings)
CARGO_FLAGS ?= --all-targets --all-features
CLIPPY_FLAGS ?= $(CARGO_FLAGS) -- $(RUST_FLAGS)
# The test-thread count, for nextest and for the `cargo test` fallback alike. It
# is never a Cargo build limit: `cargo test --jobs` would cap compilation and
# ignore a caller's `CARGO_BUILD_JOBS`. One by default so a developer's laptop
# keeps a core for the editor; CI raises it to the vCPU count of the runner the
# job is billed for, and never above it.
TEST_JOBS ?= 1
TEST_FLAGS ?= $(CARGO_FLAGS)
NEXTEST_FLAGS ?= $(TEST_FLAGS) --test-threads $(TEST_JOBS)
# The oldest nextest that understands `global-timeout`, the whole-run budget
# `rust/.config/nextest.toml` declares. Nextest warns about keys it does not
# recognize and keeps going, so an older release drops that tier silently
# while the suite still passes; rust/.config/nextest.toml declares the same
# floor for any nextest from 0.9.55, and this check covers the older releases
# that ignore the declaration too.
NEXTEST_MIN_VERSION ?= 0.9.100
# Standard input is the version lines to test, so one awk program serves
# every tool rather than one sort-and-grep pipeline per site. `sort -V` is
# not portable, and MSYS sort has no version ordering at all. The version is
# the first dotted-numeric field, matched by shape rather than by position:
# `cargo-nextest 0.9.133 (65e806bd5 2026-04-14)` puts it in $2, and a build
# that omits the parenthesized parts would shift any fixed position.
#
# The `END` guard rejects empty input, which is the one input that must not
# pass: a version check whose subject never arrived has nothing to certify.
# `command -v` can find a `cargo-nextest` that the subsequent call cannot
# run -- the probe resolves against LOCAL_TOOL_ENV's PATH, so a tool in
# ~/.local/bin passes it on a host whose ambient PATH lacks that directory.
# The call then fails with 127 and prints nothing, and without the guard
# that empty stream reads as a version above the floor. The call sites
# therefore carry LOCAL_TOOL_ENV as well, so both see one PATH; the guard
# keeps the check honest for any other way the output can go missing.
NEXTEST_VERSION_OK = awk -v min="$(NEXTEST_MIN_VERSION)" 'NR == 1 { for (i = 1; i <= NF; i++) if ($$i ~ /^[0-9]+([.][0-9]+)+$$/) { split($$i, found, "."); split(min, floor, "."); for (j = 1; j <= 3; j++) { if (found[j] + 0 > floor[j] + 0) exit 0; if (found[j] + 0 < floor[j] + 0) exit 1 } exit 0 } exit 1 } END { if (NR == 0) exit 1 }'
NEXTEST_FLOOR_MESSAGE = printf 'cargo-nextest %s or newer is required: rust/.config/nextest.toml declares a global-timeout that earlier releases ignore without failing\n' "$(NEXTEST_MIN_VERSION)" >&2; exit 1
DOCTEST_FLAGS ?= --workspace --doc --all-features $(BUILD_JOBS)
TEST_RUSTFLAGS ?= $(RUST_FLAGS) -C codegen-units=1
WHITAKER_RUSTFLAGS ?= $(RUST_FLAGS) -C codegen-units=1
# Whitaker's `--all` selects its lint libraries, rather than Cargo packages.
# Keep the package boundary explicit and Makefile-owned so every Rust member is
# checked even when the wrapper's library-selection semantics change.
override WHITAKER_PACKAGES := cuprum-rust cuprum-streams cuprum-native-io
# Both the package list and the flags built from it are `override`n. Marking
# only the list would leave the derived flags caller-writable, and a caller
# could pass `WHITAKER_PACKAGE_FLAGS=--package evil` to displace every audited
# package while the list itself still looked intact.
override WHITAKER_PACKAGE_FLAGS := $(foreach package,$(WHITAKER_PACKAGES),--package $(package))
# The audited Whitaker command is Makefile-owned end to end. It does not forward
# `CARGO_FLAGS`: that variable is caller-overridable, so a caller could pass
# `--config ../tools/dev-fast/config.toml` after Whitaker's `--` separator and
# quietly acquire the development fragment on a route that must stay
# fragment-free. The flags below are the whole of what Whitaker may receive.
override WHITAKER_CARGO_FLAGS := $(WHITAKER_PACKAGE_FLAGS) \
	--all-targets --all-features
# Extra flags for the `maturin develop` invocation in the `develop` target.
# Empty by default: a debug build is what contributors and the extension-tests
# job want. The benchmark ratchet needs an optimized build, and an optimized
# build is the *only* thing it needs differently, so it passes `--release`
# here rather than restating the three-step build sequence inline.
MATURIN_DEVELOP_FLAGS ?=
# Extra flags for the dependency sync performed by the `build` target. The
# benchmark uses this to omit lint-only tooling from its paid runner.
UV_SYNC_FLAGS ?=
# Extra flags for the `uv run` commands in the `develop` target. The benchmark
# uses `--no-sync` after preparing its narrower development environment.
UV_RUN_FLAGS ?=
# The Windows arm of the extension's `cfg` branches. `make lint` only ever sees
# the host's arm, and the Windows wheel build compiles without `-D warnings`,
# so warn-level regressions behind `#[cfg(windows)]` — dead code left by a
# `#[cfg(unix)]` gate, most of all — would reach main unremarked.
WINDOWS_TARGET ?= x86_64-pc-windows-msvc
# PyO3 cannot probe an interpreter for the target platform, so the ABI version
# must be stated. Keep it in step with the `python-version` the Windows job in
# .github/workflows/build-wheels.yml builds against.
WINDOWS_PYTHON_VERSION ?= 3.13
PYTEST_RUSTFLAGS ?= -C codegen-units=1
# Keep pytest serial by default: each batch may compile or reuse Rust artefacts,
# and parallel batches contend on the Cargo build cache with little benefit.
PYTEST_WORKERS ?= 0
# The parser half of the workflow integration harness. Deliberately separate
# from ACT_SCENARIO_TARGETS: this half is pure string handling over recorded
# `act` output, so it runs in the default suite on every machine. Only the
# scenarios need a container runtime and a few minutes.
ACT_PARSER_TARGETS ?= tests/integration/test_act_stream_parsing.py
# The scenario half, run by `test-act` rather than by `test-python`.
ACT_SCENARIO_TARGETS ?= tests/integration/test_workflow_integration.py \
  tests/integration/test_experimental_leg_integration.py \
  tests/integration/test_extension_typecheck_integration.py
PYTEST_TARGETS ?= cuprum/unittests/test_*.py \
  tests/test_ci_*.py \
  tests/test_native_pipeline_hand_off_support.py \
  tests/test_native_pipeline_liveness.py \
  tests/test_native_pipeline_liveness_runner.py \
  tests/test_native_pipeline_stall_diagnostic.py \
  tests/test_native_pipeline_stall_properties.py \
  tests/test_native_pipeline_stdout_capture.py \
  tests/test_native_sdist.py \
  tests/test_process_state_degradations.py \
  tests/test_process_state_helper.py \
  tests/test_py_typed_marker.py \
  tests/test_running_command_children_contract.py \
  scripts/tests/test_boundary_*.py \
  scripts/tests/test_check_fmt_import_order_contract.py \
  scripts/tests/test_install_pypy312.py \
  scripts/tests/test_rust_lint_baseline_contract.py \
  tests/behaviour/test_[a-h]*.py \
  tests/behaviour/test_[i-r]*.py \
  tests/behaviour/test_[s-z]*.py \
  $(ACT_PARSER_TARGETS)
# The modules gated on the compiled extension. Deliberately not the whole
# suite: with the extension installed, test_pipeline.py trips the descriptor
# close race in issue #124 and aborts the interpreter. One definition here,
# consumed by both the extension-tests CI job and the documented local command.
EXTENSION_TEST_TARGETS ?= cuprum/unittests/test_rust_streams.py \
  cuprum/unittests/test_rust_consume_stream.py \
  cuprum/unittests/test_rust_streams_boundary_property.py \
  cuprum/unittests/test_rust_streams_roundtrip_property.py \
  cuprum/unittests/test_rust_extension.py \
  cuprum/unittests/test_rust_splice.py \
  cuprum/unittests/test_rust_errno.py \
  cuprum/unittests/test_rust_errno_windows.py \
  cuprum/unittests/test_rust_stream_native_order.py \
  cuprum/unittests/test_loom_model_conformance.py \
  cuprum/unittests/test_backend.py \
  cuprum/unittests/test_extension_requirement_guard.py \
  tests/behaviour/test_rust_streams_behaviour.py \
  tests/behaviour/test_rust_streams_errors_behaviour.py \
  tests/behaviour/test_rust_extension_behaviour.py \
  tests/behaviour/test_stream_backend_pipeline.py
shell_quote = '$(subst ','"'"',$(1))'
UV_ENV = UV_CACHE_DIR=.uv-cache UV_TOOL_DIR=.uv-tools
UV ?= uv

# The CV-005 CodeScene contracts live in shared-actions and run from a full
# commit, so a fix is a pin bump. `.github/cv005.toml` holds this repository's
# only parameters.
CV005_CONTRACTS_REF ?= 3754876bc4e94dc65c83af3def37828934f8f65e
CV005_CONTRACTS = $(UV_ENV) $(UV) tool run --python 3.13 \
	--from 'git+https://github.com/leynos/shared-actions@$(CV005_CONTRACTS_REF)\#subdirectory=packages/cv005-contracts' \
	cv005-contracts

ifeq ($(OS),Windows_NT)
LOCAL_TOOL_ENV =
else
LOCAL_TOOL_PATH = $(HOME)/.local/bin:$(HOME)/.bun/bin:$(PATH)
LOCAL_TOOL_ENV = PATH="$(LOCAL_TOOL_PATH)"
endif
UV_RUN_ENV = $(LOCAL_TOOL_ENV) $(UV_ENV)
RUFF_ENV = RAYON_NUM_THREADS=1
# Pin Ruff so `make` invokes the same version as the `ruff==` dev dependency
# in pyproject.toml and the RUFF_VERSION env in .github/workflows/ci.yml.
# Bump all three sites together: a version mismatch causes version-skew lint
# failures because rule sets differ between Ruff releases. The pin-parity
# contract test in cuprum/unittests/test_toolchain_pins.py enforces this.
RUFF_VERSION ?= 0.16.4
RUFF = $(RUFF_ENV) $(UV_RUN_ENV) uv tool run --from $(call shell_quote,ruff==$(RUFF_VERSION)) ruff
# Pin ty so `make` and CI invoke the same typechecker release. ty is pre-1.0
# and diagnostics shift between releases, so an unpinned install breaks the
# typecheck gate without any code change. Bump deliberately and fix new
# diagnostics in the same commit. Kept in sync with the `ty==` dev dependency
# in pyproject.toml and the TY_VERSION env in .github/workflows/ci.yml by the
# same contract test as the Ruff pin.
TY_VERSION ?= 0.0.74
TY = $(UV_RUN_ENV) uv tool run --from $(call shell_quote,ty==$(TY_VERSION)) ty
PYTEST = $(UV_RUN_ENV) uv run pytest
# Interrogate the whole Python estate, not only the production package: tests,
# benchmarks, scripts, and the root conftest document their definitions too.
# The [tool.interrogate] section in pyproject.toml excludes overload signatures,
# whose shared implementation carries the required docstring.
INTERROGATE_TARGETS ?= benchmarks conftest.py cuprum scripts tests
INTERROGATE = $(UV_RUN_ENV) uv run interrogate --fail-under 100 $(INTERROGATE_TARGETS)
# PyPy 8.0.0's Python 3.12 build is beta quality. uv's catalogue does not yet
# expose it, so obtain the official Linux x86_64 binary and verify its checksum
# before using its explicit executable path. The lint pass itself validates the
# interpreter identity, so a caller override cannot silently select PyPy 3.11.
PYPY312_VERSION ?= 8.0.0
PYPY312_PYTHON_VERSION ?= 3.12
PYPY312_ARCHIVE ?= pypy3.12-v8.0.0-linux64.tar.gz
PYPY312_URL ?= https://downloads.python.org/pypy/$(PYPY312_ARCHIVE)
PYPY312_SHA256 ?= a1b4851459c2b3dffccab71cb08989534fab0839deddd34f0e6bf18add256fd7
PYPY312_ROOT ?= .pypy/pypy3.12-v8.0.0-linux64
PYPY312_ARCHIVE_PATH ?= .pypy/$(PYPY312_ARCHIVE)
PYPY312_PYTHON ?= $(abspath $(PYPY312_ROOT)/bin/pypy3.12)
PYLINT_PYTHON ?= $(PYPY312_PYTHON)
# Include non-package test directories directly: Pylint's recursive walk only
# descends from a package directory, so the broad roots alone skip them.
PYLINT_TARGETS ?= benchmarks conftest.py cuprum cuprum/unittests scripts \
  scripts/tests tests tests/behaviour tests/features
# The 400-line module limit remains enforced for production and benchmark
# sources. The in-package test suite has 28 pre-existing larger modules, so
# analyse it in a separate invocation with only that one test-only exception.
PYLINT_TEST_TARGETS ?= cuprum/unittests scripts/tests tests/behaviour tests/features
PYLINT_STRICT_TARGETS = $(filter-out $(PYLINT_TEST_TARGETS),$(PYLINT_TARGETS))
# DF12 retains the established package-root discovery scope. The classic pass
# owns complete source coverage, including the non-package test roots above;
# the DF12 plugin remains a focused, separately versioned policy pass.
DF12_PYLINT_TARGETS ?= benchmarks conftest.py cuprum scripts tests
# Pin pylint: a new release would otherwise change lint behaviour without any
# repository change (same skew class as ruff above). Pylint 4.0.9 runs on PyPy
# without the former pylint-pypy-shim patch.
PYLINT_VERSION ?= 4.0.9
# Pylint 4.0.9 declares Astroid <=4.1.dev0. Astroid 4.3.1 is therefore a
# future upgrade once Pylint publishes a compatible release; pin the newest
# supported stack deliberately rather than forcing incompatible metadata.
ASTROID_VERSION ?= 4.0.4
PYLINT_CACHE ?= .cache/pylint/pypy312
DF12_PYLINT_CACHE ?= .cache/pylint/cpython314
PYLINT_ENV = PYLINTHOME=$(PYLINT_CACHE)
DF12_PYLINT_ENV = PYLINTHOME=$(DF12_PYLINT_CACHE)
PYLINT = $(PYLINT_ENV) $(UV_RUN_ENV) uv tool run --python $(PYLINT_PYTHON) \
  --from 'pylint==$(PYLINT_VERSION)' --with 'astroid==$(ASTROID_VERSION)' \
  python -m pylint --jobs=1
TYPOS_CONFIG_BUILDER_VERSION ?= v0.1.3
TYPOS_CONFIG_BUILDER = $(UV_RUN_ENV) uv tool run --python 3.14 --from \
  "git+https://github.com/leynos/typos-config-builder.git@$(TYPOS_CONFIG_BUILDER_VERSION)" \
  typos-config-builder
# Use the controlled v0.3.0 release tag. Keep in step with the
# df12-python-lints dev dependency in pyproject.toml.
DF12_PYTHON_LINTS_REF ?= v0.3.0
DF12_PYTHON_LINTS = git+https://github.com/leynos/df12-python-lints.git@$(DF12_PYTHON_LINTS_REF)
DF12_PYTHON ?= 3.14
DF12_PYLINT_MESSAGES = R9101,C9102,R9103,R9104,C9105,C9106,C9107,R9108,R9109,R9110,R9111,C9112,R9112
DF12_PYLINT = $(DF12_PYLINT_ENV) $(UV_RUN_ENV) uv tool run \
  --python $(DF12_PYTHON) --from 'pylint==$(PYLINT_VERSION)' \
  --with 'astroid==$(ASTROID_VERSION)' --with '$(DF12_PYTHON_LINTS)' \
  python -m pylint --jobs=1 \
  --disable=all --load-plugins=df12_python_lints \
  --enable=syntax-error,$(DF12_PYLINT_MESSAGES)
# Snapshot leak scanning is a CPython 3.14 tool pass. Keep it out of the
# project virtual environment so linting never changes the application venv.
AMBRLEAKS = $(UV_RUN_ENV) uv run --isolated --python $(DF12_PYTHON) ambrleaks
SKYLOS_VERSION = 4.33.2
# Skylos parses source using its own Python AST, so Python 3.14 prevents
# phantom dead-code findings from syntax older tool runtimes cannot parse.
SKYLOS_CLI = $(UV_RUN_ENV) uv tool run --python 3.14 --from 'skylos==$(SKYLOS_VERSION)' skylos
SKYLOS = $(SKYLOS_CLI) --config-file pyproject.toml
SKYLOS_PRODUCTION_TARGETS ?= cuprum
SKYLOS_EXCLUDE_FOLDERS ?= cuprum/unittests
SKYLOS_WHITELIST_LOCK ?= .skylos-whitelist.lock
# The pinned `nose` duplication detector, `https://github.com/corca-ai/nose`.
# Pin so a new release cannot change the gate's findings without a repository
# change. The same literal appears as `[tool.nose] version` in pyproject.toml
# and as `NOSE_VERSION` in .github/workflows/ci.yml; the parity contract tests
# in cuprum/unittests/test_toolchain_pins.py keep the three sites aligned.
NOSE_VERSION ?= 0.20.0
NOSE_TOOLS_DIR ?= .tools/nose
NOSE_BIN ?= $(NOSE_TOOLS_DIR)/nose
CARGO_BINSTALL ?= cargo-binstall
# The gate is isolated tooling, not application code. It runs with
# `--no-project` under its own interpreter, with the inline script dependencies
# in `scripts/duplication_gate.py`'s PEP 723 header, so it needs neither the
# application virtualenv nor the compiled extension. NOSE_BIN is exported
# because a relative override resolves against the repository root, and it is
# shell-quoted so a path containing spaces survives.
DUPLICATION_PYTHON ?= 3.14
# The gate modules, in the order `[tool.ty.src] exclude` names them: `typecheck`
# re-checks them at their real floor, and the duplication gate module is the
# entry point that pulls the other four in.
DUPLICATION_SOURCES = scripts/atomic_write.py scripts/nose_schema.py \
  scripts/nose_detector.py scripts/duplication_allowlist.py \
  scripts/duplication_gate.py
# The tooling tests ride the same 3.14 interpreter as the modules they cover,
# so they carry the same floor and the same excluded-from-the-3.12-pass
# treatment.
DUPLICATION_TEST_SOURCES = scripts/tests/duplication_gate_test_support.py \
  scripts/tests/nose_detector_test_support.py \
  scripts/tests/test_atomic_write.py scripts/tests/test_duplication_gate.py \
  scripts/tests/test_duplication_gate_blocking.py \
  scripts/tests/test_duplication_gate_commands.py \
  scripts/tests/test_duplication_gate_make.py \
  scripts/tests/test_duplication_gate_persistence.py \
  scripts/tests/test_duplication_gate_properties.py \
  scripts/tests/test_duplication_gate_seams.py \
  scripts/tests/test_gate_entrypoint_binding.py \
  scripts/tests/test_make_install_nose.py \
  scripts/tests/test_nose_binary.py \
  scripts/tests/test_nose_detector.py \
  scripts/tests/test_nose_schema.py \
  scripts/tests/test_nose_scope_contract.py \
  scripts/tests/test_nose_settings.py
# A script path, not `-m`: `uv run` only reads a PEP 723 header from a script
# named on the command line, so `-m` silently falls back to the ambient
# environment and resolves the gate's pins from whatever happens to be active
# instead of from the header. PYTHONPATH supplies the repository root so the
# modules can still import each other as `scripts.<name>`, which `__package__`
# and a namespace `scripts/` directory make workable without an `__init__.py`.
DUPLICATION_GATE = $(UV_RUN_ENV) PYTHONPATH=. \
  NOSE_BIN=$(call shell_quote,$(NOSE_BIN)) \
  uv run --no-project --python $(DUPLICATION_PYTHON) \
  scripts/duplication_gate.py
# The helper tests are 3.14-only tooling tests, so they run isolated from the
# application suite with the gate's own dependencies and no project install.
DUPLICATION_TEST_DEPS = --with pytest==9.0.2 --with cyclopts==4.25.2 \
  --with tomlkit==0.15.1 --with 'hypothesis[asyncio]==6.151.9' \
  --with syrupy==6.0.0
DUPLICATION_TEST_TARGETS ?= scripts/tests/test_atomic_write.py \
  scripts/tests/test_duplication_gate.py \
  scripts/tests/test_duplication_gate_blocking.py \
  scripts/tests/test_duplication_gate_commands.py \
  scripts/tests/test_duplication_gate_make.py \
  scripts/tests/test_duplication_gate_persistence.py \
  scripts/tests/test_duplication_gate_properties.py \
  scripts/tests/test_duplication_gate_seams.py \
  scripts/tests/test_gate_entrypoint_binding.py \
  scripts/tests/test_make_install_nose.py \
  scripts/tests/test_nose_binary.py \
  scripts/tests/test_nose_detector.py \
  scripts/tests/test_nose_schema.py \
  scripts/tests/test_nose_scope_contract.py \
  scripts/tests/test_nose_settings.py
# `git ls-files` covers tracked files and nonignored untracked files without
# traversing ignored paths. The shell filter keeps only regular non-symlink
# files, and prefixes a leading dash so the linter cannot parse it as an option.
MDLINT_FILES_FIND = bash -o pipefail -c 'git ls-files -z --cached --others --exclude-standard -- "$$@" | while IFS= read -r -d "" markdown_file; do if [ -f "$$markdown_file" ] && [ ! -L "$$markdown_file" ]; then case "$$markdown_file" in -*) printf "./%s\0" "$$markdown_file" ;; *) printf "%s\0" "$$markdown_file" ;; esac; fi; done' -- $(MARKDOWN_GLOBS)
MDLINT_FIX_COMMAND = unset FORCE_COLOR; $(LOCAL_TOOL_ENV) xargs -0 -r $(MDLINT) --fix < "$$markdown_files"
MDLINT_CHECK_COMMAND = unset FORCE_COLOR; $(LOCAL_TOOL_ENV) xargs -0 -r $(MDLINT) < "$$markdown_files"
.PHONY: help all clean build build-release lint python-lint pylint-classic \
        pylint-integration pypy312 verify-classic-pylint verify-df12-pylint \
        rust-lint lint-clippy lint-whitaker \
        github-actions-lint \
        lint-windows fmt check-fmt \
        markdownlint spelling nixie test test-selection test-python test-rust loom test-act typecheck \
        test-extension test-markdown-format develop makeutil skylos-allow \
        install-nose duplication duplication-test duplication-allow \
        test-dev-fast-contract dev-fast-check dev-build dev-test msrv-check \
        benchmark-micro benchmark-e2e \
        $(TOOLS) $(VENV_TOOLS) test-workflow-contracts
# Serialize the lint hierarchy. Each aggregate target lists its leaves as plain
# prerequisites, so a caller's `-f` override file is honoured directly by the
# one Make process that reads it, with no forwarding to get wrong.
#
# `.WAIT` would express the ordering in the prerequisite list itself, but it is
# GNU Make 4.4-only. `.NOTPARALLEL` is not: the prereq-less form dates from Make
# 3.79, and `.NOTPARALLEL` with prerequisites from 4.4. Naming the aggregates
# here therefore works on both, and degrades safely in the direction that
# matters: Make 4.3 ignores the prerequisites and serializes the whole run,
# while Make 4.4 serializes exactly the two named subtrees. Both were verified
# against real 4.3 and 4.4 binaries, so the hosted runners' Make needs no pin.
#
# Leaves are deliberately not named here. Naming `lint` alone would leave
# `rust-lint`'s own prerequisites free to interleave under `-j`; naming both
# subtrees is what fixes the order without serializing unrelated work.
.NOTPARALLEL: lint rust-lint

.DEFAULT_GOAL := all

test-workflow-contracts: ## Check the CV-005 CodeScene workflow contracts
	$(CV005_CONTRACTS) check --repository .

all: build check-fmt lint typecheck test test-workflow-contracts

.venv: pyproject.toml
	$(UV_RUN_ENV) uv venv --clear

build: uv .venv ## Build virtual-env and install deps
	$(UV_RUN_ENV) uv sync --group dev $(UV_SYNC_FLAGS)

# Why this exists and why `ensurepip` comes first: see "Building the
# extension for tests" in docs/developers-guide.md.
develop: build $(DEVELOP_DEV_FAST_PREREQUISITE) ## Build the native extension into the dev virtual-env
	$(UV_RUN_ENV) uv run $(UV_RUN_FLAGS) python -m ensurepip --upgrade
	$(DEVELOP_DEV_FAST_ENV) $(UV_RUN_ENV) uv run $(UV_RUN_FLAGS) maturin develop $(MATURIN_DEVELOP_FLAGS) --manifest-path $(RUST_DIR)/cuprum-rust/Cargo.toml

build-release: ## Build artefacts (sdist & wheel)
	python -m build --sdist --wheel

clean: ## Remove build artefacts
	rm -rf build dist *.egg-info \
	  .mypy_cache .pytest_cache .coverage coverage.* \
	  lcov.info htmlcov .venv
	find . -type d -name '__pycache__' -print0 | xargs -0 -r rm -rf
	rm -f .typos-oxendict-base.json .typos-oxendict-base.toml
	cd $(RUST_DIR) && $(CARGO) clean

define ensure_tool
	@$(LOCAL_TOOL_ENV) command -v $(1) >/dev/null 2>&1 || { \
	  printf "Error: '%s' is required, but not installed\n" "$(1)" >&2; \
	  exit 1; \
	}
endef

define ensure_tool_venv
	@$(LOCAL_TOOL_ENV) $(UV_ENV) uv run which $(1) >/dev/null 2>&1 || { \
	  printf "Error: '%s' is required in the virtualenv, but is not installed\n" "$(1)" >&2; \
	  exit 1; \
	}
endef

define run_markdownlint_files
	@markdown_files="$$(mktemp)" || exit $$?; \
	trap 'rm -f "$$markdown_files"' 0; \
	if ! $(MDLINT_FILES_FIND) > "$$markdown_files"; then \
		exit 1; \
	fi; \
	if [ -s "$$markdown_files" ]; then \
		$(1); \
	fi
endef

ifneq ($(strip $(TOOLS)),)
$(TOOLS): ## Verify required CLI tools
	$(call ensure_tool,$@)
endif


ifneq ($(strip $(VENV_TOOLS)),)
.PHONY: $(VENV_TOOLS)
$(VENV_TOOLS): ## Verify required CLI tools in venv
	$(call ensure_tool_venv,$@)
endif

fmt: ruff ## Format sources
	$(RUFF) format
	$(RUFF) check --select I --fix
	cd $(RUST_DIR) && $(RUSTFMT_CARGO) fmt --all
	$(LOCAL_TOOL_ENV) $(MDTABLEFIX) --in-place $(MDTABLEFIX_SELECT) $(MDTABLEFIX_EXTENSIONS) $(MDTABLEFIX_RULES)
	$(call run_markdownlint_files,$(MDLINT_FIX_COMMAND))

check-fmt: ruff ## Verify formatting
	$(RUFF) format --check
	$(RUFF) check --select I
	cd $(RUST_DIR) && $(RUSTFMT_CARGO) fmt --all -- --check
	$(LOCAL_TOOL_ENV) $(MDTABLEFIX) --check $(MDTABLEFIX_SELECT) $(MDTABLEFIX_EXTENSIONS) $(MDTABLEFIX_RULES)

test-markdown-format: ## Validate the Markdown formatting Makefile contract
	@PYTHONPATH=scripts $(UV_RUN_ENV) uv run --no-project --python 3.13 \
		--with pytest==9.0.2 --with hypothesis==6.151.9 --with syrupy==6.0.0 \
		python -m pytest scripts/tests/test_markdown_format_makefile.py -c /dev/null \
		--rootdir=. -p no:cacheprovider

lint: python-lint rust-lint github-actions-lint ## Run Python, Rust, and GitHub Actions linters

$(PYPY312_PYTHON):
	PYPY312_URL="$(PYPY312_URL)" PYPY312_SHA256="$(PYPY312_SHA256)" \
		PYPY312_ARCHIVE_PATH="$(PYPY312_ARCHIVE_PATH)" PYPY312_ROOT="$(PYPY312_ROOT)" \
		PYPY312_PYTHON="$(PYPY312_PYTHON)" $(UV_RUN_ENV) \
		uv run --no-project --python 3.13 -m scripts.install_pypy312

pypy312: $(PYPY312_PYTHON) ## Install the checksum-verified PyPy 8.0.0 Python 3.12 linter

verify-classic-pylint: ## Verify the exact PyPy and Pylint environment before linting
	@if test "$(PYLINT_PYTHON)" = "$(PYPY312_PYTHON)"; then $(MAKE) --no-print-directory pypy312; fi
	$(PYLINT_ENV) $(UV_RUN_ENV) uv tool run --python $(PYLINT_PYTHON) \
		--from 'pylint==$(PYLINT_VERSION)' --with 'astroid==$(ASTROID_VERSION)' \
		python -c 'import astroid, pylint, sys; expected = ("pypy", (3, 12), (8, 0, 0)); actual = (sys.implementation.name, sys.version_info[:2], sys.pypy_version_info[:3]); assert actual == expected, f"classic pylint requires {expected}, got {actual}"; print(f"classic pylint: {sys.version}; pylint {pylint.__version__}; astroid {astroid.__version__}")'

verify-df12-pylint: ## Verify the CPython 3.14 DF12 environment before linting
	$(DF12_PYLINT_ENV) $(UV_RUN_ENV) uv tool run --python $(DF12_PYTHON) \
		--from 'pylint==$(PYLINT_VERSION)' --with 'astroid==$(ASTROID_VERSION)' \
		--with '$(DF12_PYTHON_LINTS)' python -c 'import astroid, pylint, sys; expected = ("cpython", (3, 14)); actual = (sys.implementation.name, sys.version_info[:2]); assert actual == expected, f"DF12 pylint requires {expected}, got {actual}"; print(f"DF12 pylint: {sys.version}; pylint {pylint.__version__}; astroid {astroid.__version__}")'

pylint-integration: verify-classic-pylint verify-df12-pylint ## Exercise both isolated Pylint environments
	PYLINT_PYTHON="$(PYLINT_PYTHON)" PYLINT_VERSION="$(PYLINT_VERSION)" ASTROID_VERSION="$(ASTROID_VERSION)" \
		DF12_PYTHON="$(DF12_PYTHON)" DF12_PYTHON_LINTS="$(DF12_PYTHON_LINTS)" $(PYTEST) cuprum/unittests/test_pylint_runtime_contract.py

pylint-classic: verify-classic-pylint ## Run the baseline Pylint pass under PyPy 8.0.0 / Python 3.12
	$(PYLINT) $(PYLINT_STRICT_TARGETS)
	$(PYLINT) --disable=too-many-lines $(PYLINT_TEST_TARGETS)

python-lint: ruff uv install-nose pylint-integration pylint-classic verify-df12-pylint ## Run Ruff, interrogate, pylint, df12-python-lints, ambrleaks, and the duplication gate
	$(RUFF) check && $(INTERROGATE)
	$(DF12_PYLINT) $(DF12_PYLINT_TARGETS)
	$(AMBRLEAKS) cuprum/unittests scripts/tests tests
	$(SKYLOS) $(SKYLOS_PRODUCTION_TARGETS) --exclude $(SKYLOS_EXCLUDE_FOLDERS) --category dead_code --gate --format concise --no-upload --no-provenance --no-grep-verify
	$(DUPLICATION_GATE) check

rust-lint: lint-clippy lint-whitaker spelling ## Run Rust documentation, Clippy, Whitaker, and spelling checks

lint-clippy: $(RUST_DEBUG_PREREQUISITE) ## Run Rust documentation and Clippy
	cd $(RUST_DIR) && RUSTDOCFLAGS="$(RUSTDOC_FLAGS)" $(RUST_DEBUG_CARGO) doc --no-deps && $(RUST_DEBUG_CARGO) clippy $(CLIPPY_FLAGS)

lint-whitaker: ## Run Whitaker for every Rust workspace package
	cd $(RUST_DIR) && $(LOCAL_TOOL_ENV) RUSTFLAGS="$(WHITAKER_RUSTFLAGS)" $(WHITAKER) --all -- $(WHITAKER_CARGO_FLAGS)

# Accept FIRST/MEMBERS/REASON only from the make command line: an ambient
# environment variable must not be able to write an exception into
# pyproject.toml, and `NAME` in particular is already taken by WSL, which
# injects the hostname there. `$(value ...)` preserves the literal text so
# shells, quotes and `$$` survive into the gate's argv uninterpreted.
cli_value = $(if $(filter command line,$(origin $(1))),$(value $(1)))

install-nose: ## Install the pinned nose duplication detector
	@if [ "$$($(call shell_quote,$(NOSE_BIN)) --version 2>/dev/null)" = "nose $(NOSE_VERSION)" ]; then \
	  printf "nose %s already installed at %s\n" "$(NOSE_VERSION)" "$(NOSE_BIN)"; \
	else \
	  printf "Installing nose %s into %s\n" "$(NOSE_VERSION)" "$(NOSE_TOOLS_DIR)"; \
	  mkdir -p "$(NOSE_TOOLS_DIR)"; \
	  $(call shell_quote,$(CARGO_BINSTALL)) \
	    --no-confirm --disable-strategies compile,quick-install \
	    --install-path "$(NOSE_TOOLS_DIR)" \
	    --git https://github.com/corca-ai/nose 'nose-cli@$(NOSE_VERSION)' || exit $$?; \
	  installed=$$($(call shell_quote,$(NOSE_BIN)) --version 2>/dev/null) || exit $$?; \
	  if [ "$$installed" != "nose $(NOSE_VERSION)" ]; then \
	    printf "install-nose: expected 'nose %s', got '%s'\n" \
	      "$(NOSE_VERSION)" "$$installed" >&2; \
	    exit 1; \
	  fi; \
	  printf "Installed %s\n" "$$installed"; \
	fi

duplication: install-nose ## Run the blocking code-duplication gate
	$(DUPLICATION_GATE) check

duplication-test: ## Run the duplication-gate helper tests
	@NOSE_BIN=$(call shell_quote,$(NOSE_BIN)) \
	  $(UV_RUN_ENV) uv run --no-project --python $(DUPLICATION_PYTHON) \
	  $(DUPLICATION_TEST_DEPS) \
	  python -m pytest -c /dev/null --rootdir=. -p no:cacheprovider \
	  $(DUPLICATION_TEST_TARGETS)

# `MEMBERS` carries every location past the first as one whitespace-separated
# value, each forwarded as its own `--second`. GNU Make overwrites a repeated
# command-line variable with its last occurrence, which is why the interface
# has no repeated `SECOND`: `SECOND=a SECOND=b` would keep only `b` and record
# a three-member family as covering two. A single list-valued variable keeps
# every member addressable. `$(value ...)` yields the list unexpanded, so
# `$(foreach)` sees the literal entries rather than a shell-quoted single
# string.
duplication-allow: export DUPLICATION_FIRST = $(call cli_value,FIRST)
duplication-allow: export DUPLICATION_MEMBERS = $(call cli_value,MEMBERS)
duplication-allow: export DUPLICATION_REASON = $(call cli_value,REASON)
duplication-allow: ## Record one reasoned duplication exception
	@case "$${DUPLICATION_FIRST}" in *[![:space:]]*) ;; *) printf "Error: FIRST is required (a 'path[::name]' key)\\n" >&2; exit 2;; esac
	@case "$${DUPLICATION_REASON}" in *[![:space:]]*) ;; *) printf "Error: REASON is required for a duplication exception\\n" >&2; exit 2;; esac
	$(DUPLICATION_GATE) allow --first "$${DUPLICATION_FIRST}" \
	  $(foreach member,$(call cli_value,MEMBERS),--second $(call shell_quote,$(member))) \
	  --reason "$${DUPLICATION_REASON}"

skylos-allow: export SKYLOS_SYMBOL = $(value SYMBOL)
skylos-allow: export SKYLOS_REASON = $(value REASON)
skylos-allow: ## Document one named Skylos exception, not an entry point
	@case "$${SKYLOS_SYMBOL}" in *[![:space:]]*) ;; *) printf "Error: SYMBOL is required for a named whitelist exception\\n" >&2; exit 2;; esac
	@case "$${SKYLOS_REASON}" in *[![:space:]]*) ;; *) printf "Error: REASON is required for a named whitelist exception\\n" >&2; exit 2;; esac
	flock "$(SKYLOS_WHITELIST_LOCK)" env $(SKYLOS_CLI) whitelist "$${SKYLOS_SYMBOL}" --reason "$${SKYLOS_REASON}"

# `-shellcheck=` disables actionlint's shellcheck integration so the gate needs
# no shellcheck binary and matches the lint job, which installs none. It is not
# a style preference: actionlint v1.7.12 writes each `run:` body to the
# shellcheck child's stdin before starting it, so a body larger than the pipe
# buffer (about 64 KiB; `ci.yml`'s benchmark step is over 9 KiB) races a
# deadlock once the pipe fills. A clean checkout of main can hang here too.
# Upstream tracks it as rhysd/actionlint#702, #704, and #712.
github-actions-lint: $(YAMLLINT) $(ACTIONLINT) ## Validate GitHub Actions workflows and composite actions
	$(YAMLLINT) --strict --config-file .yamllint.yml .github/workflows .github/actions
	$(ACTIONLINT) -config-file .github/actionlint.yaml -shellcheck=

lint-windows: ## Lint the Rust extension's Windows cfg branches (cross-target)
	@if ! rustup target list --installed | grep -qx '$(WINDOWS_TARGET)'; then \
	  echo "The $(WINDOWS_TARGET) standard library is required." >&2; \
	  echo "Install it with: rustup target add $(WINDOWS_TARGET)" >&2; \
	  exit 1; \
	fi
	cd $(RUST_DIR) && PYO3_CROSS_PYTHON_VERSION=$(WINDOWS_PYTHON_VERSION) \
	  $(CARGO) clippy --target $(WINDOWS_TARGET) $(CLIPPY_FLAGS)

typecheck: build ## Run typechecking
	$(UV_RUN_ENV) uv sync --group dev
	$(TY) --version
	$(TY) check --python .venv
	$(TY) check --python .venv --python-version $(DUPLICATION_PYTHON) \
	  $(DUPLICATION_SOURCES) $(DUPLICATION_TEST_SOURCES)

markdownlint: $(MDLINT) ## Lint Markdown files
	$(call run_markdownlint_files,$(MDLINT_CHECK_COMMAND))
	+$(MAKE) spelling

spelling: ## Enforce en-GB-oxendict spelling in prose and source
	$(TYPOS_CONFIG_BUILDER) gate --repository . --scope all

nixie: ## Validate Mermaid diagrams
	$(call ensure_tool,nixie)
	$(LOCAL_TOOL_ENV) $(NIXIE) --no-sandbox

makeutil: ## Verify the Makefile parser used by contract tests
	$(call ensure_tool,$@)

# Both suites, which is what a contributor wants locally. CI splits them: the
# coverage job is the only place the Rust suite runs, under instrumentation, so
# the interpreter matrix calls `test-python` alone. See "One execution per
# suite" in docs/developers-guide.md.
test: makeutil test-selection test-python test-rust ## Run the Python and Rust suites

test-python: test-selection build uv $(VENV_TOOLS) makeutil ## Run the Python suite
	@for pattern in $(foreach target,$(PYTEST_TARGETS),$(call shell_quote,$(target))); do \
	  set -- $$pattern; [ -e "$$1" ] || continue; \
	  RUSTFLAGS="$(PYTEST_RUSTFLAGS)" $(PYTEST) -v -n $(PYTEST_WORKERS) "$$@" || exit $$?; \
	done

# `PYTEST_TARGETS` is the selector that decides what `test-python` collects, so
# every assertion about it lives in a module *that selector collects* — and a
# selector that stopped collecting `tests/test_ci_*.py` would therefore silence
# the guard rather than fail it. This target is named directly, and is a
# prerequisite of both routes, so the selector's agreement with the module
# population is settled before the loop that depends on it.
test-selection: uv $(VENV_TOOLS) build makeutil ## Check the selector against the module population
	@$(PYTEST) tests/test_ci_test_selection_contract.py || exit $$?

# The scenario half of the harness: it runs the real `changes` job under `act`
# against a throwaway repository, one scenario at a time. It is opt-in because
# each scenario costs 15-27s warm plus image warm-up, and because it needs a
# container runtime that `make test` must not require. The scenarios carry
# their own `@pytest.mark.timeout`, so the suite-wide `timeout = 30` in
# pyproject.toml is not what keeps them out of `make test`: what does is that
# `ACT_SCENARIO_TARGETS` is absent from `PYTEST_TARGETS`. CI runs
# `make test-python`, so collecting them there would put a container-bound
# scenario on a job that has no runtime. `CUPRUM_REQUIRE_ACT=1` turns a missing
# runtime into a failure, so a job that provides one cannot report success for
# having skipped every scenario.
test-act: build uv $(VENV_TOOLS) ## Run the act workflow integration scenarios, requiring a container runtime
	CUPRUM_REQUIRE_ACT=1 $(PYTEST) -v $(ACT_SCENARIO_TARGETS)

test-rust: $(RUST_DEBUG_PREREQUISITE) ## Run the Rust suite
	@if $(LOCAL_TOOL_ENV) command -v cargo-nextest >/dev/null 2>&1; then \
	  $(LOCAL_TOOL_ENV) cargo-nextest --version | head -1 | $(NEXTEST_VERSION_OK) || { $(NEXTEST_FLOOR_MESSAGE); }; \
	  cd $(RUST_DIR) && $(LOCAL_TOOL_ENV) RUSTFLAGS="$(DEV_FAST_TEST_RUSTFLAGS)" $(RUST_DEBUG_CARGO) nextest run $(NEXTEST_FLAGS) $(BUILD_JOBS); \
	else \
	  echo "cargo-nextest not found; falling back to cargo test." >&2; \
	  cd $(RUST_DIR) && RUSTFLAGS="$(DEV_FAST_TEST_RUSTFLAGS)" $(RUST_DEBUG_CARGO) test $(TEST_FLAGS) $(BUILD_JOBS) -- --test-threads=$(TEST_JOBS); \
	fi
	cd $(RUST_DIR) && RUSTDOCFLAGS="$(DOCTEST_RUSTDOC_FLAGS)" RUSTFLAGS="$(DEV_FAST_TEST_RUSTFLAGS)" $(RUST_DEBUG_CARGO) test $(DOCTEST_FLAGS)

msrv-check: ## Verify every Rust target compiles on the published MSRV
	cd $(RUST_DIR) && $(MSRV_CARGO_COMMAND) check --workspace --all-targets --all-features

dev-fast-check: ## Verify Linux dev-fast prerequisites
	@$(DEV_FAST_CHECK_COMMAND)

dev-build: dev-fast-check ## Build Rust debug targets through the accelerated route
	cd $(RUST_DIR) && $(DEV_FAST_CARGO_COMMAND) build $(CARGO_FLAGS)

dev-test: dev-fast-check ## Test Rust through the accelerated route
	@$(DEV_FAST_TEST_COMMAND)

loom: build ## Run the full bounded Loom model suite
	$(UV_RUN_ENV) uv run scripts/run_loom.py --mode full

# Run `make develop` first. Without the extension the guard fails the run with
# a message naming that command, which is the intended diagnostic.
test-extension: build uv $(VENV_TOOLS) ## Run the extension-gated tests, requiring the extension
	CUPRUM_REQUIRE_RUST_EXTENSION=1 $(PYTEST) -v $(EXTENSION_TEST_TARGETS)

test-dev-fast-contract: build uv $(VENV_TOOLS) ## Validate dev-fast routing and adapter contracts
	$(PYTEST) -v cuprum/unittests/test_dev_fast_contract.py cuprum/unittests/test_dev_fast_adapter.py cuprum/unittests/test_dev_fast_prerequisites.py tests/test_ci_dev_fast_action.py

benchmark-micro: build uv ## Run pytest-benchmark microbenchmarks
	mkdir -p dist/benchmarks
	$(UV_RUN_ENV) CUPRUM_RUN_BENCHMARKS=1 uv run pytest -q \
	  benchmarks/test_stream_microbenchmarks.py \
	  --benchmark-json=dist/benchmarks/microbenchmarks.json

benchmark-e2e: build uv ## Run hyperfine end-to-end throughput benchmark
	mkdir -p dist/benchmarks
	$(UV_RUN_ENV) uv run python benchmarks/pipeline_throughput.py \
	  --output dist/benchmarks/pipeline-throughput.json

help: ## Show available targets
	@grep -E '^[a-zA-Z_-]+:.*?##' $(MAKEFILE_LIST) | \
	awk 'BEGIN {FS=":"; printf "Available targets:\n"} {printf "  %-20s %s\n", $$1, $$2}'

# Boundary verifiers use their own pinned binary toolchains; normal gates keep
# rust/rust-toolchain.toml. Kani install is deliberately not source-built here.
PROVER_TOOLS_SOURCE ?= git+https://github.com/leynos/rust-prover-tools@98929b558253659a0a8ae03be7c49dafeef5f673
PROVER_TOOLS = $(UV_RUN_ENV) uv tool run --python 3.14 --from $(PROVER_TOOLS_SOURCE) prover-tools
VERUS_INSTALL_DIR ?= $(HOME)/.local/share/cuprum-verus-0.2026.09.06.8dea4a2
MIRI_TOOLCHAIN = nightly-2026-08-07
KANI_VERSION = 0.67.0
KANI_LIBRARY_PATH = $(HOME)/.kani/kani-$(KANI_VERSION)/toolchain/lib:$(HOME)/.kani/kani-$(KANI_VERSION)/lib

.PHONY: install-verus boundary-verus boundary-kani boundary-miri boundary-test
install-verus: ## Install the checksum-verified prebuilt Verus release
	$(PROVER_TOOLS) verus install --install-dir $(VERUS_INSTALL_DIR)
	$(UV_RUN_ENV) uv run python scripts/install_boundary_z3.py

boundary-verus: ## Verify actual production length/accounting kernels
	$(UV_RUN_ENV) uv run python scripts/render_boundary_proofs.py
	VERUS_Z3_PATH=$(CURDIR)/.cache/boundary-z3/z3 RUSTUP_TOOLCHAIN=1.98.0 $(VERUS_INSTALL_DIR)/verus/verus rust/target/boundary-verification/progress.rs --crate-type=lib

boundary-kani: ## Check bounded native ownership and existing policy proofs
	$(PROVER_TOOLS) kani check-version
	cd $(RUST_DIR) && LD_LIBRARY_PATH="$(KANI_LIBRARY_PATH)" $(CARGO) kani --package cuprum-native-io
	cd $(RUST_DIR) && LD_LIBRARY_PATH="$(KANI_LIBRARY_PATH)" $(CARGO) kani --package cuprum-streams

boundary-miri: ## Interpret native resource and Miri-compatible stream paths
	cd $(RUST_DIR) && $(CARGO) +$(MIRI_TOOLCHAIN) miri test --package cuprum-native-io --lib
	cd $(RUST_DIR) && $(CARGO) +$(MIRI_TOOLCHAIN) miri test --package cuprum-streams --lib

boundary-test: ## Run isolated native integration and verification-tool contracts
	cd $(RUST_DIR) && $(CARGO) test --package cuprum-native-io --lib
	$(UV_RUN_ENV) uv run pytest scripts/tests/test_boundary_*.py

.PHONY: install-boundary-kani
install-boundary-kani: ## Install checksum-verified Kani binaries without a source build
	$(UV_RUN_ENV) uv run python scripts/install_boundary_kani.py
	PATH="$(CURDIR)/.cache/boundary-kani/bin:$(PATH)" $(CARGO) kani setup --use-local-bundle $(CURDIR)/.cache/boundary-kani/kani-$(KANI_VERSION)-x86_64-unknown-linux-gnu.tar.gz

.PHONY: boundary-contract
boundary-contract: ## Confirm actual safe targets reject all forms of unsafe Rust
	$(UV_RUN_ENV) uv run python scripts/check_boundary_contract.py

.PHONY: boundary-faults
boundary-faults: ## Require proof and real-unwind regressions to detect deliberate faults
	$(UV_RUN_ENV) uv run python -m scripts.check_boundary_faults