Makefile

# Convenience targets. CI runs the same commands directly (see .github/workflows);
# these just give them stable names. `uv` runs inside the pipeline/ project.

.PHONY: verify tiles tiles-geojsonl map-geometry render-site render-constants golden-refresh test contrast readability no-todos sync-static-nav mutation mutation-results iac

# The merge-blocking gate: lint, format, types, tests, the AAA contrast check,
# and the plain-language readability check. Mirrors .github/workflows/ci.yml.
verify:
	cd pipeline && uv run python scripts/generate_iso3166.py --check
	cd pipeline && uv run ruff check src tests scripts/generate_iso3166.py scripts/check_site_seo.py scripts/materialize_current_artifacts.py scripts/check_supersession_review.py
	cd pipeline && uv run ruff format --check src tests scripts/generate_iso3166.py scripts/check_site_seo.py scripts/materialize_current_artifacts.py scripts/check_supersession_review.py
	cd pipeline && uv run mypy
	cd pipeline && uv run pytest -q --cov=scorecard_pipeline --cov-branch --cov-fail-under=92
	cd pipeline && uv run python scripts/check_contrast.py
	cd pipeline && uv run python scripts/check_readability.py
	cd pipeline && uv run python scripts/check_versions.py
	cd pipeline && uv run python scripts/check_doc_stats.py
	cd pipeline && uv run python scripts/check_supersession_review.py
	$(MAKE) no-todos

# CQ-34: keep the repo's current zero-bare-TODO state a merge-blocking gate
# instead of an aspiration. A real, tracked TODO should carry an issue
# reference and live in docs/ (e.g. docs/lint-complexity-ratchet.md), not a
# bare marker in source.
no-todos:
	@if grep -rnE "TODO|FIXME|HACK" pipeline/src web/src; then \
		echo "Bare TODO/FIXME/HACK found in pipeline/src or web/src — track it in docs/ instead (CQ-34)."; \
		exit 1; \
	fi

test:
	cd pipeline && uv run pytest -q --cov=scorecard_pipeline --cov-branch --cov-fail-under=92

contrast:
	cd pipeline && uv run python scripts/check_contrast.py

readability:
	cd pipeline && uv run python scripts/check_readability.py

render-site:
	cd pipeline && uv run scorecard render-site

# Deliberately refresh deterministic render and report contracts after reviewing
# an intentional public-output change.
golden-refresh:
	cd pipeline && uv run python scripts/refresh_goldens.py
	cd pipeline && REPORT_GOLDEN_REGEN=1 uv run pytest tests/test_report_golden.py -q

# Regenerate web/src/generated/constants.js (grade bands and ranks, category and
# severity labels, rule links, thresholds) from the Python definitions in
# constants_export.py, the single source of truth. render-site runs this too;
# tests/test_generated_constants.py fails CI if the committed file drifts.
render-constants:
	cd pipeline && uv run scorecard render-constants

# Regenerate the primary nav in the hand-authored static pages (submit, subscribe,
# try, the app shell, about, data) from _NAV_ITEMS, the single source of truth.
# tests/test_static_nav.py fails CI if a static page's nav drifts from it.
sync-static-nav:
	cd pipeline && uv run python -c "from scorecard_pipeline.render_site import sync_static_navs; print('synced:', [str(p) for p in sync_static_navs()])"

# Rebuild the national all-routes vector tiles + PMTiles archive (web/tiles/).
# Requires tippecanoe on PATH (brew install tippecanoe). NOT part of `verify` or
# the daily build — tippecanoe is not in the daily image. See docs/decisions/0023.
tiles:
	cd pipeline && uv run python scripts/build_national_pmtiles.py

# Just the aggregated GeoJSONL, no tippecanoe needed (for inspecting the input).
tiles-geojsonl:
	cd pipeline && uv run python scripts/build_national_pmtiles.py --geojsonl-only

# Regenerate the committed SVG map geometry the web app colors at runtime:
# web/us-states.json, web/world-countries.json, and web/subdivisions/<cc>.json.
# Each script re-downloads its public-domain source (Natural Earth admin-0/
# admin-1, PublicaMundi US states), so this needs network access. NOT part of
# `verify` or the daily build. The .github/workflows/geometry.yml dispatch does
# the same and opens a PR when the geometry changed.
map-geometry:
	uv run --project pipeline python scripts/build_us_map.py
	uv run --project pipeline python scripts/build_world_map.py
	uv run --project pipeline python scripts/build_subdivision_maps.py

# ADVISORY mutation testing of the scoring math (src/scorecard_pipeline/score.py,
# metrics.py, and rt.py: the grade ladder, fix-priority tiers, deduction
# arithmetic, freshness slope, and realtime weighting — where a silent bug
# mis-grades an agency). Coverage there is already high, so this is the next
# signal: do the tests' assertions actually catch a regression? Scope + config
# live in pipeline/pyproject.toml [tool.mutmut]; the kill signal is the unit
# tests for those modules plus the property/corpus tests (about a minute).
#
# NOT part of `verify` and NEVER a per-PR blocker — REVIEW-GATE per
# CODE-QUALITY-STANDARD.md §10. Run it locally or via the weekly mutation.yml
# workflow. Baseline score + triaged survivors: docs/mutation-testing.md. Delete
# pipeline/mutants/ first for a clean-cache baseline; `mutation-results` reprints
# the last run's survivors without re-running.
mutation:
	cd pipeline && uv run mutmut run
	cd pipeline && uv run mutmut results

mutation-results:
	cd pipeline && uv run mutmut results

# QM-08's IaC half: the same Terraform checks .github/workflows/iac.yml runs
# in CI. Needs terraform >= 1.5 locally. Validation is offline
# (init -backend=false): no cloud credentials, no state, no plan, no apply.
iac:
	terraform fmt -check -recursive infra/
	set -e; for dir in infra/*/; do \
		[ -f "$${dir}main.tf" ] || continue; \
		echo "== $${dir}"; \
		terraform -chdir="$$dir" init -backend=false -input=false >/dev/null; \
		terraform -chdir="$$dir" validate; \
	done