Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
SHELL := /bin/bash
.SHELLFLAGS := -o pipefail -c
ifeq ($(wildcard .env),.env)
include .env
export
endif
VIRTUAL_ENV := $(CURDIR)/.venv
PROJECT_NAME := $(shell grep '^name = ' pyproject.toml | sed -E 's/name = "(.*)"/\1/')
# The interpreter is the one .python-version names, unless PYTHON_VERSION or UV_PYTHON asks for another.
# Exporting it hands the same version to every uv command, so `uv sync` never rebuilds .venv on the pin.
PYTHON_VERSION ?= $(or $(UV_PYTHON),$(shell cat .python-version))
export UV_PYTHON := $(PYTHON_VERSION)
LINT_PYTHON_VERSION ?=
# Note: VENV_* variables include quotes to handle paths with spaces (e.g., "My Projects/pipelex")
VENV_PYTHON := "$(VIRTUAL_ENV)/bin/python"
VENV_PYTEST := "$(VIRTUAL_ENV)/bin/pytest"
VENV_RUFF := "$(VIRTUAL_ENV)/bin/ruff"
VENV_PYRIGHT := "$(VIRTUAL_ENV)/bin/pyright"
VENV_MYPY := "$(VIRTUAL_ENV)/bin/mypy"
VENV_PIPELEX := "$(VIRTUAL_ENV)/bin/pipelex"
# Material for MkDocs prints a MkDocs 2.0 warning on every `mkdocs` run; we stay on MkDocs 1.x
# (capped below 2 in pyproject.toml) until the docs move to Zensical.
VENV_MKDOCS := NO_MKDOCS_2_WARNING=true "$(VIRTUAL_ENV)/bin/mkdocs"
VENV_MIKE := "$(VIRTUAL_ENV)/bin/mike"
VENV_PYLINT := "$(VIRTUAL_ENV)/bin/pylint"
VENV_PLXT := RUST_LOG=warn "$(VIRTUAL_ENV)/bin/plxt"
VENV_PIPELEX_DEV := "$(VIRTUAL_ENV)/bin/pipelex-dev"
SKELETON_DIR := "$(HOME)/.pipelex-skeleton/"
HEARTBEAT_INTERVAL ?= 20
# The node toolchain the TypeScript emission gates run against. Both packages are pinned exactly and
# both have zero dependencies, so `npm install` here is reproducible without a lockfile. The prettier
# pin is the contract: `pipelex/codegen/emitters/ts_zod.py` emits the bytes *this* prettier leaves
# alone, so moving it is an emitter change, not a dependency bump — expect the gate to red and the
# emitter to need teaching. The directory is gitignored and provisioned on demand.
TS_TOOLCHAIN_DIR := $(CURDIR)/.ts-toolchain
TS_TOOLCHAIN_PRETTIER_VERSION ?= 3.9.6
TS_TOOLCHAIN_ZOD_VERSION ?= 4.5.4
UV_MIN_VERSION = $(shell grep -m1 'required-version' pyproject.toml | sed -E 's/.*= *"([^<>=, ]+).*/\1/')
USUAL_PYTEST_MARKERS := "(dry_runnable or not (inference or llm or img_gen or extract or search or judgment)) and not pipelex_api"
# The selection the sharded CI job runs. Shared by gha-tests and store-test-durations so the map
# can never be balanced against a different set of tests than the one it is measured from.
GHA_PYTEST_MARKERS := "(dry_runnable or not inference) and not (gha_disabled or pipelex_api)"
define PRINT_TITLE
$(eval PROJECT_PART := [$(PROJECT_NAME)])
$(eval TARGET_PART := ($@))
$(eval MESSAGE_PART := $(1))
$(if $(MESSAGE_PART),\
$(eval FULL_TITLE := === $(PROJECT_PART) ===== $(TARGET_PART) ====== $(MESSAGE_PART) ),\
$(eval FULL_TITLE := === $(PROJECT_PART) ===== $(TARGET_PART) ====== )\
)
$(eval TITLE_LENGTH := $(shell echo -n "$(FULL_TITLE)" | wc -c | tr -d ' '))
$(eval PADDING_LENGTH := $(shell echo $$((126 - $(TITLE_LENGTH)))))
$(eval PADDING := $(shell printf '%*s' $(PADDING_LENGTH) '' | tr ' ' '='))
$(eval PADDED_TITLE := $(FULL_TITLE)$(PADDING))
@echo ""
@echo "$(PADDED_TITLE)"
endef
define WAIT_WITH_HEARTBEAT
start_time=$$(date +%s); \
$(1) & \
cmd_pid=$$!; \
( while kill -0 "$$cmd_pid" 2>/dev/null; do \
sleep $(HEARTBEAT_INTERVAL); \
if kill -0 "$$cmd_pid" 2>/dev/null; then \
elapsed=$$(( $$(date +%s) - $$start_time )); \
echo "• $(2) still running ($${elapsed}s elapsed)"; \
fi; \
done ) & \
heartbeat_pid=$$!; \
wait "$$cmd_pid"; \
exit_code=$$?; \
kill "$$heartbeat_pid" 2>/dev/null || true; \
wait "$$heartbeat_pid" 2>/dev/null || true
endef
define RUN_WITH_HEARTBEAT
@$(call WAIT_WITH_HEARTBEAT,$(1),$(2)); \
exit $$exit_code
endef
define HELP
Manage $(PROJECT_NAME) located in $(CURDIR).
Usage:
make env - Create python virtual env
make lock - Refresh uv.lock without updating anything
make install - Create local virtualenv & install all dependencies
make update - Upgrade dependencies via uv
make validate - Run the setup sequence to validate the config and libraries
make build - Build the wheels
make format - format with ruff and plxt
make lint - lint with ruff and plxt
make ruff-format - format with ruff format
make ruff-lint - lint with ruff check
make pyright - Check types with pyright
make mypy - Check types with mypy
make plxt-format - Format MTHDS/TOML/PLX files with plxt
make plxt-lint - Lint MTHDS/TOML/PLX files with plxt
make rules - Install agent rules for contributing to Pipelex
make rules-claude-standalone - Install a standalone CLAUDE.md (full ruleset, for contributors without the Pipelex workspace)
make up-kit-configs - Update kit configs from .pipelex/, then the api/ server's vendored inference tree from the kit
make ukc - Shorthand -> up-kit-configs
make check-config-sync - Verify .pipelex and pipelex/kit/configs are in sync
make ccs - Shorthand -> check-config-sync
make check-rules - Verify installed agent rules match kit templates
make check-urls - Check all URLs in pipelex/urls.py for broken links (quiet)
make cu - Check URLs with verbose output (shows details)
make generate-mthds-schema - Generate JSON Schema for .mthds files
make gms - Shorthand -> generate-mthds-schema
make check-mthds-schema - Check MTHDS JSON Schema is up-to-date
make cms - Shorthand -> check-mthds-schema
make generate-corpus-vocabulary - Regenerate the MTHDS Test Corpus tag vocabulary
make check-ledger - Check migration ledgers are legal and replay harmlessly
make cl - Shorthand -> check-ledger
make check-migration-schemas - Check configuration surfaces have accounted for their schema changes
make cmig - Shorthand -> check-migration-schemas
make up-migration-schemas - Regenerate the migration fingerprint and defaults goldens
make umig - Shorthand -> up-migration-schemas
make up-migration-schemas-force - Same, over a head golden recording material the models lost
make umigf - Shorthand -> up-migration-schemas-force
make generate-error-registry - Write the error registry's snapshot, typed codes and docs/errors/ pages from its source
make ger - Shorthand -> generate-error-registry
make check-error-registry - Check the error registry against the MTHDS standard, and its derived files
make cer - Shorthand -> check-error-registry
make generate-error-identity - Regenerate the committed PipelexError wire-identity snapshot
make gei - Shorthand -> generate-error-identity
make regenerate-test-models - Regenerate test model fixtures from backend configs
make rtm - Shorthand -> regenerate-test-models
make insert-skeleton - Insert skeleton from $(SKELETON_DIR)
make up - Shorthand -> generate-mthds-schema up-kit-configs rules
make cleanenv - Remove virtual env
make cleanderived - Remove extraneous compiled files, caches, logs, etc.
make cleanall - Remove all -> cleanenv + cleanderived
make merge-check-ruff-lint - Run ruff merge check without updating files
make merge-check-ruff-format - Run ruff merge check without updating files
make merge-check-mypy - Run mypy merge check without updating files
make merge-check-pyright - Run pyright merge check without updating files
make merge-check-plxt-format - Run plxt format check without modifying files
make merge-check-plxt-lint - Run plxt lint check
make v - Shorthand -> validate
make codex-tests - Run tests for Codex (exit on first failure) (no inference, no codex_disabled)
make gha-tests - Run tests for github actions (exit on first failure) (no inference, no gha_disabled)
make test - Run unit tests (no inference)
make test-xdist - Run unit tests with xdist (no inference)
make agent-test - Run unit tests, silent on success, output on failure (for AI agents), then the server's (api-agent-test)
make api-agent-check - The api/ server's own gate: its install, ruff, pyright, mypy, OpenAPI and vendored-kit drift checks
make api-agent-test - The api/ server's unit tests, in its own environment
make agent-test-debug - Debug variant: cleanup + outer timeout + live log; use when agent-test hangs or fails opaquely
make atd - Shorthand -> agent-test-debug
make ts-toolchain - Install the pinned prettier + zod the TypeScript emission gates need
make test-ts-gates - Run the codegen tests with that toolchain, where the node gates may not skip
make ttg - Shorthand -> test-ts-gates
make t - Shorthand -> test-xdist
make test-quiet - Run unit tests without prints (no inference)
make tq - Shorthand -> test-quiet
make test-with-prints - Run tests with prints (no inference)
make tp - Shorthand -> test-with-prints
make tb - Shorthand -> `make test-with-prints TEST=test_boot`
make test-inference - Run unit tests only for inference (with prints)
make ti - Shorthand -> test-inference
make tip - Shorthand -> test-inference-with-prints (parallelized inference tests)
make test-llm - Run unit tests only for llm (with prints)
make tl - Shorthand -> test-llm
make test-extract - Run unit tests only for extract (with prints)
make te - Shorthand -> test-extract
make test-img-gen - Run unit tests only for img_gen (with prints)
make test-g - Shorthand -> test-img-gen
make check-unused-imports - Check for unused imports without fixing
make fix-unused-imports - Fix unused imports with ruff
make fui - Shorthand -> fix-unused-imports
make fix-keyword-only - Auto-fix keyword-only-args violations (insert a bare *)
make fko - Shorthand -> fix-keyword-only
make subject-grant - Record a subject grant (FUNC="<path>::<qualname>" RATIONALE="…")
make sgr - Shorthand -> subject-grant
make check-hub-layering - Enforce the runtime_hub / interpreter_hub layering boundary
make chl - Shorthand -> check-hub-layering
make check-rich-imports - Refuse a module-level Rich import or reach outside pipelex/cli/ (Rich is the cli extra)
make cri - Shorthand -> check-rich-imports
make check-actions-allowlist - Refuse a workflow action outside the committed Actions allowlist
make caa - Shorthand -> check-actions-allowlist
make check-log-calls - Refuse an interpolated log message at INFO+, Rich markup, a message worded against the conventions and a spliced exception, against a baseline that only shrinks from origin/dev's merge base (LOG_CALL_BASELINE_REF=<ref> to compare with another)
make clc - Shorthand -> check-log-calls
make check-TODOs - Check for TODOs
make docs - Serve documentation locally with mkdocs
make docs-check - Check documentation build with mkdocs
make docs-serve-versioned - Serve versioned docs locally with mike
make docs-list - List deployed documentation versions
make docs-deploy VERSION=x.y.z - Deploy docs as version x.y.z (local, no push)
make docs-deploy-stable - Deploy stable docs with 'latest' alias (CI only)
make docs-deploy-specific-version-pre-release - Deploy docs for the current version with 'pre-release' alias (CI only)
make docs-deploy-root - Deploy root assets (404.html, robots.txt, index.html) to gh-pages
make docs-delete VERSION=x.y.z - Delete a deployed documentation version
make serve-graph - Start HTTP server to view ReactFlow graphs (PORT=8765, DIR=temp/test_outputs)
make stop-graph-server - Stop the graph viewer HTTP server
make view-graph - Start server and open ReactFlow graph in browser
make check - Shorthand -> format lint mypy
make c - Shorthand -> check
make cc - Shorthand -> cleanderived check
make li - Shorthand -> lock install
make test-count - Count the number of tests
make check-test-badge - Check if the test count matches the badge value
make test-durations - Show slowest tests with xdist (TOP=30, MIN=0.5)
make td - Shorthand -> test-durations
make test-durations-serial - Show slowest tests without xdist (TOP=30, MIN=0.5)
make tds - Shorthand -> test-durations-serial
make test-time - Timed test run with xdist (wall clock)
make tt - Shorthand -> test-time
make test-time-serial - Timed test run without xdist (wall clock)
make tts - Shorthand -> test-time-serial
endef
export HELP
.PHONY: \
all help env env-verbose check-uv check-uv-verbose lock install update build \
format lint ruff-format ruff-lint pyright mypy pylint plxt plxt-format plxt-lint \
rules rules-claude-standalone up-kit-configs ukc check-config-sync ccs check-keyword-only cko fix-keyword-only fko subject-grant sgr check-hub-layering chl check-rich-imports cri check-actions-allowlist caa check-log-calls clc check-rules check-urls cu insert-skeleton \
drift-plan dp drift-check dc drift-ack da \
cleanderived cleanenv cleanall \
test test-xdist t test-quiet tq test-with-prints tp test-inference ti \
test-llm tl test-img-gen tg test-extract te codex-tests gha-tests \
store-test-durations std store-test-durations-force stdf \
run-all-tests run-manual-trigger-gha-tests run-gha_disabled-tests \
validate v check c cc agent-check agent-test agent-test-debug atd api-agent-check api-agent-test \
test-durations td test-durations-serial tds test-time tt test-time-serial tts \
merge-check-ruff-lint merge-check-ruff-format merge-check-mypy merge-check-pyright merge-check-plxt-format merge-check-plxt-lint \
li check-unused-imports fix-unused-imports check-TODOs check-uv \
docs docs-check docs-serve-versioned docs-list docs-deploy docs-deploy-stable docs-deploy-specific-version-pre-release docs-delete \
generate-mthds-schema generate-mthds-schema-quiet gms check-mthds-schema cms \
generate-corpus-vocabulary generate-corpus-vocabulary-quiet \
check-ledger cl check-migration-schemas cmig up-migration-schemas up-migration-schemas-force umig umigf \
generate-error-registry generate-error-registry-quiet ger check-error-registry cer \
generate-error-identity generate-error-identity-quiet gei \
up \
test-count check-test-badge \
ts-toolchain test-ts-gates ttg \
serve-graph serve-graph-bg stop-graph-server view-graph sg vg \
docs-deploy-root
all help:
@echo "$$HELP"
##########################################################################################
### SETUP
##########################################################################################
# Quiet check-uv: only shows output if uv is missing (needs install)
check-uv:
@command -v uv >/dev/null 2>&1 || { \
echo ""; \
echo "=== [$(PROJECT_NAME)] ===== (check-uv) ====== Ensuring uv ≥ $(UV_MIN_VERSION) =========="; \
echo "uv not found – installing latest …"; \
curl -LsSf https://astral.sh/uv/install.sh | sh; \
}
@uv self update >/dev/null 2>&1 || true
# Verbose check-uv: always shows output (for setup commands)
check-uv-verbose:
$(call PRINT_TITLE,"Ensuring uv ≥ $(UV_MIN_VERSION)")
@command -v uv >/dev/null 2>&1 || { \
echo "uv not found – installing latest …"; \
curl -LsSf https://astral.sh/uv/install.sh | sh; \
}
@uv self update >/dev/null 2>&1 || true
# Quiet env: only shows output if venv needs to be created
env: check-uv
@if [ ! -d "$(VIRTUAL_ENV)" ]; then \
echo ""; \
echo "=== [$(PROJECT_NAME)] ===== (env) ====== Creating virtual environment ================="; \
echo "Creating Python virtual env in \`${VIRTUAL_ENV}\`"; \
uv venv "$(VIRTUAL_ENV)" --python $(PYTHON_VERSION); \
echo "Using Python: $$($(VENV_PYTHON) --version) from $$(readlink $(VENV_PYTHON) 2>/dev/null || echo $(VENV_PYTHON))"; \
fi
# Verbose env: always shows output (for setup commands like install, lock, update)
env-verbose: check-uv-verbose
$(call PRINT_TITLE,"Creating virtual environment")
@if [ ! -d "$(VIRTUAL_ENV)" ]; then \
echo "Creating Python virtual env in \`${VIRTUAL_ENV}\`"; \
uv venv "$(VIRTUAL_ENV)" --python $(PYTHON_VERSION); \
else \
echo "Python virtual env already exists in \`${VIRTUAL_ENV}\`"; \
fi
@echo "Using Python: $$($(VENV_PYTHON) --version) from $$(readlink $(VENV_PYTHON) 2>/dev/null || echo $(VENV_PYTHON))"
install: env-verbose
$(call PRINT_TITLE,"Installing dependencies")
@. "$(VIRTUAL_ENV)/bin/activate" && \
uv sync --all-extras && \
echo "Installed Pipelex dependencies in ${VIRTUAL_ENV} with all extras.";
@$(MAKE) --silent regenerate-test-models-quiet
lock: env
$(call PRINT_TITLE,"Resolving dependencies without update")
@uv lock && \
echo uv lock without update;
plxt: env ## Rebuild and reinstall plxt CLI from local vscode-pipelex source
$(call PRINT_TITLE,"Reinstalling plxt from source")
@. "$(VIRTUAL_ENV)/bin/activate" && \
uv sync --all-extras --reinstall-package pipelex-tools && \
echo "Reinstalled plxt in ${VIRTUAL_ENV}";
update: env
$(call PRINT_TITLE,"Updating all dependencies")
@uv lock --upgrade && \
uv sync --all-extras && \
echo "Updated dependencies in ${VIRTUAL_ENV}";
validate: env
$(call PRINT_TITLE,"Running setup sequence")
$(VENV_PIPELEX) validate --all
build: env
$(call PRINT_TITLE,"Building the wheels")
@uv build
rules: env
$(call PRINT_TITLE,"Installing agent rules for contributing to Pipelex")
$(VENV_PIPELEX_DEV) kit rules --set all
rules-claude-standalone: env
$(call PRINT_TITLE,"Installing standalone CLAUDE.md with the full ruleset for contributors without the Pipelex workspace")
$(VENV_PIPELEX_DEV) kit rules --set standalone --targets claude
check-rules: env
$(call PRINT_TITLE,"Checking installed agent rules against templates")
$(VENV_PIPELEX_DEV) check-rules --quiet
check-urls: env
$(call PRINT_TITLE,"Checking URLs in pipelex/urls.py for broken links")
$(VENV_PIPELEX_DEV) check-urls --quiet
cu: env
$(call PRINT_TITLE,"Checking URLs in pipelex/urls.py for broken links with detailed output")
$(VENV_PIPELEX_DEV) check-urls
# Kit configs are mirrored from .pipelex/ by the pipelex-dev CLI, which derives its
# exclude list from the single source of truth in pipelex/kit/paths.py — the same sets
# `make check-config-sync` enforces, so a sync is always followed by a passing check.
# The api/ server serves the models of its own vendored copy of the kit's inference tree,
# so the same step carries a kit change there too, keeping the server's own choices (its
# backend switches, its x_custom deck files); `make -C api kit-check`, part of the gate,
# fails a change that skipped it. The script only imports pipelex, so the root venv runs it.
up-kit-configs: env
$(call PRINT_TITLE,"Updating kit configs from .pipelex/")
$(VENV_PIPELEX_DEV) sync-kit-configs
$(call PRINT_TITLE,"Re-syncing the vendored inference tree of the api/ server from the kit")
$(VENV_PYTHON) api/scripts/sync_vendored_kit.py api/.pipelex
ukc: up-kit-configs
@echo "> done: ukc = up-kit-configs"
check-config-sync: env
$(call PRINT_TITLE,"Checking config sync between .pipelex and pipelex/kit/configs")
$(VENV_PIPELEX_DEV) check-config-sync --quiet
ccs: check-config-sync
@echo "> done: ccs = check-config-sync"
check-keyword-only: env
$(call PRINT_TITLE,"Enforcing the keyword-only-arguments convention across pipelex/ source")
$(VENV_PIPELEX_DEV) check-keyword-only --quiet
cko: check-keyword-only
@echo "> done: cko = check-keyword-only"
fix-keyword-only: env
$(call PRINT_TITLE,"Auto-fixing keyword-only-arguments violations across pipelex/ source")
$(VENV_PIPELEX_DEV) check-keyword-only --fix --quiet
$(VENV_RUFF) format . --config pyproject.toml
fko: fix-keyword-only
@echo "> done: fko = fix-keyword-only"
subject-grant: env
$(call PRINT_TITLE,"Recording a subject grant")
@if [ -z "$(FUNC)" ] || [ -z "$(RATIONALE)" ]; then \
echo 'Usage: make subject-grant FUNC="<relative_path>::<qualified_name>" RATIONALE="…"'; \
exit 1; \
fi
$(VENV_PIPELEX_DEV) subject-grant "$(FUNC)" --rationale "$(RATIONALE)"
sgr: subject-grant
@echo "> done: sgr = subject-grant"
check-hub-layering: env
$(call PRINT_TITLE,"Enforcing the runtime_hub / interpreter_hub layering boundary")
$(VENV_PIPELEX_DEV) check-hub-layering --quiet
chl: check-hub-layering
@echo "> done: chl = check-hub-layering"
check-rich-imports: env
$(call PRINT_TITLE,"Refusing module-level Rich imports and reaches outside pipelex/cli/")
$(VENV_PIPELEX_DEV) check-rich-imports --quiet
cri: check-rich-imports
@echo "> done: cri = check-rich-imports"
check-actions-allowlist: env
$(call PRINT_TITLE,"Refusing workflow actions the Actions allowlist does not name")
$(VENV_PIPELEX_DEV) check-actions-allowlist --quiet
caa: check-actions-allowlist
@echo "> done: caa = check-actions-allowlist"
# The revision the log-call baseline may only shrink from. Empty, the default, it is the merge base of HEAD and
# origin/dev, and the check says so when that does not resolve; CI sets it to the pull request's base.
LOG_CALL_BASELINE_REF ?=
check-log-calls: env
$(call PRINT_TITLE,"Holding log calls to the log-call conventions against the shrinking baseline")
$(VENV_PIPELEX_DEV) check-log-calls --quiet $(if $(LOG_CALL_BASELINE_REF),--against "$(LOG_CALL_BASELINE_REF)",--against-merge-base origin/dev)
clc: check-log-calls
@echo "> done: clc = check-log-calls"
drift-plan: env
$(VENV_PIPELEX_DEV) drift plan $(CONTRACT)
dp: drift-plan
@echo "> done: dp = drift-plan"
drift-check: env
$(call PRINT_TITLE,"Checking drift contracts — review obligations between code and docs")
$(VENV_PIPELEX_DEV) drift check --quiet
dc: drift-check
@echo "> done: dc = drift-check"
drift-ack: env
$(call PRINT_TITLE,"Recording drift ack")
@if [ -z "$(CONTRACT)" ] || [ -z "$(RATIONALE)" ]; then \
echo 'Usage: make drift-ack CONTRACT=<contract-id> RATIONALE="<real-catch|clean-pass|friction>: …" [BY=<reviewer>]'; \
exit 1; \
fi
$(VENV_PIPELEX_DEV) drift ack "$(CONTRACT)" --rationale "$(RATIONALE)" $(if $(BY),--by "$(BY)")
da: drift-ack
@echo "> done: da = drift-ack"
generate-mthds-schema: env
$(call PRINT_TITLE,"Generating MTHDS JSON Schema")
$(VENV_PIPELEX_DEV) generate-mthds-schema
generate-mthds-schema-quiet: env
$(VENV_PIPELEX_DEV) generate-mthds-schema --quiet
gms: generate-mthds-schema
@echo "> done: gms = generate-mthds-schema"
check-mthds-schema: env
$(call PRINT_TITLE,"Checking MTHDS JSON Schema is up-to-date")
$(VENV_PIPELEX_DEV) check-mthds-schema --quiet
cms: check-mthds-schema
@echo "> done: cms = check-mthds-schema"
# The corpus vocabulary is committed and ships in the wheel, so its freshness is gated by a unit
# test that regenerates it in memory and compares byte for byte — there is no `check-` twin here.
generate-corpus-vocabulary: env
$(call PRINT_TITLE,"Generating MTHDS Test Corpus vocabulary")
$(VENV_PIPELEX_DEV) generate-corpus-vocabulary
generate-corpus-vocabulary-quiet: env
$(VENV_PIPELEX_DEV) generate-corpus-vocabulary --quiet
check-ledger: env
$(call PRINT_TITLE,"Checking migration ledgers are legal and converge")
$(VENV_PIPELEX_DEV) check-ledger --quiet
cl: check-ledger
@echo "> done: cl = check-ledger"
check-migration-schemas: env
$(call PRINT_TITLE,"Checking configuration surfaces have accounted for their schema changes")
$(VENV_PIPELEX_DEV) check-migration-schemas --quiet
cmig: check-migration-schemas
@echo "> done: cmig = check-migration-schemas"
up-migration-schemas: env
$(call PRINT_TITLE,"Updating migration fingerprint and defaults goldens")
$(VENV_PIPELEX_DEV) update-migration-schemas
up-migration-schemas-force: env
$(call PRINT_TITLE,"Re-recording migration goldens over material the models lost")
$(VENV_PIPELEX_DEV) update-migration-schemas --force
umig: up-migration-schemas
@echo "> done: umig = up-migration-schemas"
umigf: up-migration-schemas-force
@echo "> done: umigf = up-migration-schemas-force"
generate-error-registry: env
$(call PRINT_TITLE,"Writing every file derived from the error registry")
$(VENV_PIPELEX_DEV) generate-error-registry
generate-error-registry-quiet: env
$(VENV_PIPELEX_DEV) generate-error-registry --quiet
ger: generate-error-registry
@echo "> done: ger = generate-error-registry"
check-error-registry: env
$(call PRINT_TITLE,"Checking the error registry and its derived files")
$(VENV_PIPELEX_DEV) check-error-registry
cer: check-error-registry
@echo "> done: cer = check-error-registry"
generate-error-identity: env
$(call PRINT_TITLE,"Regenerating the PipelexError wire-identity snapshot")
$(VENV_PIPELEX_DEV) generate-error-identity
generate-error-identity-quiet: env
$(VENV_PIPELEX_DEV) generate-error-identity --quiet
gei: generate-error-identity
@echo "> done: gei = generate-error-identity"
sync-main-config: env
$(call PRINT_TITLE,"Syncing main config to kit and project configs")
$(VENV_PIPELEX_DEV) sync-main-config --quiet
smc: sync-main-config
@echo "> done: smc = sync-main-config"
smc-dry: env
$(call PRINT_TITLE,Previewing main config sync - dry run)
$(VENV_PIPELEX_DEV) sync-main-config --dry-run
# Support PROF as shorthand for TEST_PROFILE
ifdef PROF
TEST_PROFILE := $(PROF)
endif
TEST_PROFILE ?= dev
regenerate-test-models: env
$(call PRINT_TITLE,"Regenerating test model fixtures")
$(VENV_PIPELEX_DEV) preprocess-test-models --generate-fixtures --profile $(TEST_PROFILE)
rtm: regenerate-test-models
@echo "> done: rtm = regenerate-test-models"
regenerate-test-models-quiet: env
$(call PRINT_TITLE,"Regenerating test model fixtures")
@$(VENV_PIPELEX_DEV) preprocess-test-models --generate-fixtures --profile $(TEST_PROFILE) > /dev/null 2>&1
rtm-full: env
$(call PRINT_TITLE,"Regenerating test model fixtures with full profile")
$(VENV_PIPELEX_DEV) preprocess-test-models --generate-fixtures --profile full
insert-skeleton:
@if [ ! -d $(SKELETON_DIR) ]; then \
echo "Error: Skeleton directory $(SKELETON_DIR) not found"; \
exit 1; \
fi
@cp -rn $(SKELETON_DIR). .
@echo "Skeleton files inserted from $(SKELETON_DIR)"
##########################################################################################
### CLEANING
##########################################################################################
cleanderived:
$(call PRINT_TITLE,"Erasing derived files and directories")
@find . -name '.coverage' -delete && \
find . -wholename '**/*.pyc' -delete && \
find . -type d -wholename '__pycache__' -exec rm -rf {} + && \
find . -type d -wholename './.cache' -exec rm -rf {} + && \
find . -type d -wholename './.mypy_cache' -exec rm -rf {} + && \
find . -type d -wholename './.ruff_cache' -exec rm -rf {} + && \
find . -type d -wholename '.pytest_cache' -exec rm -rf {} + && \
find . -type d -wholename '**/.pytest_cache' -exec rm -rf {} + && \
find . -type d -wholename './logs/*.log' -exec rm -rf {} + && \
find . -type d -wholename './.reports/*' -exec rm -rf {} + && \
rm -f tests/integration/pipelex/fixtures/_generated_model_sets.py && \
rm -f .pipelex-dev/model_availability.json && \
rm -rf derived/ && \
rm -rf .ts-toolchain/ && \
echo "Cleaned up derived files and directories";
cleanenv:
$(call PRINT_TITLE,"Erasing virtual environment")
rm -rf "$(VIRTUAL_ENV)" && \
echo "Cleaned up virtual env";
cleanconfig:
$(call PRINT_TITLE,"Erasing config files and directories")
@find . -type d -wholename './.pipelex' -exec rm -rf {} + && \
echo "Cleaned up .pipelex";
cleanall: cleanderived cleanenv cleanconfig
@echo "Cleaned up all derived files and directories";
##########################################################################################
### TESTING
##########################################################################################
codex-tests: env
$(call PRINT_TITLE,"Unit testing for Codex")
@echo "• Regenerating test model fixtures with ci profile"
$(VENV_PIPELEX_DEV) preprocess-test-models --generate-fixtures --profile ci
@echo "• Running unit tests for Codex (excluding inference and codex_disabled)"
$(VENV_PYTEST) -n auto --exitfirst -m "(dry_runnable or not inference) and not (pipelex_api or codex_disabled)" || [ $$? = 5 ]
# SPLITS/GROUP thread pytest-split through for CI sharding: each shard runs one
# GROUP of the tests, balanced by the committed .test_durations file, and still
# uses -n auto within the shard. Both unset (local runs) => the $(if ...) expands
# to nothing and the whole suite runs as before.
# Refresh .test_durations: the per-test timing map pytest-split uses to balance
# the 8 CI shards. The default is incremental — it collects (a few seconds),
# measures ONLY the tests missing from the map, and leaves recorded values alone.
# That is the whole game: measured against the real split, a map with stale
# VALUES but complete coverage costs ~7% of shard balance, while one with current
# values and weeks of missing entries costs >50%, because pytest-split imputes an
# unknown node id at the suite MEAN (~0.25s) when the median test is ~0.002s.
# A post-pass prunes entries whose test file is gone (making the
# tests/unit/repo/test_test_durations_paths.py gate self-healing) and keeps any
# stored value that has not meaningfully moved, so the release diff stays small
# enough for automated reviewers to read. See docs/contribute/test-duration-map.md.
store-test-durations: env
$(call PRINT_TITLE,"Refreshing test durations for pytest-split shard balancing")
@echo "• Regenerating test model fixtures with ci profile"
$(VENV_PIPELEX_DEV) preprocess-test-models --generate-fixtures --profile ci
$(VENV_PIPELEX_DEV) store-test-durations --markers $(GHA_PYTEST_MARKERS)
std: store-test-durations
# Re-measure every test rather than only the missing ones. Worth it when the
# machine or the suite changed enough that recorded values are no longer
# comparable to each other; otherwise the incremental target is the one to use.
store-test-durations-force: env
$(call PRINT_TITLE,"Re-measuring ALL test durations for pytest-split shard balancing")
@echo "• Regenerating test model fixtures with ci profile"
$(VENV_PIPELEX_DEV) preprocess-test-models --generate-fixtures --profile ci
$(VENV_PIPELEX_DEV) store-test-durations --markers $(GHA_PYTEST_MARKERS) --force
stdf: store-test-durations-force
gha-tests: env
$(call PRINT_TITLE,"Unit testing for github actions")
@echo "• Regenerating test model fixtures with ci profile"
$(VENV_PIPELEX_DEV) preprocess-test-models --generate-fixtures --profile ci
@echo "• Running unit tests for github actions (excluding inference and gha_disabled)"
$(VENV_PYTEST) -n auto --dist=worksteal $(if $(SPLITS),--splits $(SPLITS) --group $(GROUP)) --max-worker-restart=2 --timeout=180 --timeout-method=thread --tb=line -p no:cacheprovider --no-header -m $(GHA_PYTEST_MARKERS) || [ $$? = 5 ]
# --------------------------------------------------------------------------------------
# The TypeScript emission gates. These are the two tests that need node, and they are the
# only ones that read the emitted TypeScript as TypeScript rather than as lines of text:
# `prettier --check` parses it and holds the byte-for-byte formatting the codegen stamp
# depends on, and the wire round-trip executes the emitted schema under a real zod. Both
# were written to skip when the toolchain is absent, which on a Python repo meant always
# — so three content defects reached review with the suite green. This target provisions
# the toolchain and sets PIPELEX_REQUIRE_TS_GATES, under which a missing binary is a
# failure instead of a skip. CI runs this same target, so the gates cannot silently lapse.
# --------------------------------------------------------------------------------------
ts-toolchain:
$(call PRINT_TITLE,"Provisioning the pinned node toolchain for the TypeScript emission gates")
@command -v node >/dev/null 2>&1 && command -v npm >/dev/null 2>&1 || { \
echo "The TypeScript emission gates need node >= 22.6 and npm on PATH — install them and retry."; \
exit 1; \
}
@mkdir -p "$(TS_TOOLCHAIN_DIR)"
@npm install --silent --no-audit --no-fund --prefix "$(TS_TOOLCHAIN_DIR)" \
prettier@$(TS_TOOLCHAIN_PRETTIER_VERSION) zod@$(TS_TOOLCHAIN_ZOD_VERSION)
@echo "• prettier $$("$(TS_TOOLCHAIN_DIR)/node_modules/.bin/prettier" --version), zod $(TS_TOOLCHAIN_ZOD_VERSION), node $$(node --version)"
test-ts-gates: env ts-toolchain
$(call PRINT_TITLE,"Running the TypeScript emission gates against the pinned node toolchain")
@PATH="$(TS_TOOLCHAIN_DIR)/node_modules/.bin:$$PATH" \
PIPELEX_REQUIRE_TS_GATES=1 \
PIPELEX_ZOD_PACKAGE="$(TS_TOOLCHAIN_DIR)/node_modules/zod" \
$(VENV_PYTEST) tests/unit/pipelex/codegen --no-header -p no:cacheprovider -q --timeout=180 --timeout-method=thread
ttg: test-ts-gates
@echo "> done: ttg = test-ts-gates"
run-all-tests: env
$(call PRINT_TITLE,"Running all unit tests")
@echo "• Regenerating test model fixtures"
$(VENV_PIPELEX_DEV) preprocess-test-models --generate-fixtures --profile $(TEST_PROFILE)
@echo "• Running all unit tests"
$(VENV_PYTEST) -n auto --exitfirst --quiet
run-manual-trigger-gha-tests: env
$(call PRINT_TITLE,"Running GHA tests")
@echo "• Regenerating test model fixtures with ci profile"
$(VENV_PIPELEX_DEV) preprocess-test-models --generate-fixtures --profile ci
@echo "• Running GHA unit tests for inference, llm, and not gha_disabled"
$(VENV_PYTEST) --exitfirst --quiet -m "not (gha_disabled or pipelex_api) and (inference or llm)" || [ $$? = 5 ]
run-gha_disabled-tests: env
$(call PRINT_TITLE,"Running GHA disabled tests")
@echo "• Running GHA disabled unit tests"
$(VENV_PYTEST) --exitfirst --quiet -m "gha_disabled" || [ $$? = 5 ]
test: env
$(call PRINT_TITLE,"Unit testing without prints but displaying logs via pytest for WARNING level and above")
@echo "• Running unit tests"
@if [ -n "$(TEST)" ]; then \
if [ "$(TEST)" = "LF" ] || [ "$(TEST)" = "lf" ]; then \
$(VENV_PYTEST) -s -m $(USUAL_PYTEST_MARKERS) -o log_cli=true -o log_level=WARNING --lf $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
else \
$(VENV_PYTEST) -s -m $(USUAL_PYTEST_MARKERS) -o log_cli=true -o log_level=WARNING -k "$(TEST)" $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi; \
else \
$(VENV_PYTEST) -s -m $(USUAL_PYTEST_MARKERS) -o log_cli=true -o log_level=WARNING $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi
test-xdist: env
$(call PRINT_TITLE,"Unit testing without prints but displaying logs via pytest for WARNING level and above")
@echo "• Running unit tests"
@if [ -n "$(TEST)" ]; then \
if [ "$(TEST)" = "LF" ] || [ "$(TEST)" = "lf" ]; then \
$(VENV_PYTEST) -n auto -m $(USUAL_PYTEST_MARKERS) -o log_level=WARNING --lf $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
else \
$(VENV_PYTEST) -n auto -m $(USUAL_PYTEST_MARKERS) -o log_level=WARNING -k "$(TEST)" $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi; \
else \
$(VENV_PYTEST) -n auto -m $(USUAL_PYTEST_MARKERS) -o log_level=WARNING $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi
t: test-xdist
@echo "> done: t = test-xdist"
test-quiet: env
$(call PRINT_TITLE,"Unit testing without prints but displaying logs via pytest for WARNING level and above")
@echo "• Running unit tests"
@if [ -n "$(TEST)" ]; then \
if [ "$(TEST)" = "LF" ] || [ "$(TEST)" = "lf" ]; then \
$(VENV_PYTEST) -m $(USUAL_PYTEST_MARKERS) -o log_cli=true -o log_level=WARNING --lf $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
else \
$(VENV_PYTEST) -m $(USUAL_PYTEST_MARKERS) -o log_cli=true -o log_level=WARNING -k "$(TEST)" $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi; \
else \
$(VENV_PYTEST) -m $(USUAL_PYTEST_MARKERS) -o log_cli=true -o log_level=WARNING $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi
tq: test-quiet
@echo "> done: tq = test-quiet"
test-with-prints: env
$(call PRINT_TITLE,"Unit testing with prints and our rich logs")
@echo "• Running unit tests"
@if [ -n "$(TEST)" ]; then \
if [ "$(TEST)" = "LF" ] || [ "$(TEST)" = "lf" ]; then \
$(VENV_PYTEST) -s -m $(USUAL_PYTEST_MARKERS) --lf $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
else \
$(VENV_PYTEST) -s -m $(USUAL_PYTEST_MARKERS) -k "$(TEST)" $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi; \
else \
$(VENV_PYTEST) -s -m $(USUAL_PYTEST_MARKERS) $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi
tp: test-with-prints
@echo "> done: tp = test-with-prints"
tb: env
$(call PRINT_TITLE,"Unit testing a simple boot")
@echo "• Running unit test test_boot"
$(VENV_PYTEST) -s -m $(USUAL_PYTEST_MARKERS) -k "test_boot" $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,)));
test-inference-with-prints: env
$(call PRINT_TITLE,"Unit testing")
@if [ "$(origin TEST_PROFILE)" = "command line" ] || [ "$(origin PROF)" = "command line" ]; then \
echo "• Regenerating test model fixtures with profile: $(TEST_PROFILE)"; \
$(VENV_PIPELEX_DEV) preprocess-test-models --generate-fixtures --profile $(TEST_PROFILE); \
fi
@if [ -n "$(TEST)" ]; then \
if [ "$(TEST)" = "LF" ] || [ "$(TEST)" = "lf" ]; then \
$(VENV_PYTEST) --pipe-run-mode live -m "inference" -s -rfE --lf $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
else \
$(VENV_PYTEST) --pipe-run-mode live -m "inference" -s -rfE -k "$(TEST)" $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi; \
else \
$(VENV_PYTEST) --pipe-run-mode live -m "inference" -s -rfE $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi
test-inference-fast: env
$(call PRINT_TITLE,"Unit testing")
@if [ "$(origin TEST_PROFILE)" = "command line" ] || [ "$(origin PROF)" = "command line" ]; then \
echo "• Regenerating test model fixtures with profile: $(TEST_PROFILE)"; \
$(VENV_PIPELEX_DEV) preprocess-test-models --generate-fixtures --profile $(TEST_PROFILE); \
fi
@if [ -n "$(TEST)" ]; then \
if [ "$(TEST)" = "LF" ] || [ "$(TEST)" = "lf" ]; then \
$(VENV_PYTEST) -n auto --pipe-run-mode live -m "inference" -s -rfE --lf $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
else \
$(VENV_PYTEST) -n auto --pipe-run-mode live -m "inference" -s -rfE -k "$(TEST)" $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi; \
else \
$(VENV_PYTEST) -n auto --pipe-run-mode live -m "inference" -s -rfE $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi
tip: test-inference-with-prints
@echo "> done: tip = test-inference-with-prints"
ti: test-inference-fast
@echo "> done: ti-fast = test-inference-fast"
ti-dry: env
$(call PRINT_TITLE,"Unit testing")
@if [ -n "$(TEST)" ]; then \
if [ "$(TEST)" = "LF" ] || [ "$(TEST)" = "lf" ]; then \
$(VENV_PYTEST) --pipe-run-mode dry --exitfirst -m "inference" -s -rfE --lf $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
else \
$(VENV_PYTEST) --pipe-run-mode dry --exitfirst -m "inference" -s -rfE -k "$(TEST)" $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi; \
else \
$(VENV_PYTEST) --pipe-run-mode dry --exitfirst -m "inference" -s -rfE $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi
test-llm: env
$(call PRINT_TITLE,"Unit testing LLM")
@if [ "$(origin TEST_PROFILE)" = "command line" ] || [ "$(origin PROF)" = "command line" ]; then \
echo "• Regenerating test model fixtures with profile: $(TEST_PROFILE)"; \
$(VENV_PIPELEX_DEV) preprocess-test-models --generate-fixtures --profile $(TEST_PROFILE); \
fi
@if [ -n "$(TEST)" ]; then \
if [ "$(TEST)" = "LF" ] || [ "$(TEST)" = "lf" ]; then \
$(VENV_PYTEST) --pipe-run-mode live --exitfirst -m "llm" -s --lf $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
else \
$(VENV_PYTEST) --pipe-run-mode live --exitfirst -m "llm" -s -k "$(TEST)" $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi; \
else \
$(VENV_PYTEST) --pipe-run-mode live --exitfirst -m "llm" -s $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi
tl: test-llm
@echo "> done: tl = test-llm"
test-extract: env
$(call PRINT_TITLE,"Unit testing Extract")
@if [ "$(origin TEST_PROFILE)" = "command line" ] || [ "$(origin PROF)" = "command line" ]; then \
echo "• Regenerating test model fixtures with profile: $(TEST_PROFILE)"; \
$(VENV_PIPELEX_DEV) preprocess-test-models --generate-fixtures --profile $(TEST_PROFILE); \
fi
@if [ -n "$(TEST)" ]; then \
if [ "$(TEST)" = "LF" ] || [ "$(TEST)" = "lf" ]; then \
$(VENV_PYTEST) --pipe-run-mode live --exitfirst -m "extract" -s --lf $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
else \
$(VENV_PYTEST) --pipe-run-mode live --exitfirst -m "extract" -s -k "$(TEST)" $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi; \
else \
$(VENV_PYTEST) --pipe-run-mode live --exitfirst -m "extract" -s $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi
te: test-extract
@echo "> done: te = test-extract"
test-img-gen: env
$(call PRINT_TITLE,"Unit testing Image Generation")
@if [ "$(origin TEST_PROFILE)" = "command line" ] || [ "$(origin PROF)" = "command line" ]; then \
echo "• Regenerating test model fixtures with profile: $(TEST_PROFILE)"; \
$(VENV_PIPELEX_DEV) preprocess-test-models --generate-fixtures --profile $(TEST_PROFILE); \
fi
@if [ -n "$(TEST)" ]; then \
if [ "$(TEST)" = "LF" ] || [ "$(TEST)" = "lf" ]; then \
$(VENV_PYTEST) --pipe-run-mode live --exitfirst -m "img_gen" -s --lf $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
else \
$(VENV_PYTEST) --pipe-run-mode live --exitfirst -m "img_gen" -s -k "$(TEST)" $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi; \
else \
$(VENV_PYTEST) --pipe-run-mode live --exitfirst -m "img_gen" -s $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi
tg: test-img-gen
@echo "> done: tg = test-img-gen"
test-pipelex-api: env
$(call PRINT_TITLE,"Unit testing")
@if [ -n "$(TEST)" ]; then \
if [ "$(TEST)" = "LF" ] || [ "$(TEST)" = "lf" ]; then \
$(VENV_PYTEST) --exitfirst -m "pipelex_api" -s --lf $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
else \
$(VENV_PYTEST) --exitfirst -m "pipelex_api" -s -k "$(TEST)" $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi; \
else \
$(VENV_PYTEST) --exitfirst -m "pipelex_api" -s $(if $(filter 1,$(VERBOSE)),-v,$(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,))); \
fi
ta: test-pipelex-api
@echo "> done: ta = test-pipelex-api"
agent-test: env
@echo "• Running unit tests..."
@tmpfile=$$(mktemp); \
$(call WAIT_WITH_HEARTBEAT,$(VENV_PYTEST) -n auto -m $(USUAL_PYTEST_MARKERS) -o log_level=WARNING --tb=short -q > "$$tmpfile" 2>&1,agent-test); \
if [ $$exit_code -ne 0 ]; then grep -vE '\[\s*[0-9]+%\]\s*$$' "$$tmpfile"; fi; \
rm -f "$$tmpfile"; \
if [ $$exit_code -eq 0 ]; then echo "• All tests passed."; fi; \
exit $$exit_code
@$(MAKE) --no-print-directory api-agent-test
# The Pipelex API server is the `api/` workspace member (see api/CLAUDE.md). It keeps its own
# environment (`api/.venv`, provisioned by its own `install` on the first run) and its own gates, which
# the root `agent-check` and `agent-test` run after pipelex's: the server runs the library of the same
# commit, so a library change that breaks the server, moves its OpenAPI artifact or leaves its vendored
# inference tree behind fails here, in the same change.
api-agent-check:
@$(MAKE) --no-print-directory -C api agent-check
api-agent-test:
@$(MAKE) --no-print-directory -C api agent-test
# Debug variant of agent-test for when the suite hangs or fails opaquely.
# Use this instead of agent-test when:
# - a prior `make agent-test` hung (or got killed) without a verdict
# - failures show xdist worker crashes / "node down" noise
# - you need to see what's actually happening during the run
# Differences vs agent-test:
# - pkill stale `pytest` processes first (zombies from
# prior hung runs compound contention and cause more hangs)
# - outer wall-clock `timeout` so fixture-teardown hangs and xdist
# worker-replace loops can't run forever (`pytest --timeout` is per-test only)
# - direct file redirect — `tail -f $(DEBUG_LOG)` in another shell for live progress
# - `-v` (not `-q`) so each test name lands in the log as it runs
# Tunable: DEBUG_TIMEOUT (outer wall-clock seconds, default 480), DEBUG_LOG (log path).
# Full playbook: docs/agents/debugging-hanging-pytest-runs.md
DEBUG_TIMEOUT ?= 480
DEBUG_LOG ?= /tmp/pytest-agent-test-debug.log
TIMEOUT_CMD := $(shell command -v timeout 2>/dev/null || command -v gtimeout 2>/dev/null)
agent-test-debug: env
@if [ -z "$(TIMEOUT_CMD)" ]; then \
echo "✘ Neither 'timeout' nor 'gtimeout' is installed."; \
echo " On macOS: brew install coreutils"; \
echo " The outer wall-clock cap is the whole point of this target — install before using."; \
exit 1; \
fi
@echo "• Cleaning stale pytest processes..."
@pkill -9 -f "pytest" 2>/dev/null || true
@sleep 1
@echo "• Running with outer timeout=$(DEBUG_TIMEOUT)s, log: $(DEBUG_LOG)"
@echo " Live progress: tail -f $(DEBUG_LOG)"
@$(TIMEOUT_CMD) $(DEBUG_TIMEOUT) $(VENV_PYTEST) -n auto --timeout=120 --timeout-method=thread \
-m $(USUAL_PYTEST_MARKERS) -o log_level=WARNING --tb=short -v \
> $(DEBUG_LOG) 2>&1; \
exit_code=$$?; \
if [ $$exit_code -eq 124 ]; then \
echo ""; \
echo "TIMEOUT: outer cap hit at $(DEBUG_TIMEOUT)s — fixture teardown or xdist worker-replace loop suspected."; \
echo " Tail of log:"; \
tail -30 $(DEBUG_LOG) | sed 's/^/ /'; \
echo " Full log: $(DEBUG_LOG)"; \
echo " Playbook: docs/agents/debugging-hanging-pytest-runs.md"; \
elif [ $$exit_code -ne 0 ]; then \
echo ""; \
echo "FAIL: tests failed (exit $$exit_code). Unique failed tests:"; \
grep -oE "FAILED tests/[^ ]+" $(DEBUG_LOG) | sort -u | sed 's/^/ /'; \
echo ""; \
echo " Full log: $(DEBUG_LOG)"; \
echo " Tip: grep failures by error class name, not formatted message —"; \
echo " grep -B 2 -A 10 'YourErrorClass' $(DEBUG_LOG)"; \
echo " If failures show xdist worker crashes ('node down'), re-run that"; \
echo " slice serially: .venv/bin/pytest --timeout=60 -q tests/integration/.../"; \
echo " Playbook: docs/agents/debugging-hanging-pytest-runs.md"; \
else \
echo "PASS: all tests green. Log: $(DEBUG_LOG)"; \
fi; \
exit $$exit_code
atd: agent-test-debug
@echo "> done: atd = agent-test-debug"
##########################################################################################
### TEST DIAGNOSTICS
##########################################################################################
TOP ?= 30
MIN ?= 0.5
test-durations: env
$(call PRINT_TITLE,"Slowest tests - xdist - top=$(TOP) min=$(MIN)s")
$(VENV_PYTEST) -n auto -m $(USUAL_PYTEST_MARKERS) -o log_level=WARNING --durations=$(TOP) --durations-min=$(MIN) --tb=no -q
td: test-durations
@echo "> done: td = test-durations"
test-durations-serial: env
$(call PRINT_TITLE,"Slowest tests - serial - top=$(TOP) min=$(MIN)s")
$(VENV_PYTEST) -p no:xdist -m $(USUAL_PYTEST_MARKERS) -o log_level=WARNING --durations=$(TOP) --durations-min=$(MIN) --tb=no -q
tds: test-durations-serial
@echo "> done: tds = test-durations-serial"
test-time: env
$(call PRINT_TITLE,"Timed test run - xdist")
@time $(VENV_PYTEST) -n auto -m $(USUAL_PYTEST_MARKERS) -o log_level=WARNING --tb=no -q --no-header 2>&1 | tail -1
tt: test-time
@echo "> done: tt = test-time"
test-time-serial: env
$(call PRINT_TITLE,"Timed test run - serial")
@time $(VENV_PYTEST) -p no:xdist -m $(USUAL_PYTEST_MARKERS) -o log_level=WARNING --tb=no -q --no-header 2>&1 | tail -1
tts: test-time-serial
@echo "> done: tts = test-time-serial"
cov: env
$(call PRINT_TITLE,"Unit testing with coverage")
@echo "• Running unit tests with coverage"
@if [ -n "$(TEST)" ]; then \
if [ "$(TEST)" = "LF" ] || [ "$(TEST)" = "lf" ]; then \
$(VENV_PYTEST) --cov=$(if $(PKG),$(PKG),pipelex) --lf $(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,-v)); \
else \
$(VENV_PYTEST) --cov=$(if $(PKG),$(PKG),pipelex) -k "$(TEST)" $(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,-v)); \
fi; \
else \
$(VENV_PYTEST) --cov=$(if $(PKG),$(PKG),pipelex) $(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,-v)); \
fi
cov-missing: env
$(call PRINT_TITLE,"Unit testing with coverage and missing lines")
@echo "• Running unit tests with coverage and missing lines"
@if [ -n "$(TEST)" ]; then \
if [ "$(TEST)" = "LF" ] || [ "$(TEST)" = "lf" ]; then \
$(VENV_PYTEST) --cov=$(if $(PKG),$(PKG),pipelex) --cov-report=term-missing --lf $(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,-v)); \
else \
$(VENV_PYTEST) --cov=$(if $(PKG),$(PKG),pipelex) --cov-report=term-missing -k "$(TEST)" $(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,-v)); \
fi; \
else \
$(VENV_PYTEST) --cov=$(if $(PKG),$(PKG),pipelex) --cov-report=term-missing $(if $(filter 2,$(VERBOSE)),-vv,$(if $(filter 3,$(VERBOSE)),-vvv,-v)); \
fi
cm: cov-missing
@echo "> done: cm = cov-missing"
##########################################################################################
### FORMATTING, LINTING, AND TYPECHECKING
##########################################################################################
ruff-format: env
$(call PRINT_TITLE,"Formatting with ruff")
$(VENV_RUFF) format . --config pyproject.toml
ruff-lint: env
$(call PRINT_TITLE,"Linting with ruff")
$(VENV_RUFF) check . --fix --config pyproject.toml
plxt-format: env
$(call PRINT_TITLE,"Formatting MTHDS/TOML with plxt")
$(VENV_PLXT) fmt
# plxt validates .mthds files against the locally generated schema (see .pipelex/plxt.toml),
# so make sure it exists and is fresh before linting.
plxt-lint: env generate-mthds-schema-quiet
$(call PRINT_TITLE,"Linting MTHDS/TOML with plxt")
$(VENV_PLXT) lint
format: ruff-format plxt-format
@echo "> done: format = ruff-format plxt-format"
lint: ruff-lint plxt-lint
@echo "> done: lint = ruff-lint plxt-lint"
pyright: env
$(call PRINT_TITLE,"Typechecking with pyright")
@echo "$(VENV_PYRIGHT) --pythonpath $(VENV_PYTHON) --project pyproject.toml"
$(call RUN_WITH_HEARTBEAT,$(VENV_PYRIGHT) --pythonpath $(VENV_PYTHON) --project pyproject.toml,pyright)
mypy: env
$(call PRINT_TITLE,"Typechecking with mypy")
@echo "$(VENV_MYPY) --config-file pyproject.toml"
$(call RUN_WITH_HEARTBEAT,$(VENV_MYPY) --config-file pyproject.toml,mypy)
pylint: env
$(call PRINT_TITLE,"Linting with pylint")
@echo "$(VENV_PYLINT) --rcfile pyproject.toml pipelex tests"
$(call RUN_WITH_HEARTBEAT,$(VENV_PYLINT) --rcfile pyproject.toml pipelex tests,pylint)
##########################################################################################
### MERGE CHECKS
##########################################################################################
merge-check-ruff-format: env
$(call PRINT_TITLE,"Formatting with ruff")
$(VENV_RUFF) format --check . --config pyproject.toml
merge-check-ruff-lint: env check-unused-imports
$(call PRINT_TITLE,"Linting with ruff without fixing files")
$(VENV_RUFF) check . --config pyproject.toml
merge-check-pyright: env
$(call PRINT_TITLE,"Typechecking with pyright")
$(VENV_PYRIGHT) --pythonpath $(VENV_PYTHON) --project pyproject.toml $(if $(LINT_PYTHON_VERSION),--pythonversion $(LINT_PYTHON_VERSION))
merge-check-mypy: env
$(call PRINT_TITLE,"Typechecking with mypy")
$(VENV_MYPY) --config-file pyproject.toml $(if $(LINT_PYTHON_VERSION),--python-version $(LINT_PYTHON_VERSION))
merge-check-pylint: env
$(call PRINT_TITLE,"Linting with pylint")
$(VENV_PYLINT) --rcfile pyproject.toml .
merge-check-plxt-format: env
$(call PRINT_TITLE,"Checking MTHDS/TOML formatting with plxt")
$(VENV_PLXT) fmt --check
merge-check-plxt-lint: env generate-mthds-schema-quiet
$(call PRINT_TITLE,"Linting MTHDS/TOML with plxt")
$(VENV_PLXT) lint
##########################################################################################
### MISCELLANEOUS
##########################################################################################
check-unused-imports: env
$(call PRINT_TITLE,"Checking for unused imports without fixing")
$(VENV_RUFF) check --select=F401 --no-fix .
fix-unused-imports: env
$(call PRINT_TITLE,"Fixing unused imports")
$(VENV_RUFF) check --select=F401 --fix .
fui: fix-unused-imports
@echo "> done: fui = fix-unused-imports"
check-TODOs: env
$(call PRINT_TITLE,"Checking for TODOs")
@$(VENV_RUFF) check --select=TD -v .
##########################################################################################
### DOCUMENTATION
##########################################################################################
# Extract version from pyproject.toml for docs deployment
DOCS_VERSION := $(shell grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
SITE_DOMAIN := $(shell cat docs/CNAME 2>/dev/null | tr -d '[:space:]')
# Authoritative robots.txt for the domain root (docs.pipelex.com/robots.txt).
# Deployed by docs-deploy-root. Note: docs/robots.txt is a no-op — it only
# lands at /latest/robots.txt, which crawlers ignore per RFC 9309.
#
# Targeted Disallow: block versioned paths and non-content pages, allow
# everything else (root-level files like /sitemap.xml, /llms.txt are
# implicitly allowed).
define ROOT_ROBOTS_TXT
User-agent: *
Allow: /latest/
Allow: /sitemap.xml
Allow: /llms.txt
Allow: /llms-full.txt
Disallow: /0.
Disallow: /pre-release/
Disallow: /404.html
Sitemap: https://$(SITE_DOMAIN)/sitemap.xml
endef
export ROOT_ROBOTS_TXT
docs: env generate-error-registry-quiet
$(call PRINT_TITLE,"Serving documentation with mkdocs")
$(VENV_MKDOCS) serve -a 127.0.0.1:8000 -f "$(CURDIR)/mkdocs.yml" --watch "$(CURDIR)/docs" -s
docs-check: env generate-error-registry-quiet
$(call PRINT_TITLE,"Checking documentation build with mkdocs")
$(VENV_MKDOCS) build --strict
docs-serve-versioned: export PATH := $(VIRTUAL_ENV)/bin:$(PATH)
docs-serve-versioned: env generate-error-registry-quiet
$(call PRINT_TITLE,"Serving versioned documentation with mike")
$(VENV_MIKE) serve
docs-list: export PATH := $(VIRTUAL_ENV)/bin:$(PATH)
docs-list: env
$(call PRINT_TITLE,"Listing deployed documentation versions")
$(VENV_MIKE) list
docs-deploy: export PATH := $(VIRTUAL_ENV)/bin:$(PATH)
docs-deploy: env generate-error-registry-quiet
$(call PRINT_TITLE,"Deploying documentation version $(if $(VERSION),$(VERSION),$(DOCS_VERSION))")
$(VENV_MIKE) deploy $(if $(VERSION),$(VERSION),$(DOCS_VERSION))
docs-deploy-stable: export PATH := $(VIRTUAL_ENV)/bin:$(PATH)
docs-deploy-stable: env generate-error-registry-quiet
$(call PRINT_TITLE,"Deploying stable documentation $(DOCS_VERSION) with latest alias")
$(VENV_MIKE) deploy --push --update-aliases $(DOCS_VERSION) latest
$(VENV_MIKE) set-default --push latest
$(MAKE) docs-deploy-root
docs-deploy-specific-version-pre-release: export PATH := $(VIRTUAL_ENV)/bin:$(PATH)
docs-deploy-specific-version-pre-release: env generate-error-registry-quiet
$(call PRINT_TITLE,"Deploying documentation $(DOCS_VERSION) with pre-release alias")
$(VENV_MIKE) deploy --push --update-aliases $(DOCS_VERSION) pre-release
$(MAKE) docs-deploy-root
# Deploy root assets (404.html, robots.txt, index.html, sitemap.xml) to gh-pages.
# The root sitemap is generated from latest/sitemap.xml (not $(DOCS_VERSION)/) so
# that pre-release deploys don't overwrite it with pages not served at /latest/.
# Mike does NOT rewrite sitemap URLs for aliases — latest/sitemap.xml contains
# versioned URLs like /0.20.9/page/, identical to the version directory. The sed
# rewrites any semver path segment (including pre-release suffixes like -rc1) to /latest/.
# `pipelex-dev write-error-type-redirects` writes errors/<code>/index.html at the root for every
# error code latest/ documents, so that a problem's type URI, https://$(SITE_DOMAIN)/errors/<code>,
# reaches the code's page under /latest/ (docs/contribute/error-registry.md). While latest/ documents
# no code it writes no stub at all, so errors/ is staged only when the checkout holds it.
# WARNING: Do NOT insert comments inside the shell continuation chain below.
# Lines starting with # after a \ continuation become shell comments that silently
# truncate the command.
docs-deploy-root: env
ifeq ($(SITE_DOMAIN),)
$(error SITE_DOMAIN is empty — docs/CNAME is missing or blank. Cannot generate root assets with valid URLs)
endif
$(call PRINT_TITLE,"Deploying root assets to gh-pages")
@git fetch origin gh-pages:gh-pages 2>/dev/null || true; \
TMPDIR=$$(mktemp -d); \
trap "cd '$(CURDIR)'; git worktree remove '$$TMPDIR' 2>/dev/null || true; rm -rf '$$TMPDIR'" EXIT; \
git worktree add "$$TMPDIR" gh-pages && \
cp docs/404.html "$$TMPDIR/404.html" && \
echo "$$ROOT_ROBOTS_TXT" > "$$TMPDIR/robots.txt" && \
sed 's/__SITE_DOMAIN__/$(SITE_DOMAIN)/g' docs/root-index.html > "$$TMPDIR/index.html" && \
sed 's|/[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*[^/]*/|/latest/|g' "$$TMPDIR/latest/sitemap.xml" > "$$TMPDIR/sitemap.xml" && \
if [ -f "$$TMPDIR/latest/llms.txt" ]; then cp "$$TMPDIR/latest/llms.txt" "$$TMPDIR/llms.txt"; fi && \
if [ -f "$$TMPDIR/latest/llms-full.txt" ]; then cp "$$TMPDIR/latest/llms-full.txt" "$$TMPDIR/llms-full.txt"; fi && \
$(VENV_PIPELEX_DEV) write-error-type-redirects --site-root "$$TMPDIR" --quiet && \
cd "$$TMPDIR" && \
git add 404.html robots.txt index.html sitemap.xml && \
(git add -A llms.txt llms-full.txt 2>/dev/null || true) && \
if [ -d errors ]; then git add -A errors; fi && \
(git diff --cached --quiet || git commit -m "Update root assets (404.html, robots.txt, index.html, sitemap.xml, llms.txt, error type redirects)") && \
git push origin gh-pages
docs-delete: export PATH := $(VIRTUAL_ENV)/bin:$(PATH)
docs-delete: env
ifndef VERSION
$(error VERSION is required. Usage: make docs-delete VERSION=x.y.z)
endif
$(call PRINT_TITLE,"Deleting documentation version $(VERSION)")
$(VENV_MIKE) delete --push $(VERSION)
##########################################################################################
### GRAPH VIEWER
##########################################################################################
GRAPH_SERVER_PORT ?= 8765
GRAPH_SERVER_DIR ?= temp/test_outputs
serve-graph:
$(call PRINT_TITLE,"Starting HTTP server for ReactFlow graphs on port $(GRAPH_SERVER_PORT)")
@pkill -f "python3 -m http.server $(GRAPH_SERVER_PORT)" 2>/dev/null || true
@echo "Serving $(GRAPH_SERVER_DIR) at http://localhost:$(GRAPH_SERVER_PORT)"
@echo "Press Ctrl+C to stop the server"
@cd "$(CURDIR)" && python3 -m http.server $(GRAPH_SERVER_PORT) --directory $(GRAPH_SERVER_DIR)
serve-graph-bg:
$(call PRINT_TITLE,"Starting HTTP server for ReactFlow graphs on port $(GRAPH_SERVER_PORT) (background)")
@pkill -f "python3 -m http.server $(GRAPH_SERVER_PORT)" 2>/dev/null || true
@cd "$(CURDIR)" && python3 -m http.server $(GRAPH_SERVER_PORT) --directory $(GRAPH_SERVER_DIR) &
@echo "Server running at http://localhost:$(GRAPH_SERVER_PORT)"
@echo "Run 'make stop-graph-server' to stop"
stop-graph-server:
$(call PRINT_TITLE,"Stopping graph viewer HTTP server")
@pkill -f "python3 -m http.server $(GRAPH_SERVER_PORT)" 2>/dev/null && echo "Server stopped" || echo "No server running on port $(GRAPH_SERVER_PORT)"
view-graph:
$(call PRINT_TITLE,"Opening ReactFlow graph viewer")
@pkill -f "python3 -m http.server $(GRAPH_SERVER_PORT)" 2>/dev/null || true
@cd "$(CURDIR)" && python3 -m http.server $(GRAPH_SERVER_PORT) --directory $(GRAPH_SERVER_DIR) &
@sleep 1
@open "http://localhost:$(GRAPH_SERVER_PORT)"
@echo "Server running at http://localhost:$(GRAPH_SERVER_PORT)"
@echo "Run 'make stop-graph-server' to stop"
sg: serve-graph
@echo "> done: sg = serve-graph"
vg: view-graph
@echo "> done: vg = view-graph"
##########################################################################################
### GRAPH UI ASSET SYNC (from mthds-ui)
##########################################################################################
##########################################################################################
### SHORTHANDS
##########################################################################################
c: check-keyword-only format lint pyright mypy
@echo "> done: c = check"
cc: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet generate-corpus-vocabulary-quiet c
@echo "> done: cc = cleanderived regenerate-test-models generate-mthds-schema generate-corpus-vocabulary format lint pyright mypy"
# `up-migration-schemas` is deliberately NOT part of this aggregate. Every other regenerator here
# rewrites a derived artifact from a live source; the migration head golden is a *proof obligation*
# the coverage gate reads, so folding it into a habitual bulk regeneration would let a removal be
# erased by muscle memory. Run `make umig` on purpose, and read its diff.
up: generate-mthds-schema-quiet generate-corpus-vocabulary-quiet up-kit-configs rules
@echo "> done: up = generate-mthds-schema generate-corpus-vocabulary up-kit-configs rules"
check: cleanderived regenerate-test-models-quiet generate-mthds-schema-quiet check-unused-imports check-config-sync check-rules check-urls check-mthds-schema check-ledger check-migration-schemas check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist check-log-calls drift-check format lint pyright mypy pylint
@echo "> done: check"
agent-check: fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist check-log-calls drift-check api-agent-check
@echo "> done: agent-check"
v: validate
@echo "> done: v = validate"
li: lock install
@echo "> done: lock install"
##########################################################################################
### TEST BADGE
##########################################################################################
## Print the number of collected pytest tests (just the integer)
test-count: env
@COUNT=$$($(VENV_PYTEST) --collect-only --disable-warnings -q | awk 'NF' | wc -l | tr -d ' '); \
echo $$COUNT
## Compare current test count vs .badges/tests.json -> .message; fail if mismatch
check-test-badge: env
@EXPECTED=$$($(VENV_PYTHON) -c 'import json;print(int(json.load(open(".badges/tests.json"))["message"]))'); \
ACTUAL=$$($(VENV_PYTEST) --collect-only --disable-warnings -q | awk 'NF' | wc -l | tr -d ' '); \
if [ "$$EXPECTED" != "$$ACTUAL" ]; then \
echo "❌ Test count mismatch: badge=$$EXPECTED, actual=$$ACTUAL"; \
exit 1; \
else \
echo "✅ Test count matches: $$ACTUAL"; \
fi