Makefile

PORT ?= 4017
BIND ?= 0.0.0.0
RUBY_VERSION_REQUIRED ?= 3.4
NODE_VERSION_REQUIRED ?= 22

.DEFAULT_GOAL := help

export RUBY_VERSION_REQUIRED
export NODE_VERSION_REQUIRED

# The Codex desktop shell can inherit a truncated exported Bash function for
# Midnight Commander. Dash imports it before every recipe line and prints
# syntax errors, which makes `make doctor` look broken even when checks pass.
unexport BASH_FUNC_mc%%

.PHONY: help doctor install frontend frontend-watch build test lint check-public-pages ci-local pre-release verify-release-surface verify-benchmarks verify-use-cases verify-cli-release verify-rust-snippets verify-hospital-tutorial verify-lessons-tutorial verify-deliveries-tutorial verify-fsr-tutorial verify-maintenance-walkthrough verify-cli-getting-started verify-serio-page start clean version verify-rust-snippets-legacy verify-solver-config verify-ui-getting-started verify-python-docs verify-companion-docs

define status
	@printf '\n==> %s\n' "$(1)"
endef

help:
	@printf 'SolverForge.org Bridgetown site\n\n'
	@printf 'Setup\n'
	@printf '  make doctor                     Verify local Ruby, Bundler, Node, and npm\n'
	@printf '  make install                    Install Ruby gems and Node packages\n'
	@printf '\nBuild and run\n'
	@printf '  make frontend                   Build esbuild assets\n'
	@printf '  make frontend-watch             Watch esbuild assets during development\n'
	@printf '  make build                      Build frontend assets and Bridgetown output\n'
	@printf '  make start                      Serve locally on BIND=%s PORT=%s\n' "$(BIND)" "$(PORT)"
	@printf '  make clean                      Remove Bridgetown build output\n'
	@printf '\nQuality gates\n'
	@printf '  make test                       Build in test mode and verify worked examples\n'
	@printf '  make lint                       Run Ruby and JavaScript syntax checks\n'
	@printf '  make check-public-pages         Check public copy, internal links, nav, and layout\n'
	@printf '  make verify-release-surface     Verify current package and app version contracts\n'
	@printf '  make verify-benchmarks          Verify recorded full-run benchmark evidence\n'
	@printf '  make verify-use-cases           Verify the use-case showcase content and assets\n'
	@printf '  make verify-cli-release         Install the published CLI and verify scaffold targets\n'
	@printf '  make verify-rust-snippets       Compile Rust library doc blocks against crates.io solverforge, run shown outputs\n'
	@printf '  make verify-rust-snippets-legacy Compile-check Rust snippets on pages not yet in that scope\n'
	@printf '  make verify-hospital-tutorial   Replay, build, and solve both hospital tutorial paths\n'
	@printf '  make verify-lessons-tutorial    Replay the lessons page: CLI build, Space clone, solves\n'
	@printf '  make verify-deliveries-tutorial Replay the deliveries page: CLI build, Space clone, solves\n'
	@printf '  make verify-fsr-tutorial        Replay the FSR page: CLI build, Space clone, solves\n'
	@printf '  make verify-maintenance-walkthrough Replay, test, and solve the agent-skill walkthrough\n'
	@printf '  make verify-cli-getting-started Replay, build, and solve the CLI Getting Started page\n'
	@printf '  make verify-serio-page          Run the SERIO page trace and compare it with the page\n'
	@printf '  make verify-solver-config       Parse/solve every solver-page TOML block and run its lifecycle snippets\n'
	@printf '  make verify-ui-getting-started  Build, boot, and browser-load the solverforge-ui Getting Started app\n'
	@printf '  make verify-python-docs         Replay the Python pages against the PyPI package\n'
	@printf '  make verify-companion-docs      Check maps, bench, and boundary pages against published sources\n'
	@printf '  make ci-local                   Run the same gate used by CI\n'
	@printf '  make pre-release                Run the release-readiness gate\n'
	@printf '\nInspection\n'
	@printf '  make version                    Print toolchain and site tool versions\n'

doctor:
	$(call status,Checking required tools)
	@command -v ruby >/dev/null || { printf 'missing required command: ruby\n' >&2; exit 1; }
	@command -v bundle >/dev/null || { printf 'missing required command: bundle\n' >&2; exit 1; }
	@command -v node >/dev/null || { printf 'missing required command: node\n' >&2; exit 1; }
	@command -v npm >/dev/null || { printf 'missing required command: npm\n' >&2; exit 1; }
	@ruby -e 'required = ENV.fetch("RUBY_VERSION_REQUIRED"); actual = RUBY_VERSION; abort("Ruby #{required}.x or newer required; found #{actual}") unless actual.split(".").first.to_i >= required.to_i'
	@node -e 'const required = Number(process.env.NODE_VERSION_REQUIRED); const actual = Number(process.versions.node.split(".")[0]); if (actual < required) { console.error(`Node $${required}.x or newer required; found $${process.versions.node}`); process.exit(1); }'
	@printf 'Ruby:   '; ruby -v
	@printf 'Bundler: '; bundle -v
	@printf 'Node:   '; node -v
	@printf 'npm:    '; npm -v

install:
	$(call status,Installing Ruby gems)
	@bundle install
	$(call status,Installing Node packages)
	@npm ci

frontend:
	$(call status,Building frontend assets)
	@bundle exec rake frontend:build

frontend-watch:
	$(call status,Watching frontend assets)
	@bundle exec rake frontend:dev

build: frontend
	$(call status,Building Bridgetown site)
	@bundle exec bridgetown build

test: frontend verify-benchmarks
	$(call status,Building Bridgetown site in test mode)
	@BRIDGETOWN_ENV=test bundle exec rake test
	$(call status,Verifying current release documentation contracts)
	@ruby scripts/verify-release-surface.rb
	$(call status,Verifying use-case showcase contract)
	@ruby scripts/verify-use-cases-page.rb
	$(call status,Verifying hospital tutorial page contract)
	@ruby scripts/verify-hospital-tutorial.rb --static
	$(call status,Verifying lessons tutorial page contract)
	@ruby scripts/verify-lessons-tutorial.rb --static
	$(call status,Verifying deliveries tutorial page contract)
	@ruby scripts/verify-deliveries-tutorial.rb --static
	$(call status,Verifying FSR tutorial page contract)
	@ruby scripts/verify-fsr-tutorial.rb --static
	$(call status,Verifying maintenance walkthrough page contract)
	@ruby scripts/verify-maintenance-walkthrough.rb --static
	$(call status,Verifying CLI Getting Started page contract)
	@ruby scripts/verify-cli-getting-started.rb --static
	$(call status,Verifying SERIO page contract)
	@ruby scripts/verify-serio-page.rb --static
	$(call status,Verifying Rust snippet page contract)
	@ruby scripts/verify-rust-snippets.rb --static
	$(call status,Verifying solver page config/snippet contract)
	@ruby scripts/verify-solver-config.rb --static
	$(call status,Verifying Python docs page contract)
	@ruby scripts/verify-python-docs.rb --static
	$(call status,Verifying maps, bench, and boundary pages against published sources)
	@ruby scripts/verify-companion-docs.rb

lint:
	$(call status,Checking Ruby syntax)
	@ruby -c Gemfile
	@ruby -c Rakefile
	@find . \( -path './.git' -o -path './.bridgetown-cache' -o -path './node_modules' -o -path './output' -o -path './vendor' \) -prune -o -name '*.rb' -print0 | xargs -0 -n 1 ruby -c
	$(call status,Checking JavaScript syntax)
	@find . \( -path './.git' -o -path './.bridgetown-cache' -o -path './node_modules' -o -path './output' -o -path './vendor' \) -prune -o \( -name '*.js' -o -name '*.mjs' \) -print0 | xargs -0 -n 1 node --check

check-public-pages:
	$(call status,Checking public page copy, links, nav, and layout)
	@node scripts/check-public-pages.mjs

# Use-case pages replayed end to end (CLI build, Space clone, solves, the
# page's validation commands). CI runs them in their own matrix job.
TUTORIAL_REPLAYS ?= verify-hospital-tutorial verify-lessons-tutorial verify-deliveries-tutorial verify-fsr-tutorial

ci-local: doctor lint verify-release-surface verify-benchmarks verify-use-cases verify-rust-snippets verify-rust-snippets-legacy verify-solver-config verify-companion-docs build check-public-pages verify-ui-getting-started verify-python-docs verify-maintenance-walkthrough verify-cli-getting-started verify-serio-page $(TUTORIAL_REPLAYS)

pre-release: verify-cli-release ci-local
	$(call status,Ready for release)

verify-cli-release:
	$(call status,Verifying published solverforge-cli release)
	@ruby scripts/verify-cli-release.rb

verify-release-surface:
	$(call status,Verifying current release documentation contracts)
	@ruby scripts/verify-release-surface.rb

verify-benchmarks:
	$(call status,Verifying recorded full-run benchmark evidence)
	@ruby scripts/verify-benchmarks.rb

verify-use-cases:
	$(call status,Verifying the use-case showcase contract)
	@ruby scripts/verify-use-cases-page.rb

verify-rust-snippets:
	$(call status,Compiling and running Rust library documentation blocks)
	@ruby scripts/verify-rust-snippets.rb

verify-rust-snippets-legacy:
	$(call status,Verifying Rust snippets outside the compiled scope)
	@ruby scripts/verify-rust-snippets-legacy.rb

verify-hospital-tutorial:
	$(call status,Replaying and solving both hospital tutorial paths)
	@ruby scripts/verify-hospital-tutorial.rb

verify-lessons-tutorial:
	$(call status,Replaying, building, and solving the lessons tutorial)
	@ruby scripts/verify-lessons-tutorial.rb

verify-deliveries-tutorial:
	$(call status,Replaying, building, and solving the deliveries tutorial)
	@ruby scripts/verify-deliveries-tutorial.rb

verify-fsr-tutorial:
	$(call status,Replaying, building, and solving the FSR tutorial)
	@ruby scripts/verify-fsr-tutorial.rb

verify-maintenance-walkthrough:
	$(call status,Replaying and solving the maintenance walkthrough)
	@ruby scripts/verify-maintenance-walkthrough.rb

verify-cli-getting-started:
	$(call status,Replaying and solving the CLI Getting Started page)
	@ruby scripts/verify-cli-getting-started.rb

verify-serio-page:
	$(call status,Tracing one move through SERIO against the page)
	@ruby scripts/verify-serio-page.rb

verify-solver-config:
	$(call status,Parsing and solving solver-page config blocks; running lifecycle snippets)
	@ruby scripts/verify-solver-config.rb
verify-ui-getting-started:
	$(call status,Building and browser-loading the solverforge-ui Getting Started app)
	@ruby scripts/verify-ui-getting-started.rb

verify-python-docs:
	$(call status,Replaying the Python docs against the PyPI package)
	@ruby scripts/verify-python-docs.rb

verify-companion-docs:
	$(call status,Checking maps, bench, and boundary pages against published sources)
	@ruby scripts/verify-companion-docs.rb

start:
	$(call status,Starting Bridgetown on $(BIND):$(PORT))
	@bundle exec bridgetown start -P $(PORT) -B $(BIND)

clean:
	$(call status,Cleaning Bridgetown output)
	@bundle exec bridgetown clean

version:
	$(call status,Tool versions)
	@printf 'Ruby:      '; ruby -v
	@printf 'Bundler:   '; bundle -v
	@printf 'Node:      '; node -v
	@printf 'npm:       '; npm -v
	@printf 'Bridgetown: '; bundle exec bridgetown -v