Makefile

# Developer workflow: compositions of the cargo / cargo soothfast commands CI runs.
.PHONY: help check bot-check baselines gate spec spec-gate ci docs docs-pages llms-gate clean print-%

.DEFAULT_GOAL := help

CARGO := cargo
# Run the workspace's own cargo-soothfast so no installation is required.
# Debug: measurement runs in the bench binary and buildcost times a child
# cargo, so the CLI's optimization level reaches no measured number.
SOOTHFAST ?= $(CARGO) run -p cargo-soothfast --
BASE ?= origin/master

# rustdoc JSON is nightly-only and its format changes frequently. The pin
# lives in action.yml (the rustdoc-toolchain input default) so adopters and
# this repo bump it in one place.
export SOOTHFAST_RUSTDOC_TOOLCHAIN ?= $(shell sed -n 's/^ *default: \(nightly-[0-9-]*\)$$/\1/p' action.yml)

# Self-measuring bench crates; runs merge into the shared "self" baseline.
BENCH_CRATES := soothfast-registry soothfast-measure soothfast-docs \
                soothfast-spec soothfast-sdk soothfast-site soothfast-report
# Crates whose API reference the site carries (cargo-soothfast has no lib).
REF_CRATES := soothfast soothfast-macros soothfast-registry soothfast-measure \
              soothfast-docs soothfast-spec soothfast-sdk soothfast-site \
              soothfast-report

# Print any variable's value, so CI reads the pin from here instead of
# repeating it: `make -s print-SOOTHFAST_RUSTDOC_TOOLCHAIN`.
print-%:
	@echo $($*)

help: ## Show available commands
	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "\033[0;33m%-12s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)

check: ## fmt + clippy (-D warnings) + tests (--all-features: exercises the runner-gated doc examples)
	$(CARGO) fmt --all -- --check
	$(CARGO) clippy --workspace --all-targets --all-features -- -D warnings
	$(CARGO) test --workspace --all-features

bot-check: ## Type-check + test the soothfast-bot Worker, shellcheck the action scripts
	npm --prefix bot run check
	npm --prefix bot test
	shellcheck action/*.sh

baselines: ## Measure every self-bench crate into the "self" baseline
	@for crate in $(BENCH_CRATES); do \
		$(SOOTHFAST) measure -p $$crate --save-baseline self || exit 1; \
	done

gate: ## Merge-base gates vs $(BASE): self-benches + build cost
	$(SOOTHFAST) gate $(addprefix -p ,$(BENCH_CRATES)) --against-ref $(BASE)
	$(SOOTHFAST) gate -p soothfast --backend buildcost --against-ref $(BASE)
	$(SOOTHFAST) gate -p cargo-soothfast --backend buildcost --against-ref $(BASE)

spec: ## Regenerate every mode = "generate" spec file from the code
	$(SOOTHFAST) spec gen -p soothfast-spec

spec-gate: ## Fail on spec staleness or a consumer-breaking API change vs $(BASE)
	$(SOOTHFAST) spec gen -p soothfast-spec --check
	$(SOOTHFAST) spec gate -p soothfast-spec --base $(BASE)

ci: check baselines ## Everything PR CI runs: docs gated against this build's own run
	$(SOOTHFAST) docs check -p soothfast --baseline self README.md docs/index.md
	$(SOOTHFAST) docs capture -p soothfast --check README.md docs/index.md
	$(SOOTHFAST) docs check -p soothfast-measure --baseline self docs/measuring.md docs/gating.md
	$(SOOTHFAST) docs capture -p soothfast-measure --check docs/measuring.md docs/gating.md
	$(SOOTHFAST) docs check -p soothfast-docs --baseline self docs/living-docs.md
	$(SOOTHFAST) docs check -p soothfast-spec --baseline self docs/spec.md
	$(SOOTHFAST) docs capture -p soothfast-spec --check docs/spec.md
	$(SOOTHFAST) docs check -p soothfast-sdk --baseline self docs/sdk.md
	$(SOOTHFAST) docs check -p soothfast-report --baseline self docs/reports.md
	$(SOOTHFAST) docs capture -p soothfast-report --check docs/reports.md
	@$(MAKE) llms-gate
	@echo "All CI checks passed."

# Regenerate derived pages (API reference, perf report, coverage) from source
# + baselines. Not run-by-hand: `docs serve`'s live reload only rewatches
# docs_dir/soothfast.toml/theme_dir and rebuilds the *site* on change — it
# can't know when source code or measurements moved, so `docs` depends on
# this to make sure derived pages are fresh before serving.
docs-pages:
	@for crate in $(REF_CRATES); do \
		$(SOOTHFAST) docs reference -p $$crate --baseline self --out docs/reference || exit 1; \
	done
	$(SOOTHFAST) report render $(foreach crate,$(REF_CRATES),-p $(crate)) --baseline self --out docs/perf
	@mv docs/perf/llms.txt docs/llms.txt
	@cp docs/llms.txt llms.txt
	@{ echo "# Coverage"; echo; \
	   echo "> Generated by \`cargo soothfast coverage docs\`"; echo; \
	   echo '```text'; \
	   for crate in $(REF_CRATES); do $(SOOTHFAST) coverage docs -p $$crate; done; \
	   echo '```'; } > docs/coverage.md
	@$(SOOTHFAST) coverage docs $(foreach crate,$(REF_CRATES),-p $(crate)) \
		--badge docs/perf/badges/coverage.json \
		--badge docs/perf/badges/coverage.svg | tail -3

docs: docs-pages ## Regenerate derived pages, then serve the site locally with live reload
	$(SOOTHFAST) docs serve --baseline self

# llms.txt is checked in at repo root (unlike the other derived pages) so an
# agent reading the cloned repo sees it without a build step; this target is
# the drift gate that keeps that committed copy honest against fresh source.
# `**Measured:**` lines are excluded from the comparison: those numbers are
# point-in-time and jitter a little between any two measurement runs (see
# llms.rs) — regression detection is `make gate`'s job, not this one's.
llms-gate: ## Fail if the committed root llms.txt's docs/signatures are stale
	@rm -rf target/llms-check && mkdir -p target/llms-check
	$(SOOTHFAST) report render $(foreach crate,$(REF_CRATES),-p $(crate)) --baseline self --out target/llms-check
	@sed '/^\*\*Measured:\*\*/d' llms.txt > target/llms-check/committed.txt
	@sed '/^\*\*Measured:\*\*/d' target/llms-check/llms.txt > target/llms-check/fresh.txt
	@diff -u target/llms-check/committed.txt target/llms-check/fresh.txt || \
		(echo "error: llms.txt is stale — run 'make docs-pages' and commit the result" >&2 && exit 1)
	@rm -rf target/llms-check
	@echo "llms.txt: up to date"

clean: ## Remove build artifacts
	$(CARGO) clean