Makefile

# Every gate CI runs is reachable from here with the same command, so "it passed locally"
# and "it passed in CI" mean the same thing.

.DEFAULT_GOAL := help
SHELL := /bin/bash
VENV := .venv
PY := $(VENV)/bin/python
PIP := $(VENV)/bin/pip
WEB := apps/web

.PHONY: help
help: ## Show this help
	@grep -hE '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) \
	  | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-18s\033[0m %s\n", $$1, $$2}'

# ------------------------------------------------------------------------------ setup

$(VENV):
	python3.12 -m venv $(VENV)
	$(PIP) install --upgrade pip setuptools wheel

.PHONY: install
install: $(VENV) ## Install the backend with every extra, and the frontend
	$(PIP) install -e ".[dev,pdf,office,evals]"
	cd $(WEB) && npm ci

.PHONY: dev
dev: install migrate ## Install and bring the schema up to date
	@echo "ready: run 'make api' and 'make worker' and 'make web'"

.PHONY: env
env: ## Create .env from the example if it does not exist
	@test -f .env || (cp .env.example .env && echo "wrote .env")

# ------------------------------------------------------------------------------ run

.PHONY: api
api: ## Run the API with reload
	$(VENV)/bin/uvicorn contextforge.api.main:app --reload --port 8000

.PHONY: worker
worker: ## Run a Celery worker on both queues
	$(VENV)/bin/celery --app=contextforge.worker.celery_app:celery_app worker \
	  --queues=ingest,maintenance --concurrency=2 --loglevel=INFO

.PHONY: web
web: ## Run the Next.js dev server
	cd $(WEB) && npm run dev

.PHONY: up
up: ## The whole system in containers
	docker compose up --build

.PHONY: down
down: ## Stop the containers and delete their volumes
	docker compose down --volumes

# ------------------------------------------------------------------------- database

.PHONY: migrate
migrate: ## Apply migrations
	$(VENV)/bin/alembic upgrade head

.PHONY: revision
revision: ## Autogenerate a migration: make revision m="what changed"
	$(VENV)/bin/alembic revision --autogenerate -m "$(m)"

.PHONY: index
index: ## Rebuild the vector index to match VECTOR_INDEX
	$(PY) -m contextforge.cli db index --apply

# ---------------------------------------------------------------------------- gates

.PHONY: lint
lint: ## ruff check and format check
	$(VENV)/bin/ruff check .
	$(VENV)/bin/ruff format --check .

.PHONY: format
format: ## Apply formatting
	$(VENV)/bin/ruff format .
	$(VENV)/bin/ruff check --fix .

.PHONY: typecheck
typecheck: ## mypy
	$(VENV)/bin/mypy

.PHONY: test
test: ## The whole Python suite (warnings are errors)
	$(VENV)/bin/pytest -q

.PHONY: test-unit
test-unit: ## Unit tests only, no database needed
	$(VENV)/bin/pytest -q tests/unit

.PHONY: coverage
coverage: ## Tests with a coverage report
	$(VENV)/bin/pytest -q --cov=services/contextforge --cov-report=term-missing:skip-covered

.PHONY: web-check
web-check: ## Frontend lint, types, tests and build
	cd $(WEB) && npm run lint && npm run typecheck && npm run test && npm run build

.PHONY: openapi
openapi: ## Regenerate openapi.json and the frontend's types from it
	$(PY) scripts/export_openapi.py --output openapi.json
	cd $(WEB) && npm run generate:api -- --input ../../openapi.json

.PHONY: report
report: ## Regenerate every published figure from evals/results
	$(PY) -m evals.report

.PHONY: check-generated
check-generated: ## Fail when a document disagrees with evals/results
	$(PY) -m evals.report --check

.PHONY: check
check: lint typecheck test check-generated web-check ## Everything CI runs

# ----------------------------------------------------------------------- evaluation

.PHONY: corpus
corpus: ## Download and verify the evaluation corpus
	$(PY) -m evals.fetch

.PHONY: evals
evals: corpus ## Retrieval and generation harnesses on the held-out split, then the documents
	$(PY) -m evals.retrieval.run --split test --rebuild
	$(PY) -m evals.generation.run --split test
	$(PY) -m evals.report

.PHONY: smoke
smoke: ## End-to-end smoke test against a running stack
	$(PY) scripts/smoke.py --api http://127.0.0.1:8000

.PHONY: clean
clean: ## Remove caches and build output
	find . -name __pycache__ -type d -prune -exec rm -rf {} +
	rm -rf .pytest_cache .mypy_cache .ruff_cache $(WEB)/.next