Makefile

.PHONY: help dev install-deps lint format security test-all typecheck smoke-test pipeline push changelog changelog-draft bump ticket clean

# ─────────────────────────────────────────────────────────────────────────────
# Variables — configure these for your project
# ─────────────────────────────────────────────────────────────────────────────
PROJECT_NAME    := core
PYTHON_VERSION  := 3.12
UV              := uv

# Directory that contains your packages. For a workspace this is typically
# "packages". For a single-package project set both to ".":
#   PACKAGES_DIR := .
#   PACKAGES     := .
PACKAGES_DIR    := packages

# Space-separated list of package directory names under $(PACKAGES_DIR)/.
# Example: PACKAGES := settings core effects orchestrator
PACKAGES        := logging pipeline container-manager socket storage cache daemon event-protocol

# Packages that require mypy type checking. Leave empty to skip mypy everywhere.
# Example: MYPY_PACKAGES := core orchestrator
MYPY_PACKAGES   := logging pipeline container-manager socket storage cache daemon event-protocol #

# Smoke test configuration
# Per-package smoke test scripts at: packages/<pkg>/tests/smoke/run-smoke-tests.sh

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

# ─────────────────────────────────────────────────────────────────────────────
# Derived variables — do not edit
# ─────────────────────────────────────────────────────────────────────────────
LINT_TARGETS     := $(addprefix lint-,$(PACKAGES))
FORMAT_TARGETS   := $(addprefix format-,$(PACKAGES))
SECURITY_TARGETS := $(addprefix security-,$(PACKAGES))
TEST_TARGETS     := $(addprefix test-,$(PACKAGES))

# ─────────────────────────────────────────────────────────────────────────────
##@ General
# ─────────────────────────────────────────────────────────────────────────────
.DEFAULT_GOAL := help
help: ## Show this help message
	@echo -e "$(BLUE)$(PROJECT_NAME) - Development Makefile$(NC)"
	@echo -e ""
	@echo -e "$(GREEN)Usage:$(NC)"
	@echo -e "  make $(BLUE)<target>$(NC)"
	@echo -e ""
	@echo -e "$(GREEN)Targets:$(NC)"
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  $(BLUE)%-25s$(NC) %s\n", $$1, $$2}'

# ─────────────────────────────────────────────────────────────────────────────
##@ Setup & Installation
# ─────────────────────────────────────────────────────────────────────────────
dev: install-deps ## Set up development environment
	@$(UV) run pre-commit install --hook-type pre-commit --hook-type commit-msg
	@echo -e "$(GREEN)Development environment ready$(NC)"

install-deps: ## Install all dependencies for development
	@echo -e "$(BLUE)Installing packages...$(NC)"
	$(UV) sync --dev --all-packages
	@echo -e "$(GREEN)All dependencies installed$(NC)"

# ─────────────────────────────────────────────────────────────────────────────
##@ Code Quality
# ─────────────────────────────────────────────────────────────────────────────
lint: $(LINT_TARGETS) ## Run linting on all packages

lint-%: ## Lint a specific package
	@echo -e "$(BLUE)Linting $* package...$(NC)"
	@$(UV) run ruff check --line-length 88 $(PACKAGES_DIR)/$* || (echo -e "$(RED)Ruff found issues in $*. Run: make format-$*$(NC)" && exit 1)
	@$(UV) run black --check --line-length 88 $(PACKAGES_DIR)/$* || (echo -e "$(RED)Black formatting needed in $*. Run: make format-$*$(NC)" && exit 1)
	@$(UV) run isort --check --profile black --line-length 88 $(PACKAGES_DIR)/$* || (echo -e "$(RED)Import sorting needed in $*. Run: make format-$*$(NC)" && exit 1)
	@if echo "$(MYPY_PACKAGES)" | grep -wq "$*"; then \
		echo -e "$(BLUE)Running mypy on $*...$(NC)"; \
		$(UV) run mypy $(PACKAGES_DIR)/$*/src/ || (echo -e "$(RED)Type errors found in $*$(NC)" && exit 1); \
	fi
	@echo -e "$(GREEN)$* linting passed$(NC)"

format: $(FORMAT_TARGETS) ## Format all code in packages

format-%: ## Format a specific package
	@echo -e "$(BLUE)Formatting $* package...$(NC)"
	$(UV) run isort --profile black --line-length 88 $(PACKAGES_DIR)/$*
	$(UV) run black --line-length 88 $(PACKAGES_DIR)/$*
	$(UV) run ruff check --fix --line-length 88 $(PACKAGES_DIR)/$*
	@echo -e "$(GREEN)$* formatted$(NC)"

typecheck: ## Run mypy on all MYPY_PACKAGES (skips if MYPY_PACKAGES is empty)
	@if [ -z "$(MYPY_PACKAGES)" ]; then \
		echo -e "$(YELLOW)MYPY_PACKAGES is empty — skipping type checking$(NC)"; \
	else \
		for pkg in $(MYPY_PACKAGES); do \
			echo -e "$(BLUE)Type-checking $$pkg...$(NC)"; \
			$(UV) run mypy $(PACKAGES_DIR)/$$pkg/src/ || exit 1; \
		done; \
		echo -e "$(GREEN)Type checking passed$(NC)"; \
	fi

# ─────────────────────────────────────────────────────────────────────────────
##@ Security
# ─────────────────────────────────────────────────────────────────────────────
security: $(SECURITY_TARGETS) ## Run security scans on all packages

security-%: ## Security scan for a specific package
	@echo -e "$(BLUE)Running security scan on $* package...$(NC)"
	cd $(PACKAGES_DIR)/$* && $(UV) run bandit -r src/ -ll -f json -o bandit-report.json
	@echo -e "$(GREEN)$* security scan complete$(NC)"

# ─────────────────────────────────────────────────────────────────────────────
##@ Testing
# ─────────────────────────────────────────────────────────────────────────────
test-all: $(TEST_TARGETS) ## Run full test suite with coverage
	@echo -e "$(GREEN)All package tests completed$(NC)"

test-%: ## Test a specific package
	@echo -e "$(BLUE)Testing $* package...$(NC)"
	cd $(PACKAGES_DIR)/$* && $(UV) run pytest -n auto --color=yes --cov=src --cov-report=term
	cd $(PACKAGES_DIR)/$* && $(UV) run coverage report --fail-under=95

# ─────────────────────────────────────────────────────────────────────────────
##@ Smoke Testing
# ─────────────────────────────────────────────────────────────────────────────
smoke-test: ## Run smoke tests (VERBOSE=true for verbose output)
	@echo -e "$(BLUE)Running smoke tests...$(NC)"
	@if [ ! -f "$(SMOKE_TEST_SCRIPT)" ]; then \
		echo -e "$(RED)Smoke test script not found at $(SMOKE_TEST_SCRIPT)$(NC)"; \
		exit 1; \
	fi
	@if [ "$(VERBOSE)" = "true" ]; then \
		bash $(SMOKE_TEST_SCRIPT) --verbose; \
	else \
		bash $(SMOKE_TEST_SCRIPT); \
	fi
	@echo -e "$(GREEN)Smoke tests completed$(NC)"

# ─────────────────────────────────────────────────────────────────────────────
##@ Documentation
# ─────────────────────────────────────────────────────────────────────────────
changelog: ## Append unreleased commits to docs/changelog.md
	@$(UV) run cz changelog

bump: ## Bump version and update changelog (PKG=<name> for workspace packages, INCREMENT=patch|minor|major)
	@if [ -n "$(PKG)" ]; then \
		echo -e "$(BLUE)Bumping version for package: $(PKG)$(NC)"; \
		$(UV) run cz bump --project-root $(PACKAGES_DIR)/$(PKG) $(if $(INCREMENT),--increment $(INCREMENT),); \
	else \
		echo -e "$(BLUE)Bumping root version$(NC)"; \
		$(UV) run cz bump $(if $(INCREMENT),--increment $(INCREMENT),); \
	fi

ticket: ## Scaffold ticket documents and branch (TYPE=feature|bug|chore ID=NNNNN NAME=<name>)
	@if [ -z "$(TYPE)" ] || [ -z "$(ID)" ] || [ -z "$(NAME)" ]; then \
		echo -e "$(RED)Usage: make ticket TYPE=feature|bug|chore ID=NNNNN NAME=<name>$(NC)"; \
		echo -e "$(YELLOW)Example: make ticket TYPE=feature ID=00001 NAME=add-oauth-login$(NC)"; \
		exit 1; \
	fi
	@./scripts/scaffold-ticket.sh $(TYPE) $(ID) $(NAME)

changelog-draft: ## Scaffold docs/changelog-draft.md from git merge commits (manual fallback)
	@./scripts/generate-changelog.sh

# ─────────────────────────────────────────────────────────────────────────────
##@ CI/CD Pipeline
# ─────────────────────────────────────────────────────────────────────────────
pipeline: ## Simulate GitHub Actions locally: lint → security → test
	@echo -e "$(BLUE)Running pipeline validation...$(NC)"
	@echo -e ""
	@echo -e "$(BLUE)Step 1: Linting (All packages)$(NC)"
	@$(MAKE) lint
	@echo -e "$(GREEN)Linting passed$(NC)"
	@echo -e ""
	@echo -e "$(BLUE)Step 2: Security Scan (All packages)$(NC)"
	@$(MAKE) security
	@echo -e "$(GREEN)Security scans passed$(NC)"
	@echo -e ""
	@echo -e "$(BLUE)Step 3: Testing (All packages)$(NC)"
	@$(MAKE) test-all
	@echo -e "$(GREEN)Tests passed with 95%+ coverage$(NC)"
	@echo -e ""
	@echo -e "$(GREEN)Pipeline validation successful!$(NC)"
	@echo -e "$(GREEN)Your changes are safe to push to the cloud.$(NC)"
	@echo -e ""

push: ## Run GitHub Actions workflows locally via act (SMOKE=true for smoke tests)
	@echo -e "$(BLUE)Setting up GitHub Actions locally...$(NC)"
	@if [ ! -f ./bin/act ]; then \
		echo -e "$(BLUE)Downloading act (GitHub Actions CLI)...$(NC)"; \
		mkdir -p ./bin; \
		curl -sL https://github.com/nektos/act/releases/download/v0.2.65/act_Linux_x86_64.tar.gz -o /tmp/act.tar.gz; \
		tar -xzf /tmp/act.tar.gz -C ./bin; \
		rm /tmp/act.tar.gz; \
		echo -e "$(GREEN)act installed to ./bin/act$(NC)"; \
	else \
		echo -e "$(GREEN)act already available$(NC)"; \
	fi
	@echo -e ""
	@mkdir -p .logs
	@TIMESTAMP=$$(date +%Y%m%d-%H%M%S); \
	LOG_FILE=".logs/make-push-$$TIMESTAMP.log"; \
	if [ "$(SMOKE)" = "true" ]; then \
		echo -e "$(BLUE)═══════════════════════════════════════════════════════════$(NC)" | tee "$$LOG_FILE"; \
		echo -e "$(BLUE)Running GitHub Actions with SMOKE TESTS enabled$(NC)" | tee -a "$$LOG_FILE"; \
		echo -e "$(BLUE)═══════════════════════════════════════════════════════════$(NC)" | tee -a "$$LOG_FILE"; \
		echo -e "$(BLUE)Logs: $$LOG_FILE$(NC)" | tee -a "$$LOG_FILE"; \
		echo -e "$(BLUE)═══════════════════════════════════════════════════════════$(NC)" | tee -a "$$LOG_FILE"; \
		echo -e "" | tee -a "$$LOG_FILE"; \
		echo -e "$(BLUE)───────────────────────────────────────────────────────────$(NC)" | tee -a "$$LOG_FILE"; \
		echo -e "$(BLUE)PHASE 1: Standard CI Workflows$(NC)" | tee -a "$$LOG_FILE"; \
		echo -e "$(BLUE)───────────────────────────────────────────────────────────$(NC)" | tee -a "$$LOG_FILE"; \
		./bin/act push --container-options "--user $$(id -u):$$(id -g)" 2>&1 | tee -a "$$LOG_FILE"; \
		STANDARD_EXIT=$${PIPESTATUS[0]}; \
		echo -e "" | tee -a "$$LOG_FILE"; \
		if [ $$STANDARD_EXIT -eq 0 ]; then \
			echo -e "$(GREEN)Standard CI passed$(NC)" | tee -a "$$LOG_FILE"; \
			echo -e "" | tee -a "$$LOG_FILE"; \
			echo -e "$(BLUE)───────────────────────────────────────────────────────────$(NC)" | tee -a "$$LOG_FILE"; \
			echo -e "$(BLUE)PHASE 2: Smoke Test Workflow$(NC)" | tee -a "$$LOG_FILE"; \
			echo -e "$(BLUE)───────────────────────────────────────────────────────────$(NC)" | tee -a "$$LOG_FILE"; \
			./bin/act workflow_dispatch -W .github/workflows/smoke-test.yml --container-options "--user $$(id -u):$$(id -g)" 2>&1 | tee -a "$$LOG_FILE"; \
			SMOKE_EXIT=$${PIPESTATUS[0]}; \
			echo -e "" | tee -a "$$LOG_FILE"; \
			if [ $$SMOKE_EXIT -eq 0 ]; then \
				echo -e "$(GREEN)Smoke tests passed$(NC)" | tee -a "$$LOG_FILE"; \
				EXIT_CODE=0; \
			else \
				echo -e "$(RED)Smoke tests failed$(NC)" | tee -a "$$LOG_FILE"; \
				EXIT_CODE=$$SMOKE_EXIT; \
			fi; \
		else \
			echo -e "$(RED)Standard CI failed, skipping smoke tests$(NC)" | tee -a "$$LOG_FILE"; \
			EXIT_CODE=$$STANDARD_EXIT; \
		fi; \
	else \
		echo -e "$(BLUE)═══════════════════════════════════════════════════════════$(NC)" | tee "$$LOG_FILE"; \
		echo -e "$(BLUE)Running Standard GitHub Actions Workflows$(NC)" | tee -a "$$LOG_FILE"; \
		echo -e "$(BLUE)═══════════════════════════════════════════════════════════$(NC)" | tee -a "$$LOG_FILE"; \
		echo -e "$(BLUE)Logs: $$LOG_FILE$(NC)" | tee -a "$$LOG_FILE"; \
		echo -e "$(YELLOW)Tip: Add SMOKE=true to include smoke tests$(NC)" | tee -a "$$LOG_FILE"; \
		echo -e "$(BLUE)═══════════════════════════════════════════════════════════$(NC)" | tee -a "$$LOG_FILE"; \
		echo -e "" | tee -a "$$LOG_FILE"; \
		./bin/act push --container-options "--user $$(id -u):$$(id -g)" 2>&1 | tee -a "$$LOG_FILE"; \
		EXIT_CODE=$${PIPESTATUS[0]}; \
	fi; \
	echo -e "" | tee -a "$$LOG_FILE"; \
	echo -e "$(BLUE)═══════════════════════════════════════════════════════════$(NC)" | tee -a "$$LOG_FILE"; \
	if [ $$EXIT_CODE -eq 0 ]; then \
		echo -e "$(GREEN)GitHub Actions simulation complete$(NC)" | tee -a "$$LOG_FILE"; \
	else \
		echo -e "$(RED)GitHub Actions simulation failed (exit: $$EXIT_CODE)$(NC)" | tee -a "$$LOG_FILE"; \
	fi; \
	echo -e "$(BLUE)═══════════════════════════════════════════════════════════$(NC)" | tee -a "$$LOG_FILE"; \
	echo -e ""; \
	echo -e "$(GREEN)Full logs: $$LOG_FILE$(NC)"; \
	echo -e "$(GREEN)View logs: cat $$LOG_FILE$(NC)"; \
	echo -e "$(GREEN)Search: grep 'PASSED\|FAILED' $$LOG_FILE$(NC)"; \
	echo -e ""; \
	exit $$EXIT_CODE

# ─────────────────────────────────────────────────────────────────────────────
##@ Cleanup
# ─────────────────────────────────────────────────────────────────────────────
clean: ## Remove build artifacts and caches
	@echo -e "$(BLUE)Cleaning build artifacts...$(NC)"
	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
	find . -type d -name .pytest_cache -exec rm -rf {} + 2>/dev/null || true
	find . -type d -name .mypy_cache -exec rm -rf {} + 2>/dev/null || true
	find . -type d -name htmlcov -exec rm -rf {} + 2>/dev/null || true
	find . -type d -name dist -exec rm -rf {} + 2>/dev/null || true
	find . -type d -name build -exec rm -rf {} + 2>/dev/null || true
	find . -type f -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
	find . -type f -name ".coverage" -delete
	find . -type f -name "coverage.xml" -delete
	find . -type f -name "bandit-report.json" -delete
	@echo -e "$(GREEN)Cleanup complete$(NC)"