Makefile

# All Python tooling runs through uv pinned to 3.13 so the suite works on any
# machine regardless of the system python3 (examples use 3.12+ `type` syntax).
PY := uv run --python 3.13
NODE_DEPS_STAMP := node_modules/.package-lock.json

.PHONY: check-node-version node-deps test embed-examples embed-editorial-registry build-search-index build check-generated fingerprint prototypes browser-layout-test search-ranking-test social-cards check-social-cards seo-cache-lint verify-examples check-registry-integrity check-confusable-pairs check-broad-surface-tours check-footgun-coverage check-notes-supported check-program-covers-cells check-prose-duplication check-inline-links score-example-criteria check-quality-scores check-waiver-expiry check-no-figure-rationales check-journey-outcomes audit-example-graph quality-checks rubric-audit format-examples verify-python-version verify smoke-deployment post-deploy-smoke dev deploy upgrade-runtime-deps lint

check-node-version:
	@major="$$(node -p 'process.versions.node.split(".")[0]')"; \
	if test "$$major" != "22"; then \
		echo "Node 22 is required for Pywrangler/Pyodide (found $$(node --version))." >&2; \
		exit 1; \
	fi

$(NODE_DEPS_STAMP): package.json package-lock.json | check-node-version
	npm ci --ignore-scripts

node-deps: check-node-version $(NODE_DEPS_STAMP)

test:
	$(PY) python -m unittest discover -s tests -v

embed-examples:
	$(PY) scripts/embed_example_sources.py

embed-editorial-registry:
	$(PY) scripts/embed_editorial_registry.py

build-search-index: embed-examples
	$(PY) scripts/build_search_index.py

build: embed-examples embed-editorial-registry build-search-index fingerprint prototypes

check-generated: build check-social-cards
	git diff --exit-code src/example_sources_data.py src/editorial_registry_data.py src/asset_manifest.py public/_headers public/prototyping public/search-index.json
	# Tracked generated changes may be staged for commit; reject only untracked output here because git diff above already catches unstaged tracked drift.
	test -z "$$(git ls-files --others --exclude-standard -- public/prototyping public/*.css public/*.js public/*.json)"

fingerprint: embed-examples embed-editorial-registry build-search-index
	$(PY) scripts/fingerprint_assets.py

prototypes: embed-examples
	$(PY) scripts/build_prototypes.py
	$(PY) scripts/build_marginalia.py

browser-layout-test:
	scripts/check_browser_layout.mjs

search-ranking-test:
	scripts/check_search_ranking.mjs

social-cards:
	$(PY) scripts/build_social_cards.py
	scripts/build_social_cards.mjs

check-social-cards:
	$(PY) scripts/build_social_cards.py --check

seo-cache-lint:
	$(PY) scripts/lint_seo_cache.py

verify-examples: build
	$(PY) scripts/verify_examples.py

check-registry-integrity:
	$(PY) scripts/check_registry_integrity.py

check-confusable-pairs:
	$(PY) scripts/check_confusable_pairs.py

check-broad-surface-tours:
	$(PY) scripts/check_broad_surface_tours.py

check-footgun-coverage:
	$(PY) scripts/check_footgun_coverage.py

check-notes-supported:
	$(PY) scripts/check_notes_supported.py

check-program-covers-cells:
	$(PY) scripts/check_program_covers_cells.py

check-prose-duplication:
	$(PY) scripts/check_prose_duplication.py

check-inline-links:
	$(PY) scripts/check_inline_links.py

score-example-criteria:
	$(PY) scripts/score_example_criteria.py --limit 12

check-quality-scores:
	$(PY) scripts/check_quality_scores.py

# Manual gate, not run in CI: fail while a quality waiver has 30 days or fewer
# left, so an expiry can be caught before it turns every pull request red.
# `make verify` (CI) already prints a warning inside the same 30-day window.
check-waiver-expiry:
	$(PY) scripts/check_quality_scores.py --fail-within-days 30

check-no-figure-rationales:
	$(PY) scripts/check_no_figure_rationales.py

check-journey-outcomes:
	$(PY) scripts/check_journey_outcomes.py

audit-example-graph:
	$(PY) scripts/audit_example_graph.py --check

quality-checks: check-registry-integrity check-confusable-pairs check-broad-surface-tours check-footgun-coverage check-notes-supported check-program-covers-cells check-prose-duplication check-inline-links score-example-criteria check-quality-scores check-no-figure-rationales check-journey-outcomes audit-example-graph

rubric-audit:
	$(PY) scripts/audit_rubric_snapshot.py

format-examples:
	$(PY) scripts/format_examples.py

verify-python-version: build
	uv run --python $(VERSION) scripts/verify_examples.py --python-version $(VERSION)

lint:
	uv run ruff check src tests scripts

verify: build test seo-cache-lint verify-examples quality-checks browser-layout-test search-ranking-test lint check-generated

dev: node-deps
	uv run --group workers pywrangler dev --port 9696

smoke-deployment:
	$(PY) scripts/smoke_deployment.py $(URL) $(SMOKE_ARGS)

# Origin that `make deploy` smoke-tests once Wrangler has deployed. With
# Turnstile challenges enabled, export PBE_SMOKE_BYPASS_SECRET so the POST
# checks can run; SMOKE_ARGS passes extra flags (e.g. --skip-post) explicitly.
DEPLOY_URL ?= https://www.pythonbyexample.dev

post-deploy-smoke:
	@$(MAKE) --no-print-directory smoke-deployment URL=$(DEPLOY_URL) || { \
		echo "Deployment smoke FAILED for $(DEPLOY_URL). The new version is already live: investigate now, or roll back with 'uv run --group workers pywrangler rollback'." >&2; \
		exit 1; \
	}

deploy: node-deps check-generated
	uv run --group workers pywrangler sync --force
	git diff --exit-code -- pylock.toml
	uv run --group workers pywrangler deploy
	@$(MAKE) --no-print-directory post-deploy-smoke

# Production vendors pylock.toml; tests run against uv.lock. Refresh both together.
upgrade-runtime-deps: node-deps
	uv run --group workers pywrangler sync --force --upgrade
	$(PY) scripts/align_runtime_lock.py