Makefile

# Variables
PYTHON := uv run
UV := uv
PRE_COMMIT := uv run pre-commit
PROJECT_NAME := archipy
PYTHON_FILES := $(PROJECT_NAME) packages features/steps scripts
# Collect git-changed Python files (staged + unstaged, existing files only)
GIT_CHANGED_PY_FILES := $(shell git diff --name-only HEAD -- '*.py' | grep '^$(PROJECT_NAME)/' | xargs -r ls -d 2>/dev/null)

# Colors for terminal output
BLUE := \033[1;34m
GREEN := \033[1;32m
RED := \033[1;31m
YELLOW := \033[1;33m
NC := \033[0m # No Color

.PHONY: help
help: ## Show this help message
	@echo 'Usage:'
	@echo "${BLUE}make${NC} ${GREEN}<target>${NC}"
	@echo ''
	@echo 'Targets:'
	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z\-_0-9]+:.*?## / {printf "  ${BLUE}%-20s${NC} %s\n", $$1, $$2}' $(MAKEFILE_LIST)

.PHONY: setup
setup: ## Setup project pre-requisites
	@echo "${BLUE}Setup project pre-requisites...${NC}"
	@echo "${GREEN}Installing uv (may need your sudo password)...${NC}"
	sudo apt install pipx
	pipx install uv
	pipx ensurepath
	uv generate-shell-completion bash >> ~/.bash_completion

.PHONY: install
install: ## Install project dependencies
	@echo "${BLUE}Installing project dependencies...${NC}"
	$(UV) sync --all-extras --group dev --upgrade
	$(PRE_COMMIT) install

.PHONY: install-dev
install-dev: ## Install project dependencies with dev extras
	@echo "${BLUE}Installing project dependencies with dev extras...${NC}"
	$(UV) sync --all-extras --all-packages --all-groups --upgrade
	$(PRE_COMMIT) install

.PHONY: install-package
install-package: ## Install core + one adapter package (usage: make install-package PKG=redis)
	@echo "${BLUE}Installing archipy-$(PKG)...${NC}"
	$(UV) sync --package archipy-$(PKG) --group dev

.PHONY: update
update: ## Update dependencies to their latest versions
	@echo "${BLUE}Updating dependencies...${NC}"
	$(UV) lock --upgrade

.PHONY: update-all
update-all: ## Aggressively update all dependencies to latest versions
	@echo "${BLUE}Aggressively updating all dependencies...${NC}"
	@echo "${YELLOW}Note: This updates uv.lock; to change pyproject.toml constraints, edit manually${NC}"
	$(UV) self update
	$(UV) python upgrade
	$(UV) python update-shell
	$(UV) lock --upgrade
	$(UV) sync --all-extras --all-packages --all-groups --upgrade

.PHONY: clean
clean: ## Remove build artifacts and cache directories
	@echo "${BLUE}Cleaning project...${NC}"
	rm -rf dist/
	rm -rf build/
	rm -rf .pytest_cache/
	rm -rf .coverage .coverage.* coverage.xml .behave-logs .behave_durations.json
	rm -rf htmlcov/
	rm -rf .ty_cache/
	find . -type d -name __pycache__ -exec rm -rf {} +
	find . -type f -name "*.pyc" -delete

.PHONY: format
format: ## Format code using ruff and gherkin-formatter
	@echo "${BLUE}Formatting code...${NC}"
	$(PYTHON) ruff format --config pyproject.toml $(PYTHON_FILES)
	@echo "${BLUE}Formatting Gherkin feature files...${NC}"
	$(PYTHON) gherkin-formatter features/

.PHONY: lint
lint: ## Run all linters
	@echo "${BLUE}Running linters...${NC}"
	$(PYTHON) ruff check --config pyproject.toml $(PYTHON_FILES)
	$(PYTHON) ruff check --config pyproject.toml --exclude '' --select F features scripts
	$(PYTHON) ty check --fix $(PYTHON_FILES)
	$(PYTHON) lint-imports

.PHONY: security
security: ## Run security scan with Bandit
	@echo "${BLUE}Running security scan...${NC}"
	$(PYTHON) bandit -c pyproject.toml -r archipy/ packages/ -f json -o bandit-report.json || true

.PHONY: check-instrumentor-compat
check-instrumentor-compat: ## Check whether OTel instrumentors now support the library versions ArchiPy requires
	@echo "${BLUE}Checking OpenTelemetry instrumentor compatibility...${NC}"
	./scripts/check_instrumentor_compat.sh

# Features that run at the same time, and how many of those may start a heavy container
BEHAVE_JOBS ?= 8
BEHAVE_HEAVY_JOBS ?= 3

.PHONY: behave
behave: ## Run all features in parallel, one behave process per feature (BEHAVE_JOBS=N, FEATURE=features/x.feature, EXCLUDE="features/y.feature ...")
	@echo "${BLUE}Running tests in parallel...${NC}"
	$(UV) run --extra behave python scripts/behave_parallel.py --jobs $(BEHAVE_JOBS) --heavy-jobs $(BEHAVE_HEAVY_JOBS) $(foreach f,$(EXCLUDE),--exclude $(f)) $(FEATURE) $(if $(BEHAVE_ARGS),-- $(BEHAVE_ARGS))

.PHONY: pull-test-images
pull-test-images: ## Pull every Docker image the tests use (from .env.test), 4 at a time
	@echo "${BLUE}Pulling test images...${NC}"
	@grep -h '_IMAGE=' .env.test | cut -d= -f2 | xargs -P 4 -n 1 docker pull

.PHONY: behave-seq
behave-seq: ## Run all features one after another in a single behave process
	@echo "${BLUE}Running tests sequentially...${NC}"
	$(UV) run --extra behave behave

.PHONY: coverage
coverage: ## Run the features in parallel under coverage (FEATURE=features/x.feature for one feature)
	@echo "${BLUE}Running tests with coverage...${NC}"
	$(UV) run --extra behave python scripts/behave_parallel.py --coverage --jobs $(BEHAVE_JOBS) --heavy-jobs $(BEHAVE_HEAVY_JOBS) $(FEATURE)

.PHONY: test
test: behave ## Run tests (alias for behave)

.PHONY: build
build: clean ## Build project distribution
	@echo "${BLUE}Building project distribution...${NC}"
	$(UV) build

.PHONY: version
version: ## Display current version
	@echo "${BLUE}Current version:${NC}"
	@$(UV) run python -c "import tomllib; print(f\"archipy {tomllib.load(open('pyproject.toml', 'rb'))['project']['version']}\")"
	@echo "${YELLOW}Current tag:${NC}"
	@git describe --tags --abbrev=0 2>/dev/null || echo "No tags found"

.PHONY: docker-build
docker-build: ## Build Docker image
	@echo "${BLUE}Building Docker image...${NC}"
	docker build -t $(PROJECT_NAME) .

.PHONY: docker-run
docker-run: ## Run Docker container
	@echo "${BLUE}Running Docker container...${NC}"
	docker run -it --rm $(PROJECT_NAME)

.PHONY: pre-commit
pre-commit: ## Run pre-commit hooks
	@echo "${BLUE}Running pre-commit hooks...${NC}"
	$(PRE_COMMIT) run --all-files

.PHONY: check
check: format lint security behave ## Run all checks (format, linting, security, and tests)

.PHONY: ci
ci: ## Run CI pipeline locally
	@echo "${BLUE}Running CI pipeline...${NC}"
	$(MAKE) clean
	$(MAKE) install-dev
	$(MAKE) lint
	$(MAKE) security
	$(MAKE) behave
	$(MAKE) build

.PHONY: format-changes
format-changes: ## Format only git-changed Python and Gherkin files
	@echo "${BLUE}Formatting changed files...${NC}"
	@if [ -z "$(GIT_CHANGED_PY_FILES)" ]; then \
		echo "${YELLOW}No changed Python files found.${NC}"; \
	else \
		echo "$(GIT_CHANGED_PY_FILES)" | tr ' ' '\n'; \
		$(PYTHON) ruff format --config pyproject.toml $(GIT_CHANGED_PY_FILES); \
	fi
	@CHANGED_FEATURES=$$(git diff --name-only HEAD -- 'features/*.feature' | xargs -r ls -d 2>/dev/null); \
	if [ -z "$$CHANGED_FEATURES" ]; then \
		echo "${YELLOW}No changed Gherkin feature files found.${NC}"; \
	else \
		echo "$$CHANGED_FEATURES" | tr ' ' '\n'; \
		$(PYTHON) gherkin-formatter $$CHANGED_FEATURES; \
	fi

.PHONY: lint-changes
lint-changes: ## Lint only git-changed Python files
	@echo "${BLUE}Linting changed files...${NC}"
	@if [ -z "$(GIT_CHANGED_PY_FILES)" ]; then \
		echo "${YELLOW}No changed Python files found.${NC}"; \
	else \
		echo "$(GIT_CHANGED_PY_FILES)" | tr ' ' '\n'; \
		$(PYTHON) ruff check --config pyproject.toml $(GIT_CHANGED_PY_FILES); \
		$(PYTHON) ty check $$(echo "$(GIT_CHANGED_PY_FILES)" | tr ' ' '\n' | grep '^$(PROJECT_NAME)/' | tr '\n' ' '); \
	fi

.PHONY: security-changes
security-changes: ## Run security scan only on git-changed Python files
	@echo "${BLUE}Running security scan on changed files...${NC}"
	@if [ -z "$(GIT_CHANGED_PY_FILES)" ]; then \
		echo "${YELLOW}No changed Python files found.${NC}"; \
	else \
		echo "$(GIT_CHANGED_PY_FILES)" | tr ' ' '\n'; \
		$(PYTHON) bandit -c pyproject.toml $(GIT_CHANGED_PY_FILES) || true; \
	fi

.PHONY: check-changes
check-changes: format-changes lint-changes security-changes ## Run format, lint, and security only on git-changed files

# BASE defaults to master; use e.g. make check-mr BASE=main to diff vs main
BASE ?= master
.PHONY: check-mr
check-mr: ## Run pre-commit only on files changed vs BASE (default master), e.g. make check-mr BASE=main
	@BASE="$(BASE)"; \
	CHANGED=$$(git diff --name-only "$$BASE" -- 2>/dev/null | tr '\n' ' '); \
	if [ -z "$$CHANGED" ]; then \
	  echo "${YELLOW}No changed files vs $$BASE${NC}"; \
	  exit 0; \
	fi; \
	echo "${BLUE}Running pre-commit on files changed vs $$BASE...${NC}"; \
	$(PRE_COMMIT) run --files $$CHANGED

.PHONY: docs-serve
docs-serve: ## Serve MkDocs documentation locally (balanced mode)
	@echo "${BLUE}Serving documentation...${NC}"
	$(UV) run --group docs mkdocs serve -f docs/mkdocs.yml

.PHONY: docs-serve-fast
docs-serve-fast: ## Serve MkDocs documentation with fast build (for quick iterations)
	@echo "${BLUE}Serving documentation (fast mode)...${NC}"
	$(UV) run --group docs mkdocs serve -f docs/mkdocs-fast.yml

.PHONY: docs-serve-no-api
docs-serve-no-api: ## Serve MkDocs documentation without API auto-generation (fastest)
	@echo "${BLUE}Serving documentation (no API generation)...${NC}"
	ENABLE_MKDOCSTRINGS=false $(UV) run --group docs mkdocs serve -f docs/mkdocs.yml

.PHONY: docs-build
docs-build: ## Build MkDocs documentation (balanced mode)
	@echo "${BLUE}Building documentation...${NC}"
	$(UV) run --group docs mkdocs build -f docs/mkdocs.yml

.PHONY: docs-check
docs-check: ## Build the docs in strict mode: broken links and API reference errors fail
	@echo "${BLUE}Checking documentation...${NC}"
	$(UV) run --group docs mkdocs build --strict -f docs/mkdocs.yml -d $$(mktemp -d)

.PHONY: docs-build-fast
docs-build-fast: ## Build MkDocs documentation with fast config
	@echo "${BLUE}Building documentation (fast mode)...${NC}"
	$(UV) run --group docs mkdocs build -f docs/mkdocs-fast.yml

.PHONY: docs-build-full
docs-build-full: ## Build MkDocs documentation with full features (for production)
	@echo "${BLUE}Building documentation (full mode)...${NC}"
	$(UV) run --group docs mkdocs build -f docs/mkdocs-full.yml --clean

.PHONY: docs-time
docs-time: ## Time the documentation build
	@echo "${BLUE}Timing documentation build...${NC}"
	time $(UV) run --group docs mkdocs build -f docs/mkdocs.yml

.PHONY: docs-deploy
docs-deploy: ## Deploy MkDocs to GitHub Pages
	@echo "${BLUE}Deploying documentation...${NC}"
	$(UV) run --group docs mkdocs gh-deploy --force -f docs/mkdocs-full.yml

.DEFAULT_GOAL := help