# core-api — the repo's command surface (D-27).
#
# Paths resolve here rather than in callers (D-10). `python3` on this host is
# 3.8 and cannot parse these sources, and a bare `pytest` resolves only in a
# login shell — so both are named explicitly through the venv.

VENV   := $(CURDIR)/.venv
PYTHON ?= python3.12

.DEFAULT_GOAL := help

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

.PHONY: setup
setup: ## Create the venv, install dependencies, and prove the result is usable
	$(PYTHON) -m venv .venv
	$(VENV)/bin/pip install -r requirements.txt -r dev-requirements.txt
	# Exit 0 from pip install is not evidence (D-24) — it is the step's job not
	# to fail, so a broken result and a working one look identical from here.
	# On 2026-08-09 the venv existed and pip had exited 0, but sqlalchemy was
	# declared in requirements.txt and not installed; that surfaced as 11
	# pytest collection errors that read as broken imports, not as a setup
	# problem. `--collect-only` exercises every import the suite touches
	# without running a single test, so it catches exactly that class of
	# drift and stays cheap. `pip check` was considered too, but it only
	# verifies the *installed* set's internal consistency against itself —
	# it would not have caught this case, because sqlalchemy was still
	# present as another package's transitive dependency even when dropped
	# from requirements.txt. collect-only checks declared-vs-actually-usable
	# directly, which is the axis that broke.
	$(VENV)/bin/python -m pytest --collect-only tests/

.PHONY: test
test: ## Run the test suite
	@test -x $(VENV)/bin/python || { echo "FAIL — no venv; run: make setup"; exit 69; }
	$(VENV)/bin/python -m pytest tests/

# No `lint` target, deliberately. This repo configures no linter — no ruff or
# flake8 config, and neither in requirements. Per D-27 the name is reserved for
# repos that lint; an empty target here would report clean for something never
# run. Add the target when a linter is added, not before.

# git hands a hook a non-login shell, which never sees ~/.local/bin — where
# gitleaks lands. Without this the scan reports "not installed" on every push,
# which is a check that fails open (D-24).
export PATH := $(HOME)/.local/bin:/usr/local/bin:$(PATH)

.PHONY: secrets
secrets: ## Scan the commits about to be pushed for credentials
	@ci/secrets.sh

# The call surface is identical in every repo; what it runs is not.
#
# `secrets` runs first, deliberately: it is the only failure here that cannot be
# undone by fixing it afterwards. A failed lint costs another commit; a pushed
# credential is cached and indexed whether or not it is later deleted.
#
# Some of these fail today, and are left wired anyway. The state was measured
# once and written down in T-56 rather than being worked around here — a gate
# quietly narrowed to what already passes is a gate that reports success for
# doing nothing, which is the failure this workspace keeps rediscovering.
.PHONY: pre-push
pre-push: secrets ## Everything the pre-push hook runs
	@echo "  --   not gated here yet: lint (no linter configured) and test (T-56)"
