Makefile

# mx build/check driver.
# ============================================================================
#
# The generated mx::core C++ model lives in src/private/mx/core/generated
# (emitted by `make gen-cpp`, committed). Every gate runs through the pinned
# `mx-sdk` Docker toolchain: outside a container a target builds the image
# once and re-invokes itself inside it; inside (MX_RUNNING_IN_DOCKER, set by
# the image) it drives the tools directly. Setting MX_RUNNING_IN_DOCKER=1 on
# a dev machine runs natively with the host toolchain instead (used by the
# macOS CI job, which has no Docker). Requires CMake >= 3.13.
#
# ============================================================================

CMAKE      ?= cmake
DOCKER     ?= docker
BUILD_TYPE ?= Debug
BUILD_ROOT := build
JOBS       ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 4)

# Coverage report output. gcov-14 matches the pinned g++-14 toolchain.
COV_DIR := data/testOutput/coverage
GCOV    ?= gcov-14

# gen-quality / gen-lint: static analysis of the gen/ generator. The floors are
# the CI gate -- a build fails below them; ratchet them upward as the generator
# improves. gen-quality scores design (size + complexity); gen-lint enforces
# genuine lint defects. Pinned analyzers live in the mx-sdk venv (see
# Dockerfile). GEN_PY is every .py under gen/ except the measurer itself.
QUALITY_VENV      := /opt/quality-venv
QUALITY_DIR       := data/testOutput/gen-quality
GEN_PY            := $(shell find gen -name '*.py' ! -name quality.py | sort)
GEN_QUALITY_FLOOR ?= 84.5
GEN_LINT_FLOOR    ?= 9.29

# For GitHub Actions. When present, push/pull the Docker layer cache to the
# GitHub Actions cache.
ifneq ($(ACTIONS_RUNTIME_TOKEN),)
DOCKER_CACHE := --cache-from type=gha --cache-to type=gha,mode=max
endif

# Docker SDK image + build volume. Incremental state persists across runs.
# Volume name includes a path hash so parallel worktrees get isolated caches.
DOCKER_IMAGE  := mx-sdk
DOCKER_VOLUME ?= mx-build-$(shell printf '%s' '$(CURDIR)' | md5sum 2>/dev/null | cut -c1-8 || printf '%s' '$(CURDIR)' | md5 -q | cut -c1-8)
DOCKER_STAMP  := $(BUILD_ROOT)/.docker-image-stamp

# Prevent root-owned files on Linux.
UNAME_S := $(shell uname -s)
ifeq ($(UNAME_S),Linux)
DOCKER_USER := --user $(shell id -u):$(shell id -g)
endif

DOCKER_RUN := $(DOCKER) run --rm \
	-v $(CURDIR):/workspace \
	-v $(DOCKER_VOLUME):/workspace/build \
	$(DOCKER_USER) \
	$(DOCKER_IMAGE)

# C++ to format. Skip vendored pugixml and the cpul/Catch test harness.
FIND_CPP := find src \
	-path 'src/private/cpul' -prune -o \
	-name 'pugixml.cpp' -prune -o \
	-name 'pugixml.hpp' -prune -o \
	-name 'pugiconfig.hpp' -prune -o \
	-type f \( -name '*.cpp' -o -name '*.h' -o -name '*.hpp' \) -print

.DEFAULT_GOAL := help
.PHONY: help sdk fmt fmt-check test-all \
        core-build core-roundtrip-test core-unit core-coverage \
        api-lib api-build api-test api-examples api-roundtrip \
        api-roundtrip-discover api-roundtrip-dump api-roundtrip-classify api-coverage \
        gen-test audit-test gen-quality gen-lint \
        gen gen-cpp gen-go gen-c gen-schema \
        audit audit-force \
        build-go build-c test-go test-c \
        clean clean-docker check-docker docker-volume

help:
	@echo 'mx targets (see AGENTS.md). All run via the mx-sdk Docker toolchain;'
	@echo 'set MX_RUNNING_IN_DOCKER=1 to run natively on the host instead.'
	@echo ''
	@echo '  Everything C++ (the default deep gate, run in CI on Linux):'
	@echo '  make test-all       core-roundtrip-test + core-unit + api-test + api-roundtrip.'
	@echo ''
	@echo '  Product surface (mx::api / mx::impl):'
	@echo '  make api-lib             Build the mx static library (MX_API=ON).'
	@echo '  make api-build           Build mx + mxtest + examples + api-roundtrip binary.'
	@echo '  make api-test            Run examples + mxtest suite (api/impl/file/control).'
	@echo '  make api-examples        Build and run all three api example programs.'
	@echo '  make api-roundtrip       Run the corpus api roundtrip in regression mode (CI gate).'
	@echo '  make api-roundtrip-discover  Run discovery mode over the full corpus (manual only).'
	@echo '  make api-roundtrip-dump      Dump normalized expected/actual XML for failures.'
	@echo '  make api-roundtrip-classify  Classify dumped failures by root cause (Python).'
	@echo '  make api-coverage        Instrumented api/impl/utility build + gcovr report.'
	@echo ''
	@echo '  Core substrate (mx::core):'
	@echo '  make core-build          Build mx_core and the corert + unit test binaries.'
	@echo "  make core-roundtrip-test Run the core roundtrip suite. Filter: ARGS='[core-roundtrip] lysuite/*'"
	@echo '  make core-unit           Run the mx::core unit tests (values, shapes, rejection suite).'
	@echo '  make core-coverage       Instrumented build, corert + unit suites, gcovr -> $(COV_DIR)/.'
	@echo ''
	@echo '  Generator (gen/):'
	@echo '  make gen-test       Run the generator (parser + IR + plates + press) Python tests.'
	@echo '  make gen            Run the generator for every target (cpp/go/c/schema).'
	@echo '  make gen-cpp        Run the generator for the C++ target (src/private/mx/core/generated).'
	@echo '  make gen-go         Run the generator for the Go target.'
	@echo '  make gen-c          Run the generator for the C target.'
	@echo '  make gen-schema     Run the generator for the JSON Schema target.'
	@echo '  make gen-quality    Score gen/ design quality; fail below the floor.'
	@echo '  make gen-lint       Lint gen/ with pylint; fail below the floor.'
	@echo ''
	@echo '  Feature audit (audit/):'
	@echo '  make audit          Write missing *.features.xml sidecars + rebuild data/corpus.xml.'
	@echo '  make audit-force    Rewrite every *.features.xml sidecar (use after a format change).'
	@echo '  make audit-test     Run the audit tool Python tests (incl. failure classifier).'
	@echo ''
	@echo '  Generated Go target:'
	@echo '  make build-go       Build Go corert tests.'
	@echo '  make test-go        Run Go corert tests.'
	@echo ''
	@echo '  Generated C target:'
	@echo '  make build-c        Build C corert test binary.'
	@echo '  make test-c         Run C corert tests.'
	@echo ''
	@echo '  Housekeeping:'
	@echo '  make fmt            Format C++ under src/ via mx-sdk.'
	@echo '  make fmt-check      clang-format gate (checks formatting; builds nothing).'
	@echo '  make sdk            Build the mx-sdk Docker toolchain image.'
	@echo '  make clean          Remove the build/ tree and gen build artifacts.'
	@echo '  make clean-docker   Remove the sdk image and build volume.'

# --- Housekeeping -----------------------------------------------------------

clean:
	rm -rf $(BUILD_ROOT)
	rm -rf gen/test/c/build
	rm -rf gen/test/go/build

clean-docker:
	-rm -f $(DOCKER_STAMP)
	-$(DOCKER) rmi $(DOCKER_IMAGE) 2>/dev/null || true
	-$(DOCKER) volume rm $(DOCKER_VOLUME) 2>/dev/null || true
	@echo "Removed mx-sdk image and mx-build volume."

check-docker:
	@command -v $(DOCKER) >/dev/null 2>&1 || \
		{ echo "Docker not found. Install it to use the mx-sdk gates:"; \
		  echo "  https://docs.docker.com/get-docker/"; exit 1; }

# === Docker-gated targets ===================================================

ifdef MX_RUNNING_IN_DOCKER

# ----- Inside the container (or native via MX_RUNNING_IN_DOCKER=1) ----------

# All C++ suites: the core substrate (corert + unit) and the api product
# surface (mxtest + examples + corpus round-trip). The deep gate; CI runs it
# on Linux. gen/go/c and the audit tool are separate (see their targets).
test-all: core-roundtrip-test core-unit api-test api-roundtrip

api-lib:
	$(CMAKE) -S . -B $(BUILD_ROOT)/api -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) -DMX_API=on
	$(CMAKE) --build $(BUILD_ROOT)/api --target mx --parallel $(JOBS)

api-build: api-lib
	$(CMAKE) --build $(BUILD_ROOT)/api --parallel $(JOBS)

api-test: api-examples
	$(BUILD_ROOT)/api/mxtest $(ARGS)

api-examples: api-build
	$(BUILD_ROOT)/api/mxread
	$(BUILD_ROOT)/api/mxwrite $(BUILD_ROOT)/api/example.musicxml
	$(BUILD_ROOT)/api/mxhide
	@echo 'api-examples: all three examples ran successfully.'

# Corpus api roundtrip -- regression mode (CI gate): every file in the
# pinned baseline must pass; exit non-zero if any fails.
api-roundtrip: api-build
	$(BUILD_ROOT)/api/mxtest-api-roundtrip regression \
		$(CURDIR)/data \
		$(CURDIR)/src/private/mxtest/api/roundtrip-baseline.txt

# Discovery mode: walk the full corpus and report pass/fail.
# Never a CI gate; use to grow the pinned list (manual commits only).
api-roundtrip-discover: api-build
	$(BUILD_ROOT)/api/mxtest-api-roundtrip discovery $(CURDIR)/data

# Dump normalized expected/actual XML for every failing api round-trip.
# Output goes to build/api/roundtrip-dump/ (build dir, already gitignored).
# Feeds the classifier: make api-roundtrip-dump && make api-roundtrip-classify
api-roundtrip-dump: api-build
	rm -rf $(BUILD_ROOT)/api/roundtrip-dump
	mkdir -p $(BUILD_ROOT)/api/roundtrip-dump
	$(BUILD_ROOT)/api/mxtest-api-roundtrip discovery $(CURDIR)/data \
		--dump $(CURDIR)/$(BUILD_ROOT)/api/roundtrip-dump

# Classify api round-trip failures by root cause.
# Reads the dump produced by api-roundtrip-dump; writes build/api/classified.json.
# Fast (pure Python); kept separate from the slow dump step so classification
# logic can be re-run without re-dumping. Pass DUMP_DIR=path to override.
DUMP_DIR ?= $(BUILD_ROOT)/api/roundtrip-dump
api-roundtrip-classify:
	python3 -m audit classify $(DUMP_DIR) \
		--data $(CURDIR)/data \
		--out $(BUILD_ROOT)/api/classified.json

# Instrumented api coverage: build mx+mxtest with --coverage, run all
# suites, produce gcovr report for src/private/mx/{api,impl,utility}/.
api-coverage:
	@echo "=== build (api, instrumented) ==="
	$(CMAKE) -S . -B $(BUILD_ROOT)/cov-api \
		-DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \
		-DCMAKE_C_COMPILER_LAUNCHER= \
		-DCMAKE_CXX_COMPILER_LAUNCHER= \
		-DMX_API=on \
		-DMX_COVERAGE=on
	$(CMAKE) --build $(BUILD_ROOT)/cov-api --parallel $(JOBS)
	@echo "=== run mxtest + corpus roundtrip ==="
	$(BUILD_ROOT)/cov-api/mxtest
	$(BUILD_ROOT)/cov-api/mxtest-api-roundtrip regression \
		$(CURDIR)/data \
		$(CURDIR)/src/private/mxtest/api/roundtrip-baseline.txt
	@echo "=== gcovr report (src/private/mx/{api,impl,utility}/) ==="
	@mkdir -p $(COV_DIR)/api
	gcovr --root . \
		--gcov-executable '$(GCOV)' \
		--filter 'src/private/mx/api/' \
		--filter 'src/private/mx/impl/' \
		--filter 'src/private/mx/utility/' \
		--print-summary \
		--txt $(COV_DIR)/api/coverage.txt \
		--xml $(COV_DIR)/api/coverage.xml \
		--html-self-contained --html $(COV_DIR)/api/index.html \
		$(BUILD_ROOT)/cov-api | tee $(COV_DIR)/api/summary.txt
	@echo "=== api-coverage written to $(COV_DIR)/api/ ==="

core-build:
	$(CMAKE) -S . -B $(BUILD_ROOT)/core-dev -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) -DMX_CORE_DEV=on
	$(CMAKE) --build $(BUILD_ROOT)/core-dev --parallel $(JOBS)

core-roundtrip-test: core-build
	$(BUILD_ROOT)/core-dev/mxtest-core-dev --allow-running-no-tests $(ARGS)

core-unit: core-build
	$(BUILD_ROOT)/core-dev/mxtest-core $(ARGS)

# Instrumented core coverage: build with --coverage (off ccache so the
# notes/data stay exact), run the corert AND unit suites, then gcovr. The
# report lands in $(COV_DIR) on the bind-mounted workspace. Filtered to
# src/private/mx/core/ -- the generated model and its runtime.
core-coverage:
	@echo "=== build (core, instrumented) ==="
	$(CMAKE) -S . -B $(BUILD_ROOT)/cov-core-dev \
		-DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \
		-DCMAKE_C_COMPILER_LAUNCHER= \
		-DCMAKE_CXX_COMPILER_LAUNCHER= \
		-DMX_CORE_DEV=on \
		-DMX_COVERAGE=on
	$(CMAKE) --build $(BUILD_ROOT)/cov-core-dev --parallel $(JOBS)
	@echo "=== run corert + unit suites ==="
	$(BUILD_ROOT)/cov-core-dev/mxtest-core-dev --allow-running-no-tests $(ARGS)
	$(BUILD_ROOT)/cov-core-dev/mxtest-core
	@echo "=== gcovr report (src/private/mx/core/) ==="
	@mkdir -p $(COV_DIR)
	gcovr --root . \
		--gcov-executable '$(GCOV)' \
		--filter 'src/private/mx/core/' \
		--print-summary \
		--txt $(COV_DIR)/coverage.txt \
		--xml $(COV_DIR)/coverage.xml \
		--html-self-contained --html $(COV_DIR)/index.html \
		$(BUILD_ROOT)/cov-core-dev | tee $(COV_DIR)/summary.txt
	@echo "=== coverage written to $(COV_DIR)/ ==="

gen-test:
	python3 -m unittest discover -s gen/tests -t . $(ARGS)

# Audit tool Python tests (feature-audit + the round-trip failure classifier).
audit-test:
	python3 -m unittest discover -s audit/tests -t . $(ARGS)

# Static analysis of the gen/ generator. quality.py measures and writes the
# report tree to the workspace mount; the floor check below is the gate.
gen-quality:
	@$(QUALITY_VENV)/bin/python gen/quality.py --floor $(GEN_QUALITY_FLOOR)
	@score=$$(python3 -c "import json; print(json.load(open('$(QUALITY_DIR)/score.json'))['composite'])"); \
	 if awk "BEGIN{exit !($$score < $(GEN_QUALITY_FLOOR))}"; then \
	   echo "ERROR: gen-quality $$score is below floor $(GEN_QUALITY_FLOOR)"; exit 1; \
	 else echo "=== gen-quality OK: $$score >= floor $(GEN_QUALITY_FLOOR) ==="; fi

# pylint as a binary gate (model-A ratchet). --exit-zero so the parsed rating,
# not pylint's message-category exit bitmask, decides pass/fail.
gen-lint:
	@out=$$($(QUALITY_VENV)/bin/pylint --rcfile=gen/.pylintrc --exit-zero $(GEN_PY) 2>&1); \
	 echo "$$out"; \
	 rating=$$(echo "$$out" | sed -n 's/.*rated at \([0-9.]*\)\/10.*/\1/p'); \
	 if [ -z "$$rating" ]; then echo "ERROR: gen-lint could not parse a pylint rating"; exit 1; fi; \
	 if awk "BEGIN{exit !($$rating < $(GEN_LINT_FLOOR))}"; then \
	   echo "ERROR: gen-lint rating $$rating is below floor $(GEN_LINT_FLOOR)"; exit 1; \
	 else echo "=== gen-lint OK: $$rating >= floor $(GEN_LINT_FLOOR) ==="; fi

fmt:
	@$(FIND_CPP) | xargs -r clang-format -i
	@echo "Formatted C++ under src/."

fmt-check:
	@$(FIND_CPP) | xargs -r clang-format --dry-run --Werror
	@echo "fmt-check passed."

gen: gen-cpp gen-go gen-c gen-schema

gen-cpp:
	python3 -m gen gen/cpp/config.toml

gen-go:
	python3 -m gen gen/test/go/config.toml

gen-c:
	python3 -m gen gen/test/c/config.toml

gen-schema:
	python3 -m gen gen/schema/config.toml

# Feature audit: inventory which MusicXML features the corpus uses, for comparing
# against mx::api support. See audit/README.md and the mx-api-feature-audit skill.
audit:
	python3 -m audit all

audit-force:
	python3 -m audit all --force

build-go:
	cd gen/test/go && MX_REPO_ROOT=$(CURDIR) go test -c -o build/corert-test ./corert/

test-go:
	cd gen/test/go && MX_REPO_ROOT=$(CURDIR) go test -count=1 -v ./corert/ $(ARGS)

build-c:
	$(CMAKE) -S gen/test/c -B gen/test/c/build \
		-DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \
		-DMX_REPO_ROOT=$(CURDIR)
	$(CMAKE) --build gen/test/c/build --parallel $(JOBS)

test-c: build-c
	gen/test/c/build/corert-c

else

# ----- Outside the container: build image, then docker run ------------------

$(DOCKER_STAMP): Dockerfile | check-docker
	@mkdir -p $(BUILD_ROOT)
	$(DOCKER) buildx build $(DOCKER_CACHE) --load -t $(DOCKER_IMAGE) . \
		|| $(DOCKER) build -t $(DOCKER_IMAGE) .
	@touch $@

sdk: $(DOCKER_STAMP)

docker-volume: | check-docker
	@$(DOCKER) volume inspect $(DOCKER_VOLUME) >/dev/null 2>&1 \
		|| $(DOCKER) volume create $(DOCKER_VOLUME) >/dev/null

test-all: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make test-all BUILD_TYPE=$(BUILD_TYPE) ARGS='$(ARGS)'

api-lib: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make api-lib BUILD_TYPE=$(BUILD_TYPE)

api-build: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make api-build BUILD_TYPE=$(BUILD_TYPE)

api-test: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make api-test BUILD_TYPE=$(BUILD_TYPE) ARGS='$(ARGS)'

api-examples: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make api-examples BUILD_TYPE=$(BUILD_TYPE)

api-roundtrip: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make api-roundtrip BUILD_TYPE=$(BUILD_TYPE)

api-roundtrip-discover: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make api-roundtrip-discover BUILD_TYPE=$(BUILD_TYPE)

api-roundtrip-dump: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make api-roundtrip-dump BUILD_TYPE=$(BUILD_TYPE)
	@rm -rf $(BUILD_ROOT)/api/roundtrip-dump
	@mkdir -p $(BUILD_ROOT)/api/roundtrip-dump
	$(DOCKER) run --rm -v $(DOCKER_VOLUME):/vol:ro -v $(CURDIR)/$(BUILD_ROOT)/api/roundtrip-dump:/out \
		alpine sh -c 'cp -a /vol/api/roundtrip-dump/. /out/'

api-roundtrip-classify: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make api-roundtrip-classify BUILD_TYPE=$(BUILD_TYPE)
	@mkdir -p $(BUILD_ROOT)/api
	$(DOCKER) run --rm -v $(DOCKER_VOLUME):/vol:ro -v $(CURDIR)/$(BUILD_ROOT)/api:/out \
		alpine cp /vol/api/classified.json /out/classified.json

api-coverage: $(DOCKER_STAMP) docker-volume
	@rm -rf $(COV_DIR)/api
	$(DOCKER_RUN) make api-coverage BUILD_TYPE=$(BUILD_TYPE) ARGS='$(ARGS)'
	@echo "API coverage written to $(COV_DIR)/api/ (open $(COV_DIR)/api/index.html)"

core-build: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make core-build BUILD_TYPE=$(BUILD_TYPE)

core-roundtrip-test: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make core-roundtrip-test BUILD_TYPE=$(BUILD_TYPE) ARGS='$(ARGS)'

core-unit: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make core-unit BUILD_TYPE=$(BUILD_TYPE) ARGS='$(ARGS)'

core-coverage: $(DOCKER_STAMP) docker-volume
	@rm -rf $(COV_DIR)
	$(DOCKER_RUN) make core-coverage BUILD_TYPE=$(BUILD_TYPE) ARGS='$(ARGS)'
	@echo "Coverage written to $(COV_DIR)/ (open $(COV_DIR)/index.html)"

gen-test: $(DOCKER_STAMP)
	$(DOCKER_RUN) make gen-test ARGS='$(ARGS)'

audit-test: $(DOCKER_STAMP)
	$(DOCKER_RUN) make audit-test ARGS='$(ARGS)'

gen-quality: $(DOCKER_STAMP)
	@rm -rf $(QUALITY_DIR)
	$(DOCKER_RUN) make gen-quality

gen-lint: $(DOCKER_STAMP)
	$(DOCKER_RUN) make gen-lint

fmt: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make fmt

fmt-check: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make fmt-check

gen: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make gen

gen-cpp: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make gen-cpp

gen-go: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make gen-go

gen-c: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make gen-c

gen-schema: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make gen-schema

audit: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make audit

audit-force: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make audit-force

build-go: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make build-go

test-go: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make test-go ARGS='$(ARGS)'

build-c: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make build-c BUILD_TYPE=$(BUILD_TYPE)

test-c: $(DOCKER_STAMP) docker-volume
	$(DOCKER_RUN) make test-c BUILD_TYPE=$(BUILD_TYPE)

endif