Makefile

MAKE_MAJOR_VER    := $(shell echo $(MAKE_VERSION) | cut -d'.' -f1)

ifneq ($(shell test $(MAKE_MAJOR_VER) -gt 3; echo $$?),0)
$(error Make version $(MAKE_VERSION) is not supported, please install GNU Make 4.x)
endif

# Strict shell and Make settings for robust recipes
SHELL          := bash
.SHELLFLAGS    := -eu -o pipefail -c
.DELETE_ON_ERROR:
MAKEFLAGS      += --warn-undefined-variables
MAKEFLAGS      += --no-builtin-rules
.DEFAULT_GOAL  := help

# Directory path of Makefile
BASE_DIR       := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))

# Path to the Python bindings crate. Absolute path so the recipes
# below resolve correctly even when Make is invoked from a nested
# directory. BASE_DIR ends in a trailing slash (from $(dir ...))
# which absorbs into the concatenation; BCA_PY_DIR has no trailing
# slash and that's intended (matches how cargo / maturin invocations
# read it).
BCA_PY_DIR     := $(BASE_DIR)big-code-analysis-py

# The release/wheel smoke harness lives outside the bindings package, so the
# package-scoped py-* gates below pull it in explicitly (#995). Linting it
# with the bindings' ruff/mypy config — rather than letting it drift outside
# every per-PR gate — is the whole point of extracting it from workflow YAML
# (lesson #80). `--config` forces the bindings config since there is no
# config to discover from scripts/smoke upward.
SMOKE_PY_DIR   := $(BASE_DIR)scripts/smoke
SMOKE_LIB_PY   := $(SMOKE_PY_DIR)/lib_wheel_smoke.py

# Directories excluded from linting and file-search operations.
# `tests/repositories` holds vendored fixtures (incl. the
# big-code-analysis-output submodule); `tree-sitter-*` are vendored
# grammar crates that follow upstream conventions; `enums/` is excluded
# from the workspace and owns its own files. None of these may be
# reformatted by this project's tooling. Glob entries (e.g. `tree-sitter-*`)
# are quoted at the use site below — keep this list plain.
EXCLUDE_DIRS   := .claude .git target tests/repositories \
                  big-code-analysis-book/book \
                  tree-sitter-* enums

# File finder: prefer fd/fdfind (fast, .gitignore-aware), fall back to find
FD             := $(shell command -v fdfind 2>/dev/null || command -v fd 2>/dev/null)

# Precomputed exclusion flags for fd and find. Single-quote each entry so
# the recipe shell does not glob-expand patterns like `tree-sitter-*` into
# absolute paths before fd/find see them (see #160). `find -path` uses its
# own glob engine and accepts unquoted patterns the same way fd does.
FD_EXCLUDE     := $(foreach dir,$(EXCLUDE_DIRS),--exclude '$(dir)')
FIND_EXCLUDE   := $(foreach dir,$(EXCLUDE_DIRS),! -path './$(dir)/*')

# Find files by extension with fd (preferred) or find (fallback).
# Usage: $(call find-by-ext,EXTENSION,EXTRA_FD_ARGS). Always pass the
# second arg (empty if unused) to avoid --warn-undefined-variables
# warnings on `$(2)`, e.g. $(call find-by-ext,md,).
find-by-ext = $(if $(FD),$(FD) --extension $(1) $(FD_EXCLUDE) $(2),find . -name "*.$(1)" -type f $(FIND_EXCLUDE))

# Test runner: prefer cargo-nextest, fall back to `cargo test` (#1120).
# `cargo test` runs the workspace's 72 test binaries strictly one after
# another — parallelism exists only *within* a binary, so the ten root
# integration binaries that hold a single `#[test]` each pin the whole
# machine to one core for their duration. nextest schedules every
# binary's tests into one global pool instead. CI already runs nextest
# (the `test` job in .github/workflows/ci.yml); this is the local half.
#
# The two paths execute an identical target set: nextest's default
# selection is exactly `--lib --bins --tests`, verified by diffing
# `cargo nextest list --workspace --all-features` against the same
# invocation with those flags spelled out (4,731 tests, plus the 10
# `#[ignore]`d ones both runners skip).
#
# Expect a smaller wall-clock win than the scheduling change implies:
# one test (`cfg_predicate::tests::rust_attr_test_handles_deeply_nested_
# cfg_without_overflow`, the O(len^2) blowup tracked in #1105) runs for
# ~78s and is now the critical path. The other 4,730 finish in ~17s
# together, so fixing #1105 is what converts this into a ~4x win.
#
# Held in a variable rather than probed inline with `command -v`, and used
# as the command itself, so it overrides the same way `FD` above does:
# `make test NEXTEST=` exercises the fallback without uninstalling
# anything, and `make test NEXTEST=/path/to/cargo-nextest` picks a
# specific build. A cargo subcommand binary takes its own name as the
# first argument, hence `$(NEXTEST) nextest run`.
NEXTEST        := $(shell command -v cargo-nextest 2>/dev/null)
TEST_CMD       = $(if $(NEXTEST),$(NEXTEST) nextest run --workspace --all-features,cargo test --workspace --all-features --lib --bins --tests)

.PHONY: help check-tools worktree-setup worktree-setup-test build build-release check test test-doc chain-audit fmt fmt-check markdown-fmt markdown-lint shellcheck sh-fmt sh-fmt-check toml-fmt toml-fmt-check toml-lint makefile-check actionlint snapshot-anchors snapshot-anchors-test rustfmt-bail rustfmt-bail-test grammar-marker-sync grammar-marker-sync-test check-versions check-excluded-manifests check-excluded-manifests-test check-ruff-lockstep check-ruff-lockstep-test check-publish-metadata check-publish-metadata-test check-manpage-assets check-manpage-drift-test check-diagnostic-prefix check-diagnostic-prefix-test check-feature-gates check-feature-gates-test check-test-lang-gates check-test-lang-gates-compare check-test-lang-gates-test check-safety-doc-pin check-safety-doc-pin-test gate-status-test check-tools-test enums-check enums-codegen-drift enums-codegen-drift-test self-scan self-scan-headroom self-scan-write-baseline self-scan-write-baseline-headroom vcs lint clippy udeps insta-review insta-accept clean distclean install install-cli install-web doc doc-open doc-check doc-check-docsrs book book-serve book-pot book-po-update book-ja book-deploy all pre-commit ci release-check verify-changelog pkg-deb-local pkg-rpm-local dev-env-build dev-env-run dev-env-shell dev-env-rm py-bootstrap py-sync py-relock py-clean py-fmt py-fmt-check py-lint py-typecheck py-test py-stubtest smoke smoke-cli smoke-lib bench bench-scaling bench-walk fuzz-check fuzz-smoke fuzz-replay fuzz-run fuzz-tmin _check-find _pc-all _pc-fmt _pc-clippy _pc-test _pc-doc-check _pc-udeps _pc-shellcheck _pc-markdown-lint _pc-toml-lint _pc-makefile-check _pc-actionlint _pc-snapshot-anchors _pc-snapshot-anchors-test _pc-rustfmt-bail _pc-rustfmt-bail-test _pc-grammar-marker-sync _pc-grammar-marker-sync-test _pc-check-versions _pc-check-versions-test _pc-check-grammar-crate-test _pc-check-excluded-manifests _pc-check-excluded-manifests-test _pc-check-ruff-lockstep _pc-check-ruff-lockstep-test _pc-check-publish-metadata _pc-check-publish-metadata-test _pc-check-manpage-assets _pc-check-manpage-drift-test _pc-check-diagnostic-prefix _pc-check-diagnostic-prefix-test _pc-check-feature-gates-test _pc-check-test-lang-gates _pc-check-test-lang-gates-test _pc-check-safety-doc-pin _pc-check-safety-doc-pin-test _pc-worktree-setup-test _pc-gate-status-test _pc-check-tools-test _pc-enums-check _pc-enums-codegen-drift _pc-enums-codegen-drift-test _pc-self-scan _pc-self-scan-headroom _pc-py-fmt _pc-py-typecheck _pc-py-test _pc-py-stubtest _ci-all _ci-fmt-check _ci-clippy _ci-test _ci-doc-check _ci-build _ci-udeps _ci-shellcheck _ci-markdown-lint _ci-toml-lint _ci-makefile-check _ci-actionlint _ci-snapshot-anchors _ci-snapshot-anchors-test _ci-rustfmt-bail _ci-rustfmt-bail-test _ci-grammar-marker-sync _ci-grammar-marker-sync-test _ci-check-versions _ci-check-versions-test _ci-check-grammar-crate-test _ci-check-excluded-manifests _ci-check-excluded-manifests-test _ci-check-ruff-lockstep _ci-check-ruff-lockstep-test _ci-check-publish-metadata _ci-check-publish-metadata-test _ci-check-manpage-assets _ci-check-manpage-drift-test _ci-check-diagnostic-prefix _ci-check-diagnostic-prefix-test _ci-check-feature-gates-test _ci-check-test-lang-gates _ci-check-test-lang-gates-test _ci-check-safety-doc-pin _ci-check-safety-doc-pin-test _ci-worktree-setup-test _ci-gate-status-test _ci-check-tools-test _ci-enums-check _ci-enums-codegen-drift _ci-enums-codegen-drift-test _ci-enums-codegen-drift-test _ci-self-scan _ci-self-scan-headroom _ci-cargo-pipeline _ci-py-fmt-check _ci-py-lint _ci-py-typecheck _ci-py-test _ci-py-stubtest

# Default target
help:
	@echo "Build and test commands for big-code-analysis"
	@echo ""
	@echo "Usage: make <target>"
	@echo ""
	@echo "Prerequisites:"
	@echo "  check-tools                          Verify required tools are present"
	@echo "  worktree-setup                       Bootstrap a fresh clone/worktree: corpora + Python venv"
	@echo ""
	@echo "Build targets:"
	@echo "  build                                Build debug binaries"
	@echo "  build-release                        Build optimized release binaries"
	@echo "  check                                Run cargo check"
	@echo ""
	@echo "Test targets:"
	@echo "  test                                 Run unit and integration tests (nextest if present)"
	@echo "  test-doc                             Run cargo doc tests"
	@echo "  chain-audit                          Re-run the suite with the exact ancestor-chain assertion (out-of-band)"
	@echo "  insta-review                         Review pending insta snapshot diffs"
	@echo "  insta-accept                         Accept all pending insta snapshots"
	@echo ""
	@echo "Code quality:"
	@echo "  fmt                                  Format Rust + Markdown + TOML + Bash"
	@echo "  fmt-check                            Verify formatting without modifying files"
	@echo "  clippy                               Run clippy with -D warnings"
	@echo "  udeps                                Detect unused deps (requires nightly)"
	@echo "  markdown-fmt                         Auto-fix Markdown with rumdl"
	@echo "  markdown-lint                        Lint Markdown with rumdl"
	@echo "  shellcheck                           Lint bash scripts"
	@echo "  sh-fmt                               Format bash scripts with shfmt"
	@echo "  sh-fmt-check                         Check bash formatting without modifying"
	@echo "  toml-fmt                             Format TOML files with taplo"
	@echo "  toml-fmt-check                       Check TOML formatting without modifying"
	@echo "  toml-lint                            Lint TOML files with taplo"
	@echo "  makefile-check                       Lint Makefile with checkmake"
	@echo "  actionlint                           Lint GitHub Actions workflows with actionlint"
	@echo "  snapshot-anchors                     Block new bare insta snapshots"
	@echo "  snapshot-anchors-test                Self-tests for the snapshot-anchors gate"
	@echo "  rustfmt-bail                         Block new match arms rustfmt refuses to format"
	@echo "  rustfmt-bail-test                    Self-tests for the rustfmt-bail gate"
	@echo "  grammar-marker-sync                  Block grammar-marker bumps without source regen"
	@echo "  grammar-marker-sync-test             Self-tests for the grammar-marker-sync gate"
	@echo "  check-versions                       Enforce lockstep version invariant across owned crates"
	@echo "  check-versions-test                  Self-tests for the check-versions gate"
	@echo "  check-grammar-crate-test            Sync-test EXTENSIONS table vs langs.rs"
	@echo "  check-excluded-manifests             Assert excluded crates root a workspace, declare lints, and =-pin grammars"
	@echo "  check-excluded-manifests-test        Self-tests for the check-excluded-manifests gate"
	@echo "  check-ruff-lockstep                  Assert the ruff-pre-commit rev, uv.lock, and the requirements export agree"
	@echo "  check-ruff-lockstep-test             Self-tests for the check-ruff-lockstep gate"
	@echo "  check-publish-metadata               Assert every publishable crate carries the metadata crates.io needs"
	@echo "  check-publish-metadata-test          Self-tests for the check-publish-metadata gate"
	@echo "  check-manpage-assets                 Assert every bca-*.1 man page is in deb+rpm asset lists"
	@echo "  check-manpage-drift-test             Self-tests for the man-page drift gate"
	@echo "  check-diagnostic-prefix              Block capitalised Warning:/Error:/Note: literals"
	@echo "  check-diagnostic-prefix-test         Self-tests for the diagnostic-prefix gate"
	@echo "  check-feature-gates                  Assert union-gated tests are absent under a disjoint feature set"
	@echo "  check-feature-gates-test             Self-tests for the feature-gates gate"
	@echo "  check-test-lang-gates                Assert every test naming a language carries its cfg"
	@echo "  check-test-lang-gates-compare        Fail if a test stopped being built by a language leg since COMPARE_REF"
	@echo "  check-test-lang-gates-test           Self-tests for the test-language gate"
	@echo "  check-safety-doc-pin                 Assert node.rs's unsafe soundness doc cites the live tree-sitter pin"
	@echo "  check-safety-doc-pin-test            Self-tests for the safety-doc-pin gate"
	@echo "  worktree-setup-test                  Self-tests for the worktree-setup submodule classifier"
	@echo "  gate-status-test                     Self-tests for the pre-commit/ci BCA_GATE verdict line"
	@echo "  check-tools-test                     Self-tests for the check-tools tool probes and hints"
	@echo "  enums-check                          cargo clippy + cargo test on workspace-excluded enums crate"
	@echo "  enums-codegen-drift                  Block enums codegen output drifting from checked-in files"
	@echo "  enums-codegen-drift-test             Self-tests for the enums-codegen-drift gate"
	@echo "  self-scan                            bca threshold gate against this repo (hard: 100%)"
	@echo "  self-scan-headroom                   bca threshold gate (soft: BCA_HEADROOM, default 0.95)"
	@echo "  self-scan-write-baseline             Refresh .bca-baseline.toml at the hard thresholds"
	@echo "  self-scan-write-baseline-headroom    Refresh .bca-baseline.toml at the soft thresholds"
	@echo "  vcs                                  Change-history (VCS) risk report for this repo"
	@echo "  bench                                bench-scaling + bench-walk (out-of-band; never in ci)"
	@echo "  bench-scaling                        Complexity-class gate for the metric walk"
	@echo "  bench-walk                           Criterion metric-walk benchmarks over a corpus slice"
	@echo "  fuzz-check                           Lint, test + build the cargo-fuzz targets (out-of-band)"
	@echo "  fuzz-smoke                           Short bounded fuzz run over the committed corpora"
	@echo "  fuzz-replay                          Replay the committed seeds only (regression check)"
	@echo "  fuzz-run                             One target, FUZZ_RUNS iterations (FUZZ_TARGET=name)"
	@echo "  fuzz-tmin                            Minimise a crash artifact (FUZZ_TARGET, FUZZ_INPUT)"
	@echo "  lint                                 Run all linters"
	@echo ""
	@echo "Python bindings (big-code-analysis-py):"
	@echo "  py-bootstrap                         Create .venv from uv.lock (alias: py-sync) — requires uv"
	@echo "  py-relock                            Regenerate uv.lock from pyproject.toml (run after editing deps)"
	@echo "  py-clean                             Remove .venv, _native*.so, *_cache, __pycache__"
	@echo "  py-fmt                               Format Python sources with ruff"
	@echo "  py-fmt-check                         Verify Python formatting"
	@echo "  py-lint                              Lint Python sources with ruff"
	@echo "  py-typecheck                         Type-check with mypy --strict + pyright"
	@echo "  py-test                              maturin develop + pytest (needs active venv)"
	@echo "  py-stubtest                          maturin develop + mypy stubtest of _native.pyi (needs venv)"
	@echo "  smoke                                Run the release/wheel smoke scripts locally (smoke-cli + smoke-lib)"
	@echo "  smoke-cli                            CLI smoke (scripts/smoke/cli_wheel_smoke.sh) against a debug bca"
	@echo "  smoke-lib                            Library smoke (scripts/smoke/lib_wheel_smoke.py) via maturin develop"
	@echo "  (first-time setup: 'make worktree-setup' — corpora + this venv; 'make py-bootstrap' for the venv alone)"
	@echo ""
	@echo "Maintenance:"
	@echo "  clean                                Remove cargo build artifacts (target/) only"
	@echo "  distclean                            Remove cargo + Python artifacts (full wipe — chains py-clean and clean)"
	@echo "  install                              Install both CLI and web binaries"
	@echo "  install-cli                          Install bca"
	@echo "  install-web                          Install bca-web"
	@echo ""
	@echo "Documentation:"
	@echo "  doc                                  Generate rustdoc (warning-tolerant viewer)"
	@echo "  doc-open                             Generate and open rustdoc (warning-tolerant viewer)"
	@echo "  doc-check                            Strict rustdoc gate (RUSTDOCFLAGS appends -D warnings)"
	@echo "  doc-check-docsrs                     Reproduce the docs.rs build (nightly, --cfg docsrs); skips if nightly absent"
	@echo "  book                                 Build the mdBook"
	@echo "  book-serve                           Serve the mdBook with live reload"
	@echo "  book-pot                             Regenerate the translation template (po/messages.pot)"
	@echo "  book-po-update                       Merge English doc changes into po/ja.po (msgmerge)"
	@echo "  book-ja                              Build the Japanese mdBook into book/ja"
	@echo "  book-deploy                          Publish the mdBook to the gh-pages branch (manual fallback)"
	@echo ""
	@echo "Combined targets:"
	@echo "  all                                  Check, test, build release"
	@echo "  pre-commit                           Verify formatting, lint, test (recommended before commit)"
	@echo "  ci                                   Validate formatting, lint, test (no auto-fix)"
	@echo ""
	@echo "Release engineering:"
	@echo "  release-check                        Pre-tag gate: deny + about + CHANGELOG (VERSION=x.y.z)"
	@echo "  verify-changelog                     Verify CHANGELOG.md has section for VERSION=x.y.z"
	@echo "  pkg-deb-local                        Build .deb locally (host target, no CI matrix)"
	@echo "  pkg-rpm-local                        Build .rpm locally (host target, no CI matrix)"
	@echo ""
	@echo "Dev container (Claude Code + MCP servers):"
	@echo "  dev-env-build                        Build the dev image (Rust/Python/Node + MCP servers)"
	@echo "  dev-env-run                          Start the dev container (detached, repo mounted)"
	@echo "  dev-env-shell                        Open a shell in the running dev container"
	@echo "  dev-env-rm                           Stop and remove the dev container"

# ---------------------------------------------------------------------------
# Prerequisites
# ---------------------------------------------------------------------------
check-tools:
	@bash $(BASE_DIR)utils/check-tools.sh

# Self-tests for utils/check-tools.sh. The install hints are the whole
# product of that script, and one of them — cargo-about's — is only
# correct with `--features cli`; without the flag the install exits 0
# and installs nothing (#1226). Cheap enough (~0.1s, stubbed cargo) to
# run in both gates.
check-tools-test:
	@bash $(BASE_DIR)utils/check-tools-test.sh

# One-shot bootstrap for a fresh clone or a fresh `git worktree`: the
# two steps nothing else states and nothing else detects (#1171).
#
# 1. The integration corpora under tests/repositories/. Without them 24
#    tests fail — 5 corpus tests and 19 CLI tests that analyse a real
#    source file from the DeepSpeech corpus.
# 2. big-code-analysis-py/.venv. Without it `make pre-commit`'s
#    py-typecheck stage reports ~33 mypy errors (pytest is untyped
#    without its stubs) and py-test dies with "Couldn't find a
#    virtualenv".
#
# Idempotent and cheap when there is nothing to do: the corpus half
# classifies each submodule with a stat-only `git diff` (~60 ms for all
# four) and skips the ones already checked out, and `uv sync --locked`
# re-audits an up-to-date venv in ~30 ms. It does rebuild the compiled
# extension when the Rust sources have moved since the last sync — that
# is the venv being brought up to date, not waste, and it is why this
# delegates to py-bootstrap rather than short-circuiting on a `.venv`
# directory that an interrupted bootstrap may have left half-built.
# Deliberately NOT wired into pre-commit or ci — it is a developer
# bootstrap, not a gate.
#
# The venv half is a soft skip when uv is absent, matching how the other
# py-* targets behave on a barebones host; `make py-bootstrap` remains
# the hard-failing entry point for someone who asked for it by name.
worktree-setup:
	@python3 $(BASE_DIR)utils/worktree-setup.py
	@if command -v uv >/dev/null 2>&1; then \
	  $(MAKE) --no-print-directory py-bootstrap; \
	else \
	  echo "worktree-setup: uv not found; skipping the Python venv."; \
	  echo "  Until it exists, 'make pre-commit' reports ~33 mypy errors from"; \
	  echo "  py-typecheck and py-test dies with \"Couldn't find a virtualenv\"."; \
	  echo "  Install uv (curl -LsSf https://astral.sh/uv/install.sh | sh), then"; \
	  echo "  re-run 'make worktree-setup'."; \
	fi

# Self-tests for the worktree-setup classifier. Not a gate over the
# tree's contents, but the classifier decides when to run a destructive
# `git submodule update --force`, so it is held to the same standard as
# the utils/ gates and runs in pre-commit alongside them.
worktree-setup-test:
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/worktree-setup-test.py)

# Self-tests for utils/gate-status.sh, which wraps `pre-commit` and `ci`
# and is the only thing standing between a red gate and a log that reads
# as green. Held to the same standard as the utils/ gates for that
# reason, and cheap enough (~0.1s, no cargo) to run in both.
gate-status-test:
	@bash $(BASE_DIR)utils/gate-status-test.sh

# ---------------------------------------------------------------------------
# Build
# ---------------------------------------------------------------------------
build:
	cargo build --workspace --all-targets

build-release:
	cargo build --workspace --release

check:
	cargo check --workspace --all-targets

# ---------------------------------------------------------------------------
# Test
# ---------------------------------------------------------------------------
test:
	@if [ -z "$(NEXTEST)" ]; then \
	  echo "cargo-nextest not found or disabled; using 'cargo test' (same tests, slower)."; \
	  echo "Install with: cargo install --locked cargo-nextest"; \
	fi
	$(TEST_CMD)

# Doctests stay on `cargo test`: nextest cannot run them at all, so this
# is a separate target rather than an oversight (see .config/nextest.toml).
test-doc:
	cargo test --workspace --all-features --doc

# The ancestor-chain audit (#1122). `--cfg chain_audit` restores the
# exact `chain.last() == node.parent()` assertion in `Ancestors::checked`
# that the default build trades for an O(1) approximation, so every walk
# that threads a chain is verified node-by-node against the tree.
#
# Out of band because that assertion is `Node::parent`'s O(depth) lookup
# per node, which turns the linear shipped walk quadratic and roughly
# triples the lib suite's wall time. Runs in the `chain-audit` CI lane;
# run it locally around any change to a walk's truncate/push bookkeeping.
#
# Library-scoped, matching that lane: the walks that thread a chain live
# in the root crate (`spaces::compute`, `ops`, `suppression`) and in
# `big-code-analysis-ast` (`comment_rm`, `Search::act_on_node` — which
# `find` and `count` also walk through — and the `Ast` dump's `build`),
# so the CLI / web / integration tiers would re-pay the quadratic cost
# without reaching an assertion the lib tests do not already reach.
#
# RUSTFLAGS rather than a Cargo feature on purpose: `make test` passes
# `--all-features`, so a feature would switch the audit back on in the
# very inner loop this target exists to keep fast.
chain-audit:
	RUSTFLAGS="$${RUSTFLAGS:-} --cfg chain_audit" \
	  cargo test -p big-code-analysis -p big-code-analysis-ast --lib --all-features

# `cargo insta test` shells out to `cargo test`, not $(TEST_CMD): insta's
# nextest integration needs `--test-runner nextest`, and under it insta
# cannot force-pass a failing assertion to collect every pending snapshot
# in one run — which is exactly what review/accept need. Snapshot review
# is an interactive, non-hot-loop operation, so it keeps the slower runner.
insta-review:
	cargo insta test --review

insta-accept:
	cargo insta test --accept

# ---------------------------------------------------------------------------
# Formatting
# ---------------------------------------------------------------------------
fmt:
	@echo "Formatting Rust code..."
	@cargo fmt --all
	@echo "Formatting Markdown files..."
	@$(MAKE) --no-print-directory markdown-fmt
	@echo "Formatting bash scripts..."
	@$(MAKE) --no-print-directory sh-fmt
	@echo "Formatting TOML files..."
	@$(MAKE) --no-print-directory toml-fmt

fmt-check:
	@echo "Checking Rust code formatting..."
	@cargo fmt --all --check || { echo "Rust code is not formatted (run 'make fmt')"; exit 1; }
	@echo "Checking Markdown formatting..."
	@$(MAKE) --no-print-directory markdown-lint
	@echo "Checking bash script formatting..."
	@$(MAKE) --no-print-directory sh-fmt-check
	@echo "Checking TOML formatting..."
	@$(MAKE) --no-print-directory toml-fmt-check
	@echo "All formatting checks passed"

# Sanity guard for the find-by-ext helper. If EXCLUDE_DIRS over-matches
# (as it did in #160 when `tree-sitter-*` was unquoted and the recipe
# shell expanded the glob into absolute paths), every lint that pipes
# through `xargs -r` silently no-ops. Run as a prerequisite of every
# recipe that consumes find-by-ext.
_check-find:
	@N=$$($(call find-by-ext,md,) | wc -l); \
	  [ "$$N" -ge 5 ] || { echo "ERROR: find-by-ext returned $$N .md files (expected >=5); EXCLUDE_DIRS is over-matching — see #160"; exit 1; }

# `rumdl check --fix` is preferred over `rumdl fmt` here: `fmt`
# exits 0 even when unfixable findings remain (formatter semantics),
# whereas `check --fix` applies every auto-fix it can and then exits
# non-zero if any finding is still outstanding. The latter is what
# we want for a Makefile gate — auto-fix what you can, then fail
# loudly on the rest so the contributor knows to edit manually.
markdown-fmt: _check-find
	@echo "Auto-fixing Markdown files..."
	@$(call find-by-ext,md,) | xargs -r rumdl check --fix || { echo "rumdl could not auto-fix all issues"; exit 1; }

markdown-lint: _check-find
	@echo "Linting Markdown files..."
	@$(call find-by-ext,md,) | xargs -r rumdl check || { echo "rumdl found issues"; exit 1; }

sh-fmt: _check-find
	@$(call find-by-ext,sh,) | xargs -r shfmt -w -i 0 -ci -bn

sh-fmt-check: _check-find
	@$(call find-by-ext,sh,) | xargs -r shfmt -d -i 0 -ci -bn || { echo "Bash scripts are not formatted (run 'make sh-fmt')"; exit 1; }

shellcheck: _check-find
	@echo "Linting bash scripts with shellcheck..."
	@$(call find-by-ext,sh,) | xargs -r shellcheck || { echo "Shellcheck found issues"; exit 1; }

toml-fmt:
	@taplo fmt

toml-fmt-check:
	@taplo fmt --check || { echo "TOML files are not formatted (run 'make toml-fmt')"; exit 1; }

toml-lint:
	@echo "Linting TOML files..."
	@taplo lint || { echo "TOML lint found issues"; exit 1; }

makefile-check:
	@echo "Linting Makefile with checkmake..."
	@checkmake --config $(BASE_DIR).checkmake.ini $(BASE_DIR)Makefile || { echo "checkmake found issues"; exit 1; }

# actionlint scans every workflow under .github/workflows/ and shells
# out to shellcheck (when present on PATH) for the `run:` blocks. It
# takes no file arguments here: invoked at the repo root it discovers
# .github/workflows/ automatically, which matches the canonical
# upstream invocation and keeps the recipe robust against new
# workflows being added.
actionlint:
	@echo "Linting GitHub Actions workflows with actionlint..."
	@(cd $(BASE_DIR) && actionlint -no-color) || { echo "actionlint found issues"; exit 1; }

snapshot-anchors:
	@echo "Checking insta snapshot anchors..."
	@python3 $(BASE_DIR)utils/check-snapshot-anchors.py

# Self-tests for the snapshot-anchors gate. Separate target for the
# same reason as rustfmt-bail-test below: the gate stays a one-line
# invariant check and test failures get their own parallel-arm output.
snapshot-anchors-test:
	@echo "Running snapshot-anchors self-tests..."
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/check-snapshot-anchors-test.py)

# rustfmt-bail gate (#1136). `cargo fmt --check` exits 0 over regions
# rustfmt declined to format — a comment inside a match pattern makes
# it emit the whole match verbatim, silently. This probe over-indents
# every match arm and counts the ones rustfmt refuses to put back;
# any increase over `.rustfmt-bail-baseline.txt` fails.
rustfmt-bail:
	@echo "Checking rustfmt bail count..."
	@python3 $(BASE_DIR)utils/check-rustfmt-bail.py

# Self-tests for the rustfmt-bail gate. Kept separate from the gate
# target so the gate stays a one-line invariant check (matching the
# grammar-marker-sync pattern) and test failures get their own clean
# parallel-arm output in the pre-commit/CI DAG.
rustfmt-bail-test:
	@echo "Running rustfmt-bail self-tests..."
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/check-rustfmt-bail-test.py)

# Grammar-marker-sync gate. Blocks the failure mode from #400:
# bumping the notification-only `tree-sitter-{javascript,cpp}`
# marker in `tree-sitter-{mozjs,mozcpp}/Cargo.toml` without
# re-running the matching `./generate-grammars/generate-*.sh`.
# Static lint — no network, no cargo, runs in milliseconds.
grammar-marker-sync:
	@echo "Checking grammar-marker sync against baseline..."
	@python3 $(BASE_DIR)utils/check-grammar-marker-sync.py

# Enums-codegen drift gate. Closes #405: running any
# `recreate-grammars.sh` invocation silently regenerated
# `big-code-analysis-ast/src/c_langs_macros/{c_macros,c_specials}.rs`
# to a pre-optimization form. This gate runs the codegen into a
# tempdir
# and diffs against the checked-in files; drift fails.
enums-codegen-drift:
	@echo "Checking enums codegen drift..."
	@bash $(BASE_DIR)utils/check-enums-codegen-drift.sh

# Self-tests for the enums-codegen-drift gate. Kept separate from
# the gate target so the gate stays a one-line invariant check
# (matching the grammar-marker-sync pattern) and test failures
# get their own clean parallel-arm output in the pre-commit/CI DAG.
enums-codegen-drift-test:
	@echo "Running enums-codegen-drift self-tests..."
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/check-enums-codegen-drift-test.py)

# Self-tests for the grammar-marker-sync gate. Kept separate from
# the gate target so the gate stays a one-line invariant check
# (matching the snapshot-anchors / check-versions pattern) and
# the test failures get their own clean parallel-arm output in
# the pre-commit/CI DAG.
grammar-marker-sync-test:
	@echo "Running grammar-marker-sync self-tests..."
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/check-grammar-marker-sync-test.py)

# Regenerate the man pages under `man/` from the live clap schema.
# Auto-fix flavour: `cargo xtask` rewrites every `.1` file so a
# subsequent `git diff --exit-code -- man/` is clean. Used by
# `_pc-manpages` so contributors can stage the regenerated output.
manpages:
	@echo "Regenerating man pages from clap schema..."
	@cargo xtask

# Regenerate-then-assert-clean drift gate. Like the CI `manpage`
# job in `.github/workflows/ci.yml`, this recipe runs `cargo xtask`
# (which rewrites `man/*.1` in place — the same side effect CI
# accepts on its ephemeral runners) and then fails if the resulting
# tree differs from what is committed — modified, deleted, *and*
# added pages (#1249; `git diff` alone cannot see an untracked new
# page). Used by `_ci-manpages` and `_pc-manpages`. Locally,
# contributors with hand-edited `.1` files will see those edits
# overwritten; man pages are generated artifacts and should not be
# hand-edited.
#
# The assertion itself lives in `utils/check-manpage-drift.py`, which
# the CI job's "Verify no drift" step calls too, so the two sites
# cannot drift apart. Its self-tests are `check-manpage-drift-test`.
manpages-check:
	@echo "Checking man pages match clap schema..."
	@cargo xtask
	@python3 $(BASE_DIR)utils/check-manpage-drift.py

# Self-tests for the man-page drift gate. Kept separate from
# `manpages-check` (matching the check-versions-test pattern) so the
# gate stays a regenerate-then-assert pair and the test failures get
# their own clean parallel-arm output in the pre-commit/CI DAG. The
# tests run against scratch repositories only — never the real `man/`,
# which `_pc-manpages` rewrites concurrently.
check-manpage-drift-test:
	@echo "Running manpage-drift self-tests..."
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/check-manpage-drift-test.py)

# Lockstep-version invariant: every owned crate and every internal
# `=<v>` dep pin must equal `[workspace.package].version`. See
# `RELEASING.md` "Lockstep version policy" and `check-versions.py`.
check-versions:
	@echo "Checking lockstep version invariant..."
	@python3 $(BASE_DIR)utils/check-versions.py

# Self-tests for the lockstep-version gate. Kept separate from the
# gate target (matching the grammar-marker-sync-test pattern) so the
# gate stays a one-line invariant check and the test failures get
# their own clean parallel-arm output in the pre-commit/CI DAG.
check-versions-test:
	@echo "Running check-versions self-tests..."
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/check-versions-test.py)

# Workspace-exclusion gate. Closes #1145: a crate in the root
# `[workspace] exclude` array must root its own workspace, because
# `exclude` denies membership without stopping cargo's upward search
# for a workspace root. In a git worktree under `.claude/worktrees/`
# that search escapes the worktree and resolves against the main
# checkout, breaking `cargo fmt --all` and every `make pre-commit`
# stage chained behind it. Also asserts every tree-sitter dependency
# in the root manifest and in each excluded crate carries an `=X.Y.Z`
# pin (#1151), and that each excluded crate declares its own `[lints]`
# table or is listed exempt — `[workspace.lints]` reaches members only,
# so without one a crate is gated at `-D warnings` against the compiler
# defaults (#1228). Static lint — no network, no cargo.
check-excluded-manifests:
	@echo "Checking workspace-excluded manifests..."
	@python3 $(BASE_DIR)utils/check-excluded-manifests.py

# Self-tests for the workspace-exclusion gate. Kept separate from the
# gate target (matching the check-versions-test pattern) so the gate
# stays a one-line invariant check and test failures get their own
# clean parallel-arm output in the pre-commit/CI DAG.
check-excluded-manifests-test:
	@echo "Running check-excluded-manifests self-tests..."
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/check-excluded-manifests-test.py)

# ruff version lockstep (#1230). One adopted ruff is declared in four
# places and nothing compared them: the `ruff-pre-commit` `rev:` in
# .pre-commit-config.yaml, the version big-code-analysis-py/uv.lock
# resolves, the `ruff==` pin in its requirements/dev.txt export (what
# CI installs), and the bound in its pyproject.toml. The rev had
# already drifted once — v0.15.14 against a lockfile resolving
# 0.15.22 — which is silent until the two versions happen to disagree,
# and then presents as "works locally, red in CI". Static lint — no
# network, no cargo.
check-ruff-lockstep:
	@echo "Checking ruff version lockstep..."
	@python3 $(BASE_DIR)utils/check-ruff-lockstep.py

# Self-tests for the ruff-lockstep gate. Separate target for the same
# reason as the other gate self-tests: the gate stays a one-line
# invariant check and test failures get their own parallel-arm output.
check-ruff-lockstep-test:
	@echo "Running check-ruff-lockstep self-tests..."
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/check-ruff-lockstep-test.py)

# Publish-metadata gate (#1224). `cargo publish --dry-run` is the
# natural pre-tag check, but it cannot run for the four top-level
# crates: each pins an internal dependency at `=<version>`, and the
# Lockstep policy makes that the version being released — which is by
# definition not yet on crates.io. The workaround it replaces skipped
# the parent dry-run whenever the pinned leaf was absent from the
# sparse index, so it skipped on every release and the crate went out
# with no metadata gate at all. This asserts the same fields
# registry-free, from `cargo metadata` (which resolves
# `[workspace.package]` inheritance) plus `cargo package --list` (the
# one packaging step that does not resolve dependencies). Two cargo
# calls per crate, no build, and no workspace `target/` lock — measured
# at ~0.8s alongside a running build, so it fans out with the other
# static gates rather than chaining into the cargo pipeline.
check-publish-metadata:
	@echo "Checking crates.io publish metadata..."
	@python3 $(BASE_DIR)utils/check-publish-metadata.py

# Self-tests for the publish-metadata gate. Separate target for the
# same reason as the other gate self-tests: the gate stays a one-line
# invariant check and test failures get their own parallel-arm output.
check-publish-metadata-test:
	@echo "Running check-publish-metadata self-tests..."
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/check-publish-metadata-test.py)

# Man-page packaging gate. Blocks the failure mode from #444:
# a bca subcommand man page that drops out of the hand-maintained
# deb/rpm asset lists in the CLI / web crate Cargo.toml. Static
# lint — no network, no cargo, runs in milliseconds. See #446.
check-manpage-assets:
	@echo "Checking man-page packaging asset lists..."
	@python3 $(BASE_DIR)utils/check-manpage-assets.py

# Diagnostic-prefix gate (#1199). Every severity prefix this workspace
# prints is lowercase and written by one helper per crate (`diag.rs`);
# a fresh `eprintln!("Warning: ...")` reads as correct in review and
# nothing else notices. Static lint — no network, no cargo.
check-diagnostic-prefix:
	@echo "Checking diagnostic severity prefixes..."
	@python3 $(BASE_DIR)utils/check-diagnostic-prefix.py

# Self-tests for the diagnostic-prefix gate. Separate target for the
# same reason as the other gate self-tests: a source-scanning gate that
# stops matching reports a clean tree, so its own tests have to fail
# loudly and on their own parallel arm.
check-diagnostic-prefix-test:
	@echo "Running check-diagnostic-prefix self-tests..."
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/check-diagnostic-prefix-test.py)

# Feature-gate reachability (#1472). Deliberately NOT in `pre-commit` /
# `ci`: it needs a test-binary build per feature set, and the answer is
# only interesting for a feature set that enables none of some subject's
# rows — which is what the `feature-matrix` job in ci.yml already builds
# ten of. This target is the manual spelling; pass a leg's flags, e.g.
#   make check-feature-gates FLAGS="--no-default-features --features go -p big-code-analysis"
check-feature-gates:
	@echo "Checking union-gated test reachability..."
	@(cd $(BASE_DIR) && python3 utils/check-feature-gates.py $(FLAGS))

# Self-tests for the feature-gates gate. Pure Python with the cargo call
# stubbed, so this one *is* cheap enough for the parallel gate — and a
# scanner that silently stops matching reports a clean tree, which is
# precisely why it needs its own arm.
check-feature-gates-test:
	@echo "Running check-feature-gates self-tests..."
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/check-feature-gates-test.py)

# Per-language test gating (#1472). The companion to the gate above,
# and the opposite question: that one asks whether a *declared* union
# still excludes what it claims to, this one derives what the marker
# should be from the languages an item names and reports the ones
# missing it. A scanner of declared markers cannot see a missing one —
# deleting the marker deletes the subject it scans for.
#
# Unlike `check-feature-gates`, this IS in `pre-commit` / `ci`: it is a
# pure source scan with no cargo invocation, so it costs a few seconds.
# `--fix` writes the missing markers in place.
check-test-lang-gates:
	@echo "Checking per-language test gates..."
	@(cd $(BASE_DIR) && python3 utils/check-test-lang-gates.py)

# The third direction (#1478), and the only one that needs history.
# Both checks above compare a marker against the derivation; when the
# two agree and are both wrong, nothing static can tell. This scans the
# tree at COMPARE_REF too, computes which single-language builds compile
# each test in each, and fails on a test that still exists but stopped
# being built somewhere. No cargo: `git archive` plus the same scanner.
#
# Deliberately NOT in `pre-commit`. It needs a base revision to be
# meaningful, and a working tree mid-edit has none — the PR's merge
# base is the answer, so CI supplies it. Locally:
#
#   make check-test-lang-gates-compare COMPARE_REF=origin/main
#
# Spelled out rather than a bare `REF`, which `?=` would take from
# an exported environment variable of that name.
COMPARE_REF ?= origin/main
check-test-lang-gates-compare:
	@echo "Comparing per-language test membership against $(COMPARE_REF)..."
	@(cd $(BASE_DIR) && python3 utils/check-test-lang-gates.py --compare $(COMPARE_REF))

# Self-tests for the test-language gate. Its `RepositoryTest` also pins
# that the derivation still reproduces every marker written by hand,
# which is what licenses the ~3,000 it generated.
check-test-lang-gates-test:
	@echo "Running check-test-lang-gates self-tests..."
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/check-test-lang-gates-test.py)

# Safety-doc pin gate (#1057). The module doc of
# big-code-analysis-py/src/node.rs is the canonical soundness argument
# for this workspace's only sanctioned `unsafe` block, and it reasons
# about a named tree-sitter release. When the pin moves and that literal
# does not, the argument keeps reading as verified while describing a
# crate nobody compiles against. Static lint - no network, no cargo.
check-safety-doc-pin:
	@echo "Checking the unsafe soundness doc's tree-sitter citation..."
	@python3 $(BASE_DIR)utils/check-safety-doc-pin.py

# Self-tests for the safety-doc-pin gate. Separate target for the same
# reason as the other gate self-tests: a source-scanning gate that stops
# matching reports a clean tree.
check-safety-doc-pin-test:
	@echo "Running check-safety-doc-pin self-tests..."
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/check-safety-doc-pin-test.py)

# Sync gate for check-grammar-crate.py's EXTENSIONS table. Re-derives
# the grammar -> extension mapping from the parse layer's langs.rs
# `mk_langs!` and fails if the hand-maintained table has drifted
# (#869). Static — no
# network, no cargo — so it rides the cheap test DAG alongside the
# other helper-script self-tests.
check-grammar-crate-test:
	@echo "Running check-grammar-crate self-tests..."
	@(cd $(BASE_DIR) && python3 -m unittest -q utils/check-grammar-crate-test.py)

# The `enums/` crate is listed in `[workspace].exclude` (it ships a
# non-published codegen binary used only by `recreate-grammars.sh`), so
# it is invisible to `cargo {check,clippy,test} --workspace` and to the
# `lint` / `test` CI jobs. Without an explicit gate, lint regressions in
# `enums/src/*.rs` drift silently — the `unused_imports` warning fixed
# in #162 went unnoticed for that exact reason (see #164).
#
# RUSTFLAGS is set per-recipe (defensive): CI exports the same value at
# workflow scope, so the recipe-local export is redundant in CI but
# necessary locally to keep `make enums-check` behave identically
# everywhere.
#
# Uses `cargo clippy` (not `cargo check`) so the gate enforces the same
# lint floor as the workspace `clippy` job: rustc-level warnings plus the
# clippy default group. The three `manual_is_ascii_check` sites that
# previously blocked this (tracked as #166) have been fixed.
#
# Also runs `cargo test` on the same manifest because the workspace
# `test` job (`cargo test --workspace`) skips this crate by exclusion,
# leaving `enums/tests/dispatch.rs` and any other integration tests
# unexecuted in CI / pre-commit. The dispatch test pins each `Lang`
# variant to its expected backing grammar crate (issue #350); without
# this runtime gate, an arm in `mk_get_language!` pointing at the wrong
# grammar would compile cleanly and only fail when a developer
# manually invoked `cargo test` against the enums manifest.
enums-check:
	@echo "Linting workspace-excluded enums crate..."
	@RUSTFLAGS="-D warnings" cargo clippy \
	  --manifest-path $(BASE_DIR)enums/Cargo.toml \
	  --all-targets --locked -- -D warnings
	@echo "Running tests for workspace-excluded enums crate..."
	@cargo test \
	  --manifest-path $(BASE_DIR)enums/Cargo.toml \
	  --locked

# ---------------------------------------------------------------------------
# bca self-scan threshold gate
#
# Re-runs the CI threshold gate against the in-tree bca binary.
# Mirrors the `Threshold gate (baseline-ratcheted)` step in
# .github/workflows/pages.yml. We build from source on purpose:
# any in-progress change to metric computation is reflected in the
# values we gate on. When pages.yml bumps the pinned release
# binary, the two invocations re-sync.
#
# Path selection (`paths = ["."]`), the ignore file
# (`exclude_from = ".bcaignore"`), the baseline
# (`baseline = ".bca-baseline.toml"`), the per-function thresholds,
# and the cyclomatic `?` policy (`cyclomatic_count_try = false`) all
# live in the auto-discovered `bca.toml` manifest, so a bare
# `bca check` reproduces the full hard-tier gate with no flags.
#
# Two tiers:
#
#   self-scan            hard gate (limits as configured in bca.toml;
#                        absorbed by .bca-baseline.toml). Mirrors CI.
#
#   self-scan-headroom   soft gate (`--tier=soft=BCA_HEADROOM`).
#                        Scales every limit by BCA_HEADROOM (default
#                        0.95) and runs the same baseline-ratcheted
#                        check, so new functions encroaching into the
#                        95-100% band fail before they would trip the
#                        hard gate. Set BCA_HEADROOM=0.90 to widen the
#                        band, 0.99 to tighten it. The ratio rides on
#                        the soft tier itself (#688): `--tier=soft=R`
#                        replaces the retired `--headroom R` dial.
#
# Refresh the baseline (after an intentional regression or after
# raising a limit):
#
#   self-scan-write-baseline   refreshes .bca-baseline.toml in place.
# ---------------------------------------------------------------------------
SELF_SCAN_BCA := cargo run --quiet --release -p big-code-analysis-cli --
# `--jobs` defaults to `auto` (effective CPU count, cgroup-/cpuset-
# aware on Linux via Rust's std lib), so no `$(nproc)` plumbing is
# needed for the self-scan recipes (issue #383).
#
# The walk root is left to the manifest's `paths = ["."]` key: a bare
# `bca check` resolves it to an absolute root, but the walker now
# re-anchors that root to the `./`-prefixed relative form before
# matching (#488), so the `./`-anchored `.bcaignore` deny-set matches
# the same files whether the seed was `.`, `$PWD`, or a manifest-
# resolved absolute path. The previous `--paths .` workaround is no
# longer needed.
#
# Diff-aware footer partitioning in the self-scan gate (#356/#387). Set
# BCA_SINCE=<ref> to append `--since <ref>`, which splits the per-file
# rollup footer into "Files in this range:" (offenders the diff touched)
# vs "Other offenders:". CI (`.github/workflows/pages.yml`) sets it to
# `origin/${GITHUB_BASE_REF:-main}` so PR runs highlight the offenders a
# PR introduced; local runs leave it unset, so the gate is unchanged and
# the local/CI invocation stays identical by construction. `--since` is
# presentational only — it never changes pass/fail (that would be
# `--changed-only`, deliberately not adopted here, see #387). The
# `--github-annotations` / `$GITHUB_STEP_SUMMARY` digest / remediation
# block all auto-enable from GitHub Actions env vars, so no flag is
# needed for them.
#
# `--since` is a `check` *subcommand* argument, so it is spliced in
# after `check` in each gate target below.
#
# Default to empty so the `:=` expansion does not trip
# `--warn-undefined-variables` when the var is unset (the common
# case); CI's environment value still overrides, since `?=` only
# assigns when undefined.
BCA_SINCE ?=
SELF_SCAN_SINCE_ARGS := $(if $(BCA_SINCE),--since $(BCA_SINCE),)

self-scan:
	@echo "bca self-scan (hard gate)..."
	@$(SELF_SCAN_BCA) check $(SELF_SCAN_SINCE_ARGS)

self-scan-headroom:
	@echo "bca self-scan (soft gate, BCA_HEADROOM=$${BCA_HEADROOM:-0.95})..."
	@$(SELF_SCAN_BCA) check $(SELF_SCAN_SINCE_ARGS) \
	  --tier=soft=$${BCA_HEADROOM:-0.95}

self-scan-write-baseline:
	@echo "Refreshing .bca-baseline.toml from current offenders..."
	@$(SELF_SCAN_BCA) check --write-baseline

# Refresh `.bca-baseline.toml` against the SOFT thresholds
# (the `bca.toml` limits scaled by BCA_HEADROOM, default 0.95).
# Records every current offender at the soft tier — strictly a
# superset of the hard-tier offenders. Use this when launching the
# soft gate or after raising BCA_HEADROOM so the baseline absorbs
# the new headroom band rather than firing on every commit.
self-scan-write-baseline-headroom:
	@echo "Refreshing .bca-baseline.toml from current soft-tier offenders (BCA_HEADROOM=$${BCA_HEADROOM:-0.95})..."
	@$(SELF_SCAN_BCA) check \
	  --tier=soft=$${BCA_HEADROOM:-0.95} \
	  --write-baseline

# ---------------------------------------------------------------------------
# Change-history (VCS) risk report (issue #328). Dogfoods `bca vcs` on
# this repo: ranks tracked files by composite change-history risk (churn,
# commit/author counts, ownership dilution, bug-/security-fix history)
# over the default 12mo / 90d windows. Informational only — it never
# gates (always exits 0). Path selection and the `.bcaignore` deny-set
# come from the auto-discovered `bca.toml` manifest, exactly like
# `make self-scan`. The two file universes are close but not identical:
# `.bcaignore` shapes what is *walked* and both commands honour it,
# whereas `[check] exclude` shapes what is *gated* and only `check`
# consults it — so the dev-tooling trees exempted there (#1146) are
# ranked here and absent from the gate.
# `BCA_VCS_TOP` overrides the row cap (default 40; 0 = all). This prints
# the quick terminal table; for the styled, sortable page (published to
# Pages by the `pages.yml` workflow, issue #573) run
# `bca vcs --format html --output vcs.html`.
# ---------------------------------------------------------------------------
vcs:
	@$(SELF_SCAN_BCA) vcs --top $${BCA_VCS_TOP:-40}

# ---------------------------------------------------------------------------
# Python tooling (big-code-analysis-py)
#
# Most targets in this section gracefully no-op when the corresponding
# tool is absent — matching how the markdown / TOML lint families
# behave on a barebones host. CI installs all tools, so the skip path
# never fires there. Exception: `py-bootstrap` is the documented
# setup entry point and hard-fails when `uv` is missing, so a
# contributor sees the install instruction immediately rather than
# silently skipping.
#
# Tools used:
#   uv       — Python env / lockfile manager (required for py-bootstrap)
#   ruff     — lint + format
#   mypy     — type check (strict mode, invoked from the bindings dir)
#   pyright  — type check (strict mode, second opinion)
#   maturin  — build the compiled extension into the active venv
#
# `py-test` requires an active venv that maturin can write the .so
# into. The recipe does NOT create one — if `VIRTUAL_ENV` is not set,
# maturin will fail with a clear error. CI explicitly creates one per
# matrix leg (see `.github/workflows/ci.yml`). Locally, run
# `make py-bootstrap` once to create big-code-analysis-py/.venv from
# the checked-in uv.lock.
# ---------------------------------------------------------------------------

# Bootstrap the bindings dev environment from uv.lock. Hard-fails if
# uv is missing — there is no pip fallback because uv.lock is the
# project's source of truth for the resolved dev set, and consuming
# it requires uv. `uv sync --locked` creates big-code-analysis-py/.venv,
# installs the locked `dev` extra into it, and is idempotent. The
# `--locked` flag refuses to mutate uv.lock — if pyproject.toml has
# drifted from the lockfile, this target fails loudly and points at
# `make py-relock` instead of silently rewriting the lockfile on
# every contributor's machine.
py-bootstrap:
	@command -v uv >/dev/null 2>&1 || { \
	  echo "ERROR: uv missing — install via 'curl -LsSf https://astral.sh/uv/install.sh | sh' (or 'brew install uv', 'pipx install uv')"; \
	  exit 1; }
	@cd "$(BCA_PY_DIR)" && uv sync --locked --extra dev

# Alias so contributors familiar with `uv sync` find the right target.
py-sync: py-bootstrap

# Regenerate uv.lock after editing pyproject.toml (e.g. bumping a
# dev-extra floor). Separated from py-bootstrap so lockfile churn is
# always a deliberate, reviewable act — `make py-bootstrap` will not
# silently update the lockfile on contributors' machines.
# The hash-pinned exports under big-code-analysis-py/requirements/
# are regenerated in the same breath: CI installs its Python tooling
# with `pip install --require-hashes -r` from those files (OpenSSF
# Scorecard Pinned-Dependencies), so they must always mirror uv.lock.
py-relock:
	@command -v uv >/dev/null 2>&1 || { \
	  echo "ERROR: uv missing — install via 'curl -LsSf https://astral.sh/uv/install.sh | sh' (or 'brew install uv', 'pipx install uv')"; \
	  exit 1; }
	@cd "$(BCA_PY_DIR)" && uv lock
	@cd "$(BCA_PY_DIR)" && mkdir -p requirements && \
	  uv export --locked --no-emit-project --extra dev -o requirements/dev.txt && \
	  uv export --locked --no-emit-project --extra examples -o requirements/examples.txt

# `scripts/smoke` is a second, separate ruff invocation rather than an extra
# path on the bindings call: `--config` would otherwise re-root the bindings
# dir's own `extend-exclude` (e.g. `_native.pyi`) against the wrong base and
# spuriously flag excluded files. The smoke dir has nothing to exclude, so
# pointing `--config` at the bindings pyproject just gives it the same
# ruleset (line-length 100, the `[tool.ruff.lint] select` set) (#995).
#
# Resolve ruff the way `py-typecheck` resolves mypy and pyright: prefer
# the bindings dir's `.venv/bin/ruff`, fall back to PATH, skip cleanly
# when neither exists. Hoisted into one variable because all three ruff
# targets need the identical resolution, and because PATH-first was
# wrong in the same way three times over (#1230). Three provisioning
# paths install an *unpinned* ruff onto PATH — `mise.toml`'s
# `"pipx:ruff" = "latest"`, the Dockerfile's `uv tool install ruff`, and
# the `pipx install ruff` CONTRIBUTING documents — so PATH-first let the
# local gate run a ruff outside the `pyproject.toml` `<0.17` ceiling
# while CI ran the `uv.lock`-resolved one. The venv copy is by
# construction the version `make check-ruff-lockstep` gates.
#
# `exit 0` (not a shell `if/else` around the whole body) keeps each
# recipe a single logical line: the resolve step ends the sub-shell
# successfully and make moves on, exactly as the old `else echo
# "...skipping"` arm did.
#
# The `|| true` is load-bearing under this Makefile's
# `.SHELLFLAGS := -eu -o pipefail -c`. An assignment takes the exit
# status of its command substitution, and the right-hand side of `||`
# is the list's last command, so a failing `command -v` (bash returns 1
# when the name is absent) kills the shell under `-e` — turning the
# skip-when-missing path into `make: *** [py-lint] Error 1` with no
# diagnostic at all. Measured, not theorised.
PY_RUFF_RESOLVE = ruff="$(BCA_PY_DIR)/.venv/bin/ruff"; \
	  [ -x "$$ruff" ] || ruff="$$(command -v ruff 2>/dev/null || true)"; \
	  if [ -z "$$ruff" ]; then echo "ruff not found; skipping $@"; exit 0; fi

py-fmt:
	@$(PY_RUFF_RESOLVE); \
	  echo "Formatting Python sources..."; \
	  "$$ruff" format "$(BCA_PY_DIR)" && \
	  "$$ruff" format --config "$(BCA_PY_DIR)/pyproject.toml" "$(SMOKE_PY_DIR)" || \
	    { echo "ruff format failed"; exit 1; }

py-fmt-check:
	@$(PY_RUFF_RESOLVE); \
	  echo "Checking Python formatting..."; \
	  "$$ruff" format --check "$(BCA_PY_DIR)" && \
	  "$$ruff" format --check --config "$(BCA_PY_DIR)/pyproject.toml" "$(SMOKE_PY_DIR)" || \
	    { echo "Python files not formatted (run 'make py-fmt')"; exit 1; }

py-lint:
	@$(PY_RUFF_RESOLVE); \
	  echo "Linting Python sources..."; \
	  "$$ruff" check "$(BCA_PY_DIR)" && \
	  "$$ruff" check --config "$(BCA_PY_DIR)/pyproject.toml" "$(SMOKE_PY_DIR)" || \
	    { echo "ruff lint found issues"; exit 1; }

py-typecheck:
	@# Prefer the bindings dir's `.venv/bin/{mypy,pyright}` when
	@# present so the type checker resolves dev-dependencies
	@# (pytest, etc.) declared in `big-code-analysis-py/pyproject.toml`
	@# from the project's documented venv layout. Fall back to the
	@# host's PATH when the venv hasn't been provisioned (CI sets
	@# `VIRTUAL_ENV` and uses PATH-resolved binaries). A pipx-isolated
	@# system `mypy` can't see the bindings dir's pytest stubs.
	@# The smoke harness (`$(SMOKE_LIB_PY)`) is appended to the checked
	@# paths so it is type-gated under the same `--strict` posture (#995);
	@# mypy with cwd=$(BCA_PY_DIR) discovers the bindings `[tool.mypy]`
	@# config and resolves `import big_code_analysis` from the venv.
	@if [ -x "$(BCA_PY_DIR)/.venv/bin/mypy" ]; then \
	  echo "Type-checking with mypy --strict (venv)..."; \
	  (cd "$(BCA_PY_DIR)" && .venv/bin/mypy --strict python tests examples "$(SMOKE_LIB_PY)") || \
	    { echo "mypy --strict found issues"; exit 1; }; \
	elif command -v mypy >/dev/null 2>&1; then \
	  echo "Type-checking with mypy --strict..."; \
	  (cd "$(BCA_PY_DIR)" && mypy --strict python tests examples "$(SMOKE_LIB_PY)") || \
	    { echo "mypy --strict found issues"; exit 1; }; \
	else echo "mypy not found; skipping mypy stage of py-typecheck"; fi
	@if [ -x "$(BCA_PY_DIR)/.venv/bin/pyright" ]; then \
	  echo "Type-checking with pyright (strict, venv)..."; \
	  (cd "$(BCA_PY_DIR)" && .venv/bin/pyright) || \
	    { echo "pyright found issues"; exit 1; }; \
	elif command -v pyright >/dev/null 2>&1; then \
	  echo "Type-checking with pyright (strict)..."; \
	  (cd "$(BCA_PY_DIR)" && pyright) || \
	    { echo "pyright found issues"; exit 1; }; \
	else echo "pyright not found; skipping pyright stage of py-typecheck"; fi

# Two pre-build cleanups defend against distinct failure modes:
#
# 1. `find $(BASE_DIR)target -name 'libbig_code_analysis_py*' -delete`
#    Defeats a maturin 1.13 + cargo-incremental-cache interaction that
#    reliably emits a 0-byte .so on the second back-to-back invocation
#    when neither sources nor deps changed (the wheel-build step
#    truncates target/maturin/libbig_code_analysis_py.so before cargo
#    decides "no rebuild needed" and skips the relink). Forcing a
#    relink each time is roughly free (~50ms).
#
# 2. `rm -f $(BCA_PY_DIR)/python/big_code_analysis/_native*.so`
#    Removes the previous editable-install extension before
#    `maturin develop` writes a fresh one. A contributor who has
#    switched build modes (non-abi3 → abi3, or vice versa) ends up
#    with both `_native.cpython-3XX-<plat>.so` AND `_native.abi3.so`
#    in the source tree — Python's loader prefers the more-specific
#    cpython-tagged filename, shadowing the fresh build. Symptom:
#    ImportError for any symbol added since the last non-abi3 build,
#    even though maturin reports a successful rebuild. Glob covers
#    every tag variant in one shot.
#
# CI does NOT need these guards: each CI job starts from a fresh
# checkout (target/ is restored from cache but the .so is rebuilt on
# every job invocation, not repeated within a single job), and the
# editable install dir is never populated before the build step.
#
# Both guards live in one variable, invoked as `@$(PY_EXT_CLEAN)` by every
# maturin-develop target (py-test, py-stubtest, smoke-lib), so a fix really
# does land in one place — the #995 review caught a third copy drifting from
# the "hoisted to one place" promise this comment once made per-target.
PY_EXT_CLEAN := find "$(BASE_DIR)target" -name 'libbig_code_analysis_py*' -delete 2>/dev/null || true; rm -f "$(BCA_PY_DIR)/python/big_code_analysis/"_native*.so

py-test:
	@# Pre-build cleanups (see header comment); safe no-ops on missing files.
	@$(PY_EXT_CLEAN)
	@# Prefer the bindings dir's `.venv/bin/{maturin,python}` over the
	@# host's PATH for the same reason `py-typecheck` does: the venv
	@# has pytest (declared as a dev-dependency in
	@# `big-code-analysis-py/pyproject.toml`), the host's bare Python
	@# typically does not. CI activates the venv explicitly via
	@# `VIRTUAL_ENV` and uses PATH-resolved binaries — both paths
	@# reach the same wheel because `maturin develop` installs into
	@# whichever venv it finds.
	@if [ -x "$(BCA_PY_DIR)/.venv/bin/maturin" ] && [ -x "$(BCA_PY_DIR)/.venv/bin/python" ]; then \
	  echo "Building extension + running pytest (venv)..."; \
	  (cd "$(BCA_PY_DIR)" && .venv/bin/maturin develop --quiet && .venv/bin/python -m pytest) || \
	    { echo "py-test failed"; exit 1; }; \
	elif command -v maturin >/dev/null 2>&1; then \
	  echo "Building extension + running pytest..."; \
	  (cd "$(BCA_PY_DIR)" && maturin develop --quiet && python -m pytest) || \
	    { echo "py-test failed"; exit 1; }; \
	else echo "maturin not found; skipping py-test"; fi

# `mypy stubtest` diffs the hand-written `_native.pyi` stub against the
# compiled PyO3 extension — names, signatures, and *defaults* — catching
# the `#[pyo3(signature = …)]`-vs-stub drift that the usage-only
# `py-typecheck` mypy/pyright passes cannot see (#583 shipped one such
# drift; #673 closes the gap). Unlike `py-typecheck`, stubtest must
# import the built extension, so it carries the same `maturin develop`
# build + pre-build cleanups as `py-test` and skips cleanly when the
# venv / maturin / stubtest are absent. The allowlist covers the
# deliberate facade differences (the `vcs` submodule, runtime
# `__all__`); see `big-code-analysis-py/stubtest-allowlist.txt`.
py-stubtest:
	@$(PY_EXT_CLEAN)
	@if [ -x "$(BCA_PY_DIR)/.venv/bin/maturin" ] && [ -x "$(BCA_PY_DIR)/.venv/bin/python" ]; then \
	  if "$(BCA_PY_DIR)/.venv/bin/python" -c "import mypy.stubtest" >/dev/null 2>&1; then \
	    echo "Building extension + running mypy stubtest (venv)..."; \
	    (cd "$(BCA_PY_DIR)" && .venv/bin/maturin develop --quiet && \
	      .venv/bin/python -m mypy.stubtest big_code_analysis._native big_code_analysis.vcs \
	        --allowlist stubtest-allowlist.txt) || \
	      { echo "stubtest found stub/runtime drift"; exit 1; }; \
	  else echo "mypy stubtest not found in venv; skipping py-stubtest"; fi; \
	elif command -v maturin >/dev/null 2>&1 && python -c "import mypy.stubtest" >/dev/null 2>&1; then \
	  echo "Building extension + running mypy stubtest..."; \
	  (cd "$(BCA_PY_DIR)" && maturin develop --quiet && \
	    python -m mypy.stubtest big_code_analysis._native big_code_analysis.vcs \
	      --allowlist stubtest-allowlist.txt) || \
	    { echo "stubtest found stub/runtime drift"; exit 1; }; \
	else echo "maturin or mypy stubtest not found; skipping py-stubtest"; fi

# ---------------------------------------------------------------------------
# Benchmark harness (#1068)
# ---------------------------------------------------------------------------
# Deliberately NOT wired into `pre-commit` / `ci` / `lint`. Shared
# runners cannot produce stable numbers, and a timing assertion in the
# per-PR gate is exactly what this harness replaced — see
# docs/development/benchmarking.md. The scheduled
# .github/workflows/benchmark.yml runs `bench-scaling` out of band, and
# a human runs these around any change to the metric walk.
#
#   bench-scaling   complexity-class gate: fits time ~ size^k per probe
#                   (size = nesting depth, or one parent's child count)
#                   and fails when k exceeds the probe's bound.
#   bench-walk      criterion measurements over the corpus slice, per
#                   metric. Pass criterion flags after `--`, e.g.
#                   `make bench-walk BENCH_ARGS="--save-baseline before"`.
#   bench           both.
BENCH_ARGS ?=

bench: bench-scaling bench-walk

bench-scaling:
	@echo "Running the metric-walk complexity-class gate..."
	@cargo bench -p big-code-analysis-bench --bench scaling -- $(BENCH_ARGS)

bench-walk:
	@echo "Running criterion metric-walk benchmarks..."
	@cargo bench -p big-code-analysis-bench --bench metric_walk -- $(BENCH_ARGS)

# ---------------------------------------------------------------------------
# Fuzzing harness (#1154)
# ---------------------------------------------------------------------------
# Deliberately NOT wired into `pre-commit` / `ci` / `lint`, for the same
# reason as the benchmark harness above: a nightly libFuzzer build under
# ASan costs about a minute even warm, which does not belong in the
# per-commit loop. The scheduled + per-PR .github/workflows/fuzz.yml runs
# `fuzz-check` and `fuzz-smoke` out of band. See docs/development/fuzzing.md.
#
# The workflow calls these targets rather than `cargo fuzz` directly, so
# the sanitizer plumbing below has exactly one definition.
#
#   fuzz-check  fmt, clippy, test, and build every target. This is the
#               crate's only format, lint *and* test gate: `fuzz` is
#               workspace-excluded, so none of `cargo fmt --all`,
#               `cargo clippy --workspace` or `cargo test --workspace`
#               can see it (the #164 / #1228 blind spot). The tests it
#               runs are the ones pinning that the depth generator
#               actually exceeds the serialization bounds it exists to
#               reach — without them a generator that quietly stopped
#               nesting would still run, and still look like coverage.
#
#               Every stage is pinned to `+nightly`, the fmt one
#               included, so this target either runs wholly on nightly
#               or skips wholly. An unpinned `cargo fmt` resolves
#               through the *default* toolchain, which is stable on a
#               typical checkout and nightly in the fuzz workflow —
#               agreeing today and free to diverge on any nightly
#               rustfmt release, which is the "works locally, red in
#               CI" shape this repository keeps paying for.
#   fuzz-smoke  replay the committed corpora with a short iteration
#               bound. Bounded by `-runs`, never `-max_total_time`: a
#               wall-clock bound makes a failure non-reproducible across
#               runners of different speeds.
#   fuzz-run    one target for FUZZ_RUNS iterations, e.g.
#               `make fuzz-run FUZZ_TARGET=preproc_macro FUZZ_RUNS=1000000`.
#               With FUZZ_INPUT set it replays that one file instead —
#               the reproduce step for a crash artifact. Go through the
#               target rather than calling `cargo fuzz run` by hand: the
#               sanitizer env below is what instruments the tree-sitter
#               C scanners, and `cc` emits `rerun-if-env-changed` for
#               those variables, so a bare invocation silently *rebuilds*
#               the grammars without ASan and reproduces a C-scanner
#               crash weakly or not at all.
FUZZ_RUNS ?= 100000
# 60 s is measured, not chosen: the slowest *legitimate* input seen so
# far — nested_depth's 5-byte seed decoding to 508 alternating
# Block/Lambda levels of JavaScript — takes 11 s solo under ASan plus
# the harness's ten-walk fan-out, so the previous default of 10 failed
# on correct behaviour (#1308). Sixty keeps ~5x headroom over that
# while still catching the one thing a wall-clock timeout reliably
# catches, an unbounded loop. Raise it only for a new, slower,
# *measured* legitimate input; investigate anything else.
FUZZ_TIMEOUT ?= 60
FUZZ_TARGET ?= parse_cpp
FUZZ_INPUT ?=

# ASan on the Rust side is cargo-fuzz's own doing. The tree-sitter
# grammars are C, compiled by build scripts through the `cc` crate, and
# are *not* instrumented unless asked — which would leave the largest
# body of memory-unsafe code in the dependency graph outside the
# sanitizer. That is not hypothetical: the unbounded `deserialize` memcpy
# in tree-sitter-cpp's raw-string scanner (#1058, upstream
# tree-sitter-cpp#368) is an ASan find in exactly this code.
#
# It has to be the triple-qualified spelling. `cc` resolves
# `<VAR>_<target>`, then `<VAR>_<target_with_underscores>`, then
# `<BUILD_KIND>_<VAR>`, then bare `<VAR>` — and picks `HOST_` rather than
# `TARGET_` for the build kind when it is not cross-compiling. A native
# fuzz build is not, so `TARGET_CFLAGS` is silently inert here and bare
# `CFLAGS` would also reach host build-script compilation.
#
# Recursive `=`, not `:=`: `rustc -vV` then runs only when a fuzz target
# actually needs it rather than on every `make` invocation.
#
# Every `cargo fuzz` subcommand is passed `--target $(FUZZ_HOST_TRIPLE)`
# for the same reason, and it is not belt-and-braces. cargo-fuzz derives
# its default target from the triple *it was itself built for*, not from
# the host's `rustc`. Install it with `cargo install` and that is the
# host; install it through a binstall-backed action, as the fuzz workflow
# does, and you get the prebuilt `x86_64-unknown-linux-musl` artifact —
# whereupon it builds the targets for musl, which is not installed as a
# rustup target and is statically linked, so the build dies on
# "sanitizer is incompatible with statically linked libc".
#
# The quieter half is why this is pinned rather than worked around in
# CI: keying the CFLAGS to one triple while cargo-fuzz builds for
# another attaches the instrumentation to nothing at all, and the build
# still succeeds. Naming the triple once and using it for both makes
# that disagreement unrepresentable.
FUZZ_SAN_FLAGS := -fsanitize=address -fno-omit-frame-pointer
FUZZ_HOST_TRIPLE = $(shell rustc -vV | sed -n 's/^host: //p')
FUZZ_CC_ENV = CFLAGS_$(subst -,_,$(FUZZ_HOST_TRIPLE))="$(FUZZ_SAN_FLAGS)" \
	  CXXFLAGS_$(subst -,_,$(FUZZ_HOST_TRIPLE))="$(FUZZ_SAN_FLAGS)"

# Leak detection stays ON. The one entry in the suppressions file is a
# leak we found, measured, and cannot fix from here (it is upstream in
# tree-sitter-perl); suppressing it by symbol rather than passing
# `-detect_leaks=0` keeps every *other* leak on the Perl path fatal. The
# file documents each entry — read it before adding one.
#
# A `leak:` entry names a *function*, and LSan matches it against the
# symbolized stack — so with no symbolizer reachable it matches nothing,
# every suppression silently stops applying, and the known leak becomes
# a fatal error. That is not hypothetical: it is how this first ran red
# in CI while passing locally, because this distro ships
# `/usr/bin/llvm-symbolizer` and the runner image only has the versioned
# copies under `/usr/lib/llvm-*/bin`. Note `rustup component add
# llvm-tools` does *not* provide one, despite shipping the rest of the
# LLVM binutils.
#
# Resolved rather than assumed, newest first, and the run recipes refuse
# to start without it — a silently-inapplicable suppression is precisely
# the failure this comment exists to prevent.
FUZZ_SYMBOLIZER = $(shell command -v llvm-symbolizer 2>/dev/null || \
	  ls -1 /usr/lib/llvm-*/bin/llvm-symbolizer 2>/dev/null | sort -V | tail -1)
FUZZ_RUN_ENV = LSAN_OPTIONS=suppressions=$(BASE_DIR)fuzz/lsan-suppressions.txt \
	  ASAN_SYMBOLIZER_PATH=$(FUZZ_SYMBOLIZER)

# Fail with the reason rather than with an unsuppressed leak report.
# One line, not a `define`: a multi-line define carries embedded newlines
# that break the `\`-continued `if` block each recipe splices it into.
FUZZ_REQUIRE_SYMBOLIZER = if [ -z "$(FUZZ_SYMBOLIZER)" ]; then echo "no llvm-symbolizer found; LSan cannot match the entries in fuzz/lsan-suppressions.txt, so the known tree-sitter-perl leak would be reported as a failure. Install one (Debian/Ubuntu: 'apt-get install llvm'; macOS: it ships with Xcode's clang)."; exit 1; fi

# libFuzzer *writes* every coverage-increasing input it finds into the
# first corpus directory it is given, and treats later ones as read-only
# inputs. Pointed at `fuzz/corpus/` that turns the committed seed set
# into a dumping ground — one 5 000-run pass over ten targets grew 93
# checked-in seeds to over 4 000 untracked files, so any local run left
# the tree dirty and a careless `git add` would have committed them.
# Discoveries go here instead (gitignored); the seeds stay read-only.
FUZZ_WORK = $(BASE_DIR)fuzz/corpus-work

fuzz-check:
	@if rustup toolchain list 2>/dev/null | grep -q '^nightly' && \
	    command -v cargo-fuzz >/dev/null 2>&1; then \
	  echo "Checking formatting of workspace-excluded fuzz crate..."; \
	  cargo +nightly fmt --manifest-path $(BASE_DIR)fuzz/Cargo.toml --check || \
	    { echo "fuzz crate is not formatted (run 'cargo +nightly fmt --manifest-path fuzz/Cargo.toml')"; exit 1; }; \
	  echo "Linting workspace-excluded fuzz crate..."; \
	  cargo +nightly clippy \
	    --manifest-path $(BASE_DIR)fuzz/Cargo.toml \
	    --all-targets --locked -- -D warnings; \
	  echo "Running tests for workspace-excluded fuzz crate..."; \
	  cargo +nightly test \
	    --manifest-path $(BASE_DIR)fuzz/Cargo.toml \
	    --locked; \
	  echo "Building cargo-fuzz targets (nightly, ASan)..."; \
	  $(FUZZ_CC_ENV) cargo +nightly fuzz build --target $(FUZZ_HOST_TRIPLE); \
	else \
	  echo "nightly toolchain or cargo-fuzz not found; skipping fuzz-check"; \
	fi

# The loop collects failures instead of stopping at the first, because
# this is what the quarterly cron runs and nobody is watching it. A hunt
# that trips over three unrelated crashes should report three; stopping
# at the first hides the other two until the quarter after the fix, and
# the artifact upload in fuzz.yml already globs every target's
# reproducer. `.SHELLFLAGS` carries `-e`, but a command on the left of
# `||` is not a fatal failure under it, so the run survives a crashing
# target and still exits non-zero at the end.
#
# `fuzz-replay` below keeps the opposite shape deliberately: it is the
# per-PR gate, where one broken seed is already enough to stop the
# merge, and the seconds saved by not replaying the rest are the point.
fuzz-smoke:
	@if rustup toolchain list 2>/dev/null | grep -q '^nightly' && \
	    command -v cargo-fuzz >/dev/null 2>&1; then \
	  $(FUZZ_REQUIRE_SYMBOLIZER); \
	  failed=""; \
	  for t in $$(cargo +nightly fuzz list); do \
	    echo "Fuzzing $$t for $(FUZZ_RUNS) runs..."; \
	    mkdir -p $(FUZZ_WORK)/"$$t"; \
	    $(FUZZ_CC_ENV) $(FUZZ_RUN_ENV) cargo +nightly fuzz run --target $(FUZZ_HOST_TRIPLE) "$$t" \
	      $(FUZZ_WORK)/"$$t" $(BASE_DIR)fuzz/corpus/"$$t" \
	      -- -runs=$(FUZZ_RUNS) -timeout=$(FUZZ_TIMEOUT) \
	      || failed="$$failed $$t"; \
	  done; \
	  if [ -n "$$failed" ]; then \
	    echo "fuzz-smoke: failing targets:$$failed"; \
	    echo "reproduce with: make fuzz-run FUZZ_TARGET=<target> FUZZ_INPUT=fuzz/artifacts/<target>/<file>"; \
	    exit 1; \
	  fi; \
	else \
	  echo "nightly toolchain or cargo-fuzz not found; skipping fuzz-smoke"; \
	fi

# Replay the committed seeds and stop: `-runs=0` executes the corpus once
# and exits without mutating. This is the regression half of fuzzing —
# "did this change break an input that used to be fine" — as opposed to
# the hunt, and it is what CI runs per PR. Seconds, not minutes.
fuzz-replay:
	@if rustup toolchain list 2>/dev/null | grep -q '^nightly' && \
	    command -v cargo-fuzz >/dev/null 2>&1; then \
	  $(FUZZ_REQUIRE_SYMBOLIZER); \
	  for t in $$(cargo +nightly fuzz list); do \
	    echo "Replaying committed seeds for $$t..."; \
	    mkdir -p $(FUZZ_WORK)/"$$t"; \
	    $(FUZZ_CC_ENV) $(FUZZ_RUN_ENV) cargo +nightly fuzz run \
	      --target $(FUZZ_HOST_TRIPLE) "$$t" \
	      $(FUZZ_WORK)/"$$t" $(BASE_DIR)fuzz/corpus/"$$t" \
	      -- -runs=0 -timeout=$(FUZZ_TIMEOUT); \
	  done; \
	else \
	  echo "nightly toolchain or cargo-fuzz not found; skipping fuzz-replay"; \
	fi

fuzz-run:
	@if rustup toolchain list 2>/dev/null | grep -q '^nightly' && \
	    command -v cargo-fuzz >/dev/null 2>&1; then \
	  $(FUZZ_REQUIRE_SYMBOLIZER); \
	  if [ -n "$(FUZZ_INPUT)" ]; then \
	    echo "Replaying $(FUZZ_TARGET) against $(FUZZ_INPUT)..."; \
	    $(FUZZ_CC_ENV) $(FUZZ_RUN_ENV) cargo +nightly fuzz run --target $(FUZZ_HOST_TRIPLE) $(FUZZ_TARGET) \
	      "$(FUZZ_INPUT)" -- -timeout=$(FUZZ_TIMEOUT); \
	  else \
	    echo "Fuzzing $(FUZZ_TARGET) for $(FUZZ_RUNS) runs..."; \
	    mkdir -p $(FUZZ_WORK)/$(FUZZ_TARGET); \
	    $(FUZZ_CC_ENV) $(FUZZ_RUN_ENV) cargo +nightly fuzz run --target $(FUZZ_HOST_TRIPLE) $(FUZZ_TARGET) \
	      $(FUZZ_WORK)/$(FUZZ_TARGET) $(BASE_DIR)fuzz/corpus/$(FUZZ_TARGET) \
	      -- -runs=$(FUZZ_RUNS) -timeout=$(FUZZ_TIMEOUT); \
	  fi; \
	else \
	  echo "nightly toolchain or cargo-fuzz not found; skipping fuzz-run"; \
	fi

fuzz-tmin:
	@if [ -z "$(FUZZ_INPUT)" ]; then \
	  echo "fuzz-tmin needs FUZZ_INPUT=<path to a crash artifact>"; \
	  exit 2; \
	fi
	@if rustup toolchain list 2>/dev/null | grep -q '^nightly' && \
	    command -v cargo-fuzz >/dev/null 2>&1; then \
	  $(FUZZ_REQUIRE_SYMBOLIZER); \
	  echo "Minimising $(FUZZ_INPUT) for $(FUZZ_TARGET)..."; \
	  $(FUZZ_CC_ENV) $(FUZZ_RUN_ENV) cargo +nightly fuzz tmin --target $(FUZZ_HOST_TRIPLE) $(FUZZ_TARGET) \
	    "$(FUZZ_INPUT)" -- -timeout=$(FUZZ_TIMEOUT); \
	else \
	  echo "nightly toolchain or cargo-fuzz not found; skipping fuzz-tmin"; \
	fi

# ---------------------------------------------------------------------------
# Release/wheel smoke harnesses (#995)
# ---------------------------------------------------------------------------
# The wheel workflows (python-wheels.yml, python-cli-wheels.yml) and the
# per-PR smoke-dryrun.yml all invoke the *same* checked-in scripts under
# scripts/smoke/. These targets run them locally against a dev build so a
# stale assertion (the #530 integer-metric / #614 AnalysisFailure drift that
# blocked v2.0.0) surfaces before a tag, not at release time.
smoke: smoke-cli smoke-lib

# Build a debug `bca` and run the CLI smoke against it — mirrors the
# python-cli-wheels.yml smoke step, which runs the identical script against
# the packaged console binary.
smoke-cli:
	@echo "Building bca + running CLI smoke..."
	@cargo build -q -p big-code-analysis-cli
	@BCA="$(BASE_DIR)target/debug/bca" bash "$(BASE_DIR)scripts/smoke/cli_wheel_smoke.sh"

# Build the bindings via `maturin develop` and run the library smoke —
# mirrors the python-wheels.yml smoke step (packaged abi3 wheel) and carries
# the same 0-byte-.so pre-build cleanups as py-test.
smoke-lib:
	@$(PY_EXT_CLEAN)
	@if [ -x "$(BCA_PY_DIR)/.venv/bin/maturin" ] && [ -x "$(BCA_PY_DIR)/.venv/bin/python" ]; then \
	  echo "Building extension + running library smoke (venv)..."; \
	  (cd "$(BCA_PY_DIR)" && .venv/bin/maturin develop --quiet) && \
	    "$(BCA_PY_DIR)/.venv/bin/python" "$(BASE_DIR)scripts/smoke/lib_wheel_smoke.py" || \
	    { echo "smoke-lib failed"; exit 1; }; \
	elif command -v maturin >/dev/null 2>&1; then \
	  echo "Building extension + running library smoke..."; \
	  (cd "$(BCA_PY_DIR)" && maturin develop --quiet) && \
	    python "$(BASE_DIR)scripts/smoke/lib_wheel_smoke.py" || \
	    { echo "smoke-lib failed"; exit 1; }; \
	else echo "maturin not found; skipping smoke-lib"; fi

# ---------------------------------------------------------------------------
# Lint aggregate
# ---------------------------------------------------------------------------
clippy:
	@echo "Running Rust lints..."
	@cargo clippy --workspace --all-targets -- -D warnings
	@cargo clippy --workspace --all-targets --all-features -- -D warnings

udeps:
	@echo "Detecting unused dependencies..."
	@cargo +nightly udeps --workspace --all-targets

# Reuse the _ci-* family so `make lint` runs the same set of gates as
# `make ci`'s non-cargo-pipeline branch, in parallel. _ci-clippy holds
# the workspace `target/` lock; the other lints don't use cargo at all
# (or use a separate `target/`, in _ci-enums-check's case), so they
# fan out safely.
lint:
	$(MAKE) -j --output-sync=target \
	  _ci-clippy \
	  _ci-shellcheck _ci-markdown-lint _ci-toml-lint _ci-makefile-check \
	  _ci-actionlint _ci-snapshot-anchors _ci-snapshot-anchors-test _ci-rustfmt-bail _ci-rustfmt-bail-test _ci-grammar-marker-sync _ci-grammar-marker-sync-test _ci-check-versions _ci-check-versions-test _ci-check-grammar-crate-test _ci-check-excluded-manifests _ci-check-excluded-manifests-test _ci-check-ruff-lockstep _ci-check-ruff-lockstep-test _ci-check-publish-metadata _ci-check-publish-metadata-test _ci-check-manpage-assets _ci-check-manpage-drift-test _ci-check-diagnostic-prefix _ci-check-diagnostic-prefix-test _ci-check-feature-gates-test _ci-check-test-lang-gates _ci-check-test-lang-gates-test _ci-check-safety-doc-pin _ci-check-safety-doc-pin-test _ci-worktree-setup-test _ci-gate-status-test _ci-check-tools-test _ci-enums-check _ci-enums-codegen-drift _ci-enums-codegen-drift-test

# ---------------------------------------------------------------------------
# Maintenance
# ---------------------------------------------------------------------------

# Python-only clean. Removes everything maturin / pytest / ruff / mypy
# can recreate from sources: the uv-managed venv, the editable
# install's compiled extension (matches both abi3 and per-version
# tagged variants — switching build modes leaves stale `.so` files
# that Python's loader prefers over the fresh one), the per-tool
# caches, and `__pycache__` trees. Does NOT remove `uv.lock` (a
# checked-in artifact) or `target/maturin/` (handled by `cargo
# clean`).
#
# Best-effort: `rm -rf` and `rm -f` are no-ops on missing paths, and
# `find` swallows its own missing-root errors via `2>/dev/null || true`
# (matching the idiom used by py-test on `find $(BASE_DIR)target`).
# A missing BCA_PY_DIR (sparse checkout, experimental removal) leaves
# every line as a silent no-op and the recipe still exits 0 under
# `.SHELLFLAGS := -eu -o pipefail -c`.
py-clean:
	@echo "Removing Python build artifacts..."
	@# `.venv` is a bind-mount point inside the dev container
	@# (see dev-env-run), and a mount point cannot be unlinked:
	@# plain `rm -rf` would abort the recipe with EBUSY. Empty it in
	@# place when the directory itself refuses to go away.
	@rm -rf "$(BCA_PY_DIR)/.venv" 2>/dev/null || \
	  { find "$(BCA_PY_DIR)/.venv" -mindepth 1 -maxdepth 1 \
	      -exec rm -rf {} + && \
	    echo "  .venv is a mount point; emptied it in place."; }
	@rm -rf "$(BCA_PY_DIR)/.pytest_cache"
	@rm -rf "$(BCA_PY_DIR)/.mypy_cache"
	@rm -rf "$(BCA_PY_DIR)/.ruff_cache"
	@rm -f  "$(BCA_PY_DIR)/python/big_code_analysis/"_native*.so
	@find "$(BCA_PY_DIR)" -type d -name '__pycache__' -prune -exec rm -rf {} + 2>/dev/null || true

# `clean` stays cargo-only by default — a Rust-only contributor running
# `make clean` to reset incremental state should not lose their
# uv-managed venv as collateral (forcing a multi-step rebootstrap on
# the next Python invocation). Use `make distclean` for the full wipe.
clean:
	cargo clean

# Full wipe: cargo target/ AND every Python artifact (.venv, caches,
# editable-install .so, __pycache__). Useful before a fresh-checkout
# bootstrap or when reproducing CI from scratch.
distclean: py-clean clean

install: install-cli install-web

# `--locked` makes `cargo install` honour the committed Cargo.lock rather than
# re-resolving to the newest semver-compatible deps. The lock pins `time` to
# 0.3.46: 0.3.47+ trips a coherence error (E0119) in the blanket impl of
# cookie 0.16.2 (pulled transitively by actix-web 4) under rustc 1.95.
install-cli:
	RUSTFLAGS="-C target-cpu=native" cargo install --locked --path big-code-analysis-cli

install-web:
	RUSTFLAGS="-C target-cpu=native" cargo install --locked --path big-code-analysis-web

# ---------------------------------------------------------------------------
# Documentation
#
# `doc` and `doc-open` are warning-tolerant interactive viewers — they build
# whatever they can so a developer mid-refactor can still scroll the rendered
# output even when an unrelated doc-comment has drifted. `doc-check` is the
# strict gate invoked by the pre-commit and CI pipelines (`_pc-doc-check` /
# `_ci-doc-check`); it appends `-D warnings` to any caller-set `RUSTDOCFLAGS`
# so docs.rs-style invocations (e.g. `RUSTDOCFLAGS="--cfg docsrs"`) still
# compose correctly instead of being clobbered.
# ---------------------------------------------------------------------------
doc:
	cargo doc --no-deps --workspace --all-features

doc-open:
	cargo doc --no-deps --workspace --all-features --open

doc-check:
	@echo "Building rustdoc with -D warnings..."
	@RUSTDOCFLAGS="$${RUSTDOCFLAGS:-} -D warnings" \
	  cargo doc --no-deps --workspace --all-features

# Reproduce the docs.rs build locally: all-features plus `--cfg docsrs` on
# nightly (docs.rs's toolchain), so the `feature(doc_cfg)` badges compile and
# the published `vcs` surface is exercised. Skips cleanly when nightly is
# absent so it never blocks a stable-only checkout.
doc-check-docsrs:
	@if rustup toolchain list 2>/dev/null | grep -q '^nightly'; then \
	  echo "Building docs.rs-style rustdoc (nightly, --cfg docsrs, -D warnings)..."; \
	  RUSTDOCFLAGS="--cfg docsrs -D warnings" \
	    cargo +nightly doc --no-deps -p big-code-analysis -p big-code-analysis-ast --all-features; \
	else \
	  echo "nightly toolchain not found; skipping docs.rs-style doc check"; \
	fi

book:
	mdbook build big-code-analysis-book

book-serve:
	mdbook serve big-code-analysis-book

# Translation workflow (gettext via mdbook-i18n-helpers). English
# sources are the single source of truth; translations live in
# big-code-analysis-book/po/<lang>.po. messages.pot is generated on
# demand and is not tracked. Untranslated or stale (fuzzy) entries
# fall back to English at build time, so doc PRs never block on
# translation. See docs/development/translations.md.
#
# `-d` is absolute on purpose: mdbook 0.4 resolved a relative dest
# against the book root, 0.5 resolves it against the cwd. Under 0.5 the
# former `-d po` silently wrote the pot to ./po/ at the repo root, and
# book-po-update then failed on the missing file.
book-pot:
	@command -v mdbook-xgettext >/dev/null 2>&1 || { echo "mdbook-xgettext not found; install with: cargo install mdbook-i18n-helpers --version '=0.3.6' --locked"; exit 1; }
	@command -v mdbook >/dev/null 2>&1 || { echo "mdbook not found; this workflow needs the 0.4.x line (see MDBOOK_VERSION in .github/workflows/pages.yml and docs/development/translations.md)"; exit 1; }
	@ver="$$(mdbook --version | awk '{print $$2}' | tr -d v)"; \
	case "$$ver" in \
	  0.4.*) ;; \
	  *) echo "mdbook $$ver cannot be paired with mdbook-i18n-helpers 0.3.x."; \
	     echo "CI pins mdbook 0.4.40 + helpers 0.3.6 (MDBOOK_VERSION in"; \
	     echo ".github/workflows/pages.yml); helpers 0.4.0+ target mdbook 0.5."; \
	     echo "A mismatched pair still produces a pot, but one that splits"; \
	     echo "code blocks per line instead of whole — msgmerge then marks"; \
	     echo "every code-block entry fuzzy and silently shreds po/ja.po."; \
	     exit 1 ;; \
	esac
	MDBOOK_OUTPUT='{"xgettext": {}}' mdbook build big-code-analysis-book -d "$(CURDIR)/big-code-analysis-book/po"

book-po-update: book-pot
	msgmerge --update --backup=off big-code-analysis-book/po/ja.po big-code-analysis-book/po/messages.pot

book-ja:
	@command -v mdbook-gettext >/dev/null 2>&1 || { echo "mdbook-gettext not found; install with: cargo install mdbook-i18n-helpers --version '=0.3.6' --locked"; exit 1; }
	MDBOOK_BOOK__LANGUAGE=ja mdbook build big-code-analysis-book -d book/ja

# Manual fallback for publishing the book to GitHub Pages. The
# canonical publish path is .github/workflows/book.yml, which fires
# on every push to main; this target exists so contributors can
# republish from a checkout when CI is unavailable.
book-deploy:
	./utils/deploy-book-to-gh-pages.sh

# ---------------------------------------------------------------------------
# Combined workflows
# ---------------------------------------------------------------------------
all: check test build-release

# `pre-commit` and `ci` delegate their real work to the `_pc-all` /
# `_ci-all` aggregates below and run it under utils/gate-status.sh, which
# ends the log with exactly one `BCA_GATE: pass` / `BCA_GATE: fail
# (stage=…)` line (#1172). It replaces the old prose "Pre-commit checks
# passed", which existed only on the success path — a failing run had no
# terminal verdict at all, only `make[1]: *** [… _pc-fmt] Error 2` lines
# that a parallel run emits mid-stream while other stages are still
# going, and which are therefore not a verdict. The wrapper exits with
# the gate's own status; it never converts a red run into a green exit.
#
# The aggregates exist so the wrapper has a single command to run:
# `ci` needs two sequential sub-makes, and one verdict line per gate is
# the whole point. Do not invoke `_pc-all` / `_ci-all` directly — that
# skips the verdict.
pre-commit:
	@bash $(BASE_DIR)utils/gate-status.sh pre-commit $(MAKE) _pc-all

ci:
	@bash $(BASE_DIR)utils/gate-status.sh ci $(MAKE) _ci-all

_pc-all:
	$(MAKE) -j --output-sync=target \
	  _pc-test \
	  _pc-shellcheck _pc-markdown-lint _pc-toml-lint _pc-makefile-check \
	  _pc-actionlint _pc-snapshot-anchors _pc-snapshot-anchors-test _pc-rustfmt-bail _pc-rustfmt-bail-test _pc-grammar-marker-sync _pc-grammar-marker-sync-test _pc-check-versions _pc-check-versions-test _pc-check-grammar-crate-test _pc-check-excluded-manifests _pc-check-excluded-manifests-test _pc-check-ruff-lockstep _pc-check-ruff-lockstep-test _pc-check-publish-metadata _pc-check-publish-metadata-test _pc-check-manpage-assets _pc-check-manpage-drift-test _pc-check-diagnostic-prefix _pc-check-diagnostic-prefix-test _pc-check-feature-gates-test _pc-check-test-lang-gates _pc-check-test-lang-gates-test _pc-check-safety-doc-pin _pc-check-safety-doc-pin-test _pc-worktree-setup-test _pc-gate-status-test _pc-check-tools-test _pc-enums-check _pc-enums-codegen-drift _pc-enums-codegen-drift-test \
	  _pc-manpages \
	  _pc-self-scan _pc-self-scan-headroom \
	  _pc-py-fmt _pc-py-typecheck _pc-py-test _pc-py-stubtest

_ci-all:
	$(MAKE) _ci-fmt-check
	$(MAKE) -j --output-sync=target \
	  _ci-cargo-pipeline \
	  _ci-shellcheck _ci-markdown-lint _ci-toml-lint _ci-makefile-check \
	  _ci-actionlint _ci-snapshot-anchors _ci-snapshot-anchors-test _ci-rustfmt-bail _ci-rustfmt-bail-test _ci-grammar-marker-sync _ci-grammar-marker-sync-test _ci-check-versions _ci-check-versions-test _ci-check-grammar-crate-test _ci-check-excluded-manifests _ci-check-excluded-manifests-test _ci-check-ruff-lockstep _ci-check-ruff-lockstep-test _ci-check-publish-metadata _ci-check-publish-metadata-test _ci-check-manpage-assets _ci-check-manpage-drift-test _ci-check-diagnostic-prefix _ci-check-diagnostic-prefix-test _ci-check-feature-gates-test _ci-check-test-lang-gates _ci-check-test-lang-gates-test _ci-check-safety-doc-pin _ci-check-safety-doc-pin-test _ci-worktree-setup-test _ci-gate-status-test _ci-check-tools-test _ci-enums-check _ci-enums-codegen-drift _ci-enums-codegen-drift-test \
	  _ci-py-fmt-check _ci-py-lint _ci-py-typecheck _ci-py-test _ci-py-stubtest

# ---------------------------------------------------------------------------
# Parallel pre-commit DAG
#
# These _pc-* targets express the dependency graph so `make -j` runs
# independent stages concurrently. The `pre-commit` target invokes them
# with `-j --output-sync=target`.
#
# All cargo invocations against the workspace `target/` (clippy, test,
# udeps, py-test's maturin develop) share the package cache and the
# target/.cargo-lock mutex, so they are serialized into one chain.
# Non-cargo checks (lint families, py-fmt's ruff, py-typecheck's
# mypy + pyright) run in parallel with the cargo pipeline, gated only
# on _pc-fmt.
#
# Dependency graph:
#
#   _pc-fmt
#    ├── _pc-clippy → _pc-test → _pc-doc-check → _pc-udeps → _pc-manpages
#    │                → _pc-self-scan → _pc-self-scan-headroom → _pc-py-test
#    ├── _pc-shellcheck
#    ├── _pc-markdown-lint
#    ├── _pc-toml-lint
#    ├── _pc-makefile-check
#    ├── _pc-actionlint
#    ├── _pc-snapshot-anchors
#    ├── _pc-snapshot-anchors-test
#    ├── _pc-rustfmt-bail
#    ├── _pc-rustfmt-bail-test
#    ├── _pc-grammar-marker-sync
#    ├── _pc-grammar-marker-sync-test
#    ├── _pc-check-versions
#    ├── _pc-check-ruff-lockstep
#    ├── _pc-check-ruff-lockstep-test
#    ├── _pc-check-publish-metadata
#    ├── _pc-check-publish-metadata-test
#    ├── _pc-check-diagnostic-prefix
#    ├── _pc-check-diagnostic-prefix-test
#    ├── _pc-check-safety-doc-pin
#    ├── _pc-check-feature-gates-test
#    ├── _pc-check-safety-doc-pin-test
#    ├── _pc-worktree-setup-test
#    ├── _pc-gate-status-test
#    ├── _pc-check-tools-test
#    ├── _pc-enums-check
#    ├── _pc-enums-codegen-drift (chained after _pc-enums-check)
#    ├── _pc-py-fmt
#    └── _pc-py-typecheck
#
# _pc-self-scan and _pc-self-scan-headroom both invoke
# `cargo run --release -p big-code-analysis-cli`, which holds the
# workspace `target/` lock for the release-profile build, so they
# serialize into the cargo chain after _pc-manpages rather than
# fanning out in parallel. The hard tier runs first so a regression
# is named before the soft tier reports near-limit headroom.
#
# _pc-enums-check runs cargo on `enums/Cargo.toml`, which has its own
# `target/` (the crate is workspace-excluded), so it does NOT share the
# `target/` lock with the workspace cargo chain and is safe to run in
# parallel with _pc-clippy/_pc-test/_pc-udeps.
#
# _pc-py-fmt and _pc-py-typecheck do NOT touch cargo — they invoke
# ruff and mypy/pyright respectively against pre-built sources/stubs
# — so they run in parallel with the cargo pipeline.
#
# _pc-py-test runs `maturin develop` against the workspace target/, so
# it MUST chain after the tail of the cargo lock-holding pipeline
# (currently _pc-self-scan-headroom) rather than fanning out in
# parallel. Fanning out caused implicit serialization via cargo's
# lock anyway and obscured the true wall-clock cost. When a new
# cargo-lock-holding stage is added, extend this chain at the tail
# (and update the dependency graph comment above) — do not parallelise.
#
# Do not invoke _pc-* targets directly; use `make pre-commit`.
# ---------------------------------------------------------------------------
_pc-fmt:
	$(MAKE) fmt-check

_pc-clippy: _pc-fmt
	cargo clippy --workspace --all-targets -- -D warnings
	cargo clippy --workspace --all-targets --all-features -- -D warnings

_pc-test: _pc-clippy
	$(MAKE) test
	$(MAKE) test-doc

_pc-doc-check: _pc-test
	$(MAKE) doc-check

_pc-udeps: _pc-doc-check
	cargo +nightly udeps --workspace --all-targets

_pc-shellcheck: _pc-fmt
	$(MAKE) shellcheck

_pc-markdown-lint: _pc-fmt
	$(MAKE) markdown-lint

_pc-toml-lint: _pc-fmt
	$(MAKE) toml-lint

_pc-makefile-check: _pc-fmt
	$(MAKE) makefile-check

_pc-actionlint: _pc-fmt
	$(MAKE) actionlint

_pc-snapshot-anchors: _pc-fmt
	$(MAKE) snapshot-anchors

_pc-snapshot-anchors-test: _pc-fmt
	$(MAKE) snapshot-anchors-test

_pc-rustfmt-bail: _pc-fmt
	$(MAKE) rustfmt-bail

_pc-rustfmt-bail-test: _pc-fmt
	$(MAKE) rustfmt-bail-test

_pc-grammar-marker-sync: _pc-fmt
	$(MAKE) grammar-marker-sync

_pc-grammar-marker-sync-test: _pc-fmt
	$(MAKE) grammar-marker-sync-test

_pc-check-versions: _pc-fmt
	$(MAKE) check-versions

_pc-check-versions-test: _pc-fmt
	$(MAKE) check-versions-test

_pc-check-grammar-crate-test: _pc-fmt
	$(MAKE) check-grammar-crate-test

_pc-check-manpage-drift-test: _pc-fmt
	$(MAKE) check-manpage-drift-test

_pc-check-excluded-manifests: _pc-fmt
	$(MAKE) check-excluded-manifests

_pc-check-excluded-manifests-test: _pc-fmt
	$(MAKE) check-excluded-manifests-test

_pc-check-ruff-lockstep: _pc-fmt
	$(MAKE) check-ruff-lockstep

_pc-check-ruff-lockstep-test: _pc-fmt
	$(MAKE) check-ruff-lockstep-test

_pc-check-publish-metadata: _pc-fmt
	$(MAKE) check-publish-metadata

_pc-check-publish-metadata-test: _pc-fmt
	$(MAKE) check-publish-metadata-test

_pc-check-manpage-assets: _pc-fmt
	$(MAKE) check-manpage-assets

_pc-check-diagnostic-prefix: _pc-fmt
	$(MAKE) check-diagnostic-prefix

_pc-check-diagnostic-prefix-test: _pc-fmt
	$(MAKE) check-diagnostic-prefix-test

_pc-check-safety-doc-pin: _pc-fmt
	$(MAKE) check-safety-doc-pin

_pc-check-feature-gates-test: _pc-fmt
	$(MAKE) check-feature-gates-test

_pc-check-test-lang-gates: _pc-fmt
	$(MAKE) check-test-lang-gates

_pc-check-test-lang-gates-test: _pc-fmt
	$(MAKE) check-test-lang-gates-test

_pc-check-safety-doc-pin-test: _pc-fmt
	$(MAKE) check-safety-doc-pin-test

_pc-worktree-setup-test: _pc-fmt
	$(MAKE) worktree-setup-test

_pc-gate-status-test: _pc-fmt
	$(MAKE) gate-status-test

_pc-check-tools-test: _pc-fmt
	$(MAKE) check-tools-test

_pc-enums-check: _pc-fmt
	$(MAKE) enums-check

# Chain after enums-check so the cargo invocations share warm
# dependency fingerprints. The two stages target different
# build profiles (clippy/test vs run), so the leaf binary still
# needs its own build pass; the win is dependency-fingerprint
# reuse, not zero-cost. Note this ordering applies only inside
# the Makefile pipeline — the pre-commit framework's own hook
# scheduling does NOT honor it, so direct hook invocations pay
# a cold cargo build.
_pc-enums-codegen-drift: _pc-enums-check
	$(MAKE) enums-codegen-drift

# Self-tests run after the gate. The tests stand up a tempdir
# fixture (symlinked enums + copied target dirs) and exercise
# every documented failure mode of the gate. Cheap once the
# enums binary build is warm from _pc-enums-codegen-drift.
_pc-enums-codegen-drift-test: _pc-enums-codegen-drift
	$(MAKE) enums-codegen-drift-test

# Man-page drift gate. Uses the verify flavour (`manpages-check`,
# not `manpages`) so `make pre-commit` exits non-zero when man
# pages drift — matching CI semantics. Chains after `_pc-udeps`
# rather than `_pc-fmt` because `cargo xtask` shares the workspace
# `target/` lock with the rest of the cargo pipeline; explicit
# serialization is clearer (and faster) than letting cargo's lock
# implicitly serialize parallel arms.
_pc-manpages: _pc-udeps
	$(MAKE) manpages-check

# bca self-scan tiers. Both build with `cargo run --release` against
# the workspace target/, so they chain after _pc-manpages (the
# tail of the workspace cargo chain) rather than fanning out in
# parallel. The hard gate runs before the soft gate so a regression
# beyond the configured limit surfaces first.
_pc-self-scan: _pc-manpages
	$(MAKE) self-scan

_pc-self-scan-headroom: _pc-self-scan
	$(MAKE) self-scan-headroom

# Python pre-commit stages. _pc-py-fmt auto-fixes (ruff format +
# ruff check --fix); the typecheck and test stages are check-only
# (they cannot reasonably auto-fix). _pc-py-fmt and _pc-py-typecheck
# gate on _pc-fmt — they do not touch cargo so they parallelise
# safely with the clippy/test chain. _pc-py-test runs `maturin
# develop` against the workspace target/, so it must chain after
# _pc-udeps to avoid lock contention with the cargo pipeline.
_pc-py-fmt: _pc-fmt
	@if command -v ruff >/dev/null 2>&1; then \
	  ruff format "$(BCA_PY_DIR)" && ruff check --fix "$(BCA_PY_DIR)"; \
	else echo "ruff not found; skipping _pc-py-fmt"; fi

_pc-py-typecheck: _pc-fmt
	$(MAKE) py-typecheck

_pc-py-test: _pc-self-scan-headroom
	$(MAKE) py-test

# Chain after _pc-py-test, never concurrently: both run `maturin
# develop` against the shared workspace target/, so a parallel run
# would race the editable `_native` .so the other just wrote.
_pc-py-stubtest: _pc-py-test
	$(MAKE) py-stubtest

# ---------------------------------------------------------------------------
# CI validation targets (no auto-formatting)
#
# These _ci-* targets have NO prerequisites — they can be invoked
# individually from GitHub Actions workflow steps or composed via `make ci`
# for local use.
#
# Execution order (enforced by `ci` target + _ci-cargo-pipeline):
#   1. _ci-fmt-check (sequential, must pass before anything else)
#   2. parallel:
#      _ci-cargo-pipeline: clippy → test → build → doc-check → udeps
#                          → manpages → self-scan → self-scan-headroom
#      _ci-shellcheck, _ci-markdown-lint, _ci-toml-lint, _ci-makefile-check,
#      _ci-actionlint, _ci-snapshot-anchors, _ci-rustfmt-bail,
#      _ci-rustfmt-bail-test, _ci-grammar-marker-sync,
#      _ci-grammar-marker-sync-test, _ci-check-versions, _ci-enums-check,
#      _ci-enums-codegen-drift
#
# _ci-enums-check runs on `enums/Cargo.toml`, which has its own `target/`
# (workspace-excluded), so it does NOT share the workspace cargo lock and
# is safe to run alongside _ci-cargo-pipeline.
# ---------------------------------------------------------------------------
_ci-fmt-check:
	$(MAKE) fmt-check

_ci-clippy:
	cargo clippy --workspace --all-targets -- -D warnings
	cargo clippy --workspace --all-targets --all-features -- -D warnings

# Mirrors the `test` job in .github/workflows/ci.yml (nextest for the
# lib/bin/integration tests, `cargo test --doc` for doctests). The
# workflow additionally passes `--profile ci --locked`. Neither changes
# the executed test set: the `ci` profile differs from `default` only in
# emitting JUnit XML for the PR annotation step (both disable fail-fast,
# see .config/nextest.toml), and `--locked` is a lockfile assertion that
# every `_ci-*` target omits — `make ci` will not catch a `Cargo.lock`
# that CI's `--locked` rejects.
_ci-test:
	$(MAKE) test
	$(MAKE) test-doc

_ci-doc-check:
	$(MAKE) doc-check

_ci-build:
	cargo build --workspace --all-targets

_ci-udeps:
	cargo +nightly udeps --workspace --all-targets

_ci-shellcheck:
	$(MAKE) shellcheck

_ci-markdown-lint:
	$(MAKE) markdown-lint

_ci-toml-lint:
	$(MAKE) toml-lint

_ci-makefile-check:
	$(MAKE) makefile-check

_ci-actionlint:
	$(MAKE) actionlint

_ci-snapshot-anchors:
	$(MAKE) snapshot-anchors

_ci-snapshot-anchors-test:
	$(MAKE) snapshot-anchors-test

_ci-rustfmt-bail:
	$(MAKE) rustfmt-bail

_ci-rustfmt-bail-test:
	$(MAKE) rustfmt-bail-test

_ci-grammar-marker-sync:
	$(MAKE) grammar-marker-sync

_ci-grammar-marker-sync-test:
	$(MAKE) grammar-marker-sync-test

_ci-check-versions:
	$(MAKE) check-versions

_ci-check-versions-test:
	$(MAKE) check-versions-test

_ci-check-grammar-crate-test:
	$(MAKE) check-grammar-crate-test

_ci-check-manpage-drift-test:
	$(MAKE) check-manpage-drift-test

_ci-check-excluded-manifests:
	$(MAKE) check-excluded-manifests

_ci-check-excluded-manifests-test:
	$(MAKE) check-excluded-manifests-test

_ci-check-ruff-lockstep:
	$(MAKE) check-ruff-lockstep

_ci-check-ruff-lockstep-test:
	$(MAKE) check-ruff-lockstep-test

_ci-check-publish-metadata:
	$(MAKE) check-publish-metadata

_ci-check-publish-metadata-test:
	$(MAKE) check-publish-metadata-test

_ci-check-manpage-assets:
	$(MAKE) check-manpage-assets

_ci-check-diagnostic-prefix:
	$(MAKE) check-diagnostic-prefix

_ci-check-diagnostic-prefix-test:
	$(MAKE) check-diagnostic-prefix-test

_ci-check-safety-doc-pin:
	$(MAKE) check-safety-doc-pin

_ci-check-feature-gates-test:
	$(MAKE) check-feature-gates-test

_ci-check-test-lang-gates:
	$(MAKE) check-test-lang-gates

_ci-check-test-lang-gates-test:
	$(MAKE) check-test-lang-gates-test

_ci-check-safety-doc-pin-test:
	$(MAKE) check-safety-doc-pin-test

_ci-worktree-setup-test:
	$(MAKE) worktree-setup-test

_ci-gate-status-test:
	$(MAKE) gate-status-test

_ci-check-tools-test:
	$(MAKE) check-tools-test

_ci-enums-check:
	$(MAKE) enums-check

# Chain after enums-check for warm dependency fingerprints. See
# the matching _pc-enums-codegen-drift comment for the scope of
# the cache reuse.
_ci-enums-codegen-drift: _ci-enums-check
	$(MAKE) enums-codegen-drift

# CI parallel arm for the drift gate's self-tests. Chained
# after the gate so the cargo cache is hot.
_ci-enums-codegen-drift-test: _ci-enums-codegen-drift
	$(MAKE) enums-codegen-drift-test

# Check-only man-page drift gate. Mirrors `.github/workflows/ci.yml`'s
# `manpage` job so `make ci` produces the same verdict as the CI
# workflow on the same tree state.
_ci-manpages:
	$(MAKE) manpages-check

# bca self-scan tiers under `make ci`. Same shape as the _pc-
# counterparts; chained into _ci-cargo-pipeline (not parallelised)
# because both run `cargo run --release` against the shared
# workspace target/. Mirrors `.github/workflows/pages.yml`'s
# `Threshold gate` step.
_ci-self-scan:
	$(MAKE) self-scan

_ci-self-scan-headroom:
	$(MAKE) self-scan-headroom

# Python CI stages — check-only versions of the py-* targets.
# Mirror the _pc-py-* shape but without the auto-fix path.
_ci-py-fmt-check:
	$(MAKE) py-fmt-check

_ci-py-lint:
	$(MAKE) py-lint

_ci-py-typecheck:
	$(MAKE) py-typecheck

_ci-py-test:
	$(MAKE) py-test

# Chain after _ci-py-test (see _pc-py-stubtest): both run `maturin
# develop` against the shared target/, so they must not race.
_ci-py-stubtest: _ci-py-test
	$(MAKE) py-stubtest

# Sequential cargo pipeline for local `make ci`. Every step here
# touches the workspace `target/` lock, so they are serialized in
# this single chain rather than fanned out in parallel.
# _ci-manpages (`cargo xtask`), _ci-self-scan, and
# _ci-self-scan-headroom all share the same target/, so they are
# chained at the tail of this pipeline rather than fanned out as
# parallel arms of `ci:` — parallel scheduling would just block on
# cargo's lock anyway. When adding a new cargo-target-touching
# step, extend the tail here and also extend the
# `_pc-self-scan-headroom → _pc-py-test` chain on the pre-commit
# side.
_ci-cargo-pipeline:
	$(MAKE) _ci-clippy
	$(MAKE) _ci-test
	$(MAKE) _ci-build
	$(MAKE) _ci-doc-check
	$(MAKE) _ci-udeps
	$(MAKE) _ci-manpages
	$(MAKE) _ci-self-scan
	$(MAKE) _ci-self-scan-headroom

# ---------------------------------------------------------------------------
# Release engineering
#
# These targets mirror the gates `.github/workflows/release.yml` runs at
# tag time. Run `make release-check VERSION=x.y.z` before pushing a tag —
# it surfaces deny/about/CHANGELOG drift locally instead of letting CI
# fail mid-release. None of the targets here actually publishes or
# uploads anything; the release workflow is the only mutator.
# ---------------------------------------------------------------------------

# The five vendored grammar leaves, in publish order. `release-check`
# reads this list twice, once to confirm the directories are committed
# and once to dry-run the publish, so the two cannot drift apart.
# `release.yml` keeps its own copy; a make variable cannot reach a
# workflow.
GRAMMAR_LEAVES := tree-sitter-ccomment tree-sitter-mozcpp tree-sitter-mozjs \
                  tree-sitter-preproc tree-sitter-tcl

# verify-changelog: confirm CHANGELOG.md has a `## [VERSION]` section.
# Fixed-string match so dots in the version aren't treated as regex
# wildcards. Mirrors the preflight check in release.yml.
verify-changelog:
	@if [ -z "$(VERSION)" ]; then \
	  echo "ERROR: VERSION not set. Usage: make verify-changelog VERSION=0.1.0"; \
	  exit 1; \
	fi
	@if ! grep -Fq "## [$(VERSION)]" CHANGELOG.md; then \
	  echo "ERROR: CHANGELOG.md has no section for [$(VERSION)]"; \
	  exit 1; \
	fi
	@echo "CHANGELOG.md contains section for [$(VERSION)]"

# release-check: full pre-tag gate. cargo-deny enforces the license /
# advisory / source allowlists; cargo-about's dry-run renders the
# per-binary THIRD-PARTY-LICENSES files the release archives ship; the
# publish dry-runs catch metadata regressions (missing
# description/license/readme, non-packageable files, version drift)
# before any external publish fires.
#
# Only the five vendored grammar leaves can be dry-run, so they are all
# that last sentence covers. They carry no internal pins, so `cargo
# publish --dry-run` resolves for them at any time. The four top-level
# crates cannot: each pins an internal
# dependency at `=<version>` and the Lockstep policy makes that the
# version being released, which is by definition not yet on
# crates.io. `make check-publish-metadata` is the registry-independent
# stand-in — see `utils/check-publish-metadata.py` and #1224. It is
# also part of `make lint` / `pre-commit` / `ci`, so a regression is
# normally caught long before anyone reaches for this target; the call
# here is what makes the pre-tag gate self-contained.
#
# What is deliberately *not* here is a `cargo publish --dry-run` for
# the parent. The version of this recipe #1224 removed wrapped one in
# a sparse-index probe for `bca-tree-sitter-ccomment` at the
# workspace-pinned version. Because that is always the version being
# released, the probe never hit and the dry-run never ran — on any
# release, not just the first, contrary to what this comment and
# RELEASING.md both used to claim.
#
# Two preconditions are checked before any slow stage runs.
#
# cargo-deny and cargo-about are probed by
# `utils/check-tools.sh --release-only`, which names the missing one
# and its install command. Left to fail in place, a missing subcommand
# surfaces as cargo's bare `no such command`, and the obvious remedy
# for cargo-about installs nothing at all unless `--features cli` is
# passed (#1226).
#
# The grammar leaves are then checked for uncommitted changes, because
# `cargo publish` refuses to package a directory that has any (#1225).
# Left to fail in place that costs a cargo-deny run and two cargo-about
# renders first, and cargo's own message offers `--allow-dirty` as the
# remedy — which would gate content the tag will not carry. The check
# is scoped and untracked-blind to match what cargo actually rejects:
# measured, a modified `src/lib.rs` does not stop a leaf packaging, and
# an untracked file outside the leaf's `include` is never packaged, so
# neither is worth failing over. cargo stays the backstop for the
# residue (an untracked file that `include` does cover).
release-check:
	@if [ -z "$(VERSION)" ]; then \
	  echo "ERROR: VERSION not set. Usage: make release-check VERSION=0.1.0"; \
	  exit 1; \
	fi
	@bash $(BASE_DIR)utils/check-tools.sh --release-only
	@dirty="$$(git status --porcelain --untracked-files=no -- $(GRAMMAR_LEAVES))"; \
	  if [ -n "$$dirty" ]; then \
	    echo "ERROR: uncommitted changes in the vendored grammar leaves:"; \
	    echo "$$dirty"; \
	    echo ""; \
	    echo "release-check dry-runs 'cargo publish' for these crates, which"; \
	    echo "cargo refuses to do while they hold uncommitted changes. Run the"; \
	    echo "gate on the tree you are about to tag: commit (or amend), then"; \
	    echo "'make release-check VERSION=$(VERSION)', then tag."; \
	    echo "Do not pass --allow-dirty; it gates content the tag will not carry."; \
	    exit 1; \
	  fi
	@echo "Running cargo deny check..."
	@cargo deny check
	@echo "Generating THIRD-PARTY-LICENSES-bca.md (dry-run)..."
	@cargo about generate --locked \
	  --config about.toml \
	  --manifest-path big-code-analysis-cli/Cargo.toml \
	  about.hbs > /dev/null
	@echo "Generating THIRD-PARTY-LICENSES-bca-web.md (dry-run)..."
	@cargo about generate --locked \
	  --config about.toml \
	  --manifest-path big-code-analysis-web/Cargo.toml \
	  about.hbs > /dev/null
	@echo "Dry-running cargo publish for the five vendored grammar leaves..."
	@for d in $(GRAMMAR_LEAVES); do \
	  cargo publish --dry-run --locked --manifest-path "$$d/Cargo.toml" || exit 1; \
	done
	@$(MAKE) check-publish-metadata
	@$(MAKE) verify-changelog VERSION=$(VERSION)
	@echo "release-check passed for $(VERSION)"

# Local cargo-deb invocation. Builds the binary first because the
# release workflow's `--no-build` path requires the cross/runner layout
# to be staged — this target is just for smoke-testing the metadata
# block locally on the host triple.
pkg-deb-local:
	cargo build --release -p big-code-analysis-cli -p big-code-analysis-web
	mkdir -p out
	cargo deb -p big-code-analysis-cli --no-build --output out/
	cargo deb -p big-code-analysis-web --no-build --output out/
	@ls -lh out/*.deb

pkg-rpm-local:
	cargo build --release -p big-code-analysis-cli -p big-code-analysis-web
	mkdir -p out
	cargo generate-rpm -p big-code-analysis-cli --payload-compress zstd --output out/
	cargo generate-rpm -p big-code-analysis-web --payload-compress zstd --output out/
	@ls -lh out/*.rpm

# ---------------------------------------------------------------------------
# Dev container
#
# A self-contained image with every runtime and tool needed to run Claude
# Code plus the project's MCP servers (Context7, codegraph, Serena) and the
# full validation gate against a mounted checkout. See docker/README.md.
#
# Plain `docker build` / `docker run` — no docker-compose. The build args
# pass the caller's UID/GID so the bind-mounted repo stays writable; the
# container mounts this repo at $(DEV_MOUNT) and Claude launches the MCP
# servers itself (they are registered into its user scope at image build).
# ---------------------------------------------------------------------------
DEV_IMAGE      := big-code-analysis-dev:latest
DEV_CONTAINER  := big-code-analysis-dev
DEV_MOUNT      := /home/dev/source/big-code-analysis

# The container needs its own big-code-analysis-py/.venv. A venv records
# absolute interpreter paths in every console-script shebang and in
# pyvenv.cfg, so the one directory cannot serve both sides of the bind
# mount: whichever environment ran `uv sync` last owns it, and the other
# gets `bad interpreter: .../.venv/bin/python: No such file or directory`
# from every py-* recipe. Mounting a host-side directory over that path
# keeps the in-container path spelled `.venv`, so none of the recipes
# that resolve `$(BCA_PY_DIR)/.venv/bin/*` need to know this exists.
# Ownership lines up because dev-env-build passes the caller's UID/GID.
#
# The cache outlives the container while the container's home — and the
# uv-managed interpreter the venv points at — does not, so after
# `dev-env-rm` + `dev-env-run` a stale venv can name a missing
# interpreter. uv's remediation is to delete and recreate `.venv`, which
# cannot work on a mount point; empty the cache dir on the host instead.
# See docker/README.md.
#
# Default XDG_CACHE_HOME to empty so the `:=` expansion below does not
# trip `--warn-undefined-variables` when it is unset (the common case
# off XDG-configured desktops); an environment value still wins, since
# `?=` only assigns when undefined. Without this the warning fires once
# per recursive sub-make -- 45 times in one `make pre-commit`.
XDG_CACHE_HOME ?=
DEV_VENV       := $(or $(XDG_CACHE_HOME),$(HOME)/.cache)/big-code-analysis-dev/py-venv
DEV_PY_VENV    := $(DEV_MOUNT)/big-code-analysis-py/.venv

dev-env-build:
	docker build \
	  --build-arg USER_UID=$(shell id -u) \
	  --build-arg USER_GID=$(shell id -g) \
	  --tag $(DEV_IMAGE) \
	  --file $(BASE_DIR)Dockerfile "$(BASE_DIR)"

dev-env-run:
	mkdir -p "$(DEV_VENV)"
	@# Pre-create the mount target too. Docker mounts the repo first and
	@# then creates the deeper target if it is missing — as root, and on
	@# the host, since that path lives inside the bind-mounted checkout.
	@# A contributor who has not yet run `make py-bootstrap` on the host
	@# would otherwise find a root-owned `.venv` in their working tree
	@# and host-side `uv sync` failing with permission denied.
	mkdir -p "$(BCA_PY_DIR)/.venv"
	docker run --detach --init \
	  --name $(DEV_CONTAINER) \
	  --volume "$(BASE_DIR):$(DEV_MOUNT)" \
	  --volume "$(DEV_VENV):$(DEV_PY_VENV)" \
	  --env ANTHROPIC_API_KEY \
	  --env CODEGRAPH_LLM_API_KEY \
	  $(DEV_IMAGE) sleep infinity
	@echo "Started $(DEV_CONTAINER). Open a shell with: make dev-env-shell"
	@echo "Run 'make py-bootstrap' inside it once to populate $(DEV_PY_VENV)"
	@echo "  (backed by $(DEV_VENV) on the host)."

dev-env-shell:
	docker exec --interactive --tty --workdir $(DEV_MOUNT) $(DEV_CONTAINER) bash

dev-env-rm:
	docker rm --force $(DEV_CONTAINER)