Makefile

# Copyright (c) 2026 José M. Requena Plens
# SPDX-License-Identifier: MIT

.PHONY: build build-all build-linux-amd64 build-linux-arm64 build-windows-amd64 build-windows-arm64 build-darwin-amd64 build-darwin-arm64 \
	run brand brand-check brand-rasters ensure-mcp-publisher mcp-publisher-version test test-short test-race coverage-conditions coverage-conditions-tree coverage-mutants test-pkg test-integration test-e2e test-e2e-harness test-e2e-http test-e2e-cloudflare-tunnel test-e2e-stdio test-e2e-collector ensure-gotestsum test-e2e-docker test-e2e-docker-enterprise test-e2e-gitlab-com \
	e2e-server-binary test-e2e-ce test-e2e-ee test-e2e-gitlab e2e-clean-orphans \
	orbit-setup-fixtures orbit-wait-indexer orbit-run-live-tests orbit-ensure-token gen-orbit-record check-orbit-record \
	coverage \
	modeleval-ce modeleval-ee modeleval-probe \
	lint fmt clean version release release-check checksum \
	golangci-lint govulncheck check-binary-vulns check-vex image-vulns-images check-image-vulns check-dependency-vulns check-repeatable check-reproducible check-site-headers sonar sonar-status \
	mdlint mdlint-fix audit-docs check-doc-links check-md-tables \
	analyze analyze-fix analyze-report install-tools \
	audit-output audit-tokens audit-tools audit-surface-quality check-surface-quality check-spec-conditions audit-metrics audit-dynamic-aliases audit-test-names audit-godocs audit-godocs-check check-godocs fix-godocs \
	audit-catalog-first \
	audit-struct-completeness audit-action-coverage audit-1to1 audit-1to1-sdk audit-1to1-enums audit-1to1-paths audit-1to1-paths-report audit-1to1-paths-e2e audit-1to1-grants audit-1to1-grants-report audit-1to1-required audit-1to1-required-report audit-1to1-params audit-1to1-params-report audit-1to1-routes audit-1to1-routes-report audit-1to1-validate-docs gen-audit-1to1-baseline check-audit-1to1-baseline audit-1to1-issues audit-edition-tier \
	audit-discovery audit-discovery-check audit-e2e-gaps audit-e2e-coverage e2e-go-coverage e2e-support-coverage e2e-support-coverage-record check-e2e-support-coverage check-e2e-static audit-gateway-chars check-gateway-chars check-test-file-names audit-test-subtests check-test-subtests check-supply-chain \
	e2e-coverage-record e2e-coverage-record-ce e2e-coverage-record-ee e2e-coverage-record-render check-e2e-coverage-record check-e2e-coverage-page \
	audit-md-escaping check-md-escaping \
	check-em-dash check-pr-description check-plan-untracked check-dco check-file-headers fix-file-headers \
	audit-action-ids check-action-ids \
	audit-i18n check-i18n \
	audit-dead-consts check-dead-consts \
	audit-sdk-context check-sdk-context \
	audit-closed-servers check-closed-servers \
	audit-tenancy check-tenancy tenancy-code-identity \
	check-readonly-graphql audit-readonly-graphql \
	audit-meta-descriptions check-meta-descriptions \
	gen-graphql-schema gen-graphql-release-schema check-graphql-schema check-graphql-documents audit-graphql-documents check-graphql-documents-live check-graphql-shapes audit-graphql-shapes audit-graphql-sent check-graphql-sdk-shapes audit-graphql-sdk-sent \
	gen-api-live check-api-live gen-api-doc-endpoints check-meta-descriptions \
	gen-action-grants check-action-grants check-action-grants-derivation \
	record-request-inventory gen-request-inventory check-request-inventory audit-request-inventory \
	gen-tool-reference check-tool-reference \
	gen-action-catalog-manifest check-action-catalog-manifest gen-llms check-llms gen-lhm-manifest check-lhm-manifest gen-model-corpus check-model-corpus gen-model-results model-results-record model-results-refold model-results-dry-run check-model-results gen-icon-webp check-icon-webp check-server-json check-server-json-packages check-openplugin audit-doc-tool-names check-doc-tool-names check-install-buttons check-mcpb mcpb gen-npm sync-npm-version validate-npm validate-npm-local publish-npm-dry publish-npm gen-pypi validate-pypi validate-pypi-local publish-pypi-dry publish-pypi gen-nuget validate-nuget validate-nuget-local publish-nuget-dry publish-nuget publish-lobehub gen-footprint check-footprint gen-site-stats check-site-stats gen-testing-docs check-testing-docs update-all \
	bench-resources bench-resources-render check-bench-resources bench-fairness bench-held bench-sessions \
	docs-local-go \
       docker-build docker-push docker-run \
       inspector inspector-stop help

BINARY_NAME=gitlab-mcp-server
CMD_PATH=./cmd/server
PKGS=./cmd/... ./internal/...
# Keep in lockstep with MCP_PUBLISHER_VERSION in .github/workflows/release.yml:
# this one validates the manifest, that one publishes it. check-server-json
# refuses to run when the two disagree.
MCP_PUBLISHER_VERSION=v1.8.6
# The publisher is installed once per pinned version into a directory named
# after that version, so a stale binary can never validate with another
# release, and CI caches that directory by version instead of resolving the
# module on every push. It is not a go.mod tool on purpose: the registry
# module carries 77 direct dependencies that are not this project's.
MCP_PUBLISHER_DIR=$(HOME)/.cache/gitlab-mcp-server/mcp-publisher/$(MCP_PUBLISHER_VERSION)
MCP_PUBLISHER=$(MCP_PUBLISHER_DIR)/publisher
GO_ANALYSIS_PKGS=./...
# Every e2e build tag, and it must stay every one. A tagged file is invisible
# to go vet and to golangci-lint unless its tag is listed here, so a suite
# added behind a new tag is analysed by nothing until it is added. That has
# happened three times: `httpe2e` was missing until the HTTP suite broke CI,
# `stdioe2e` until the stdio suite did, and `orbitlive` had never been listed
# at all, so test/e2e/orbit had gone unlinted since it was written. The same
# list lives in cmd/gen_testing_docs as e2eTags, for the same reason, and in
# cmd/audit_test_closed_servers as analysisTags, which a test of that command
# holds to this line. Every
# file under test/e2e/gitlab and test/e2e/internal carries
# `e2e` and nothing else, so this one list is the whole of what the analysis
# has to know: no package under test/e2e selects between two file sets any
# more, and one run sees all of them.
GO_ANALYSIS_TAGS=e2e,collectore2e,httpe2e,orbitlive,stdioe2e
# The arguments the Markdown gate is run with, named once because it is run
# from two places. `all` expands to the six escaping contexts and to neither
# staged rule, so a target that spells `--check` without this list gates the
# escaping verdict and silently lets a hand-written card row and a raw flag or
# timestamp through. `make analyze` was in exactly that state while
# `check-md-escaping` gated all three, which is two gates disagreeing about
# what the rule is.
MD_ESCAPING_ARGS=-contexts all,card,bool-time -fail-unresolved-in internal/toolutil
PROJECT_GO_VERSION := $(shell awk '/^go / {print $$2; exit}' go.mod)
GO_TOOLCHAIN ?= go$(PROJECT_GO_VERSION)
export GOTOOLCHAIN := $(GO_TOOLCHAIN)

# E2E test report directory (inside dist/, gitignored)
E2E_REPORT_DIR=dist/e2e-reports

# Where the e2e suite records what it asked the server to do and what the
# server dispatched, one shard per test process, under one directory per
# Docker target (dist/e2e-calls/ce, dist/e2e-calls/ee). The shards are a
# byproduct of one run and are never committed; cmd/audit_e2e_coverage reads
# them back. The e2e targets export it as an absolute path, since the recorder
# refuses a relative one for the same reason the request inventory does, and
# clear the target's directory first, so a shard of an earlier run never
# folds into a later one's record. Every one of them runs with -count=1: a
# package-list run can answer from the test cache, and a cached PASS records
# nothing.
E2E_CALLS_DIR=dist/e2e-calls

# COVER=1 measures how much of the server binary an e2e run executed, which is
# a different question from the one the calls directory answers: that one says
# which catalog actions dispatched, and this one says which statements of the
# program ran at all: startup, the catalog build, the middleware chain, the
# error branches no scenario reaches. It is off by default because it costs a
# build of its own and slows every child, and because the merged profile is a
# report rather than a gate: only a live GitLab produces the input, so no
# committed artifact could be verified offline and no floor could be moved
# without booting one.
#
# With it on, the shared build carries -cover and each run target hands its
# children a GOCOVERDIR under here, one directory per target, cleared where the
# calls directory is cleared: in run-docker-e2e.sh for the two Docker targets,
# since CI invokes that script rather than the target, and in the recipe for
# the self-hosted one, for the three transport modules and for the HTTP
# module's Cloudflare Tunnel target. `make e2e-go-coverage` merges what the run
# left, so a GitLab run and a transport run fold into one figure. dist/ is
# gitignored, so `make clean` removes all of it.
#
# Two names for two things, the way E2E_CALLS_DIR and the exported
# GITLAB_MCP_TEST_E2E_CALLS_DIR are two names: E2E_COVER_ROOT is the parent
# every target writes a leaf under and the one `make e2e-go-coverage` searches,
# and E2E_COVER_DIR, exported to the harness and to run-docker-e2e.sh, is the
# one leaf a single run is handed. They were one name until the collision bit:
# CI set it to an absolute leaf for the run and passed it to make as a relative
# parent for the merge, and the two readings only happened to agree.
#
# E2E_COVER_ROOT is repository-relative and must stay so, since the line below
# joins $(CURDIR) onto it: an absolute override would be appended to the
# repository path rather than replacing it, and the counters would land under
# dist/ while the merge looked where the override said. E2E_CALLS_DIR is joined
# the same way, so this is the convention here rather than a property of
# coverage.
COVER ?=
E2E_COVER_ROOT=dist/e2e-cover
E2E_COVER_PROFILE=$(E2E_REPORT_DIR)/e2e-go-coverage.out
# Empty unless COVER is set, so an ordinary run is unaffected: nothing is built
# with -cover and the children carry no GOCOVERDIR at all. Absent rather than
# empty, because the runtime of a child given an empty one prints "GOCOVERDIR
# not set, no coverage data emitted" on its stderr the moment it starts, which
# would head every child's log for the whole run.
e2e_cover_build = $(if $(COVER),-cover)
e2e_cover_env = $(if $(COVER),E2E_COVER_DIR="$(CURDIR)/$(E2E_COVER_ROOT)/$(1)")

# The support packages of the e2e suite, test/e2e/internal/fixture and
# test/e2e/modeleval, are measured where their code runs (issue 1461): most of
# it is the part only a GitLab reaches, the fixture builders and the sessions
# that start the real binary, so their offline tests alone say little about
# it. The two complete runs, test-e2e-ce and test-e2e-ee, hand the list to
# run-docker-e2e.sh as E2E_COVERPKG, which builds every test binary of the run
# with -coverpkg naming them and writes the statements they reached to
# <stem>-coverprofile.out in the report directory, and `make
# e2e-support-coverage` merges those profiles with the one the packages'
# offline tests write (cmd/merge_coverage).
#
# Unlike COVER this is always on for those two targets: it instruments the two
# packages in the test binaries and nothing of the server, costs no build of
# its own, and a complete run is the only measurement there is of the code only
# a GitLab reaches. It is spelled once, comma-separated as -coverpkg takes it;
# .github/workflows/e2e.yml hands the same list to the script it runs directly,
# and cmd/merge_coverage's tests hold the two to each other. No package the
# complete runs test imports test/e2e/modeleval, so go test warns that nothing
# being tested depends on it and the run half reads absent for it: its online
# code runs under the modeleval targets, which do not measure it.
E2E_SUPPORT_COVERPKG = ./test/e2e/internal/fixture,./test/e2e/modeleval
e2e_comma := ,
E2E_SUPPORT_PACKAGES = $(subst $(e2e_comma), ,$(E2E_SUPPORT_COVERPKG))
# What e2e-support-coverage writes beside the runs' profiles, named so its
# pattern for those, *-coverprofile.out, never reads one of them back.
E2E_SUPPORT_OFFLINE_PROFILE = $(E2E_REPORT_DIR)/e2e-support-offline.out
E2E_SUPPORT_PROFILE = $(E2E_REPORT_DIR)/e2e-support-coverage.out
# The offline half, spelled once for the report target and the gate: the two
# packages' own tests on this tree, with no GitLab, and with the model
# evaluation's two switches set empty in the environment, which outranks
# every dotenv file the harness reads, so a .env that names a model or asks
# for the provider probe cannot turn it into a paid run. The on-demand sweep's
# two settings are set empty as well: TestSweepOrphans_Leftovers_OnDemand is
# one of the fixture package's tests, and with E2E_SWEEP_MIN_AGE or
# E2E_SWEEP_PREFIX exported in the shell, or given on the command line, it
# would delete what it matches on the instance GITLAB_URL names and add what
# that reaches to the offline half, which CI's never reaches.
e2e_support_offline = MODELEVAL_MODELS= MODELEVAL_PROBE= E2E_SWEEP_MIN_AGE= E2E_SWEEP_PREFIX= go test -tags e2e -count=1 -coverpkg=$(E2E_SUPPORT_COVERPKG) -coverprofile="$(E2E_SUPPORT_OFFLINE_PROFILE)" $(E2E_SUPPORT_PACKAGES)
# The committed record of what the complete runs reached in the two packages,
# which is the half CI cannot take: make e2e-support-coverage-record writes it
# after a complete run, and check-e2e-support-coverage, which the coverage job
# of ci.yml runs, holds each package to it (issue 1461).
E2E_SUPPORT_RECORD = docs/development/e2e-support-coverage.json
# How the gate judges a record that predates the tree: checked, as main and a
# stack's top are, or deferred, below a stack's top, where an excess the
# stale record explains is a note. CI hands it the FRESHNESS it decides.
E2E_SUPPORT_FRESHNESS ?= checked

# The revision the e2e run records on its run line, so a recorded baseline
# says which tree produced it. Overridable for a run of a tree git cannot see.
E2E_COMMIT ?= $(shell git rev-parse HEAD 2>/dev/null)
export E2E_COMMIT

# Where the unit suite records the requests it issues, one shard per test
# process. A shard is a byproduct of one run and only the merged inventory is
# committed, so this lives in the gitignored build directory. The path handed
# to the recorder is absolute because a test binary runs in its own package
# directory.
REQUEST_INVENTORY_SHARDS=dist/request-inventory

# GitLab.com Orbit live-test fixtures. All overridable on the command line
# or via .env. Defaults are designed for the canonical fixture group,
# jmrp-oss/orbit-fixtures: the subgroup rather than jmrp-oss itself, which
# holds other projects the path-bounded queries must not count.
ORBIT_FIXTURES_NAMESPACE ?= jmrp-oss/orbit-fixtures
ORBIT_FIXTURES_GITLAB_URL ?= https://gitlab.com
# How long to wait for the indexer to catch up after provisioning fixtures
# (in seconds, polled every 15s). When this elapses the make target
# proceeds with a warning; the live test assertions are tolerant of
# partial indexing (row_count > 0 rather than strict equality).
ORBIT_FIXTURES_INDEXER_TIMEOUT ?= 600
# When set to "true", additionally mirror gitlab-org/cli for realistic
# cross-entity CI/MR data. Adds ~5 min of mirror time on first run.
ORBIT_FIXTURES_MIRROR ?= false
# The -timeout handed to go test by the licensed Docker run, test-e2e-ee. go
# test applies it to each test binary on its own, so with the run naming two
# packages, common and ee, each package gets the whole budget rather than the
# two sharing it. E2E_GITLAB_TIMEOUT below is the same flag for the CE run.
#
# E2E_SWEEP_MIN_AGE, at e2e-clean-orphans, must stay above this timeout plus
# the exit hooks' budgets: it is the only thing that keeps the orphan sweep off
# a package still running.
# TestSweepMinAge_MakefileDefaults_OutlastEveryPackage fails once this default
# plus those budgets' 8m reaches it, a timeout of 112 minutes or more at the 2h
# default; a run given a longer timeout on the command line is one that test
# cannot see, and e2e-clean-orphans below says what to do then.
E2E_DOCKER_ENTERPRISE_TIMEOUT ?= 3600s
# Where the e2e Docker fixture is reached from the machine running the suite.
# Docker itself follows DOCKER_HOST or the active context, so the fixture can
# run on another host: `DOCKER_HOST=ssh://truenas
# E2E_DOCKER_GITLAB_URL=http://192.168.0.40:8929 make test-e2e-docker`. GitLab's
# own idea of its URL (external_url) follows the same value, so the web_url
# fields it answers with are the ones the tests reach. The registry and
# Bitbucket follow the same host, and test/e2e/scripts/run-docker-e2e.sh
# derives them there rather than here, reading the host out of the GitLab URL
# whatever port or path it carries: the registry's external URL, http:// and
# that host on port 5050, Bitbucket's URL, the same on port 7990, and
# Bitbucket's bind, chosen from the Bitbucket URL (the derived one, or
# E2E_DOCKER_BITBUCKET_URL when set): the loopback it names, 127.0.0.1 for
# localhost, whatever its case, the address itself for 127.x.y.z and for
# [::1], the loopback a name resolves to on this machine when it resolves to
# no other address, and 0.0.0.0 for any other host, since the setup script on
# this machine has to reach a remote container's port. Overriding
# E2E_DOCKER_BITBUCKET_URL therefore moves the
# bind with it unless E2E_BITBUCKET_BIND is set too. The
# import test never dials Bitbucket; GitLab does, over the compose network.
# E2E_REGISTRY_EXTERNAL_URL, E2E_DOCKER_BITBUCKET_URL and E2E_BITBUCKET_BIND,
# set in the environment or on the make command line, override each. A
# default here would reach the script as a value someone chose and switch the
# derivation off.
E2E_DOCKER_GITLAB_URL ?= http://localhost:8929
export E2E_GITLAB_EXTERNAL_URL = $(E2E_DOCKER_GITLAB_URL)

# Read version from VERSION file (single source of truth)
VERSION := $(strip $(file < VERSION))
COMMIT  := $(shell git rev-parse --short HEAD 2>/dev/null || echo none)

LDFLAGS := -s -w -X main.version=$(VERSION) -X main.commit=$(COMMIT)

# OS detection for portable commands. Each helper takes one path and quotes
# it, so a directory an override names with a space is one argument: with the
# path unquoted, a coverage root of "dist/e2e cover" made RM_RF remove
# dist/e2e and the staged server binary in it. Every recipe that hands a tool
# a path in such a directory, or a file an override names, quotes it as well:
# a mkdir that makes the whole directory turns an unquoted path from a loud
# failure into a quiet one, as audit-e2e-coverage showed when its -o, given a
# report directory of "my reports", wrote the report to a file named my and
# exited 0. Such a path never goes through make's own path functions, which
# split it at every blank and read its glob characters as a pattern; a helper
# that carried each space through $(abspath) as a | turned every | the path
# already held into a space as well. A recipe asks the shell instead: cd and
# pwd for the absolute path a validate target mounts, test -e for the calls
# directory audit-1to1-grants-report reads.
ifeq ($(OS),Windows_NT)
  BINARY_EXT=.exe
  MKDIR_P=if not exist "$(subst /,\,$1)" mkdir "$(subst /,\,$1)"
  RM_RF=if exist "$(subst /,\,$1)" rmdir /s /q "$(subst /,\,$1)"
  RM_F=if exist "$(subst /,\,$1)" del /q "$(subst /,\,$1)"
else
  BINARY_EXT=
  MKDIR_P=mkdir -p "$1"
  RM_RF=rm -rf "$1"
  RM_F=rm -f "$1"
endif

# Analysis output directory
ANALYSIS_DIR=dist/analysis
PKGSITE ?= $(shell command -v pkgsite 2>/dev/null || printf "%s/bin/pkgsite" "$$(go env GOPATH 2>/dev/null)")

version: build
	dist/$(BINARY_NAME)$(BINARY_EXT) --version

build:
	go build -trimpath -buildmode=pie -ldflags="$(LDFLAGS)" -o dist/$(BINARY_NAME)$(BINARY_EXT) $(CMD_PATH)

build-all: build-linux-amd64 build-linux-arm64 build-windows-amd64 build-windows-arm64 build-darwin-amd64 build-darwin-arm64

build-linux-amd64:
	$(call MKDIR_P,dist)
	CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -buildmode=pie -ldflags="$(LDFLAGS)" -o dist/$(BINARY_NAME)-linux-amd64 $(CMD_PATH)

build-linux-arm64:
	$(call MKDIR_P,dist)
	CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -buildmode=pie -ldflags="$(LDFLAGS)" -o dist/$(BINARY_NAME)-linux-arm64 $(CMD_PATH)

build-windows-amd64:
	$(call MKDIR_P,dist)
	CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -trimpath -buildmode=pie -ldflags="$(LDFLAGS)" -o dist/$(BINARY_NAME)-windows-amd64.exe $(CMD_PATH)

build-windows-arm64:
	$(call MKDIR_P,dist)
	CGO_ENABLED=0 GOOS=windows GOARCH=arm64 go build -trimpath -buildmode=pie -ldflags="$(LDFLAGS)" -o dist/$(BINARY_NAME)-windows-arm64.exe $(CMD_PATH)

build-darwin-amd64:
	$(call MKDIR_P,dist)
	CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -trimpath -buildmode=pie -ldflags="$(LDFLAGS)" -o dist/$(BINARY_NAME)-darwin-amd64 $(CMD_PATH)

build-darwin-arm64:
	$(call MKDIR_P,dist)
	CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -trimpath -buildmode=pie -ldflags="$(LDFLAGS)" -o dist/$(BINARY_NAME)-darwin-arm64 $(CMD_PATH)

run:
	go run $(CMD_PATH)

## test: run all unit tests with verbose output and coverage profile
test:
	go test -v -coverprofile=coverage.out $(PKGS)

## test-short: run all unit tests (fast, no verbose, no coverage)
test-short:
	go test -count=1 $(PKGS)

## test-race: run all unit tests with race detector enabled
# The timeout is explicit because go test's default is ten minutes per package
# binary and internal/tools alone takes about 976 s under the detector, against
# 113 s without it, so this target could never finish and reported a timeout
# rather than a race (issue 536). 60m is the same bound the Race Detector
# workflow carries, and it is a bound rather than an expectation: it exists to
# end a deadlock with every goroutine stack printed.
RACE_TIMEOUT ?= 60m
test-race:
	go test -v -race -timeout $(RACE_TIMEOUT) -coverprofile=coverage.out $(PKGS)

## test-pkg: run tests for a specific package domain (usage: make test-pkg PKG=branches)
test-pkg:
	go test -v -count=1 ./internal/tools/$(PKG)/

## test-integration: run integration tests (build tag: integration)
test-integration:
	go test -v -tags integration -coverprofile=coverage.out $(PKGS)

## test-e2e: run end-to-end tests against a real GitLab instance (reads GITLAB_URL, GITLAB_TOKEN from .env); an alias of test-e2e-gitlab.
# The self-hosted run under its shortest name. It used to run the suite the
# rebuilt one supersedes, and it points at the rebuilt one now so the name a
# developer already types runs the suite that gates releases.
test-e2e: test-e2e-gitlab

# ensure-gotestsum installs gotestsum on demand, so the e2e targets work on
# a fresh checkout without a separate install-tools step. The tool was an
# unstated assumption of the developer machine before this — the first run
# on a clean Linux box provisioned an entire GitLab stack and then died on
# "gotestsum: command not found" after several minutes.
# GOTESTSUM resolves to the PATH binary when present, else to the location
# go install writes to (GOBIN, falling back to GOPATH/bin). Recursive (=) on
# purpose: the fallback must be re-evaluated after ensure-gotestsum runs,
# because a prerequisite shell cannot extend the PATH of later recipes.
# Every recipe that runs it or hands it on quotes it, as it does PKGSITE and
# MCP_PUBLISHER, since the environment decides each path and a GOBIN, a GOPATH,
# a PATH directory or a HOME can hold a space.
GOTESTSUM_INSTALL_DIR = $(or $(shell go env GOBIN),$(shell go env GOPATH)/bin)
GOTESTSUM = $(or $(shell command -v gotestsum 2>/dev/null),$(GOTESTSUM_INSTALL_DIR)/gotestsum)

ensure-gotestsum:
	@command -v gotestsum >/dev/null 2>&1 || test -x "$(GOTESTSUM_INSTALL_DIR)/gotestsum" || { \
		echo "gotestsum not found; installing with go install..."; \
		go install gotest.tools/gotestsum; \
	}

## test-e2e-harness: run the e2e harness library's own tests (no GitLab needed).
# The harness is the only route from an e2e test to a server, so a defect in it
# would surface as a failure in whichever domain test happened to run first.
# These tests hold it on its own terms: the ledger, the waits, the names, the
# runtime guard's message, the environment a child is given, and one run of the
# real binary against a stub GitLab.
test-e2e-harness: ensure-gotestsum
	$(call MKDIR_P,$(E2E_REPORT_DIR))
	bash -o pipefail -c '"$(GOTESTSUM)" \
	  --format testdox \
	  --junitfile "$(E2E_REPORT_DIR)/e2e-harness-junit.xml" \
	  -- -tags e2e -count=1 -timeout 600s ./test/e2e/internal/...'

# The three transport modules below stage the server the way the rebuilt
# suite's targets do, through e2e-server-binary and E2E_SERVER_BINARY. Each of
# them builds cmd/server once per test binary when the variable is unset, so a
# developer running all three used to pay for three compiles of the same tree;
# with it set the build happens once here and every module drives that file.
#
# Two properties of it are the modules' own and are worth knowing before
# setting it by hand. A path naming nothing, a directory, or a file that cannot
# be executed is refused rather than built around, so a stale dist/e2e fails the
# run instead of being silently replaced by a build of its own. And a
# `go test -race` run refuses a staged binary outright, because the detector
# reaches only a binary compiled with -race and this target compiles plainly;
# nothing here passes -race, and .github/workflows/race.yml runs the modules
# directly and stages nothing, which is what keeps that refusal theoretical
# there.
#
# COVER=1 measures these three like every other run target: the shared build
# carries -cover and each of them hands its children a GOCOVERDIR under its own
# leaf. They used to stage a plain build instead, because an instrumented
# binary given no GOCOVERDIR prints "warning: GOCOVERDIR not set, no coverage
# data emitted" from the meta-data emit its init runs, before the server writes
# anything, and the stdio module requires every stderr line to parse as JSON
# (test/e2e/stdio/transport_test.go). Each module reads E2E_COVER_DIR itself
# now (test/e2e/{stdio,http,collector}/coverage_test.go), so the key is there
# and the line never appears. What that buys is the only measurement of the
# transport there is: pipes, process lifetime, the handler chain, the listener,
# and every flag a scenario against a GitLab cannot reach.

## test-e2e-stdio: run the stdio transport end-to-end module (no GitLab needed; drives the real binary over pipes).
test-e2e-stdio: ensure-gotestsum e2e-server-binary
	$(call MKDIR_P,$(E2E_REPORT_DIR))
	$(if $(COVER),$(call RM_RF,$(E2E_COVER_ROOT)/stdio))
	bash -o pipefail -c 'E2E_SERVER_BINARY="$(CURDIR)/$(E2E_SERVER_BINARY)" \
	  $(call e2e_cover_env,stdio) \
	  "$(GOTESTSUM)" \
	  --format testdox \
	  --junitfile "$(E2E_REPORT_DIR)/e2e-stdio-junit.xml" \
	  -- -tags stdioe2e -count=1 -timeout 900s ./test/e2e/stdio/'

## test-e2e-http: run the HTTP transport end-to-end module (no GitLab needed; the documented proxies and balancers skip without Docker, and fail without it under E2E_HTTP_DOCKER=required, as ci.yml's e2e-http job sets).
test-e2e-http: ensure-gotestsum e2e-server-binary
	$(call MKDIR_P,$(E2E_REPORT_DIR))
	$(if $(COVER),$(call RM_RF,$(E2E_COVER_ROOT)/http))
	bash -o pipefail -c 'E2E_SERVER_BINARY="$(CURDIR)/$(E2E_SERVER_BINARY)" E2E_CLOUDFLARE_QUICK_TUNNEL= \
	  $(call e2e_cover_env,http) \
	  "$(GOTESTSUM)" \
	  --format testdox \
	  --junitfile "$(E2E_REPORT_DIR)/e2e-http-junit.xml" \
	  -- -tags httpe2e -count=1 -timeout 900s ./test/e2e/http/'

## test-e2e-cloudflare-tunnel: run the HTTP module's Cloudflare Tunnel cases, a real quick tunnel through Cloudflare's edge included (Docker and Internet needed; opens a public trycloudflare.com address while it runs; refuses to run on CI).
# Run by hand, when a change touches the tunnel or the headers the edge passes
# on. The quick tunnel case opens a public address to a server on this
# machine, so it never runs on CI (decided on issue 1112, 31 October 2026):
# with CI set the target stops before it builds or starts anything, and the
# case refuses on its own when it is run some other way.
#
# An interrupted test binary runs no cleanup, and go test does not pass an
# interrupt on to it, so an interrupt would leave the cloudflared container
# and its public address behind. The run is therefore started in a process
# group of its own (set -m, POSIX job control: on Windows, run the target under
# WSL), and the recipe's shell, which exec makes make's own child so that the
# TERM make forwards reaches it, passes an INT, a TERM or a HUP (a closed
# terminal or a dropped SSH session, which signals make's group and not the
# run's) on to that group as an interrupt, and a second one kills the group.
# Once the run has ended, each container the case named in its log line ("if
# this run is interrupted: docker rm -f <name>") is removed by that exact name,
# never by a pattern, as it is after any run that ends with a nonzero status:
# a timeout, a panic off the test's goroutine or a killed process runs no
# cleanup either, and a container the case's own cleanup removed is no longer
# there to remove. The removal ignores SIGPIPE, so a reader of the output that
# went away (ssh without a terminal) does not end it at its first message, and
# a closed terminal under which make itself leads the session (ssh -t host
# make ...), whose HUP make does not pass on, ends the run at its next line of
# output, which gotestsum cannot write. The names are read from the run's own
# JSON log, named after the recipe shell's process ID so that two runs in one
# checkout never share it (a second run used to delete the first one's log and
# write its own in its place, and the first then removed the second's
# container and left its own), and deleted before the run starts, so a name
# an earlier run with that ID printed is never taken for one of this run's.
# test-e2e-http clears the quick tunnel's switch, so this is the only target
# that opens the tunnel. COVER=1 hands the run a leaf of its own, as every
# other run target does.
ifneq ($(filter test-e2e-cloudflare-tunnel,$(MAKECMDGOALS)),)
ifneq ($(CI),)
$(error test-e2e-cloudflare-tunnel never runs on CI (CI=$(CI)): its quick tunnel opens a public trycloudflare.com address to a server on this machine, see test/e2e/README.md)
endif
endif
test-e2e-cloudflare-tunnel: ensure-gotestsum e2e-server-binary
	$(call MKDIR_P,$(E2E_REPORT_DIR))
	$(if $(COVER),$(call RM_RF,$(E2E_COVER_ROOT)/cloudflare-tunnel))
	exec bash -o pipefail -c 'log="$(E2E_REPORT_DIR)/e2e-cloudflare-tunnel-log-$$$$.json"; pid=; \
	  rm -f "$$log"; \
	  remove_named() { \
	    trap "" PIPE; \
	    for name in $$(sed -n "s/.*if this run is interrupted: docker rm -f \([A-Za-z0-9][A-Za-z0-9_.-]*\).*/\1/p" "$$log" 2>/dev/null | sort -u); do \
	      if docker container inspect "$$name" >/dev/null 2>&1; then \
	        echo "test-e2e-cloudflare-tunnel: the run $$1; removing $$name, which the case named" >&2; \
	        docker rm -f "$$name" >/dev/null; \
	      fi; \
	    done; \
	  }; \
	  stop() { \
	    pid=$${pid:-$$!}; \
	    trap "kill -KILL -- -$$pid 2>/dev/null" INT TERM HUP; \
	    if [ -n "$$pid" ]; then kill -INT -- "-$$pid" 2>/dev/null; wait "$$pid" 2>/dev/null; fi; \
	    remove_named "was interrupted by $$1"; \
	    exit "$$2"; \
	  }; \
	  trap "stop INT 130" INT; \
	  trap "stop TERM 143" TERM; \
	  trap "stop HUP 129" HUP; \
	  set -m; \
	  E2E_SERVER_BINARY="$(CURDIR)/$(E2E_SERVER_BINARY)" E2E_CLOUDFLARE_QUICK_TUNNEL=true E2E_HTTP_DOCKER=required \
	  $(call e2e_cover_env,cloudflare-tunnel) \
	  "$(GOTESTSUM)" \
	  --format standard-verbose \
	  --junitfile "$(E2E_REPORT_DIR)/e2e-cloudflare-tunnel-junit.xml" \
	  --jsonfile "$$log" \
	  -- -tags httpe2e -count=1 -v -timeout 20m -run TestProxyGuide_Cloudflare ./test/e2e/http/ & \
	  pid=$$!; set +m; \
	  wait "$$pid"; status=$$?; \
	  if [ "$$status" -ne 0 ]; then remove_named "ended with status $$status"; fi; \
	  exit "$$status"'

## test-e2e-collector: run this server's telemetry into a real OpenTelemetry Collector (Docker required; skips cleanly without it).
# Deliberately absent from the push-triggered CI jobs, which run the httpe2e and
# stdioe2e tags and never this one. Those two need no daemon; this one pulls a
# container image, which belongs with the Docker-mode targets rather than in the
# path every commit waits on.
test-e2e-collector: ensure-gotestsum e2e-server-binary
	$(call MKDIR_P,$(E2E_REPORT_DIR))
	$(if $(COVER),$(call RM_RF,$(E2E_COVER_ROOT)/collector))
	bash -o pipefail -c 'E2E_SERVER_BINARY="$(CURDIR)/$(E2E_SERVER_BINARY)" \
	  $(call e2e_cover_env,collector) \
	  "$(GOTESTSUM)" \
	  --format testdox \
	  --junitfile "$(E2E_REPORT_DIR)/e2e-collector-junit.xml" \
	  -- -tags collectore2e -count=1 -timeout 900s ./test/e2e/collector/'

## test-e2e-docker: the ephemeral GitLab CE run under its older name; an alias of test-e2e-ce.
# It used to carry a Docker lifecycle of its own, written out here, that ran
# the suite this one replaced. That lifecycle now lives once in
# test/e2e/scripts/run-docker-e2e.sh and the suite it started is gone,
# so this name points at the rebuilt CE run and keeps working for anything
# that still spells it: the same GitLab CE, the same Bitbucket fixture, the
# same runner.
test-e2e-docker: test-e2e-ce

# The rebuilt suite: three packages under test/e2e/gitlab that drive the real
# binary over stdio. Each declares the runtime it needs, so the two Docker
# targets below name packages rather than build tags, and both run `common`.
# The Docker lifecycle lives in test/e2e/scripts/run-docker-e2e.sh rather than
# here, once, and every run carries -p 1 (capability locks are process-local)
# and -count=1 (a cached PASS records no calls), which the script adds.
#
# The server binary is built once and handed to every package through
# E2E_SERVER_BINARY, so the three test binaries do not each build cmd/server.
E2E_SERVER_BINARY=dist/e2e/$(BINARY_NAME)$(BINARY_EXT)
# Per package binary, like E2E_DOCKER_ENTERPRISE_TIMEOUT above: common and ce
# each get the whole of it.
#
# It was 1800s and that was not a budget, it was the wall the run hit. A CE
# run of common measures ~1800s on a developer machine, so the margin was two
# seconds, and CI, on a slower runner, panicked with "test timed out after
# 30m0s" after 1800.077s. The figure is the same 3600s the licensed run uses:
# common grows with every scenario, and a timeout is meant to stop a hang
# rather than to cap a suite that is doing its work.
#
# Raising it has a second consequence: E2E_SWEEP_MIN_AGE, at
# e2e-clean-orphans, must stay above this timeout plus the exit hooks'
# budgets, or make e2e-clean-orphans could delete the fixtures of a package
# still running. TestSweepMinAge_MakefileDefaults_OutlastEveryPackage fails
# once this default plus those budgets' 8m reaches it, a timeout of 112 minutes
# or more at the 2h default; raising it for one run on the command line
# (E2E_GITLAB_TIMEOUT=3h) is invisible to that test, and e2e-clean-orphans
# below says what to do then.
E2E_GITLAB_TIMEOUT ?= 3600s

# What makes the two Docker runs of the rebuilt suite, test-e2e-ce and
# test-e2e-ee, the complete runs: the ones whose record says what the suite
# covers, and so the ones nothing may quietly leave out.
#
# E2E_GATE_SKIPS asks run-docker-e2e.sh for a complete run. It holds the run's
# skips to the ones cmd/audit_e2e_coverage/skip_declarations.go declares for
# its runtime, so a run whose tests all passed still fails on a scenario that
# skipped for a reason nobody declared, and on a declaration no skip of it
# matched; a green run used to read as full coverage whatever it had skipped
# (issue 1014). On CE it runs the throttle probe of test/e2e/gitlab/ce, which
# changes an instance-wide setting, last and alone, in a final pass on the same
# stack before the one teardown, and the gate holds that pass to having passed
# it. It also starts the run with E2E_EXTERNAL_NETWORK=true, so the
# GitHub, Gists and Bitbucket Cloud importers, which call a public URL, run:
# the harness keeps that opt-in, since such a test fails for reasons that have
# nothing to do with this server, but the host running a complete run has
# Internet. The script sets it only when the caller did not, in the
# environment, on the make command line, in the file E2E_ENV_FILE names or in
# the repository .env, and refuses to start when the caller turned it off,
# since four importer scenarios would then skip and the gate fail the run an
# hour later. An offline host says E2E_GATE_SKIPS=false, which is not a
# complete run. The modeleval targets share the script and set neither: a
# model evaluation is not a coverage claim, and its cases skip by design where
# a tier lacks them.
e2e_complete_run_env = E2E_GATE_SKIPS="$${E2E_GATE_SKIPS:-true}"

## e2e-server-binary: build the server the rebuilt e2e suite drives, once for every package.
# Instrumented under COVER=1: the binary every documented run drives is the one
# built here, so this is where -cover has to enter. The target is .PHONY, so an
# uninstrumented build left by an earlier run can never be reused.
e2e-server-binary:
	$(call MKDIR_P,dist/e2e)
	go build $(e2e_cover_build) -o "$(E2E_SERVER_BINARY)" $(CMD_PATH)

## test-e2e-ce: start ephemeral GitLab CE (+ Bitbucket fixture), run the common and ce packages of the rebuilt suite, then the throttle probe alone on the same stack, tear down.
test-e2e-ce: ensure-gotestsum e2e-server-binary
	$(e2e_complete_run_env) \
	E2E_SERVER_BINARY="$(CURDIR)/$(E2E_SERVER_BINARY)" \
	E2E_REPORT_DIR="$(CURDIR)/$(E2E_REPORT_DIR)" \
	GITLAB_MCP_TEST_E2E_CALLS_DIR="$(CURDIR)/$(E2E_CALLS_DIR)/ce" \
	$(call e2e_cover_env,ce) \
	E2E_COVERPKG=$(E2E_SUPPORT_COVERPKG) \
	GOTESTSUM="$(GOTESTSUM)" \
	./test/e2e/scripts/run-docker-e2e.sh ce -- -timeout $(E2E_GITLAB_TIMEOUT) ./test/e2e/gitlab/common/ ./test/e2e/gitlab/ce/

## test-e2e-ee: start ephemeral GitLab EE with the cached license or the activation code (+ Bitbucket fixture), run the common and ee packages of the rebuilt suite, tear down.
test-e2e-ee: ensure-gotestsum e2e-server-binary
	$(e2e_complete_run_env) \
	E2E_SERVER_BINARY="$(CURDIR)/$(E2E_SERVER_BINARY)" \
	E2E_REPORT_DIR="$(CURDIR)/$(E2E_REPORT_DIR)" \
	GITLAB_MCP_TEST_E2E_CALLS_DIR="$(CURDIR)/$(E2E_CALLS_DIR)/ee" \
	$(call e2e_cover_env,ee) \
	E2E_COVERPKG=$(E2E_SUPPORT_COVERPKG) \
	GOTESTSUM="$(GOTESTSUM)" \
	./test/e2e/scripts/run-docker-e2e.sh ee -- -timeout $(E2E_DOCKER_ENTERPRISE_TIMEOUT) ./test/e2e/gitlab/common/ ./test/e2e/gitlab/ee/

## test-e2e-docker-enterprise: the licensed Docker run under its older name; an alias of test-e2e-ee.
# The files it used to run, the Enterprise half of the retired suite behind a
# build tag of its own, were deleted once every one of their tests had a
# successor under test/e2e/gitlab/ee, so the licensed run is the rebuilt
# suite's and this name keeps working for anything that still spells it.
test-e2e-docker-enterprise: test-e2e-ee

## test-e2e-gitlab: run the rebuilt suite against a self-hosted GitLab (reads GITLAB_URL, GITLAB_TOKEN from .env); a package the instance cannot serve skips.
test-e2e-gitlab: ensure-gotestsum e2e-server-binary
	$(call MKDIR_P,$(E2E_REPORT_DIR))
	$(call RM_RF,$(E2E_CALLS_DIR)/self-hosted)
	$(call MKDIR_P,$(E2E_CALLS_DIR)/self-hosted)
	$(if $(COVER),$(call RM_RF,$(E2E_COVER_ROOT)/self-hosted))
	bash -o pipefail -c 'E2E_RUNTIME_MISMATCH=skip E2E_SERVER_BINARY="$(CURDIR)/$(E2E_SERVER_BINARY)" \
	  $(call e2e_cover_env,self-hosted) \
	  GITLAB_MCP_TEST_E2E_CALLS_DIR="$(CURDIR)/$(E2E_CALLS_DIR)/self-hosted" "$(GOTESTSUM)" \
	  --format testdox \
	  --junitfile "$(E2E_REPORT_DIR)/e2e-gitlab-junit.xml" \
	  --jsonfile "$(E2E_REPORT_DIR)/e2e-gitlab-log.json" \
	  -- -tags e2e -p 1 -count=1 -timeout $(E2E_GITLAB_TIMEOUT) ./test/e2e/gitlab/...'

## e2e-clean-orphans: delete what earlier runs left on a GitLab (reads GITLAB_URL, GITLAB_TOKEN from .env): every project and group the token owns, every personal snippet of its user and, with an administrator's token, every user, whose name carries the ID of a run that started more than E2E_SWEEP_MIN_AGE (default 2h) ago; E2E_SWEEP_PREFIX=<prefix> sweeps by name prefix instead, whatever run and however recent.
# Run by hand and by nothing else. A run sweeps only what carries its own run
# ID, at its own exit, and a run that was killed never gets there; this is the
# sweep for what such a run left. It knows no run ID, so it reads the one a name
# carries and the second that run started, and takes it only once that is
# E2E_SWEEP_MIN_AGE ago.
#
# The default, 2h, outlasts every package of a run started with the default
# timeouts above. Each package stamps its own start, and its tests end by its
# timeout, E2E_GITLAB_TIMEOUT or E2E_DOCKER_ENTERPRISE_TIMEOUT (3600s each),
# since the binary's own alarm at that moment is a fatal panic. The exit hooks
# therefore run only after tests that ended in time, and then on the exit
# sweep's 5m and the World teardown's 3m budgets, which bound how long the
# package's fixtures are in use: its timeout plus 8m. go test's own backstop
# only shortens that: it sends SIGQUIT max(1m, timeout/10) past the timeout,
# 6m at 3600s, and kills the binary up to timeout/10 after that.
# TestSweepMinAge_MakefileDefaults_OutlastEveryPackage fails when a default
# timeout plus the exit hooks' 8m reaches E2E_SWEEP_MIN_AGE, a timeout of 112
# minutes or more at the 2h default. It cannot see a run started with a longer
# timeout on the command line or through a go test of its own: after such a
# run, set E2E_SWEEP_MIN_AGE above that timeout plus 8m, and while a run
# started with -timeout 0 is going, do not run this at all. Set it to 0 only
# when no run is going. It is read from the make command line
# (make e2e-clean-orphans E2E_SWEEP_MIN_AGE=3h10m), then from the environment,
# then from .env, and only then is the 2h default used: the recipe sources .env
# before it runs the sweep, so a floor raised there has to survive the recipe
# rather than be replaced by the default below.
#
# A self-hosted run going at the same time is not failed by this either. Such
# a run fails at its end when a group or project it saw at its start is gone
# or renamed, and it leaves out of that check every object whose name carries
# a run identifier the harness minted (not one an E2E_RUN_ID override named),
# so an older run's leftover deleted here does not count against it.
#
# A run started with E2E_RUN_ID carries no date in its names, so this default
# never reaches it. E2E_SWEEP_PREFIX sweeps by name prefix instead: it applies
# one prefix to all four kinds, reaches the token user's own objects as
# readily as the suite's, and would reach a run still going. It cannot pick
# one run either. A name opens with the prefix its test or its builder chose
# (a test's own such as adm-alert- or member-, a builder's such as snippet-
# and mergetrain-, proj- and grp- when a test names none, and the World's
# e2e-world- and world-snippet-), never with the run ID, so a prefix picks
# what some tests named across every run; reaching an E2E_RUN_ID run that way
# takes one sweep per prefix its tests used, and each also reaches other runs,
# live ones included. The prefix is read from the make command line or the
# environment only, never from .env: the recipe hands make's value on even
# when it is empty, so one left in .env is dropped rather than turning every
# later clean into a sweep by name that reaches live runs. It is a test of
# the fixture package because that library is importable only from
# test/e2e. The test skips when neither
# variable is set, which guards a bare go test run; this target always passes
# the age.
E2E_SWEEP_MIN_AGE ?= 2h
E2E_SWEEP_PREFIX ?=
e2e-clean-orphans:
	bash -o pipefail -c 'if [ -f .env ]; then set -a; . ./.env; set +a; fi; \
	  E2E_SWEEP_MIN_AGE="$(if $(filter command line environment,$(origin E2E_SWEEP_MIN_AGE)),$(E2E_SWEEP_MIN_AGE),$${E2E_SWEEP_MIN_AGE:-$(E2E_SWEEP_MIN_AGE)})" E2E_SWEEP_PREFIX=$(E2E_SWEEP_PREFIX) go test -tags e2e -count=1 -v -run "^TestSweepOrphans_Leftovers_OnDemand$$" ./test/e2e/internal/fixture/'

## test-e2e-gitlab-com: end-to-end live test of the Orbit knowledge graph
## handlers against https://gitlab.com. Reads GITLAB_COM_TOKEN from .env,
## provisions the kg-fixtures and security-fixtures projects in
## $(ORBIT_FIXTURES_NAMESPACE) (default: jmrp-oss/orbit-fixtures),
## polls the indexer until it has caught up, runs the orbitlive-tagged
## live tests, and re-records what GitLab.com answers the six Orbit actions
## (gen-orbit-record), which fails every run while the recorded key tree
## differs from the one committed at HEAD. Idempotent: the setup script
## reconciles an existing project (its visibility and the fixture files it
## lacks) and leaves other existing resources alone, so re-running is safe.
##
## Overridable variables (command line or .env):
##   ORBIT_FIXTURES_NAMESPACE      default: jmrp-oss/orbit-fixtures
##   ORBIT_FIXTURES_GITLAB_URL     default: https://gitlab.com
##   ORBIT_FIXTURES_INDEXER_TIMEOUT  default: 600s
##   ORBIT_FIXTURES_MIRROR         default: false  (set to "true" to
##                                                  mirror gitlab-org/cli
##                                                  as <namespace>/glab-mirror)
##   ORBIT_FIXTURES_VISIBILITY     default: public (set to "private" for
##                                                  a private group of
##                                                  your own)
##
## Examples:
##   make test-e2e-gitlab-com                                # default group
##   make test-e2e-gitlab-com ORBIT_FIXTURES_NAMESPACE=acme
##   make test-e2e-gitlab-com ORBIT_FIXTURES_MIRROR=true     # also mirror
test-e2e-gitlab-com: orbit-ensure-token orbit-setup-fixtures orbit-wait-indexer orbit-run-live-tests gen-orbit-record check-graphql-documents-live
	@echo ""
	@echo "=== test-e2e-gitlab-com complete ==="
	@echo "Reports and timings printed above. To re-run later without"
	@echo "re-provisioning fixtures, just call: make orbit-run-live-tests"

## orbit-ensure-token: validate that .env exists and exports GITLAB_COM_TOKEN.
## Note: Make runs each @-prefixed recipe line in a fresh subshell,
## so . ./.env and the GITLAB_COM_TOKEN check must share a shell
## invocation (joined with \ and wrapped in {}).
orbit-ensure-token:
	@if [ ! -f .env ]; then \
		echo "" 1>&2; \
		echo "ERROR: .env not found in repo root" 1>&2; \
		echo "  cp .env.example .env  # then add: GITLAB_COM_TOKEN=glpat-..." 1>&2; \
		echo "" 1>&2; \
		exit 1; \
	fi
	@. ./.env && { \
		if [ -z "$$GITLAB_COM_TOKEN" ]; then \
			echo "ERROR: GITLAB_COM_TOKEN is not set in .env" 1>&2; \
			exit 1; \
		fi; \
		printf "✓ GITLAB_COM_TOKEN is set (length=%d)\n" "$${#GITLAB_COM_TOKEN}"; \
	}

## orbit-setup-fixtures: idempotently provision the fixture projects.
## Passes the resolved namespace and optional --mirror-cli through to
## the script. An existing project is reconciled (its visibility and the
## fixture files it lacks) and other existing resources are left alone.
## ORBIT_FIXTURES_VISIBILITY is read from the make command line, then the
## environment, then .env: the recipe sources .env after make has handed
## the shell its value, so make's value is passed on explicitly, and an
## empty one leaves the script its public default.
orbit-setup-fixtures: orbit-ensure-token
	@. ./.env && { \
		mirror_flag=""; \
		if [ "$(ORBIT_FIXTURES_MIRROR)" = "true" ]; then mirror_flag="--mirror-cli"; fi; \
		echo ""; \
		echo "=== Provisioning Orbit fixtures in $(ORBIT_FIXTURES_NAMESPACE) on $(ORBIT_FIXTURES_GITLAB_URL) ==="; \
		export GITLAB_COM_TOKEN \
			ORBIT_FIXTURES_VISIBILITY="$(if $(filter command line environment,$(origin ORBIT_FIXTURES_VISIBILITY)),$(ORBIT_FIXTURES_VISIBILITY),$${ORBIT_FIXTURES_VISIBILITY:-})" \
			ORBIT_FIXTURES_NAMESPACE=$(ORBIT_FIXTURES_NAMESPACE) \
			ORBIT_FIXTURES_GITLAB_URL=$(ORBIT_FIXTURES_GITLAB_URL); \
		./scripts/setup-orbit-fixtures.sh $$mirror_flag; \
	}

## orbit-wait-indexer: poll the Orbit index of $(ORBIT_FIXTURES_NAMESPACE)
## until it has caught up, or until ORBIT_FIXTURES_INDEXER_TIMEOUT elapses:
## caught up is GitLab's own answer, indexing.state READY with no project left
## out (projects.notIndexed 0) and at least the two fixture projects indexed,
## so a namespace indexed on an earlier run is done on the first poll rather
## than waiting the whole timeout for a count it already holds (issue 1534).
## It reads Group.orbit.indexing through GitLab's GraphQL API, which replaced
## GET /api/v4/orbit/graph_status when GitLab.com removed that route on
## 2026-10-28 (issue 1516). A null index, GitLab's answer when Orbit is not
## served to the token there, is said and polled like any other state.
## Proceeds with a warning in the timeout case: the live test skips what it
## cannot ask and is tolerant of partial indexing.
orbit-wait-indexer: orbit-ensure-token
	@. ./.env && { \
		echo ""; \
		echo "=== Waiting for Orbit indexer to catch up (timeout: $(ORBIT_FIXTURES_INDEXER_TIMEOUT)s) ==="; \
		attempts=$$(( $(ORBIT_FIXTURES_INDEXER_TIMEOUT) / 15 )); \
		query='{"query":"query OrbitWaitIndexer($$fullPath: ID!) { group(fullPath: $$fullPath) { orbit { indexing { state projects { indexed notIndexed } } } } }","variables":{"fullPath":"$(ORBIT_FIXTURES_NAMESPACE)"}}'; \
		for i in $$(seq 1 $$attempts); do \
			progress=$$(curl -sS "$(ORBIT_FIXTURES_GITLAB_URL)/api/graphql" -H "Authorization: Bearer $$GITLAB_COM_TOKEN" -H "Content-Type: application/json" -d "$$query" 2>/dev/null \
				| python3 -I -c "import sys,json; d=json.load(sys.stdin); x=(((d.get('data') or {}).get('group') or {}).get('orbit') or {}).get('indexing'); p=(x or {}).get('projects') or {}; print((x or {}).get('state') or 'null', p.get('indexed') or 0, p.get('notIndexed') or 0)" 2>/dev/null || echo "? 0 0"); \
			set -- $$progress; \
			printf "  [%d/%d] state=%s indexed=%s not_indexed=%s\n" "$$i" "$$attempts" "$$1" "$$2" "$$3"; \
			if [ "$$1" = "READY" ] && [ "$$3" -eq 0 ] && [ "$$2" -ge 2 ]; then \
				printf "  ✓ indexer caught up (%s projects indexed)\n" "$$2"; \
				exit 0; \
			fi; \
			if [ "$$1" = "null" ]; then \
				echo "    GitLab answered the index null: Orbit is not served for $(ORBIT_FIXTURES_NAMESPACE) to this token" 1>&2; \
			fi; \
			sleep 15; \
		done; \
		echo "  ⚠ indexer did not catch up within $(ORBIT_FIXTURES_INDEXER_TIMEOUT)s" 1>&2; \
		echo "    Proceeding anyway — live test assertions are tolerant of" 1>&2; \
		echo "    partial indexing (row_count > 0 rather than strict equality)" 1>&2; \
	}

## orbit-run-live-tests: run the orbitlive-tagged live tests against
## gitlab.com. Standalone — useful for re-running the tests after
## manual setup or after the indexer has had more time to settle.
##
## The live suite lives at test/e2e/orbit/live_test.go (external
## `orbit_test` package, build tag `orbitlive`), not in
## internal/tools/orbit/ — pointing go test at the unit-test package
## would run only the mock-based tests and silently skip the live
## integration coverage.
orbit-run-live-tests: orbit-ensure-token
	@. ./.env && { \
		echo ""; \
		echo "=== Running live tests (build tag: orbitlive) ==="; \
		export GITLAB_COM_TOKEN \
			ORBIT_FIXTURES_NAMESPACE=$(ORBIT_FIXTURES_NAMESPACE); \
		go test -tags orbitlive -count=1 -v -timeout 300s ./test/e2e/orbit/; \
	}

## gen-orbit-record: record what GitLab.com answers the requests the six Orbit
## handlers build (GraphQL, the Orbit MCP endpoint and POST /orbit/query), and
## write the key tree of every answer, never a value, to
## docs/development/orbit-responses.json. Reads only, through a proxy on the
## loopback interface, with GITLAB_COM_TOKEN from .env and the fixture
## namespace $(ORBIT_FIXTURES_NAMESPACE), and refuses to record over a
## namespace the indexer has not reached. It prints every key added, dropped
## or changed against the record committed at HEAD (read through git, not
## from the file it has just rewritten) and exits 1 when the tree differs,
## after writing it, so every run fails until the record is committed;
## `make audit-1to1-paths` then says what the change means for the Orbit
## output types (cmd/audit_1to1, shapes.orbit).
## ORBIT_RECORD_FLAGS=-allow-unanswered records past a call GitLab refuses the
## account (403, null where the handler reads, or a top-level group's Orbit
## access with no index, as since Orbit's general availability for a
## namespace without the orbit_promo add-on or a trial):
## it carries the answer HEAD's record holds for the same request, or lists
## the call as unrecorded with GitLab's answer.
ORBIT_RECORD_FLAGS ?=
gen-orbit-record: orbit-ensure-token
	@. ./.env && { \
		echo ""; \
		echo "=== Recording the Orbit answers from GitLab.com ==="; \
		export GITLAB_COM_TOKEN \
			ORBIT_FIXTURES_NAMESPACE=$(ORBIT_FIXTURES_NAMESPACE); \
		go run ./cmd/gen_orbit_record/ $(ORBIT_RECORD_FLAGS); \
	}

## check-orbit-record: fail when the committed Orbit response record is not one
## this build can read, was taken from anywhere but GitLab.com, names no Orbit
## version or fixture namespace, lacks an expected call or holds one twice or
## refused, carries a key tree that does not hang together or a path that is
## not made of key names, is past the shared staleness window
## (cmd/internal/provenance), or is not in the form the generator writes. No
## token and no network, so it is a gate.
check-orbit-record:
	go run ./cmd/gen_orbit_record/ -check

# A prompt that hands a case its own answer is refused by the unit suite now
# rather than by a target nobody remembers to run: TestContract_NoStimulusNamesItsOwnAnswer
# in internal/testutil/modelcorpus renders every case's stimulus and fails on
# one that names that case's own tool, action or parameter, and
# TestContract_FindsAPlantedAnswer proves the rule can fail. Both run under
# `go test ./internal/...`, so there is nothing to schedule and nothing to
# forget.

# The rebuilt model evaluation: the corpus put to a model against the real
# binary and a real GitLab, recorded as observation and scored afterwards.
#
# The two targets below are the e2e Docker lifecycle with one package swapped
# in, so a model run boots the same GitLab, the same runner and the same
# fixture service the end-to-end suite does. Nothing about them is scheduled:
# a run with a real model costs money at a provider and refuses to start
# without MODELEVAL_SPEND=yes, and a run with no MODELEVAL_MODELS at all skips.
#
# The two record directories are deliberately both under dist/modeleval and
# neither under $(E2E_CALLS_DIR). The coverage audit reads a calls directory's
# parent when it is given one, so a model run recording beside the end-to-end
# suite's shards would fold into the coverage record, and a model call is
# credited to no action by design.
MODELEVAL_DIR=dist/modeleval

## modeleval-ce: put the corpus to the configured models against an ephemeral GitLab CE (usage: MODELEVAL_MODELS=fake:perfect make modeleval-ce)
modeleval-ce: ensure-gotestsum e2e-server-binary
	$(call RM_RF,$(MODELEVAL_DIR)/ce)
	$(call MKDIR_P,$(MODELEVAL_DIR)/ce)
	E2E_SERVER_BINARY="$(CURDIR)/$(E2E_SERVER_BINARY)" \
	E2E_REPORT_DIR="$(CURDIR)/$(E2E_REPORT_DIR)" \
	E2E_REPORT_NAME=modeleval-ce \
	GITLAB_MCP_TEST_MODELEVAL_DIR="$(CURDIR)/$(MODELEVAL_DIR)/ce" \
	GITLAB_MCP_TEST_E2E_CALLS_DIR="$(CURDIR)/$(MODELEVAL_DIR)/ce/e2e-calls" \
	GOTESTSUM="$(GOTESTSUM)" \
	./test/e2e/scripts/run-docker-e2e.sh ce -- -timeout $(E2E_GITLAB_TIMEOUT) ./test/e2e/modeleval/

## modeleval-ee: the same against an ephemeral licensed GitLab EE, which is what the licensed cases need.
modeleval-ee: ensure-gotestsum e2e-server-binary
	$(call RM_RF,$(MODELEVAL_DIR)/ee)
	$(call MKDIR_P,$(MODELEVAL_DIR)/ee)
	E2E_SERVER_BINARY="$(CURDIR)/$(E2E_SERVER_BINARY)" \
	E2E_REPORT_DIR="$(CURDIR)/$(E2E_REPORT_DIR)" \
	E2E_REPORT_NAME=modeleval-ee \
	GITLAB_MCP_TEST_MODELEVAL_DIR="$(CURDIR)/$(MODELEVAL_DIR)/ee" \
	GITLAB_MCP_TEST_E2E_CALLS_DIR="$(CURDIR)/$(MODELEVAL_DIR)/ee/e2e-calls" \
	GOTESTSUM="$(GOTESTSUM)" \
	./test/e2e/scripts/run-docker-e2e.sh ee -- -timeout $(E2E_DOCKER_ENTERPRISE_TIMEOUT) ./test/e2e/modeleval/

## modeleval-probe: ask each configured provider whether it accepts the request this repository builds (PAID; needs MODELEVAL_PROBE=yes).
# It needs no GitLab: it never opens an Env, so the bootstrap that probes an
# instance never runs. It is the only paid thing here that is not a run, and it
# is two requests per model plus one slice request, which is a contract check.
modeleval-probe:
	MODELEVAL_PROBE=$${MODELEVAL_PROBE:-yes} \
	go test -tags e2e -count=1 -v -run TestProviderContract ./test/e2e/modeleval/

## coverage-conditions: report the boolean conditions of PKG never evaluated both ways (gobco). A line reported is a missing test case; `&&`, `||` and `!` operands count separately.
# The recipe is scripts/coverage-conditions.sh. gobco parses and type-checks
# every .go file of a directory together, whatever its build constraint says,
# so a package declaring one function per platform (cmd/server,
# internal/toolutil, test/e2e/internal/harness) died with a redeclaration
# panic before measuring anything (issue 1017). The script stages such a
# package in a copy of the module under the temporary directory, holding only
# the files the go command builds here, and blanks the constraint lines of the
# kept files whose constraint names more than the platform (a tag, a release,
# cgo, the compiler), which gobco's own narrower build context would decline
# to instrument; it runs gobco there, names the files it left out, whose
# conditions this run does not measure, and removes the copy whatever
# happens. The copy is of the module so that import paths, relative paths and
# directory names stay the original's. A package whose external test package
# gobco cannot read is staged too. gobco type-checks that package against the
# package's non-test files alone, so the copy makes each test file of the
# package that declares no test (an export_test.go) a file of the package
# behind //go:build gc, which go builds and gobco does not instrument; and
# gobco bridges to it through an import of the package it may not find, so an
# external test package that imports nothing of the package is given one,
# until a gobco release fixes both (upstream-bugs entries 97 and 140). A
# package gobco could already read, a constraint on the platform alone
# included, is run where it is, as before.
# TAGS names build tags for a package behind one (TAGS=e2e), passed to go list
# and to gobco's go test alike, and a report that measured no condition (0/0)
# is refused. GOBCO_GATE=all turns the report into the gate a touched package
# is held to (it fails on any condition not evaluated both ways), and
# GOBCO_GATE=beyond:linux/amd64 into the one the Windows and macOS legs of CI
# run, which holds only the files linux/amd64 does not build. The script
# exits 3 when the gate fails a run, which no other failure of it uses, so the
# on-demand measurement (.github/workflows/conditions.yml), which runs the
# script itself, can tell a held figure from no figure; make reports any
# failure of this recipe as its own, with status 2.
coverage-conditions:
	@test -n "$(PKG)" || { echo "usage: make coverage-conditions PKG=./cmd/gen_llms [TAGS=e2e]"; exit 2; }
	@scripts/coverage-conditions.sh $(PKG) $(TAGS)

# Where coverage-conditions-tree leaves each package's record and raw output,
# how many packages it measures at once, and what gobco counts.
CONDITIONS_RECORDS ?= dist/conditions-tree
CONDITIONS_PARALLEL ?= 1
CONDITIONS_MODE ?= condition

## coverage-conditions-tree: condition or branch coverage (gobco) of every package under cmd/ and internal/, one row each and the total, written as the summary conditions.yml's tree dispatch writes. CONDITIONS_RECORDS keeps the records (dist/conditions-tree); CONDITIONS_PARALLEL packages run at once (1); CONDITIONS_MODE is condition or branch (condition).
# Each package is measured by scripts/coverage-conditions.sh, the recipe
# behind coverage-conditions, with GOBCO_GATE=all as the workflow's default,
# which decides only which conditions the summary marks as held and moves no
# figure, and GOBCO_MODE=$(CONDITIONS_MODE): condition is gobco's default,
# every operand of && and || and every comparison, and branch is gobco's
# -branch, the whole condition of each if and for and each switch case. The
# summary goes to stdout and to summary.md beside the records. It is the
# command docs/development/testing/README.md takes the recorded figures with,
# so they can be taken again on any machine without a dispatch; that page
# says how long each run behind them took, on how many cores and with how
# many packages at a time.
coverage-conditions-tree:
	@mkdir -p "$(CONDITIONS_RECORDS)"
	@bash -o pipefail -c 'go run ./cmd/measure_conditions tree -records "$(CONDITIONS_RECORDS)" -parallel "$(CONDITIONS_PARALLEL)" -mode "$(CONDITIONS_MODE)" -commit "$$(git rev-parse HEAD)" | tee "$(CONDITIONS_RECORDS)/summary.md"'

## coverage-mutants: mutation-test PKG with gremlins, INVERT_LOGICAL on so `&&`/`||` independence is checked. The gate on a changed package is Lived 0 and Not covered 0.
# The recipe itself is scripts/coverage-mutants.sh. It moved out of this file
# when it gained the staging step that makes a `package main` measurable at all
# (issue 872): that needs a copy of the package inside the module, a run against
# the copy and a removal that happens whatever the outcome, and a cleanup
# guaranteed by a trap is not something a one-line make recipe can express. The
# reasons below still describe what it does, and the reason for the staging is
# written beside it.
#
# The per-mutant timeout is derived from PKG's own baseline, because gremlins
# computes it as that baseline times a coefficient and applies no floor. On a
# fast package that product is smaller than the fixed cost of starting `go
# test` at all, so every mutant is reported TIMED OUT having never run: measured
# here, internal/tools/surfaces (0.015s of tests) reported 1 killed and 12 timed
# out, and the same package under a budget that clears the startup cost reports
# 13 killed and none timed out. A timeout is not a kill and gremlins leaves it
# out of the efficacy quotient, so the default flatters exactly the packages it
# never managed to test, and internal/edition reported 0.00% efficacy over four
# mutants none of which ever ran.
#
# MUTANT_BUDGET is the per-mutant budget in seconds; the coefficient is whatever
# reaches it, never below 8 so a slow package still gets a real multiple of its
# own runtime. A timeout that survives a budget this size is a finding rather
# than a setting: it is a mutant that made the package pathologically slow,
# which is what mutating a memo does, and the answer is a test that asserts the
# memo.
#
# The baseline is a run of the same command gremlins times, timed by the clock.
# gremlins multiplies the coefficient by the wall time of its own `go test
# [-tags T] [-coverpkg P] -cover -coverprofile F ./<pkg>/...` from the module
# root, so the script runs that command, with the tags and -coverpkg it reads
# out of GREMLINS_FLAGS or gremlins' own GREMLINS_UNLEASH_TAGS and
# GREMLINS_UNLEASH_COVERPKG, and --integration from the flag alone, since
# gremlins v0.6.0 never reads GREMLINS_UNLEASH_INTEGRATION as a bool. The flag
# is the only source of it the script can read: integration set in a
# .gremlins.yaml, where a YAML bool does pass that assertion, reaches gremlins
# and not the baseline, so an integration run is asked for with -i. It runs
# it once untimed, which is the gate below and warms the build cache the way
# gremlins' run will find it, and once under bash's `time`. It used to read the
# duration off go test's summary line, which is the test binary's run without
# the build, and to guess 0.010s when that line carried none. A tag that
# reached gremlins and not the baseline left the harness printing `[no test
# files]`, and the guess turned 114 seconds of tests into a deadline of 95
# hours per mutant (issue 915). A package with no test file under its tags is
# refused instead, since each mutant runs only that package's tests and so none
# could be killed, unless GREMLINS_FLAGS asks for an integration run with a
# -coverpkg that names the package, under which the module's other tests cover
# and kill its mutants; a -coverpkg naming only other packages is refused too.
# The exception covers only an importable package measured where it is: a
# package main, or one measured through a staged copy, is linked by no other
# package's test, so it is refused whatever -i and -coverpkg say.
#
# The budget was set at five minutes to cover a compile as well as a run.
# gremlins copies the module into a directory per worker, and without -trimpath
# Go keys a compile on the package's directory, so the first mutant on each of
# the four workers recompiled every package of this module its test imports,
# inside its own deadline. Measured on five cores after a content edit:
# cmd/audit_dynamic_aliases, whose tests take half a second and which imports
# all of internal/tools, needed 110 seconds for that first compile with four
# workers at it at once, and 2 for every run after. At a 30-second budget it
# reported 2 killed and 8 timed out; at 300 it reported all 10 killed. The
# script now runs every go command, and gremlins, under -trimpath, which leaves
# the directory out of the key, and runs the per-mutant command once before
# gremlins starts, so a worker's copy finds everything compiled and the first
# mutant costs what every later one does (issue 1029). A fixed coefficient
# passed through GREMLINS_FLAGS, which the 300-second budget never protected,
# stopped reporting those first mutants TIMED OUT.
#
# A package that does not pass its own tests is refused rather than measured,
# and so is one whose subtree does not, since the baseline runs the subtree as
# gremlins does. Gremlins would otherwise run against a suite that already
# fails, where every mutant is reported KILLED: a perfect score over a broken
# package, which is the one reading this recipe exists to prevent. A suite that
# passes the first run and fails the timed one is refused for the same reason.
#
# MUTANT_BUDGET is a knob and MUTANT_BUDGET_FLOOR is what it may not go under.
# Raising the budget is the caller's business; lowering it past a few seconds
# recreates the defect this whole recipe exists to prevent, since the budget
# would again be smaller than the cost of starting `go test` and every mutant
# would be reported TIMED OUT having never run. The floor is applied out loud
# rather than silently: a run told to use one second and given ten should say
# so, or the printed budget is a second lie on top of the first.
#
# MUTANT_DEADLINE_MAX holds each mutant's deadline to about its value, in
# seconds: the coefficient is held at the ceiling's multiple of the baseline,
# so a mutant that makes the tests hang is reported TIMED OUT within about that
# long instead of holding a worker for as long as the coefficient allows. About,
# because gremlins multiplies the coefficient by its own coverage run rather
# than by the script's baseline, and a run of that command a few percent slower
# gives a deadline a few percent over the ceiling. It answers to the floor as
# the budget does, and a baseline longer than half of it is refused, since no
# mutant could run the suite twice inside it. At an hour it binds only on a
# baseline over 450 seconds, where the floor of 8 would otherwise exceed it.
# All three knobs are written in seconds as a plain number; anything else is
# refused, since awk would read 2h as 2.
#
# -count=1 is what makes the coefficient mean what the line above says, and it
# is a second defect rather than the same one. The coefficient is not applied to
# the baseline measured here: gremlins multiplies it by the elapsed time of ITS
# OWN coverage run, and that run is a plain `go test -cover -coverprofile`,
# which Go's test cache answers instantly for a package whose files have not
# changed since it last ran. So the second invocation on an unchanged tree, or
# the first after a `--dry-run` that gathered coverage the same way, measures a
# fraction of a second and derives a per-mutant budget from that fraction.
# Measured here, ./cmd/server (44s of tests) had its coverage served from cache
# in 0.65s and reported 0 killed with every mutant TIMED OUT, which reads
# exactly like a package nothing tests. The script exports it in GOFLAGS beside
# -trimpath, and a go command ignores a GOFLAGS entry it does not know, so the
# same setting is safe for every other go command it and gremlins run. Under
# -trimpath a binary no longer records where the toolchain is installed, so the
# script also exports GOROOT as `go env GOROOT` names it: without it the
# commands that run the go command out of cmd/internal/golist failed their own
# tests there.
MUTANT_BUDGET ?= 300
MUTANT_BUDGET_FLOOR ?= 10
MUTANT_DEADLINE_MAX ?= 3600
coverage-mutants:
	@test -n "$(PKG)" || { echo "usage: make coverage-mutants PKG=./cmd/gen_llms"; exit 2; }
	@scripts/coverage-mutants.sh $(PKG) $(MUTANT_BUDGET) $(MUTANT_BUDGET_FLOOR) $(MUTANT_DEADLINE_MAX)

## coverage: run tests and generate HTML coverage report
coverage: test
	go tool cover -html=coverage.out -o coverage.html

# ─── Static Analysis (individual) ────────────────────────────────────────────
# Documentation URLs for each tool:
#   golangci-lint  https://golangci-lint.run/
#   govulncheck    https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck
#   markdownlint   https://github.com/DavidAnson/markdownlint-cli2
# See docs/development/static-analysis.md for full documentation.

## golangci-lint: run configured Go formatters and linters via .golangci.yml.
## Includes govet, modernize, gosec, staticcheck, goimports, gofumpt, and gci.
## Docs: https://golangci-lint.run/
golangci-lint:
	@echo === golangci-lint config verify ===
	golangci-lint config verify
	@echo === golangci-lint fmt ===
	golangci-lint fmt --diff
	@echo === golangci-lint run ===
	golangci-lint run --build-tags $(GO_ANALYSIS_TAGS) $(GO_ANALYSIS_PKGS)

## govulncheck: scan Go dependencies for known CVEs using call-graph analysis.
## Only reports vulnerabilities where the vulnerable function is actually called,
## and its exit status is the gate: no advisory is accepted, so there is no list
## to hold beside it (docs/development/static-analysis.md).
## Docs: https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck
govulncheck:
	govulncheck -tags $(GO_ANALYSIS_TAGS) $(GO_ANALYSIS_PKGS)

## check-binary-vulns: build every target .goreleaser.yml names and hold each binary to the vulnerability database at module grain, which is how a scanner reading a shipped binary or its SBOM judges it.
## Fails on an advisory cmd/audit_binary_vulns/declarations.go does not accept, and on a declaration that no longer matches anything.
## The source scan above answers whether our code calls a vulnerable symbol; this one answers what every published binary carries, and the two diverged for 3.0.0 and 3.1.0 (GO-2026-5932 through golang.org/x/crypto).
check-binary-vulns:
	go run ./cmd/audit_binary_vulns/

## check-vex: hold vex/gitlab-mcp-server.openvex.json, the OpenVEX document every GitHub release carries, to OpenVEX v0.2.0, to the dependency set make govulncheck scans, with the same packages and build tags, and to the require directives of go.mod.
## Fails when what a statement says of the module names an advisory the scan does not report against a module it loads, or a module go.mod no longer requires (stale), or one the scan disproves or reports called (contradicted), and on an advisory the scan reports without a call that no statement accounts for, which OpenSSF Baseline OSPS-VM-04.02 asks the document to carry. What a statement says of a published image is not held to the current tree.
check-vex:
	go run ./cmd/audit_vex/ -tags $(GO_ANALYSIS_TAGS) $(GO_ANALYSIS_PKGS)

## check-repeatable: build every release target .goreleaser.yml names twice from this tree, the second time with an empty build cache, and fail unless the two builds are the same bytes.
## Needs no release and no git, and no network once the module cache holds the modules, so it runs anywhere the tree does, a copy synced without .git included.
check-repeatable:
	go run ./cmd/reproduce_release/ -twice

# Where check-reproducible downloads a release's assets when PUBLISHED names
# none, one directory per tag.
REPRODUCE_DIR=dist/reproduce

## check-reproducible: rebuild the binaries of release TAG from the commit it tags (REF overrides) and compare each with the binary the release published, byte for byte.
## Fetches the release's assets and verifies them against its cosign-signed checksums.txt first (scripts/fetch-release-assets.sh, which needs gh and cosign),
## unless PUBLISHED names a directory that already holds them, which is how the reproduce job of release.yml runs it.
## Every release up to 3.3.0 was stamped with the abbreviated commit, which another clone may abbreviate to another length, so it also needs SHORT_COMMIT, the commit `gitlab-mcp-server --version` prints for it.
## A release before 3.2.0 is not covered: it publishes no THIRD_PARTY_NOTICES, which the fetch requires, and names no ELF loader, so its Linux binaries carry whichever one its build host offered.
##   make check-reproducible TAG=v3.3.0 SHORT_COMMIT=f8813193
check-reproducible:
	@test -n "$(TAG)" || { echo "usage: make check-reproducible TAG=vX.Y.Z [REF=<commit>] [PUBLISHED=<dir>] [SHORT_COMMIT=<hash>]" >&2; exit 2; }
	@set -eu; published="$(PUBLISHED)"; \
	if [ -z "$$published" ]; then \
		published="$(REPRODUCE_DIR)/$(TAG)"; rm -rf "$$published"; \
		bash scripts/fetch-release-assets.sh "$(patsubst v%,%,$(TAG))" "$$published"; \
	fi; \
	go run ./cmd/reproduce_release/ -published "$$published" -tag "$(TAG)" -ref "$(or $(REF),$(TAG))" $(if $(SHORT_COMMIT),-short-commit "$(SHORT_COMMIT)")

## check-site-headers: fetch the documentation site (SITE_URL overrides its root) and judge the four security headers the OpenSSF Best Practices criterion hardened_site names.
## Fails, with the value to set, when one of them, each declared required in cmd/audit_site_headers/headers.go, is missing or permissive.
## Needs the network, so make analyze does not run it; the headers job of pages.yml runs it after every deploy.
check-site-headers:
	go run ./cmd/audit_site_headers/ $(if $(SITE_URL),-url "$(SITE_URL)")

# Trivy's own image, pinned by digest, at the release the release workflow
# fetches as a tarball (TRIVY_VERSION and TRIVY_SHA256 in release.yml), so a
# verdict here is reached by the scanner a release reaches its verdict with;
# a test of cmd/audit_image_vulns holds the two to one version. Its signature
# verifies against Aqua's release workflow at that tag:
#   cosign verify $(TRIVY_IMAGE) --certificate-oidc-issuer https://token.actions.githubusercontent.com \
#     --certificate-identity https://github.com/aquasecurity/trivy/.github/workflows/reusable-release.yaml@refs/tags/v0.76.1
TRIVY_IMAGE=ghcr.io/aquasecurity/trivy:0.76.1@sha256:790fd66d1697395d8693d1acaa1ea702406a20f109b6fc7bac8db623eca6c06c
IMAGE_VULNS_PLATFORMS ?= linux/amd64,linux/arm64
IMAGE_VULNS_DIR=dist/image-vulns

## image-vulns-images: build the image for each platform of IMAGE_VULNS_PLATFORMS and save it to dist/image-vulns, as the release saves its smoke images for the scan.
## A platform the host cannot run needs QEMU binfmt (docker run --privileged tonistiigi/binfmt --install all).
image-vulns-images:
	@command -v docker >/dev/null || { echo "ERROR: Docker is required"; exit 1; }
	@set -eu; dir="$(CURDIR)/$(IMAGE_VULNS_DIR)"; mkdir -p "$$dir"; \
	for platform in $$(echo "$(IMAGE_VULNS_PLATFORMS)" | tr ',' ' '); do \
		name=$$(echo "$$platform" | tr '/' '-'); \
		docker buildx build --platform "$$platform" --load \
			--build-arg VERSION=$(VERSION) --build-arg COMMIT=$(COMMIT) -t "$(BINARY_NAME):scan-$$name" .; \
		docker save -o "$$dir/$$name.tar" "$(BINARY_NAME):scan-$$name"; \
	done

## check-image-vulns: scan the images image-vulns-images saved with the Trivy release the release workflow pins, and hold their Alpine packages to its database with cmd/audit_image_vulns, as the release does between the smoke test and the push.
## Fails on a fixable HIGH or CRITICAL advisory cmd/audit_image_vulns/declarations.go does not accept, on a declaration past its day or one that accepts nothing in a run of every platform the release pushes, and on a report or a database the command cannot vouch for.
## A run of fewer platforms (IMAGE_VULNS_PLATFORMS=linux/amd64) lists a declaration that accepts nothing as unjudged rather than stale, since it may accept another platform's finding.
## Needs Docker, so make analyze does not run it.
##   make check-image-vulns [IMAGE_VULNS_PLATFORMS=linux/amd64]
check-image-vulns: image-vulns-images
	@set -eu; dir="$(CURDIR)/$(IMAGE_VULNS_DIR)"; mkdir -p "$$dir/cache"; \
	trivy() { docker run --rm --user "$$(id -u):$$(id -g)" -v "$$dir:/scan" "$(TRIVY_IMAGE)" "$$@"; }; \
	trivy image --download-db-only --cache-dir /scan/cache --no-progress --disable-telemetry --skip-version-check --config ""; \
	trivy version --format json --cache-dir /scan/cache --config "" > "$$dir/trivy-version.json"; \
	set --; \
	for platform in $$(echo "$(IMAGE_VULNS_PLATFORMS)" | tr ',' ' '); do \
		name=$$(echo "$$platform" | tr '/' '-'); \
		trivy image --input "/scan/$$name.tar" --cache-dir /scan/cache --skip-db-update \
			--scanners vuln --vuln-severity-source auto --list-all-pkgs --format json --output "/scan/report-$$name.json" \
			--no-progress --disable-telemetry --skip-version-check --config "" --ignorefile ""; \
		trivy convert --format table --scanners vuln --config "" --ignorefile "" "/scan/report-$$name.json"; \
		set -- "$$@" "$$dir/report-$$name.json"; \
	done; \
	go run ./cmd/audit_image_vulns/ -platforms "$(IMAGE_VULNS_PLATFORMS)" -db "$$dir/trivy-version.json" "$$@"

# OSV-Scanner's own image, pinned by the digest of its multi-platform index,
# which make check-supply-chain requires. The target below reads three things
# off what this release prints, so a bump checks that each still reads that
# way: an entry that sets nothing aside from the line "<file> has unused
# ignores:" (on stdout beside the table, on stderr beside a JSON report), each
# lockfile read from the line "Scanned /src/<path> file", and a malicious
# package from the JSON report, where its MAL- id, or the CWE-506 GitHub
# classifies embedded malware under, is a string of its own.
OSV_SCANNER_IMAGE=ghcr.io/google/osv-scanner:v2.7.0@sha256:4f3b7e2c64b9d38a5febc5a7e4a3dfef1d1362f726dea7a2ef4762b46469fcd0
# The pip locks, which OSV-Scanner does not recognize by their names, handed to
# it as requirements files; every other lockfile it finds by walking the tree.
DEPENDENCY_VULNS_PIP_LOCKS=$(wildcard .github/requirements/*.txt)
# The lockfile names OSV-Scanner finds by walking the tree, for the ecosystems
# this repository could take a dependency from. Every file of one of these
# names that git holds has to be one the scan reports reading, which is how an
# --x-exclude, a narrower scan path or a lockfile the scanner stopped reading
# shows; a name added here that the scanner does not read fails the same way
# the day git holds such a file.
DEPENDENCY_VULNS_LOCKFILES=go.mod package-lock.json npm-shrinkwrap.json pnpm-lock.yaml yarn.lock bun.lock \
	requirements.txt poetry.lock Pipfile.lock pdm.lock uv.lock Cargo.lock Gemfile.lock composer.lock
DEPENDENCY_VULNS_DIR=dist/dependency-vulns

## check-dependency-vulns: hold every lockfile the tree holds (every go.mod, site/pnpm-lock.yaml, the pip locks under .github/requirements) to OSV.dev's advisories, the OpenSSF malicious-package (MAL-) entries included, with OSV-Scanner's image pinned by digest.
## Fails on an advisory of any severity that the osv-scanner.toml beside its lockfile does not set aside, on an entry there that sets nothing aside, and on a scan that reached no verdict, an OSV.dev that did not answer or a lockfile it could not read included.
## Scans twice: over the allow lists, and under --config /dev/null, which honors none, failing on any MAL- advisory or one classified CWE-506 (embedded malware) whichever of its ids an entry names, since OSV-Scanner sets an advisory aside with all of its aliases.
## Fails as well when either scan did not report reading a lockfile git holds (DEPENDENCY_VULNS_LOCKFILES).
## Module grain, as check-binary-vulns reads a binary: Go call analysis is off, so an advisory against a module counts whether or not our code calls it.
## The policy is SECURITY.md#dependencies, and make check-supply-chain holds every osv-scanner.toml entry to it.
## Needs Docker, git and the network, so make analyze does not run it; the dependency-vulns job of ci.yml does, inside the required check.
check-dependency-vulns:
	@command -v docker >/dev/null || { echo "ERROR: Docker is required"; exit 1; }
	@set -u; dir="$(CURDIR)/$(DEPENDENCY_VULNS_DIR)"; mkdir -p "$$dir"; failed=0; \
	scan="scan source --recursive --no-call-analysis=go --x-exclude /src/.claude/worktrees $(foreach lock,$(DEPENDENCY_VULNS_PIP_LOCKS),--lockfile requirements.txt:/src/$(lock))"; \
	status=0; docker run --rm --user "$$(id -u):$$(id -g)" -v "$(CURDIR):/src:ro" "$(OSV_SCANNER_IMAGE)" $$scan /src \
		> "$$dir/report.txt" 2> "$$dir/scan.log" || status=$$?; \
	cat "$$dir/scan.log" "$$dir/report.txt"; \
	unfiltered=0; docker run --rm --user "$$(id -u):$$(id -g)" -v "$(CURDIR):/src:ro" "$(OSV_SCANNER_IMAGE)" $$scan \
		--config /dev/null --format json /src > "$$dir/unfiltered.json" 2> "$$dir/unfiltered.log" || unfiltered=$$?; \
	case "$$status" in \
		0) ;; \
		1) failed=1; echo "ERROR: an advisory no osv-scanner.toml sets aside affects a dependency (listed above): take the fixed version, remove a malicious package, or declare why it is not exploitable as SECURITY.md#dependencies says";; \
		*) failed=1; echo "ERROR: OSV-Scanner reached no verdict (exit $$status): OSV.dev did not answer or a lockfile could not be read (error above), so nothing vouches for the dependencies";; \
	esac; \
	if grep -q ' has unused ignores:' "$$dir/scan.log" "$$dir/report.txt"; then \
		failed=1; echo "ERROR: an osv-scanner.toml entry sets nothing aside (listed above): remove it, or renew it after a review if its ignoreUntil has passed"; \
	fi; \
	case "$$unfiltered" in \
		0|1) malicious=$$(grep -oE '"(MAL-[^"]*|CWE-506)"' "$$dir/unfiltered.json" | tr -d '"' | sort -u | tr '\n' ' '); \
			if [ -n "$$malicious" ]; then \
				failed=1; echo "ERROR: a lockfile holds a malicious package ($${malicious% }), which no osv-scanner.toml entry sets aside whichever of its ids it names: remove it and regenerate the lockfile ($(DEPENDENCY_VULNS_DIR)/unfiltered.json names it)"; \
			fi;; \
		*) failed=1; cat "$$dir/unfiltered.log"; echo "ERROR: the scan without allow lists reached no verdict (exit $$unfiltered): OSV.dev did not answer or a lockfile could not be read (error above), so nothing shows the lockfiles hold no malicious package";; \
	esac; \
	locks=$$(git ls-files -- $(foreach name,$(DEPENDENCY_VULNS_LOCKFILES),':(glob)**/$(name)')) || locks=""; \
	if [ -z "$$locks" ]; then failed=1; echo "ERROR: git listed no lockfile, so nothing shows the scans read every one it holds"; fi; \
	unread=""; for lock in $$locks $(DEPENDENCY_VULNS_PIP_LOCKS); do \
		{ grep -qF "Scanned /src/$$lock file" "$$dir/scan.log" "$$dir/report.txt" && grep -qF "Scanned /src/$$lock file" "$$dir/unfiltered.log"; } || unread="$$unread $$lock"; \
	done; \
	if [ -n "$$unread" ]; then \
		failed=1; echo "ERROR: git holds lockfiles a scan did not report reading:$$unread: an --x-exclude or the scan path leaves them out, or OSV-Scanner no longer reads that name"; \
	fi; \
	if [ "$$failed" -ne 0 ]; then exit 1; fi; \
	echo "dependency advisories: every lockfile git holds scanned, no malicious package, and nothing found that an osv-scanner.toml does not set aside"

## sonar: run the full SonarCloud pipeline like CI — unit tests with coverage,
## upload via sonar-scanner, poll the Compute Engine task, then print the quality
## gate and key measures. Reads SONARQUBE_TOKEN from .env; analyzes the current
## git branch (override with SONAR_BRANCH=<name>). Exits non-zero if the gate fails.
sonar:
	@./scripts/sonar-scan.sh

## sonar-status: fetch and print the latest SonarCloud quality gate for the
## current branch without re-running tests or re-uploading (SONAR_BRANCH overrides).
sonar-status:
	@./scripts/sonar-scan.sh --no-scan

## mdlint: lint Markdown and MDX files for style, consistency, and correctness,
## with the globs CI's Markdown job passes. Excludes plan/ (working drafts) and
## node_modules/. Uses .markdownlint-cli2.jsonc.
## Docs: https://github.com/DavidAnson/markdownlint-cli2
mdlint:
	@echo === markdownlint ===
	npx markdownlint-cli2 "**/*.{md,mdx}" "#plan" "#node_modules"

## mdlint-fix: auto-fix Markdown and MDX lint issues (writes files)
mdlint-fix:
	@echo === markdownlint --fix ===
	npx markdownlint-cli2 --fix "**/*.{md,mdx}" "#plan" "#node_modules"

## check-doc-links: verify the Markdown/MDX pages' local links resolve, anchor included,
## and links to the documentation site resolve to a page and an anchor it has.
## The gate is cmd/audit_doc_links, which reads the pages from disk, so it needs
## neither Node nor a checkout.
check-doc-links:
	@echo === documentation local links ===
	go run ./cmd/audit_doc_links/

## check-md-tables: verify the pipe tables of README.md, docs/ and the site are formatted.
check-md-tables:
	go run ./cmd/format_md_tables/ --check

## audit-docs: run documentation checks in one pass: markdownlint over the top-level
## Markdown files, docs/, test/e2e/ and the site pages; the pipe tables; the freshness
## of the llms files, the LobeHub manifest, the tool reference, the testing reference
## and the site statistics; the links; the Go doc comment gate; the surface quality
## and dynamic alias audits; and the site's check, build and lint. Not every
## documentation gate: check-doc-tool-names, for one, is a target and a CI step of its own.
audit-docs:
	npx markdownlint-cli2 README.md AGENTS.md CLAUDE.md CONTRIBUTING.md CODE_OF_CONDUCT.md GOVERNANCE.md SECURITY.md "docs/**/*.md" "test/e2e/**/*.md" "site/src/content/docs/**/*.mdx" "site/src/content/i18n/**/*.md"
	go run ./cmd/format_md_tables/ --check
	go run ./cmd/gen_llms/ --check
	go run ./cmd/gen_lhm_manifest/ --check
	$(MAKE) check-tool-reference
	$(MAKE) check-testing-docs
	go run ./cmd/audit_metrics/ -site-stats site/src/data/stats.json -check
	$(MAKE) check-doc-links
	$(MAKE) check-godocs
	go run ./cmd/audit_surface_quality/ -view=all
	go run ./cmd/audit_dynamic_aliases/
	cd site && pnpm run check
	cd site && pnpm run build
	cd site && pnpm run lint

# ─── Static Analysis (combined) ─────────────────────────────────────────────
# These targets orchestrate multiple tools for convenience.

## lint: quick lint alias for the configured Go lint/format gate.
lint:
	$(MAKE) golangci-lint

## analyze: run the complete static analysis suite sequentially.
## Use this for full project health check before committing.
## Runs every tool and exits non-zero if any tool fails.
analyze:
	@analysis_status=0; \
	run_check() { \
		step="$$1"; \
		shift; \
		echo "$$step"; \
		output="$$( "$$@" 2>&1 )"; \
		status="$$?"; \
		if [ "$$status" -ne 0 ]; then \
			if [ -n "$$output" ]; then \
				echo "$$output"; \
			fi; \
			echo "FAIL (exit $$status)"; \
			analysis_status=1; \
		else \
			echo "OK"; \
		fi; \
		echo ""; \
	}; \
	echo "============================================================"; \
	echo " Static Analysis Suite - gitlab-mcp-server"; \
	echo "============================================================"; \
	echo "Go toolchain: $$GOTOOLCHAIN (go.mod: $(PROJECT_GO_VERSION))"; \
	echo "Go analysis packages: $(GO_ANALYSIS_PKGS)"; \
	echo "Go analysis build tags: $(GO_ANALYSIS_TAGS)"; \
	echo ""; \
	run_check "[1/40] golangci-lint config verify" golangci-lint config verify; \
	run_check "[2/40] golangci-lint fmt" golangci-lint fmt --diff; \
	run_check "[3/40] golangci-lint run" golangci-lint run --build-tags $(GO_ANALYSIS_TAGS) $(GO_ANALYSIS_PKGS); \
	run_check "[4/40] constants nothing reads" go run ./cmd/audit_dead_consts/ -check; \
	run_check "[5/40] govulncheck" govulncheck -tags $(GO_ANALYSIS_TAGS) $(GO_ANALYSIS_PKGS); \
	run_check "[6/40] markdownlint" npx markdownlint-cli2 "**/*.{md,mdx}" "#plan" "#node_modules"; \
	run_check "[7/40] test-goroutine aborts" go run ./cmd/audit_test_goroutines --check; \
	run_check "[8/40] case loops without subtests" go run ./cmd/audit_test_subtests --check; \
	run_check "[9/40] supply-chain policy" go run ./cmd/audit_supply_chain; \
	run_check "[10/40] Markdown escaping" go run ./cmd/audit_md_escaping --check $(MD_ESCAPING_ARGS); \
	run_check "[11/40] published action IDs" go run ./cmd/audit_action_ids/ -check -json ''; \
	run_check "[12/40] pinned GraphQL schemas, gitlab.com's and the release's" $(MAKE) --no-print-directory check-graphql-schema; \
	run_check "[13/40] GraphQL documents" go run ./cmd/audit_graphql_documents/; \
	run_check "[14/40] request paths (R-PATH)" go run ./cmd/audit_1to1/ -scope=paths -check-endpoints -gaps-only; \
	run_check "[15/40] meta descriptions" go run ./cmd/audit_meta_descriptions/ -check; \
	run_check "[16/40] pinned live GitLab record" go run ./cmd/gen_api_live/ -check; \
	run_check "[17/40] GraphQL response shapes, ours and client-go's" $(MAKE) --no-print-directory check-graphql-shapes check-graphql-sdk-shapes; \
	run_check "[18/40] catalog-first invariants" go run ./cmd/audit_catalog_first/; \
	run_check "[19/40] e2e coverage (static)" go run ./cmd/audit_e2e_coverage/ -static; \
	run_check "[20/40] e2e coverage record" go run ./cmd/audit_e2e_coverage/ -check-record -check-record-page; \
	run_check "[21/40] MCP tool surface quality" go run ./cmd/audit_surface_quality/ -check; \
	run_check "[22/40] SDK calls carry the caller's context" go run ./cmd/audit_sdk_context/ -check; \
	run_check "[23/40] tenant policy declared once" go run ./cmd/audit_tenancy/ -check; \
	run_check "[24/40] recorded Orbit answers" go run ./cmd/gen_orbit_record/ -check; \
	run_check "[25/40] release binaries at module grain" go run ./cmd/audit_binary_vulns/; \
	run_check "[26/40] fine-grained derivation" $(MAKE) --no-print-directory check-action-grants-derivation; \
	run_check "[27/40] fine-grained permissions per action" $(MAKE) --no-print-directory check-action-grants; \
	run_check "[28/40] fine-grained grants (R-GRANT)" go run ./cmd/audit_1to1/ -scope=grants -gaps-only; \
	run_check "[29/40] parameter requiredness (R-REQUIRED)" go run ./cmd/audit_1to1/ -scope=required -gaps-only; \
	run_check "[30/40] params of the routes reached (R-PARAM)" go run ./cmd/audit_1to1/ -scope=params -gaps-only; \
	run_check "[31/40] routes the live record mounts (R-ROUTE)" go run ./cmd/audit_1to1/ -scope=routes -gaps-only; \
	run_check "[32/40] httptest servers closed while their address is used" go run ./cmd/audit_test_closed_servers/ -check; \
	run_check "[33/40] Go doc comments" go run ./cmd/godoc_tool/ audit --fail-on-findings; \
	run_check "[34/40] copyright and license headers" go run ./cmd/audit_file_headers/; \
	run_check "[35/40] person-facing text from the catalog" go run ./cmd/audit_i18n/ -check; \
	run_check "[36/40] the OpenVEX document against the dependency set" go run ./cmd/audit_vex/ -tags $(GO_ANALYSIS_TAGS) $(GO_ANALYSIS_PKGS); \
	run_check "[37/40] SDK parity at the pinned client-go" go run ./cmd/audit_1to1/ -scope=sdk -gaps-only; \
	run_check "[38/40] enum values (R-ENUM)" go run ./cmd/audit_1to1/ -scope=enums -gaps-only; \
	run_check "[39/40] report-only 1:1 findings against the committed baseline" go run ./cmd/audit_1to1/ -check-baseline; \
	run_check "[40/40] discovery metadata (META-001)" go run ./cmd/audit_discovery_completeness/ -gaps-only -check; \
	echo "============================================================"; \
	if [ "$$analysis_status" -ne 0 ]; then \
		echo "Analysis failed. Review findings above."; \
		echo "============================================================"; \
		exit "$$analysis_status"; \
	fi; \
	echo "Analysis complete. All tools passed."; \
	echo "============================================================"

## analyze-fix: apply automatic fixes from format + lint tools.
## Order: golangci-lint formatters → golangci-lint fixes → markdownlint.
## Always run 'make analyze' after to verify remaining findings.
analyze-fix:
	@echo === Applying automatic fixes ===
	@echo [1/3] golangci-lint fmt
	golangci-lint fmt
	@echo [2/3] golangci-lint run --fix
	-golangci-lint run --fix --build-tags $(GO_ANALYSIS_TAGS) $(GO_ANALYSIS_PKGS)
	@echo [3/3] markdownlint --fix
	-npx markdownlint-cli2 --fix "**/*.{md,mdx}" "#plan" "#node_modules"
	@echo === Fixes applied. Run 'make analyze' to verify. ===

## analyze-report: generate combined analysis report for LLM consumption.
## Output: dist/analysis/report.txt (Markdown-formatted, one section per tool).
analyze-report:
	$(call MKDIR_P,$(ANALYSIS_DIR))
	@echo "Generating analysis report to $(ANALYSIS_DIR)/report.txt ..."
	@echo "# Static Analysis Report - gitlab-mcp-server" > "$(ANALYSIS_DIR)/report.txt"
	@echo "# Tools: golangci-lint, govulncheck, markdownlint" >> "$(ANALYSIS_DIR)/report.txt"
	@echo "# Go analysis packages: $(GO_ANALYSIS_PKGS)" >> "$(ANALYSIS_DIR)/report.txt"
	@echo "# Go analysis build tags: $(GO_ANALYSIS_TAGS)" >> "$(ANALYSIS_DIR)/report.txt"
	@echo "" >> "$(ANALYSIS_DIR)/report.txt"
	@echo "## 1. golangci-lint config verify" >> "$(ANALYSIS_DIR)/report.txt"
	@echo '```text' >> "$(ANALYSIS_DIR)/report.txt"
	-golangci-lint config verify >> "$(ANALYSIS_DIR)/report.txt" 2>&1
	@echo '```' >> "$(ANALYSIS_DIR)/report.txt"
	@echo "" >> "$(ANALYSIS_DIR)/report.txt"
	@echo "## 2. golangci-lint fmt" >> "$(ANALYSIS_DIR)/report.txt"
	@echo '```text' >> "$(ANALYSIS_DIR)/report.txt"
	-golangci-lint fmt --diff >> "$(ANALYSIS_DIR)/report.txt" 2>&1
	@echo '```' >> "$(ANALYSIS_DIR)/report.txt"
	@echo "" >> "$(ANALYSIS_DIR)/report.txt"
	@echo "## 3. golangci-lint run" >> "$(ANALYSIS_DIR)/report.txt"
	@echo '```text' >> "$(ANALYSIS_DIR)/report.txt"
	-golangci-lint run --build-tags $(GO_ANALYSIS_TAGS) $(GO_ANALYSIS_PKGS) >> "$(ANALYSIS_DIR)/report.txt" 2>&1
	@echo '```' >> "$(ANALYSIS_DIR)/report.txt"
	@echo "" >> "$(ANALYSIS_DIR)/report.txt"
	@echo "## 4. govulncheck" >> "$(ANALYSIS_DIR)/report.txt"
	@echo '```text' >> "$(ANALYSIS_DIR)/report.txt"
	-govulncheck -tags $(GO_ANALYSIS_TAGS) $(GO_ANALYSIS_PKGS) >> "$(ANALYSIS_DIR)/report.txt" 2>&1
	@echo '```' >> "$(ANALYSIS_DIR)/report.txt"
	@echo "" >> "$(ANALYSIS_DIR)/report.txt"
	@echo "## 5. markdownlint" >> "$(ANALYSIS_DIR)/report.txt"
	@echo '```text' >> "$(ANALYSIS_DIR)/report.txt"
	-npx markdownlint-cli2 "**/*.{md,mdx}" "#plan" "#node_modules" >> "$(ANALYSIS_DIR)/report.txt" 2>&1
	@echo '```' >> "$(ANALYSIS_DIR)/report.txt"
	@echo "Report saved to $(ANALYSIS_DIR)/report.txt"

# ─── Tool Installation ───────────────────────────────────────────────────────
# All tools install into $GOBIN (usually $GOPATH/bin).
# Ensure $GOBIN is in your PATH. See docs/development/static-analysis.md.

## install-tools: install all Go static analysis tools to $GOBIN
install-tools:
	@echo Installing static analysis tools...
	go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(GOLANGCI_LINT_VERSION)
	go install golang.org/x/vuln/cmd/govulncheck
	go install gotest.tools/gotestsum
	@echo All tools installed.

# ─── Docker ──────────────────────────────────────────────────────────────────

## docker-build: build Docker image tagged with version and latest
docker-build:
	docker build \
		--build-arg VERSION=$(VERSION) \
		--build-arg COMMIT=$(COMMIT) \
		-t $(BINARY_NAME):$(VERSION) \
		-t $(BINARY_NAME):latest \
		.

## docker-push: build and push Docker image to DOCKER_REGISTRY
## Usage: make docker-push DOCKER_REGISTRY=registry.example.com/group/project
docker-push:
ifndef DOCKER_REGISTRY
	$(error DOCKER_REGISTRY is required. Usage: make docker-push DOCKER_REGISTRY=registry.example.com/group/project)
endif
	docker build \
		--build-arg VERSION=$(VERSION) \
		--build-arg COMMIT=$(COMMIT) \
		-t $(DOCKER_REGISTRY):$(VERSION) \
		-t $(DOCKER_REGISTRY):latest \
		.
	docker push $(DOCKER_REGISTRY):$(VERSION)
	docker push $(DOCKER_REGISTRY):latest

GITLAB_URL ?= https://gitlab.com

## docker-run: run the Docker image locally in HTTP mode (port 8080)
## Usage: make docker-run [GITLAB_URL=https://gitlab.example.com]
docker-run:
	docker run --rm -p 8080:8080 \
		$(BINARY_NAME):latest \
		--http \
		--http-addr=0.0.0.0:8080 \
		--gitlab-url="$(GITLAB_URL)"

# ─── LLM Discovery Files ─────────────────────────────────────────────────────

## gen-llms: generate llms.txt and llms-full.txt from registered tools/resources/prompts.
gen-llms:
	go run ./cmd/gen_llms/

## check-llms: validate llms.txt/llms-full.txt are current and structurally valid.
check-llms:
	go run ./cmd/gen_llms/ --check

# ─── Tool Reference ──────────────────────────────────────────────────────────

## gen-tool-reference: write the per-domain tool reference of the site, one
## page per catalog group in English and Spanish under
## site/src/content/docs/reference/tools/ and its es/ twin, from the action
## catalog and the overviews in cmd/gen_tool_reference/domains.json.
gen-tool-reference:
	go run ./cmd/gen_tool_reference/

## check-tool-reference: fail when a page of the per-domain tool reference is
## not what the catalog generates now. Deferred on a stacked layer in CI like
## every other committed-artifact gate.
check-tool-reference:
	go run ./cmd/gen_tool_reference/ -check

## gen-model-corpus: regenerate the model evaluation corpus breadth ledger.
gen-model-corpus:
	go run ./cmd/gen_model_corpus/

## check-model-corpus: verify the corpus breadth ledger matches the corpus and
## the catalog this tree builds.
check-model-corpus:
	go run ./cmd/gen_model_corpus/ -check

## gen-model-results: redraw the five managed blocks of the results page from the
## committed record. It measures nothing and needs no shards, which is why update-all
## runs it: the measurement is a paid run, like the e2e coverage record's half.
gen-model-results:
	go run ./cmd/gen_model_results/ -render

## model-results-record: fold a model evaluation run's shards into the committed
## record and redraw the pages from it (usage: make model-results-record
## MODELEVAL_SHARDS=dist/modeleval/ce). Every row the fold refuses
## (cmd/gen_model_results/refusals.go) is reported and dropped, the fake
## provider's included, so a run of the fake publishes nothing and says why row
## by row.
model-results-record:
	$(if $(MODELEVAL_SHARDS),,$(error MODELEVAL_SHARDS is unset: name the run's record directory, e.g. make $@ MODELEVAL_SHARDS=dist/modeleval/ce))
	go run ./cmd/gen_model_results/ -shards "$(MODELEVAL_SHARDS)" -render

## model-results-refold: re-score a run already published, from the shards it
## left behind (usage: make model-results-refold MODELEVAL_SHARDS=dist/modeleval/ce).
## It drops the rows those shards publish, naming each, and folds them again
## under today's scoring rules and the corpus at HEAD. This is the only path by
## which a corrected rule reaches a row already published: the record holds
## scored columns and a redraw scores nothing, so a run whose shards were not
## kept cannot be re-scored.
model-results-refold:
	$(if $(MODELEVAL_SHARDS),,$(error MODELEVAL_SHARDS is unset: name the run's record directory, e.g. make $@ MODELEVAL_SHARDS=dist/modeleval/ce))
	go run ./cmd/gen_model_results/ -shards "$(MODELEVAL_SHARDS)" -refold -render

## model-results-dry-run: rehearse the whole publishing path into dist/, without
## touching the committed record or the pages (usage: make model-results-dry-run
## MODELEVAL_SHARDS=dist/modeleval/ce). It is what makes a fake run readable: a
## fold refuses every row the fake would publish, rightly, since the fake answers
## from the corpus's own key, so until this existed the only way to see how a
## result is stored and how a page is drawn from it was to pay for a real run.
## Only that one rule is set aside; a stale, filtered or unobserved run is
## refused here exactly as a real fold would refuse it.
model-results-dry-run:
	$(if $(MODELEVAL_SHARDS),,$(error MODELEVAL_SHARDS is unset: name the run's record directory, e.g. make $@ MODELEVAL_SHARDS=dist/modeleval/ce))
	go run ./cmd/gen_model_results/ -shards "$(MODELEVAL_SHARDS)" -dry-run -render

## check-model-results: the offline gate over the committed results record and
## the blocks drawn from it. No GitLab, no network and no provider; a tree with
## no record yet passes with a note, which is the state until the first paid run
## is published.
check-model-results:
	go run ./cmd/gen_model_results/ -check

## gen-lhm-manifest: regenerate the tools/prompts/resources arrays in lhm.plugin.json.
gen-lhm-manifest:
	go run ./cmd/gen_lhm_manifest/

## check-lhm-manifest: verify lhm.plugin.json declares the registered MCP surface.
check-lhm-manifest:
	go run ./cmd/gen_lhm_manifest/ --check

# ─── Icon Assets ─────────────────────────────────────────────────────────────

## gen-icon-webp: regenerate the light/dark WebP fallbacks for every icon in
## internal/toolutil/icons.go. Maintainer-only: requires rsvg-convert
## (librsvg) and cwebp (libwebp) on PATH — `brew install librsvg webp` or the
## equivalent apt/dnf packages. Not part of CI; the generated .webp files
## under internal/toolutil/icons/webp/ are committed, so ordinary builds
## never invoke this. Run it after adding or editing an icon.
gen-icon-webp:
	go run ./cmd/gen_icon_webp/

## brand: regenerate every vector brand asset (mark, favicon, in-binary MCP brand mark) from cmd/gen_brand's parametric geometry.
brand:
	go run ./cmd/gen_brand/

## brand-check: verify the committed brand assets match the geometry.
brand-check:
	go run ./cmd/gen_brand/ --check

## brand-rasters: render the committed raster brand assets from the gen_brand vectors.
## Maintainer-only (requires rsvg-convert + cwebp, like gen-icon-webp): banner
## WebP for the README, the OG card, and the marketplace icons.
brand-rasters: brand
	tmp=$$(mktemp) && \
	{ rsvg-convert -w 1280 -h 400 .github/brand/banner.svg -o "$$tmp" && \
	  cwebp -quiet -lossless "$$tmp" -o .github/brand/banner.webp; }; \
	status=$$?; rm -f "$$tmp"; exit $$status
	rsvg-convert -w 1200 -h 630 .github/brand/og.svg -o site/public/og-image.png
	rsvg-convert -w 2560 -h 1280 .github/brand/social.svg -o .github/brand/social.png
	rsvg-convert -w 512 -h 512 site/public/favicon.svg -o mcpb/icon.png
	rsvg-convert -w 400 -h 400 site/public/favicon.svg -o site/public/logo-400.png
	rsvg-convert -w 256 -h 256 site/public/favicon.svg -o site/public/favicon.png

## check-icon-webp: verify the committed WebP icon assets match icons.go.
## Same external-tool requirement as gen-icon-webp.
check-icon-webp:
	go run ./cmd/gen_icon_webp/ --check

## audit-doc-tool-names: report documentation that names a tool no surface
## registers, or a canonical action ID the catalog does not publish. Both
## halves of one sentence: a page teaching a call names the tool on the
## individual surface and the ID on the dynamic one.
audit-doc-tool-names:
	go run ./cmd/audit_doc_tool_names/

## check-doc-tool-names: fail when the documentation names a tool or an action
## ID that does not exist.
check-doc-tool-names:
	go run ./cmd/audit_doc_tool_names/ --check

## check-install-buttons: decode the one-click install payloads and hold them to one configuration.
check-install-buttons:
	go run ./cmd/audit_install_buttons/

## check-server-json: validate server.json with the official MCP Registry publisher.
check-server-json: ensure-mcp-publisher
	@grep -q 'MCP_PUBLISHER_VERSION: "$(MCP_PUBLISHER_VERSION)"' .github/workflows/release.yml || { echo "MCP_PUBLISHER_VERSION $(MCP_PUBLISHER_VERSION) in the Makefile is not the version .github/workflows/release.yml publishes with; keep the two in lockstep"; exit 1; }
	"$(MCP_PUBLISHER)" validate server.json

## mcp-publisher-version: print the pinned MCP Registry publisher version; CI keys its cache on it.
mcp-publisher-version:
	@echo $(MCP_PUBLISHER_VERSION)

## ensure-mcp-publisher: install the pinned MCP Registry publisher into its version-named directory when it is not there yet.
ensure-mcp-publisher:
	@test -x "$(MCP_PUBLISHER)" || GOBIN="$(MCP_PUBLISHER_DIR)" go install github.com/modelcontextprotocol/registry/cmd/publisher@$(MCP_PUBLISHER_VERSION)

## check-server-json-packages: verify every package server.json declares is
## really published and really installable (cmd/release_packages). Downloads the
## artifacts, so it needs network access; the schema check above cannot see any
## of this.
check-server-json-packages:
	go run ./cmd/release_packages/ server-json-packages

## check-openplugin: validate the Agent Plugins manifests (root plugin.json +
## mcp.json) and the legacy Open Plugins manifest (.plugin/plugin.json) against
## the schema each declares, and hold them to what no schema says
## (cmd/audit_plugin_manifests).
check-openplugin:
	go run ./cmd/audit_plugin_manifests/

# Pin the MCPB CLI for supply-chain integrity. Only check-mcpb runs it:
# cmd/release_packages packs the bundles itself and never calls the CLI.
# CI reads this line for its npx cache key (ci.yml, the Markdown job).
MCPB_CLI_VERSION := 2.1.2

## GOLANGCI_LINT_VERSION: the linter release CI installs, read from here by
## .github/workflows/ci.yml so the version lives in one place. Not a go.mod tool
## directive on purpose: golangci-lint advises against building it from source
## (slower, and results can vary with the compiling Go), and its dependency
## tree would land in go.sum for every job that runs `go mod download`. Keep it
## equal to what developers run locally, so `make golangci-lint` means the same
## on both sides of a push.
GOLANGCI_LINT_VERSION := v2.15.0

## check-mcpb: validate the Claude Desktop extension manifests: mcpb/manifest.json,
## which the universal bundle packs, and the darwin, win32 and linux manifests
## cmd/release_packages derives from it for the per-OS bundles (mcpb-manifest).
## The CLI looks for the icon beside the manifest it validates, so each derived
## one gets a copy.
check-mcpb:
	npx --yes @anthropic-ai/mcpb@$(MCPB_CLI_VERSION) validate mcpb/manifest.json
	@set -e; tmp=$$(mktemp -d); trap 'rm -rf "$$tmp"' EXIT; \
	for platform in darwin win32 linux; do \
		mkdir -p "$$tmp/$$platform"; \
		cp mcpb/icon.png "$$tmp/$$platform/icon.png"; \
		go run ./cmd/release_packages/ mcpb-manifest "$$platform" > "$$tmp/$$platform/manifest.json"; \
		echo "$$platform manifest (cmd/release_packages mcpb-manifest):"; \
		npx --yes @anthropic-ai/mcpb@$(MCPB_CLI_VERSION) validate "$$tmp/$$platform/manifest.json"; \
	done

## mcpb: build the Claude Desktop extension bundles: one per operating system
## (dist/gitlab-mcp-server-darwin.mcpb, -windows.mcpb and -linux.mcpb) and the
## universal dist/gitlab-mcp-server.mcpb. Cross-compiles the darwin universal
## binary (lipo), the windows/amd64 binary and the linux/amd64 and linux/arm64
## binaries the Linux launcher chooses between, writes the third-party notices
## of those binaries (cmd/gen_third_party_notices, from the module cache), then
## assembles, packs and measures the bundles with cmd/release_packages.
mcpb:
	@command -v lipo >/dev/null || { echo "ERROR: lipo is required (macOS Xcode CLT)"; exit 1; }
	@set -e; \
	VER=$$(tr -d '[:space:]' < VERSION); \
	rm -rf dist/local_darwin_arm64 dist/local_darwin_amd64 dist/local_darwin_all dist/local_windows_amd64 dist/local_linux_amd64 dist/local_linux_arm64; \
	mkdir -p dist/local_darwin_arm64 dist/local_darwin_amd64 dist/local_darwin_all dist/local_windows_amd64 dist/local_linux_amd64 dist/local_linux_arm64; \
	CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -trimpath -ldflags "-s -w -X main.version=$$VER" -o dist/local_darwin_arm64/gitlab-mcp-server ./cmd/server; \
	CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -trimpath -ldflags "-s -w -X main.version=$$VER" -o dist/local_darwin_amd64/gitlab-mcp-server ./cmd/server; \
	lipo -create -output dist/local_darwin_all/gitlab-mcp-server dist/local_darwin_arm64/gitlab-mcp-server dist/local_darwin_amd64/gitlab-mcp-server; \
	CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -trimpath -ldflags "-s -w -X main.version=$$VER" -o dist/local_windows_amd64/gitlab-mcp-server.exe ./cmd/server; \
	CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags "-s -w -X main.version=$$VER" -o dist/local_linux_amd64/gitlab-mcp-server ./cmd/server; \
	CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -ldflags "-s -w -X main.version=$$VER" -o dist/local_linux_arm64/gitlab-mcp-server ./cmd/server; \
	go run ./cmd/gen_third_party_notices -o dist/THIRD_PARTY_NOTICES \
		-targets darwin/amd64,darwin/arm64,linux/amd64,linux/arm64,windows/amd64 \
		dist/local_darwin_amd64/gitlab-mcp-server dist/local_darwin_arm64/gitlab-mcp-server \
		dist/local_linux_amd64/gitlab-mcp-server dist/local_linux_arm64/gitlab-mcp-server \
		dist/local_windows_amd64/gitlab-mcp-server.exe; \
	go run ./cmd/release_packages/ mcpb "$$VER"

## gen-npm: assemble the npm distribution (launcher + 6 per-platform packages).
## Reads release binaries from a directory of assets named as published
## (gitlab-mcp-server-linux-amd64, ...). Version defaults to VERSION.
##   make gen-npm NPM_BINARIES=dist
gen-npm:
	@command -v node >/dev/null || { echo "ERROR: Node.js is required"; exit 1; }
	@test -n "$(NPM_BINARIES)" || { echo "ERROR: set NPM_BINARIES=<dir of release binaries>"; exit 1; }
	node scripts/build-npm.mjs --binaries "$(NPM_BINARIES)" --version "$$(tr -d '[:space:]' < VERSION)"

## sync-npm-version: rewrite npm/gitlab-mcp-server/package.json version + pins to VERSION.
## Run by the release version-stamp; safe to run anytime, needs no binaries.
sync-npm-version:
	@command -v node >/dev/null || { echo "ERROR: Node.js is required"; exit 1; }
	node scripts/build-npm.mjs --sync-only --version "$$(tr -d '[:space:]' < VERSION)"

## validate-npm: build the npm packages and validate them inside a clean
## node:24 container, so the check never installs anything on the host. Runs
## structural checks on all 7 packages plus a real install + MCP handshake for
## the container's native platform (linux-x64).
##   make validate-npm NPM_BINARIES=dist
validate-npm:
	@command -v docker >/dev/null || { echo "ERROR: Docker is required for isolated validation (or use validate-npm-local)"; exit 1; }
	@test -n "$(NPM_BINARIES)" || { echo "ERROR: set NPM_BINARIES=<dir of release binaries>"; exit 1; }
	@VER=$$(tr -d '[:space:]' < VERSION); BINARIES=$$(CDPATH= cd -- "$(NPM_BINARIES)" && pwd) || exit 1; 	docker run --rm 		-v "$(CURDIR):/work" -v "$$BINARIES:/binaries:ro" 		-w /work node:24 sh -euc '			node scripts/build-npm.mjs --binaries /binaries --version '"$$VER"' && 			node scripts/validate-npm.mjs --packages npm/packages --main npm/gitlab-mcp-server --version '"$$VER"

## validate-npm-local: same validation without Docker, for the ephemeral CI
## runner (already disposable). Builds packages from NPM_BINARIES, then validates.
validate-npm-local:
	@command -v node >/dev/null || { echo "ERROR: Node.js is required"; exit 1; }
	@test -n "$(NPM_BINARIES)" || { echo "ERROR: set NPM_BINARIES=<dir of release binaries>"; exit 1; }
	@VER=$$(tr -d '[:space:]' < VERSION); 	node scripts/build-npm.mjs --binaries "$(NPM_BINARIES)" --version "$$VER" && 	node scripts/validate-npm.mjs --packages npm/packages --main npm/gitlab-mcp-server --version "$$VER"

## publish-npm-dry: assemble and validate the npm publish set without publishing.
publish-npm-dry:
	@test -n "$(NPM_BINARIES)" || { echo "ERROR: set NPM_BINARIES=<dir of release binaries>"; exit 1; }
	scripts/publish-npm.sh "$(NPM_BINARIES)" "$$(tr -d '[:space:]' < VERSION)" --dry-run

## publish-npm: assemble and publish the npm distribution (platform packages, then launcher).
## Auth via npm login or NPM_TOKEN. See docs/development/release-process.md.
publish-npm:
	@test -n "$(NPM_BINARIES)" || { echo "ERROR: set NPM_BINARIES=<dir of release binaries>"; exit 1; }
	scripts/publish-npm.sh "$(NPM_BINARIES)" "$$(tr -d '[:space:]' < VERSION)"

## gen-pypi: assemble the PyPI wheelhouse (six platform wheels) from release
## binaries. The wheels carry the native binary in .data/scripts, the uv/ruff
## model: the installer puts it on the scripts path as the command itself.
##   make gen-pypi PYPI_BINARIES=dist
gen-pypi:
	@command -v python3 >/dev/null || { echo "ERROR: Python 3 is required"; exit 1; }
	@test -n "$(PYPI_BINARIES)" || { echo "ERROR: set PYPI_BINARIES=<dir of release binaries>"; exit 1; }
	python3 scripts/build_pypi.py --binaries "$(PYPI_BINARIES)" --version "$$(tr -d '[:space:]' < VERSION)"

## validate-pypi: build the wheels and validate them inside a clean
## python:3.14-slim container: RECORD hashes, metadata, ownership token,
## binary magic and glibc floor for all six, plus a real venv install and MCP
## initialize handshake for the container's native platform.
##   make validate-pypi PYPI_BINARIES=dist
validate-pypi:
	@command -v docker >/dev/null || { echo "ERROR: Docker is required for isolated validation (or use validate-pypi-local)"; exit 1; }
	@test -n "$(PYPI_BINARIES)" || { echo "ERROR: set PYPI_BINARIES=<dir of release binaries>"; exit 1; }
	@VER=$$(tr -d '[:space:]' < VERSION); \
	BINARIES=$$(CDPATH= cd -- "$(PYPI_BINARIES)" && pwd) || exit 1; \
	docker run --rm \
		-v "$(CURDIR):/work" -v "$$BINARIES:/binaries:ro" \
		-w /work python:3.14-slim sh -euc ' \
			python3 scripts/build_pypi.py --binaries /binaries --version '"$$VER"' && \
			python3 scripts/validate_pypi.py --wheels pypi/dist --version '"$$VER"

## validate-pypi-local: same validation without Docker, for the ephemeral CI
## runner (already disposable). Builds wheels from PYPI_BINARIES, then validates.
validate-pypi-local:
	@command -v python3 >/dev/null || { echo "ERROR: Python 3 is required"; exit 1; }
	@test -n "$(PYPI_BINARIES)" || { echo "ERROR: set PYPI_BINARIES=<dir of release binaries>"; exit 1; }
	@VER=$$(tr -d '[:space:]' < VERSION); \
	python3 scripts/build_pypi.py --binaries "$(PYPI_BINARIES)" --version "$$VER" && \
	python3 scripts/validate_pypi.py --wheels pypi/dist --version "$$VER"

## publish-pypi-dry: assemble and validate the PyPI wheelhouse, install twine
## from the hash-pinned .github/requirements/pypi-publish.txt and run its
## check, without uploading.
publish-pypi-dry:
	@test -n "$(PYPI_BINARIES)" || { echo "ERROR: set PYPI_BINARIES=<dir of release binaries>"; exit 1; }
	scripts/publish-pypi.sh "$(PYPI_BINARIES)" "$$(tr -d '[:space:]' < VERSION)" --dry-run

## publish-pypi: assemble, validate and publish the PyPI wheels out of band.
## Auth via PYPI_TOKEN, and no attestation is made. The release workflow runs
## the same script with --trusted-publishing, which mints the upload token
## from the job's identity and attests each wheel; this target is for
## bootstrap/manual publishes.
publish-pypi:
	@test -n "$(PYPI_BINARIES)" || { echo "ERROR: set PYPI_BINARIES=<dir of release binaries>"; exit 1; }
	scripts/publish-pypi.sh "$(PYPI_BINARIES)" "$$(tr -d '[:space:]' < VERSION)"

## gen-nuget: assemble the NuGet distribution (a pointer package plus six
## runtime-identifier packages) from release binaries. The .NET 10 tool
## layout: the pointer names a package per runtime identifier, each of which
## carries the native binary as the command's entry point. Packs with the
## standard library, so no .NET SDK is needed here.
##   make gen-nuget NUGET_BINARIES=dist
gen-nuget:
	@command -v python3 >/dev/null || { echo "ERROR: Python 3 is required"; exit 1; }
	@test -n "$(NUGET_BINARIES)" || { echo "ERROR: set NUGET_BINARIES=<dir of release binaries>"; exit 1; }
	python3 scripts/build_nuget.py --binaries "$(NUGET_BINARIES)" --version "$$(tr -d '[:space:]' < VERSION)"

## validate-nuget: build the packages and validate them inside a clean .NET
## SDK container: OPC layout, nuspec metadata, tool manifests, ownership
## token, binary magic and executable bit for all six, plus a real
## `dotnet tool install`, a `dnx` run and an MCP initialize handshake for the
## container's native platform. The image is pinned by digest because dnx's
## behaviour is an SDK property (10.0.403 is what was verified); bump the
## digest deliberately.
##   make validate-nuget NUGET_BINARIES=dist
NUGET_SDK_IMAGE=mcr.microsoft.com/dotnet/sdk:10.0.403@sha256:de4fe90a98845d75910b9769662465c84de1a934665c431279d1382b2bddc02b
validate-nuget:
	@command -v docker >/dev/null || { echo "ERROR: Docker is required for isolated validation (or use validate-nuget-local)"; exit 1; }
	@test -n "$(NUGET_BINARIES)" || { echo "ERROR: set NUGET_BINARIES=<dir of release binaries>"; exit 1; }
	@VER=$$(tr -d '[:space:]' < VERSION); \
	BINARIES=$$(CDPATH= cd -- "$(NUGET_BINARIES)" && pwd) || exit 1; \
	docker run --rm \
		-v "$(CURDIR):/work" -v "$$BINARIES:/binaries:ro" \
		-e DOTNET_NOLOGO=1 -e DOTNET_CLI_TELEMETRY_OPTOUT=1 \
		-w /work $(NUGET_SDK_IMAGE) sh -euc ' \
			apt-get -qq update && apt-get -qq install -y --no-install-recommends python3 >/dev/null && \
			python3 scripts/build_nuget.py --binaries /binaries --version '"$$VER"' && \
			python3 scripts/validate_nuget.py --packages nuget/dist --version '"$$VER"

## validate-nuget-local: same validation without Docker, for the ephemeral CI
## runner (already disposable; the .NET 10 SDK must be on PATH). Builds the
## packages from NUGET_BINARIES, then validates.
validate-nuget-local:
	@command -v python3 >/dev/null || { echo "ERROR: Python 3 is required"; exit 1; }
	@command -v dotnet >/dev/null || { echo "ERROR: the .NET 10 SDK is required (or use validate-nuget)"; exit 1; }
	@test -n "$(NUGET_BINARIES)" || { echo "ERROR: set NUGET_BINARIES=<dir of release binaries>"; exit 1; }
	@VER=$$(tr -d '[:space:]' < VERSION); \
	python3 scripts/build_nuget.py --binaries "$(NUGET_BINARIES)" --version "$$VER" && \
	python3 scripts/validate_nuget.py --packages nuget/dist --version "$$VER"

## publish-nuget-dry: assemble and validate the NuGet packages without pushing.
publish-nuget-dry:
	@test -n "$(NUGET_BINARIES)" || { echo "ERROR: set NUGET_BINARIES=<dir of release binaries>"; exit 1; }
	scripts/publish-nuget.sh "$(NUGET_BINARIES)" "$$(tr -d '[:space:]' < VERSION)" --dry-run

## publish-nuget: assemble, validate and push the NuGet packages out of band.
## Auth via NUGET_API_KEY (an API key from nuget.org). The release workflow
## pushes under the nuget.org trusted publishing policy instead, with a
## one-hour key minted from its OIDC identity; this is the only tokened path.
publish-nuget:
	@test -n "$(NUGET_BINARIES)" || { echo "ERROR: set NUGET_BINARIES=<dir of release binaries>"; exit 1; }
	scripts/publish-nuget.sh "$(NUGET_BINARIES)" "$$(tr -d '[:space:]' < VERSION)"

## publish-lobehub: push the current version of the existing LobeHub listing.
## Reads lhm.plugin.json (version kept in sync by scripts/update-server-json-sha.sh
## on each release) and posts it via the @lobehub/market-cli. The CLI split its
## verbs: `plugin publish <gitUrl>` is for FIRST-TIME listings only and now
## requires the git URL; an already-published plugin is refused with "use lhm
## plugin update", which is what this target runs. Requires a one-time
## interactive `lhm login` + `lhm github connect` on the machine — LobeHub has
## no CI path. See docs/development/release-process.md.
# Pinned: the CLI has already changed its verb contract under this target
# once (publish -> update, a new positional gitUrl); bump deliberately after
# verifying `plugin update --dir` still holds.
LOBEHUB_MARKET_CLI_VERSION := 0.0.44

publish-lobehub: check-lhm-manifest
	@command -v node >/dev/null || { echo "ERROR: Node.js >= 22 is required"; exit 1; }
	@NODE_MAJOR=$$(node -v | sed 's/^v\([0-9]*\).*/\1/'); \
	if [ "$$NODE_MAJOR" -lt 22 ]; then echo "ERROR: Node.js >= 22 is required (found $$(node -v))"; exit 1; fi
	@command -v jq >/dev/null || { echo "ERROR: jq is required"; exit 1; }
	@VER=$$(tr -d '[:space:]' < VERSION); \
	MVER=$$(jq -r '.version' lhm.plugin.json); \
	if [ "$$VER" != "$$MVER" ]; then \
		echo "ERROR: VERSION ($$VER) != lhm.plugin.json version ($$MVER); run a release stamp first"; exit 1; \
	fi; \
	echo "Updating jmrplens-gitlab-mcp-server to v$$VER on LobeHub..."; \
	npx -y @lobehub/market-cli@$(LOBEHUB_MARKET_CLI_VERSION) plugin update --dir "$(CURDIR)"

## update-all: run every generator, the brand assets included, then the table formatter.
## Generates: brand vectors, fine-grained permissions per action, the 1:1 audit's baseline of report-only findings, token footprint, site stats, llms.txt, the per-domain tool reference, LobeHub manifest, testing docs, action catalog manifest, benchmark charts and tables, markdown table formatting.
# One generator at a time, in the recipe rather than as prerequisites: brand
# rewrites internal/toolutil/brandmark_gen.go, which the generators after it
# compile, so make -j would build them against a file still being written.
# bench-resources-render is in because it redraws from
# the committed record and measures nothing, which is what check-bench-resources
# then compares; bench-resources itself stays out, and so does brand-rasters,
# which needs rsvg-convert and cwebp that only the maintainer's machine has.
# e2e-coverage-record-render is in on exactly the same terms and
# e2e-coverage-record is out on the same ones: redrawing the coverage page
# needs only the committed record, while measuring it needs a booted GitLab.
# gen-model-results is in and model-results-record is out for the third time on
# those terms, and the measurement there is not merely slow: it is a paid run
# against a provider.
# gen-audit-1to1-baseline comes right after gen-action-grants, because three of
# the scopes it reads read the request record that target rewrites. It reads the
# request inventory too, which no generator here writes (gen-request-inventory
# needs a suite run), so after one it is run again.
update-all:
	@for target in brand gen-action-grants gen-audit-1to1-baseline gen-footprint gen-site-stats gen-llms gen-tool-reference gen-lhm-manifest gen-model-corpus gen-model-results gen-testing-docs gen-action-catalog-manifest bench-resources-render e2e-coverage-record-render; do \
		$(MAKE) --no-print-directory $$target || exit 1; \
	done
	go run ./cmd/format_md_tables/
	@echo "All generators and formatters complete."

## gen-footprint: measure token footprint and write the README token-claim block, token-footprint.md and site/src/data/token-footprint.json.
gen-footprint:
	go run ./cmd/audit_tokens/ -footprint

## check-footprint: verify the README token-claim block, token-footprint.md and site/src/data/token-footprint.json are current.
check-footprint:
	go run ./cmd/audit_tokens/ -footprint -check

## gen-site-stats: regenerate the single-sourced site stats JSON (site/src/data/stats.json).
gen-site-stats:
	go run ./cmd/audit_metrics/ -site-stats site/src/data/stats.json

## check-site-stats: verify the committed site stats JSON is current.
check-site-stats:
	go run ./cmd/audit_metrics/ -site-stats site/src/data/stats.json -check

## bench-resources: measure what the server costs to run and redraw the charts.
## Starts the real binary on both transports against an in-process stand-in
## GitLab, so it needs no instance and no credentials. Takes several minutes:
## every scenario builds a tool catalog per client, which is the cost being
## measured. Writes site/src/data/resource-benchmark.json, the SVG pairs under
## site/public/benchmarks (one directory per language), and the generated block
## in the English and Spanish performance/resource-benchmark pages of the site.
bench-resources:
	go run ./cmd/bench_resources/

## bench-resources-render: redraw the charts and tables from the committed
## measurements, without re-measuring. This is what to run after changing a
## figure; the numbers stay exactly as they were published.
bench-resources-render:
	go run ./cmd/bench_resources/ -render

## check-bench-resources: verify the committed charts and tables match the
## committed measurements. Seconds, and no benchmark is run, which is what
## makes it a CI gate.
check-bench-resources:
	go run ./cmd/bench_resources/ -check

## bench-fairness: measure whether a bound leaves the quiet tenant better off.
## Two populations of credentials driven differently against one server, twice:
## with the bound in force and without it. Reports the quiet population's served
## and refused counts separately, and can answer that the bound helped nobody.
## Minutes on a modest host. Writes bench/fairness.json, which is not committed,
## and draws no chart: it touches neither the published record nor the artifacts
## check-bench-resources compares. BOUND selects which limit is measured:
## tools-call-rps, tools-list-rps, tools-list-process, oauth-verification or
## discovery. discovery is the per-address bucket on the documents served
## without a credential (register row RTC-008): a flood from an address per
## noisy lane against a hosted client's egress address the quiet lanes share.
## oauth-verification is the OAuth verification ceiling (register row ADM-014):
## it builds a second server with the ceiling taken out through the go
## command's -overlay, drives a flood of invented tokens against a stand-in
## GitLab that answers each verification in 100 ms, and needs Linux, since the
## flood is sent from addresses in 127.2.0.0/16 on the loopback.
BOUND ?= tools-call-rps
bench-fairness:
	go run ./cmd/bench_resources/ -fairness $(BOUND)

## bench-held: measure what a held call costs and what the process does with
## more of them than its descriptor limit allows. The ladder the held-call
## ceiling (register row HLD-011) was measured with, under a hard descriptor
## limit of 1024, from HELD_CREDENTIALS credentials. Minutes on a modest host,
## Linux or macOS (the limit is set through /bin/sh). Writes bench/held.json,
## which is not committed, and draws nothing.
HELD_CREDENTIALS ?= 1
bench-held:
	go run ./cmd/bench_resources/ -held 100,192,250,500,1000,2000,4000 -held-nofile 1024 \
		-held-credentials $(HELD_CREDENTIALS)

## bench-sessions: measure what a stateful session costs and what the process
## does with more of them than it keeps. The ladder the session ceiling
## (register row HLD-010) was measured with: the server on --stateless=false
## under a hard descriptor limit of 1024, each session holding its standalone
## stream open, from SESSIONS_CREDENTIALS credentials. Minutes on a modest
## host, Linux or macOS. Writes bench/sessions.json, which is not committed,
## and draws nothing.
SESSIONS_CREDENTIALS ?= 1
bench-sessions:
	go run ./cmd/bench_resources/ -sessions 50,96,100,500,1000,2000,4000 -sessions-nofile 1024 -sessions-stream \
		-sessions-credentials $(SESSIONS_CREDENTIALS)

## gen-testing-docs: regenerate testing.md counts and coverage tables.
## Runs unit-test coverage over ./cmd/... and ./internal/..., so it takes minutes.
## Add -skip-coverage to refresh only the counts, keeping the recorded values.
gen-testing-docs:
	go run ./cmd/gen_testing_docs/

## check-testing-docs: verify everything in testing.md that a checkout determines.
## Seconds, not minutes: a check carries the recorded coverage values forward
## instead of recomputing them, because those depend on the machine (privilege,
## and whether rsvg-convert is installed) while counts and package rows do not.
## This is the CI gate. To verify the coverage values too, regenerate with
## gen-testing-docs and look at the diff.
##
## No -skip-coverage here on purpose: --check implies it, so every caller gets
## the cheap answer rather than whoever remembered the flag. The command says
## so, and `--check -skip-coverage=false` is the explicit way to measure.
check-testing-docs:
	go run ./cmd/gen_testing_docs/ --check

## gen-action-catalog-manifest: regenerate the ActionSpec group builder manifest.
gen-action-catalog-manifest:
	go run ./cmd/gen_action_catalog_manifest/

## check-action-catalog-manifest: verify the generated ActionSpec manifest is current.
check-action-catalog-manifest:
	go run ./cmd/gen_action_catalog_manifest/ --check

# ─── Output Quality Audit ────────────────────────────────────────────────────

## audit-surface-quality: consolidated MCP tool surface quality audit (both views).
## Combines the former audit_tools (metadata) and audit_output (output quality).
audit-surface-quality:
	go run ./cmd/audit_surface_quality/

## check-surface-quality: the same audit as a gate. Prints the violations that
## gate and exits non-zero on any. The result-envelope section stays a report.
check-surface-quality:
	@echo === MCP tool surface quality ===
	go run ./cmd/audit_surface_quality/ -check

## check-spec-conditions: condition coverage (gobco) over the action_specs.go
## this branch changes against BASE (default origin/main). A condition no test
## evaluates both ways fails; a package gobco cannot instrument is reported.
check-spec-conditions:
	@echo === action spec conditions ===
	./scripts/check-spec-conditions.sh $(BASE)

## audit-output: run MCP output quality audit on all tools.
## Backward-compat wrapper over audit-surface-quality -view=output.
audit-output:
	go run ./cmd/audit_surface_quality/ -view=output

## audit-tokens: measure LLM context window overhead of all tool definitions.
## Reports per-tool token counts, domain totals, and mode comparison.
## Use --compare-schemas for the meta-tool InputSchema sizing spike.
audit-tokens:
	go run ./cmd/audit_tokens/

## audit-tools: audit MCP tool metadata violations (naming, annotations).
## Backward-compat wrapper over audit-surface-quality -view=metadata.
audit-tools:
	go run ./cmd/audit_surface_quality/ -view=metadata

## audit-metrics: report MCP tool metrics (tool/resource/prompt counts).
audit-metrics:
	go run ./cmd/audit_metrics/

## audit-catalog-first: enforce catalog-first registration invariants (ADR-0004).
audit-catalog-first:
	go run ./cmd/audit_catalog_first/

## audit-action-spec-coverage: backward-compat wrapper for audit-catalog-first.
audit-action-spec-coverage:
	go run ./cmd/audit_catalog_first/

## audit-1to1: run the three 1:1-audit gap streams (struct/action/enums), merge
## into plan/1to1-backlog.json, then gate on SDK parity (audit-1to1-sdk), the request
## paths (audit-1to1-paths), the fine-grained grants (audit-1to1-grants), the
## parameters each schema requires (audit-1to1-required), the params each reached
## route declares (audit-1to1-params) and the routes the live record mounts
## (audit-1to1-routes).
## Single binary cmd/audit_1to1 consolidates the former audit_struct_completeness,
## audit_action_coverage and gen_1to1_backlog. The discovery metadata stream it
## also carried (R-META, audit-metadata-completeness) is retired: audit-discovery
## raises the same four flags with a severity, and audit-discovery-check gates them.
## The backlog is written first so a gate failure still leaves the artifact behind.
audit-1to1:
	go run ./cmd/audit_1to1/ -gaps-only -output plan/1to1-backlog.json
	@echo "1:1 audit backlog written to plan/1to1-backlog.json"
	$(MAKE) audit-1to1-sdk
	$(MAKE) audit-1to1-paths
	$(MAKE) audit-1to1-grants
	$(MAKE) audit-1to1-required
	$(MAKE) audit-1to1-params
	$(MAKE) audit-1to1-routes

## audit-1to1-sdk: gate every client-go service, every raw-GraphQL operation and every
## enum value on a decision (R-SERVICE/R-GRAPHQL/R-ENUM), with the option structs a
## call sends, the workarounds waiting on client-go, the captured keys and the
## identifiers that accept a path. Unlike the three candidate
## streams this one FAILS on a finding: a new SDK service that is neither called nor
## declared, a raw-GraphQL operation whose wrapper now exists and is not adjudicated,
## an SDK enum constant the surface does not offer (or a value it offers that the SDK
## does not declare), an option struct no input fills, a workaround whose predicate
## the pinned SDK no longer meets, a captured key the SDK struct beside it models, an
## integer input passed where GitLab accepts a path, or a declaration or exemption
## that has gone stale. Step 37 of make analyze and a step of CI's generated job, at the
## client-go go.mod pins; .github/workflows/upstream-drift.yml asks it of the newest
## client-go every week, so what a bump will have to answer is known before the bump.
audit-1to1-sdk:
	go run ./cmd/audit_1to1/ -scope=sdk -gaps-only

## audit-1to1-paths: gate the request an action actually issues (R-PATH). The other
## five rules describe the surface and none of them looks at the request a handler
## builds, which is how nine registered tools shipped unable to work. This FAILS on a
## GraphQL document the pinned schema refuses, on an action whose owner names no
## package under internal/tools, on a package the catalog owns actions in that neither
## the committed inventory shows issuing a request nor declares a reason, on a field
## GitLab sends to an endpoint a package calls that the package publishes nowhere and
## no declaration in cmd/audit_1to1/internal/paths/sent_declarations.go answers, on a
## recorded REST endpoint neither the documentation oracle
## (docs/development/gitlab-api-doc-endpoints.json) nor a declaration in
## endpoint_declarations.go accounts for, and on a declaration that no longer describes
## the tree. A silent package means one of two things and the finding cannot tell them
## apart: no test drives that package, or the inventory is stale (`make
## gen-request-inventory`). It reads the committed inventory, live record and oracle,
## so it needs no network and no suite run.
audit-1to1-paths:
	go run ./cmd/audit_1to1/ -scope=paths -check-endpoints -gaps-only

## audit-1to1-paths-report: the whole R-PATH report, the documentation comparison
## included, written to plan/1to1-paths.json: every undocumented endpoint with the
## declaration that answers it, and every finding the reports beside the gate hold.
## It gates on nothing audit-1to1-paths does not.
audit-1to1-paths-report:
	go run ./cmd/audit_1to1/ -scope=paths -check-endpoints -output plan/1to1-paths.json
	@echo "R-PATH report written to plan/1to1-paths.json"

## gen-api-doc-endpoints: read GitLab's API documentation (doc/api of gitlab-org/gitlab,
## ~250 pages through the repository files API) at the tag of the release the live
## record was taken from, and rewrite docs/development/gitlab-api-doc-endpoints.json,
## the oracle audit-1to1-paths holds every recorded REST endpoint to. It needs the
## network and no token, reads nothing a regeneration changes for a tag already read
## (the pages are cached under .cache/gitlab-api-docs@<tag>), and writes nothing when a
## page cannot be read. Run it in the change that re-pins the live record
## (make gen-api-live): audit-1to1-paths refuses an oracle read at another release.
gen-api-doc-endpoints:
	go run ./cmd/audit_1to1/ -write-doc-endpoints -output docs/development/gitlab-api-doc-endpoints.json

## audit-1to1-paths-e2e: the same report, plus the observation question asked per ACTION
## instead of per owning package, read from the shards a Docker end-to-end run left under
## $(E2E_CALLS_DIR) (make test-e2e-ce or make test-e2e-ee writes them). The committed
## inventory can only answer at package grain, because nothing on the wire names an
## action; a trace does, so the record says which actions were themselves seen issuing a
## request and which ran without issuing one. It changes nothing the gate fails on: the
## shards are a byproduct of a run CI does not schedule, and the counts are floors, since
## a batch queue that overflowed drops client spans without saying so. A directory it
## cannot read fails the run, since the run asked for an answer it cannot give.
audit-1to1-paths-e2e:
	go run ./cmd/audit_1to1/ -scope=paths -e2e-calls "$(E2E_CALLS_DIR)" -output plan/1to1-paths-e2e.json
	@echo "R-PATH report with per-action observation written to plan/1to1-paths-e2e.json"

## audit-1to1-grants: gate the fine-grained permission of each action (R-GRANT) on the
## consistency of what make gen-action-grants committed with the live GitLab record it was
## joined from: the table joined at the record's release, naming its permission vocabulary
## and its public sets, denying nothing on an element the record does not hold as the kind
## the denial's cause says, demanding on each REST operation what the record's route
## declares, and covering the actions the request record and the catalog cover. It reads
## committed files only (the table compiled in, action-requests.json, the live record and
## the request inventory) and the catalog the tree builds, so it needs no network, no Docker
## and no program load; CI runs it under the FRESHNESS deferral like every committed-artifact
## gate.
audit-1to1-grants:
	go run ./cmd/audit_1to1/ -scope=grants -gaps-only

## audit-1to1-grants-report: the whole R-GRANT report, written to plan/1to1-grants.json:
## every action's permissions in GitLab's words with the directive or declaration that
## shaped its requests, the actions no fine-grained token reaches by cause, the parts of an
## answer served empty, the REST operations a public project or group serves with no grant,
## the GraphQL worklist of upstream register row 87 with its REST leads, and the derivation
## held to the request inventory and, when a Docker run left shards under $(E2E_CALLS_DIR),
## to each action's request count. It reports and gates on nothing audit-1to1-grants does
## not.
audit-1to1-grants-report:
	@mkdir -p plan
	if test -e "$(E2E_CALLS_DIR)"; then set -- -e2e-calls "$(E2E_CALLS_DIR)"; fi; \
	go run ./cmd/audit_1to1/ -scope=grants "$$@" -output plan/1to1-grants.json
	@echo "R-GRANT report written to plan/1to1-grants.json"

## audit-1to1-required: gate the parameters every input schema requires (R-REQUIRED,
## issue 1100). The three surfaces read one required list, the `,required`
## marker of each field's jsonschema tag, and this holds it to GitLab: a field the schema
## leaves optional that every way the action runs sends to a route GitLab requires it on,
## and a field the schema requires that some way runs without. It FAILS on either unless
## cmd/audit_1to1/internal/required/declarations.go answers it with a category and a
## reason, and on a declaration or alias that answers nothing. It reads the catalog the tree
## builds, the committed request record (action-requests.json) and the live GitLab record,
## so it needs no network and no program load; CI runs it under the FRESHNESS deferral with
## R-GRANT, since it reads the request record make gen-action-grants commits.
audit-1to1-required:
	go run ./cmd/audit_1to1/ -scope=required -gaps-only

## audit-1to1-required-report: the same, with the fields no route was found to carry and
## the ones a way of the action could not be read for, written to plan/1to1-required.json.
## It gates on nothing audit-1to1-required does not.
audit-1to1-required-report:
	@mkdir -p plan
	go run ./cmd/audit_1to1/ -scope=required -output plan/1to1-required.json
	@echo "R-REQUIRED report written to plan/1to1-required.json"

## audit-1to1-params: hold every param a route this server reaches declares to whether
## anything here can send it (R-PARAM). A param no recorded request carries is a finding:
## unmodeled (no option struct the route's requests carry models it and no input offers
## it, client-go's to fix), not_offered (an option struct models it and no input offers
## it), offered_unrecorded (an input offers it and no test sends it) or unjudged. It
## FAILS on a not_offered finding no declaration answers, which an input can offer today,
## and on a declaration in cmd/audit_1to1/internal/params/declarations.go that answers
## nothing; the other findings are a report. It reads the committed request record, the
## inventory and the live record and loads the tool packages for their raw requests; CI
## runs it under the FRESHNESS deferral with R-GRANT.
audit-1to1-params:
	go run ./cmd/audit_1to1/ -scope=params -gaps-only

## audit-1to1-params-report: the same, with the declared findings and the requests whose
## options could not be read, written to plan/1to1-params.json. It gates on nothing
## audit-1to1-params does not.
audit-1to1-params-report:
	@mkdir -p plan
	go run ./cmd/audit_1to1/ -scope=params -output plan/1to1-params.json
	@echo "R-PARAM report written to plan/1to1-params.json"

## audit-1to1-routes: hold every route the live record mounts to an action that sends
## it or a reason none does (R-ROUTE): outside the API, a skip reason the closed table
## excludes, a slug the caller names, a deprecated /services/ alias, a decision about its
## client-go methods that holds without a request, or a family row of
## cmd/audit_1to1/internal/routes/family_table.go. Anything else is a finding, reported
## with the client-go methods that send it, and it FAILS on a finding as it does on a
## declaration that no longer describes the tree: a family row that answers no route,
## another number than it pins, a route another row answers, or that lacks what its
## category needs; a skip row no route carries, or a reason a route carries that no row
## holds; a skip exception or a GraphQL
## actions row that answers no route; a slug rule that answers nothing. It reads the
## committed request record, the live record and the pinned client-go; CI runs it under
## the FRESHNESS deferral with R-GRANT.
audit-1to1-routes:
	go run ./cmd/audit_1to1/ -scope=routes -gaps-only

## audit-1to1-routes-report: the same, with every route the findings leave out (the
## answered ones with what answers them, ordered by family, and the reached ones),
## written to plan/1to1-routes.json: the work list a triage reads. It gates on nothing
## audit-1to1-routes does not.
audit-1to1-routes-report:
	@mkdir -p plan
	go run ./cmd/audit_1to1/ -scope=routes -output plan/1to1-routes.json
	@echo "R-ROUTE report written to plan/1to1-routes.json"

## audit-1to1-enums: the enum value rule on its own (R-ENUM), in its native shape.
## Fails on a value the SDK declares that no schema enum or description offers, on a
## value offered that the SDK does not declare, or on a stale exemption. Step 38 of make
## analyze and a step of CI's generated job.
audit-1to1-enums:
	go run ./cmd/audit_1to1/ -scope=enums -gaps-only

## audit-1to1-validate-docs: verify every doc/api citation behind the 1:1 adjudication tables is
## still fetchable from gitlab-org/gitlab's master. It needs the network, so it is not a step of
## make analyze; .github/workflows/upstream-drift.yml runs it every week.
audit-1to1-validate-docs:
	go run ./cmd/audit_1to1/ -validate-docs

## gen-audit-1to1-baseline: write every finding the 1:1 audit reports without gating to
## docs/development/audit-1to1-baseline.json, as keys by stream: the struct and action
## candidates, the four classes of R-PARAM, the R-PATH shapes, always-sent params and
## identifier leads, the fields R-REQUIRED places on no route, the R-GRANT cross-check with
## the request inventory and the enum output fields no schema names a value of. A change
## that adds or settles one regenerates it, and the diff of the file is what the change
## adds. It reads committed records only, so it needs no network.
gen-audit-1to1-baseline:
	go run ./cmd/audit_1to1/ -write-baseline -output docs/development/audit-1to1-baseline.json

## check-audit-1to1-baseline: hold the findings the 1:1 audit reports without gating to
## docs/development/audit-1to1-baseline.json. FAILS on a finding the file does not hold,
## naming its stream and key, and on a key of the file no finding answers. It reads the
## request records make gen-action-grants and make gen-request-inventory commit, so the
## unit suite's comparison of the file with the tree waits on the FRESHNESS deferral, as
## R-GRANT's does, and so does its step in CI's generated job. Step 39 of make analyze. No
## network.
check-audit-1to1-baseline:
	go run ./cmd/audit_1to1/ -check-baseline

## audit-1to1-issues: ask GitHub whether every issue a tracked row names is still open: the
## domain issue of each tracked family row of R-ROUTE and the issue of each tracked
## identifier of the sdk scope. FAILS on an issue that is closed, is a pull request or is not
## in the repository, naming the rows that rest on it, and on one it could not ask about (a
## refused token, a rate limit, no network), which is never a pass. It asks with
## GITHUB_TOKEN or GH_TOKEN when either is set, and needs the network, so it is not a step of
## make analyze; .github/workflows/upstream-drift.yml runs it every week.
audit-1to1-issues:
	go run ./cmd/audit_1to1/ -check-issues

## audit-struct-completeness: diff MCP input/output structs vs client-go fields (R-INPUT/R-OUTPUT).
## Backward-compat wrapper over audit-1to1 -scope=structs.
audit-struct-completeness:
	go run ./cmd/audit_1to1/ -scope=structs -gaps-only

## audit-action-coverage: report client-go SDK endpoints no MCP action invokes (R-ACTION).
## Backward-compat wrapper over audit-1to1 -scope=actions.
audit-action-coverage:
	go run ./cmd/audit_1to1/ -scope=actions -gaps-only

## audit-edition-tier: report each action's doc-grounded licensing tier vs current gating.
audit-edition-tier:
	go run ./cmd/audit_edition_tier/ -gaps-only

## audit-discovery: report discovery-metadata gaps (aliases/usage/related/param-guidance/sibling-cluster) across the ActionSpec catalog (META-001).
audit-discovery:
	go run ./cmd/audit_discovery_completeness/ -gaps-only -output plan/discovery-backlog.json

## audit-discovery-check: gate META-001, step 40 of make analyze and a step of CI's generated
## job. FAILS on any error-severity finding: a generic Usage line, a variant that does not tell
## itself from its siblings, and the alias, related-action and individual description flags of
## an action whose cluster holds a non-CRUD variant. The catalog reads 0 of them, so a change
## that adds one fails here; `make audit-discovery` writes the whole report with its warnings
## and infos.
audit-discovery-check:
	go run ./cmd/audit_discovery_completeness/ -gaps-only -check

## audit-dynamic-aliases: audit Dynamic search aliases and canonical action reachability.
audit-dynamic-aliases:
	go run ./cmd/audit_dynamic_aliases/

## audit-e2e-gaps: report catalog actions the e2e suite does not exercise, as
## a TSV work list. It reads the same recorded calls audit-e2e-coverage does,
## so a gap here is an action no test dispatched rather than an action no
## source file mentions.
audit-e2e-gaps:
	go run ./cmd/audit_e2e_coverage/ -calls "$(E2E_CALLS_DIR)" -report

## audit-e2e-coverage: report what the e2e suite covered, from the calls it
## recorded rather than from mentions in its source: one runtime per directory
## under $(E2E_CALLS_DIR), every runtime x surface x mode x action classified,
## the levels L1 to L3, and the non-tool capabilities. Needs a run that had
## GITLAB_MCP_TEST_E2E_CALLS_DIR set; the JSON goes to $(E2E_REPORT_DIR).
audit-e2e-coverage:
	$(call MKDIR_P,$(E2E_REPORT_DIR))
	go run ./cmd/audit_e2e_coverage/ -calls "$(E2E_CALLS_DIR)" -report -o "$(E2E_REPORT_DIR)/e2e-coverage.json" -summary -

## e2e-coverage-record: fold both Docker runs into the committed per-runtime
## coverage record and redraw the page beside it. Needs the shards and the
## gotestsum streams of a run of each half, so it is a maintainer's command
## and deliberately not a member of update-all. Each half is written by its
## own invocation: one -results stream belongs to one runtime, and joining
## the ce stream to the ee shards would credit each against the other's tests.
e2e-coverage-record:
	@for target in e2e-coverage-record-ce e2e-coverage-record-ee; do \
		$(MAKE) --no-print-directory $$target || exit 1; \
	done

## e2e-coverage-record-ce: record the unlicensed half alone, for a maintainer
## who ran only `make test-e2e-ce`. The write folds into the committed
## document and leaves the ee entry exactly as it was.
e2e-coverage-record-ce:
	go run ./cmd/audit_e2e_coverage/ -calls "$(E2E_CALLS_DIR)/ce" -results "$(E2E_REPORT_DIR)/e2e-ce-log.json" \
		-runtime ce -static -record -o "$(E2E_REPORT_DIR)/e2e-coverage-ce.json"

## e2e-coverage-record-ee: record the licensed half alone, for a maintainer
## who ran only `make test-e2e-ee`.
e2e-coverage-record-ee:
	go run ./cmd/audit_e2e_coverage/ -calls "$(E2E_CALLS_DIR)/ee" -results "$(E2E_REPORT_DIR)/e2e-ee-log.json" \
		-runtime ee -static -record -o "$(E2E_REPORT_DIR)/e2e-coverage-ee.json"

## e2e-coverage-record-render: redraw docs/development/testing/e2e-coverage.md
## from the committed record, without a GitLab. This is what to run after
## changing the page's wording; the figures stay exactly as they were measured.
e2e-coverage-record-render:
	go run ./cmd/audit_e2e_coverage/ -render-record

## check-e2e-coverage-record: the offline gate over the committed coverage
## record: both runtimes present, the levels agreeing with the action lists
## beside them, the floors of -check re-applied, and the record inside its own
## staleness window. No GitLab, no Docker and no network; a catalog that has
## moved under the record is a note rather than a failure, since
## check-e2e-static already fails on a rename from the scenario's side. The
## page beside the record is check-e2e-coverage-page, which is a separate
## target because it is a freshness comparison and this one is not: nothing
## here can regenerate the figures, so these judgments hold on every layer of
## every stack.
check-e2e-coverage-record:
	go run ./cmd/audit_e2e_coverage/ -check-record

## check-e2e-coverage-page: compare docs/development/testing/e2e-coverage.md
## with a fresh rendering of the committed record. This is the half of the gate
## the source tree can move -- the renderer and the table formatter are code
## here -- so it is redrawn by e2e-coverage-record-render, which update-all
## runs, and CI defers it below a stack's tip exactly as it does
## check-bench-resources.
check-e2e-coverage-page:
	go run ./cmd/audit_e2e_coverage/ -check-record-page

## e2e-go-coverage: report which statements of the server binary the e2e runs
## executed, from the counter files a COVER=1 run left under $(E2E_COVER_ROOT):
## the merged profile in $(E2E_COVER_PROFILE), the per-package table and the
## total. Its sibling above answers which catalog actions dispatched, which
## says nothing about the program around them.
#
# It reads whatever runs are there, so a CE run and a licensed one merge into
# one figure, which is the honest one: a statement only the licensed catalog
# reaches was still reached. Nothing here is committed and nothing gates on
# the number: the input exists only after a live GitLab has been driven, so a
# floor could not be moved without booting one, and the profile must never be
# folded into coverage.out, which sonar-project.properties publishes as the
# unit suite's figure. The run is refused rather than reported as zero when no
# meta-data file is there at all, since that is the shape of an uninstrumented
# build and not of a binary nothing executed.
e2e-go-coverage:
	$(call MKDIR_P,$(E2E_REPORT_DIR))
	bash -o pipefail -c 'set -eu; \
	  dirs=""; \
	  while IFS= read -r meta; do \
	    dir=$$(dirname "$$meta"); \
	    case ",$$dirs," in *",$$dir,"*) continue;; esac; \
	    dirs="$${dirs:+$$dirs,}$$dir"; \
	  done < <(find "$(E2E_COVER_ROOT)" -name "covmeta.*" -type f 2>/dev/null | sort); \
	  if [ -z "$$dirs" ]; then \
	    echo "no coverage data under $(E2E_COVER_ROOT): run an e2e target with COVER=1, which builds the server with -cover and gives every child a GOCOVERDIR" >&2; \
	    exit 1; \
	  fi; \
	  echo "merging $$dirs"; \
	  go tool covdata textfmt -i="$$dirs" -o="$(E2E_COVER_PROFILE)"; \
	  go tool covdata percent -i="$$dirs"; \
	  go tool cover -func="$(E2E_COVER_PROFILE)" | tail -n 1'

## e2e-support-coverage: report which statements of the e2e support packages
## (E2E_SUPPORT_COVERPKG) their offline tests and the complete runs reach
## together: the offline half run here, merged with every run profile in
## $(E2E_REPORT_DIR), the per-package table, and the merged profile in
## $(E2E_SUPPORT_PROFILE). E2E_SUPPORT_SUMMARY names a Markdown file the table
## is appended to as well, and E2E_SUPPORT_WRITE_RECORD a record of what the
## runs reached, which is how e2e-support-coverage-record writes it.
#
# The offline half is run here rather than read from somewhere else, so both
# halves are of one tree whenever the runs were: a run profile whose blocks
# disagree with the offline half's, which is what another version of a file
# looks like, is refused by the merge, naming the file, rather than folded in.
# The merge sees only the blocks, so a run of another version whose blocks
# happen to agree is not caught: the runs are to be of this tree.
# It is e2e_support_offline, the two packages' own tests with no GitLab, as
# the harness tests run in CI.
#
# The run half is every <stem>-coverprofile.out the report directory holds, so
# a CE run, its final pass and a licensed run fold into one figure, as
# e2e-go-coverage folds the server's; run-docker-e2e.sh removes its own before
# it starts, so a stale one is only ever another stem's. With none there the
# target refuses rather than reporting the offline half alone, which is the
# figure issue 1461 says is not the measurement.
e2e-support-coverage:
	$(call MKDIR_P,$(E2E_REPORT_DIR))
	bash -o pipefail -c 'set -eu; shopt -s nullglob; \
	  runs=("$(E2E_REPORT_DIR)"/*-coverprofile.out); \
	  if [ "$${#runs[@]}" -eq 0 ]; then \
	    echo "no run profile under $(E2E_REPORT_DIR): run make test-e2e-ce or make test-e2e-ee first, which write <stem>-coverprofile.out there" >&2; \
	    exit 1; \
	  fi; \
	  online=(); for run in "$${runs[@]}"; do online+=(-online "$$run"); done; \
	  $(e2e_support_offline); \
	  go run ./cmd/merge_coverage/ -packages $(E2E_SUPPORT_COVERPKG) -offline "$(E2E_SUPPORT_OFFLINE_PROFILE)" "$${online[@]}" -o "$(E2E_SUPPORT_PROFILE)" $(if $(E2E_SUPPORT_SUMMARY),-summary "$(E2E_SUPPORT_SUMMARY)") $(if $(E2E_SUPPORT_WRITE_RECORD),-write-record "$(E2E_SUPPORT_WRITE_RECORD)")'

## e2e-support-coverage-record: write $(E2E_SUPPORT_RECORD), the committed
## record of what the complete runs reached in the e2e support packages, from
## the run profiles in $(E2E_REPORT_DIR) and the offline half of this tree.
## Run it after the complete runs the instance allows on the tree being
## committed, make test-e2e-ce and, with an EE license, make test-e2e-ee,
## which is the regeneration a stack's top makes when it changes the two
## packages; it needs a GitLab only through those runs, so it is a
## maintainer's command and deliberately not a member of update-all. A record
## of the CE run alone leaves what only the licensed run reaches to neither
## half, inside the ceiling, until a licensed run is recorded.
#
# It is e2e-support-coverage writing the record, so the record is folded from
# exactly the halves the report beside it shows. The record is taken only of
# complete runs of the two packages' sources as this tree holds them:
# run-docker-e2e.sh stamps those sources before each pass of a complete run
# builds and keeps the stamp, <stem>-coverprofile.complete, only once the run
# ended with status 0, and merge_coverage -write-record refuses a run profile
# without one, or whose stamp is not this tree's, before it writes anything.
# The scenarios, the harness and the server that drive the two packages are
# not stamped.
e2e-support-coverage-record:
	@$(MAKE) --no-print-directory e2e-support-coverage E2E_SUPPORT_WRITE_RECORD="$(E2E_SUPPORT_RECORD)"

## check-e2e-support-coverage: the gate the coverage job of ci.yml runs over
## the e2e support packages: their offline half on this tree, merged with
## the runs' half from $(E2E_SUPPORT_RECORD), and each package held to the
## number of statements the record says neither half reached. No GitLab and
## no Docker. E2E_SUPPORT_FRESHNESS=deferred, below a stack's top, makes an
## excess a record that predates the tree explains a note; until the first
## record is committed it reports the offline half and holds nothing.
check-e2e-support-coverage:
	$(call MKDIR_P,$(E2E_REPORT_DIR))
	bash -o pipefail -c 'set -eu; \
	  $(e2e_support_offline); \
	  go run ./cmd/merge_coverage/ -packages $(E2E_SUPPORT_COVERPKG) -offline "$(E2E_SUPPORT_OFFLINE_PROFILE)" -check-record "$(E2E_SUPPORT_RECORD)" -freshness $(E2E_SUPPORT_FRESHNESS) $(if $(E2E_SUPPORT_SUMMARY),-summary "$(E2E_SUPPORT_SUMMARY)")'

## check-e2e-static: the push-time gate over the new e2e suite, with no
## GitLab: every typed action id names a catalog action, sits in a package
## that can run it, and an Ultimate id in ee declares its tier; a harness
## result thrown away is a finding. With the ratchet on it holds the other
## direction too: a catalog action no scenario names and no exemption
## declares fails, and so does a harness export nothing consumes.
check-e2e-static:
	go run ./cmd/audit_e2e_coverage/ -static

## audit-test-goroutines: report testing.T aborts made off the test goroutine
## (t.Fatal inside HTTP mock handlers, go statements, MCP tool handlers) and
## t.Errorf calls without the contract-required return. Writes the JSON work
## list consumed by the conversion batches.
audit-test-goroutines:
	go run ./cmd/audit_test_goroutines/ -json plan/test-goroutines-backlog.json

## check-test-goroutines: fail when any testing.T abort remains off the test
## goroutine. CI runs it on every pull request and every push to main.
check-test-goroutines:
	go run ./cmd/audit_test_goroutines/ -check

## audit-test-subtests: report case loops in Test functions that assert
## without opening a t.Run subtest (the table-driven rule), with the JSON work
## list. `go run ./cmd/audit_test_subtests/ -fix` rewrites the unambiguous
## sites; a `// sequential:` comment above a loop declares dependent steps.
audit-test-subtests:
	go run ./cmd/audit_test_subtests/ -json plan/test-subtests-backlog.json

## check-test-subtests: fail when any case loop still asserts without a
## subtest. CI gate.
check-test-subtests:
	go run ./cmd/audit_test_subtests/ -check

## audit-closed-servers: report every httptest server a function closes while
## its address is still used later in it: the server itself, a URL saved
## before the close, or a client built on one. Closing a server frees its port
## at once, and a parallel test or another test binary given the port can
## answer the request the test exists to see fail; a test that needs an
## address nothing answers uses internal/testutil/netfixture. Every package of
## the module is read with its tests, under GO_ANALYSIS_TAGS. -v also lists
## what a declaration excuses.
audit-closed-servers:
	go run ./cmd/audit_test_closed_servers/ -v

## check-closed-servers: the same rule as a gate, which also fails on a
## declaration that excuses nothing and on a file a build constraint hid that
## imports net/http/httptest. CI gate.
check-closed-servers:
	go run ./cmd/audit_test_closed_servers/ -check

## audit-md-escaping: report every value a Markdown formatter interpolates into
## a table cell, a heading, a list item, a link or a hand-written code fence
## without routing it through toolutil.EscapeMdTableCell, EscapeMdHeading,
## MdTitleLink or MarkdownFencedBlock, with the JSON work list. The two staged
## rules are named beside `all`: `card` lists every card row written by hand
## instead of through toolutil.Card, and `bool-time` every flag or timestamp
## printed without BoolEmoji or FormatTime; both report here and do not gate
## yet. `//gitlab:allow-unescaped <expression>: <reason>` in the owning
## package declares a value that needs no escaping, and
## `//gitlab:allow-raw <expression>: <reason>` one whose raw form is right.
audit-md-escaping:
	go run ./cmd/audit_md_escaping/ -v -contexts all,card,bool-time -json plan/md-escaping-backlog.json

## check-md-escaping: fail when a value still reaches a Markdown construct
## unescaped, when a one-object card row is written by hand, when a flag or a
## timestamp is printed raw, when a directive excuses nothing, or when
## internal/toolutil holds a value the audit cannot follow, since a blind spot
## there sits behind every formatter that calls it. CI gate.
check-md-escaping:
	go run ./cmd/audit_md_escaping/ -check $(MD_ESCAPING_ARGS)

## audit-action-ids: report every canonical action ID this repository publishes
## to a model that the catalog does not have: the RelatedActions of an
## ActionSpec, the first argument of every toolutil.HintAction call, and a
## dotted ID spelled inside a Usage line or an individual tool's description.
## Constants are folded by the type checker rather than matched as text, and
## the IDs are judged against the catalog built at Ultimate for a self-managed
## instance and for GitLab.com together, so the Orbit family does not read as
## dead. It reads the served prose besides, for a gitlab_* tool name, an alias
## or an ID that resolves nowhere: error hints and messages (errors.New,
## fmt.Errorf, toolutil.ErrorResult, toolutil.CancelledResult), next steps
## (WriteHints, WriteListFooter, Card.End), NextSteps and message fields,
## parameter guidance, jsonschema tag descriptions and the description entry of
## a schema written as a map (an input schema override), and Usage lines, the
## text a standalone surface tool serves on every surface included. And it
## reads the substrings the e2e suite asserts a served text carries
## (assertMentions, mentionsAny, containsAny and harness.ExpectToolError),
## loaded from ./test/e2e/gitlab/... under the e2e tag the command states
## itself. The work list lands in plan/action-ids.json.
audit-action-ids:
	go run ./cmd/audit_action_ids/ -v -json plan/action-ids.json

## check-action-ids: fail when a published ID is not a canonical catalog ID.
## The demand is the canonical ID and not mere resolvability: a registered
## alias fails too, because gitlab_execute_action resolves one and
## gitlab_find_action publishes IDs, so a cross-link spelled as an alias works
## when it is followed and can be found in no listing. A site the type checker
## could not fold fails as well, since a gate with a silent blind spot is one a
## new site can step into. So does served prose naming a tool, which is right
## for one surface of three, a declaration of that rule that excuses nothing,
## an e2e assertion quoting a tool name, which passes against a defective hint
## and breaks the day the hint is fixed, and a helper table entry that
## describes no call. CI gate.
check-action-ids:
	go run ./cmd/audit_action_ids/ -check -json ''

## audit-i18n: report every text shown to a person directly that bypasses the
## message catalog (internal/i18n, issue 1547): a render of i18n.T or i18n.New
## that does not fill exactly the placeholders of its English template through
## inline i18n.S, N, M or L calls with a literal name (I1), a key that is not a
## key constant of the catalog or a conversion to its Key type (I2), an English
## entry nothing outside the catalog files references or a key constant with
## no English template (I3), i18n.Verbatim outside a test file (I4), and an
## i18n.Text or i18n.Message literal outside the catalog or an i18n.Concat of
## nothing (I5). internal/ and cmd/ are read
## without test files. -v also lists the conversions declarations.go excuses.
audit-i18n:
	go run ./cmd/audit_i18n/ -v

## check-i18n: the same rules as a gate, which also fails on a declaration
## that excuses nothing or names an undefined category, and on a file a build
## constraint hid that imports the catalog. CI gate.
check-i18n:
	go run ./cmd/audit_i18n/ -check

## audit-dead-consts: report every unexported constant in internal/ and cmd/
## that nothing reads. staticcheck's unused judges a const group as one unit,
## so a member sharing a declaration with a member that is read is never
## looked at, and that group is the prevailing shape here: the action-ID block
## every domain keeps, and the assertion-message block beside it in the tests.
audit-dead-consts:
	go run ./cmd/audit_dead_consts/ -v

## check-dead-consts: the same rule as a gate. A constant nothing reads is
## deleted by the change that introduces it, so this fails rather than
## reporting. CI gate.
check-dead-consts:
	go run ./cmd/audit_dead_consts/ -check

## audit-sdk-context: report every call into client-go in internal/ and cmd/
## that does not hand the SDK the caller's context. client-go takes it only as
## the gl.WithContext request option and otherwise builds the request from
## context.Background(), so neither the action deadline nor an abandoned HTTP
## POST reaches it; noctx and contextcheck cannot see an option-carried context.
audit-sdk-context:
	go run ./cmd/audit_sdk_context/ -v

## check-sdk-context: the same rule as a gate. Test files, the e2e scenario
## packages included, are its stated blind spot. CI gate.
check-sdk-context:
	go run ./cmd/audit_sdk_context/ -check

## audit-tenancy: report where the tenant policy register (internal/tenancy)
## and the code disagree: a site that matches nothing, a declared alias or Arg
## that stopped carrying its register constant, a refusal or a charge that
## moved, a reason that changed, and anything shaped like a limit, in a shape
## the tripwire reads, outside a declared site or an exemption. -v also lists
## what the exemption table answered.
audit-tenancy:
	go run ./cmd/audit_tenancy/ -v

## check-tenancy: the same rules as a gate. Step 23 of make analyze and a CI
## gate.
check-tenancy:
	go run ./cmd/audit_tenancy/ -check

## tenancy-code-identity: prove that a change moved no code. It exports BASE
## with git archive (no worktree), builds ./cmd/server there and in the working
## tree with -trimpath -buildvcs=false and no build id, and compares the two
## with audit_tenancy -compare-binaries: every allocated ELF section but the
## line table must be byte-identical. BASE_TREE names a tree exported already,
## for a build host that holds no history. A change that imports
## internal/tenancy into a file moves sections by the import alone, so its base
## is the parent with the same import lines added as blank imports at the same
## positions, exported and passed as BASE_TREE. Linux only, since the
## comparison reads ELF.
tenancy-code-identity:
	@test -n "$(BASE)$(BASE_TREE)" || { echo "usage: make tenancy-code-identity BASE=<ref> (or BASE_TREE=<dir>)"; exit 2; }
	@tmp=$$(mktemp -d) && \
	base="$(BASE_TREE)"; \
	if [ -z "$$base" ]; then \
		base="$$tmp/base"; mkdir -p "$$base" && \
		git archive -o "$$tmp/base.tar" "$(BASE)" && tar -xf "$$tmp/base.tar" -C "$$base" || { rm -rf "$$tmp"; exit 1; }; \
	fi; \
	echo "building ./cmd/server at $(or $(BASE),$(BASE_TREE)) and in the working tree"; \
	( cd "$$base" && go build -trimpath -buildvcs=false -ldflags='-buildid= -s -w' -o "$$tmp/base.bin" ./cmd/server ) && \
	go build -trimpath -buildvcs=false -ldflags='-buildid= -s -w' -o "$$tmp/head.bin" ./cmd/server && \
	go run ./cmd/audit_tenancy/ -compare-binaries "$$tmp/base.bin" "$$tmp/head.bin"; \
	status=$$?; rm -rf "$$tmp"; exit $$status

## audit-gateway-chars: report served descriptions and titles violating the
## gateway-safe text policy (pure ASCII prose, no semicolons), across every
## tool surface plus prompts and resources.
audit-gateway-chars:
	go run ./cmd/audit_gateway_chars/

## check-gateway-chars: fail when anything served carries an offending
## character, so a rejection at a gateway's door cannot ship silently.
check-gateway-chars:
	go run ./cmd/audit_gateway_chars/ -check

## audit-meta-descriptions: report every parameter or value a served meta-tool
## description offers that its actions do not accept, and name every line
## describing an action's parameters that the extraction rule could not read,
## since a line outside the check is where a stale parameter hides.
audit-meta-descriptions:
	go run ./cmd/audit_meta_descriptions/ -uncovered

## check-meta-descriptions: fail when a served description and the schemas
## disagree. The description is read out of the same snapshot the regenerator
## writes from it, so regeneration can never notice one going stale: this is
## the third party.
check-meta-descriptions:
	go run ./cmd/audit_meta_descriptions/ -check

## check-readonly-graphql: fail when an action classified ReadOnly can reach a
## GraphQL mutation. --read-only and the surface served to a read_api token
## both keep such an action, so it would write exactly where a write is
## supposed to be impossible. The HTTP method cannot see this: client-go POSTs
## every GraphQL request, reads included.
check-readonly-graphql:
	go run ./cmd/audit_readonly_graphql/

## audit-readonly-graphql: same gate, listing the read-only actions that touch
## GraphQL at all rather than only what failed.
audit-readonly-graphql:
	go run ./cmd/audit_readonly_graphql/ -v

## gen-graphql-schema: re-pin the GitLab GraphQL schema from a live instance.
## Needs the network, so it is not a gate: run it when GitLab has changed and
## commit the result. Set GITLAB_URL=https://gitlab.com and GITLAB_TOKEN to a
## gitlab.com credential: GitLab answers introspection to anyone but tells only
## an authenticated caller which version it runs, the token is sent only to the
## instance GITLAB_URL names, and check-graphql-schema refuses a pin that
## records no version.
gen-graphql-schema:
	go run ./cmd/gen_graphql_schema/

## gen-graphql-release-schema: pin the GraphQL schema of the GitLab release the
## REST record (docs/development/gitlab-api-live.json) is taken from, beside the
## gitlab.com pin, so check-graphql-documents can refuse a document that
## release does not accept. It downloads the schema GitLab's own CI dumped for
## the release's tag (the graphql-schema-dump job), so it needs the network and
## no Docker; RELEASE_SCHEMA_FROM names a dump on disk instead, written by
## `bundle exec rake gitlab:graphql:schema:dump` at the tag once GitLab no
## longer keeps the job's artifact. Run it whenever gen-api-live moves the REST
## record to another release: check-graphql-schema refuses the two naming
## different releases.
RELEASE_SCHEMA_FROM ?=
gen-graphql-release-schema:
	go run ./cmd/gen_graphql_schema/ -release $(if $(RELEASE_SCHEMA_FROM),-from "$(RELEASE_SCHEMA_FROM)")

## check-graphql-schema: fail when either committed schema does not parse or
## its provenance record does not decode; when the gitlab.com pin is not of what
## this project claims to be pinned to (another instance, a truncated or
## narrower answer, no recorded version, or past the shared staleness window,
## cmd/internal/provenance); or when the release pin is not the schema of the
## release the REST record is taken from. No network, so it is a gate.
check-graphql-schema:
	go run ./cmd/gen_graphql_schema/ --check
	go run ./cmd/gen_graphql_schema/ --check -release

## gen-api-live: boot a released GitLab image, ask the loaded application what
## its REST API is, and rewrite docs/development/gitlab-api-live.json. It needs
## Docker and takes a few minutes on a cold image, about forty seconds
## afterwards; it needs no licence and no fixtures, because a licence gates
## feature_available? when a request is served and not when a class is defined.
## This is the only oracle here that is evaluated rather than parsed, which is
## what lets it see the ~600 fields GeoSiteStatus exposes through a loop where
## a scan of the same source sees 26. A re-pin onto a new release regenerates the
## documentation oracle beside it (make gen-api-doc-endpoints), which
## audit-1to1-paths refuses when it was read at another release than this record's.
gen-api-live:
	go run ./cmd/gen_api_live/

## check-api-live: fail when the committed live record is not one this build can
## read, is too small to have come from a GitLab, holds an entity that refused to
## describe itself or a condition that says nothing about what it tests, carries
## source figures its content does not give, has a fine-grained half (route
## authorization, the permission vocabulary, the public set, GraphQL
## authorization) that is missing, too small or holds a shape a reader would
## misread, has a keyset half (where each route serves a keyset page, by which
## parameter, and the probe of GitLab's paginators) that is missing, too small,
## unreadable or silent on a route declaring a cursor, or is past the shared
## staleness window (cmd/internal/provenance).
## No Docker and no network, so it is a gate.
check-api-live:
	go run ./cmd/gen_api_live/ -check

# action_grants runs cmd/gen_action_grants with the generated table,
# internal/tools/actiongrants/table_gen.go, replaced by the stand-in beside the
# command, both in the command's own build and in the program it loads: the
# command builds the catalog through internal/tools, which compiles the table
# in, so a table that no longer compiles after a change to a finegrained type
# would otherwise stop the very run that regenerates it. The overlay is a JSON
# file naming the two absolute paths, written to a temporary file and removed
# when the recipe ends.
define action_grants
	@overlay="$$(mktemp)"; trap 'rm -f "$$overlay"' EXIT; \
	printf '{"Replace":{"%s":"%s"}}\n' "$(CURDIR)/internal/tools/actiongrants/table_gen.go" \
		"$(CURDIR)/cmd/gen_action_grants/table_stub.go.txt" > "$$overlay"; \
	go run -overlay "$$overlay" ./cmd/gen_action_grants/ $(1)
endef

## gen-action-grants: derive what every catalog action sends from its handlers,
## join it to what the live GitLab record declares for a fine-grained token,
## and rewrite docs/development/action-requests.json,
## internal/tools/actiongrants/table_gen.go and the reference page,
## site/src/content/docs/reference/fine-grained-permissions.mdx with its
## Spanish twin under site/src/content/docs/es/. It writes nothing while the
## derivation has a finding.
gen-action-grants:
	$(call action_grants,)

## check-action-grants: fail when the three artifacts gen-action-grants writes
## are not what the tree and the committed record give now. Deferred on a
## stacked layer in CI like every other committed-artifact gate.
check-action-grants:
	$(call action_grants,-check)

## check-action-grants-derivation: derive and join every action and fail on any
## finding: an action not derived or declared, a route or element the record
## does not place, a permission no assignable expands to, a stale declaration
## or directive, and the five gates (an unqualified second request on a path,
## a denial naming something the record does not hold, a way of running that
## sends nothing, ways of one action needing different classic scopes, and a
## read or write classification that departs from what read_api reaches with
## no declaration saying why). It compares none of the three artifacts, so it
## is never deferred.
check-action-grants-derivation:
	$(call action_grants,-check-derivation)

## check-graphql-documents: fail when a raw GraphQL document in the source is
## one GitLab would refuse. The test transport catches the documents a test
## sends; this catches the ones no test reaches.
check-graphql-documents:
	go run ./cmd/audit_graphql_documents/

## audit-graphql-documents: same gate, listing every document checked rather
## than only the refused ones.
audit-graphql-documents:
	go run ./cmd/audit_graphql_documents/ -v

## check-graphql-shapes: fail when a struct a GraphQL response is decoded into
## cannot hold what its document selects, or declares a field the document
## never selects. Every other GraphQL gate reads the request; this one pairs
## each document with its decoder and reads the answer.
check-graphql-shapes:
	go run ./cmd/audit_graphql_shapes/

## audit-graphql-shapes: same gate, listing every pairing judged, every
## selection nothing reads and every position left unjudged.
audit-graphql-shapes:
	go run ./cmd/audit_graphql_shapes/ -v

## audit-graphql-sent: the reverse question, written to plan/graphql-sent.json.
## What does the pinned schema offer at an object one of our decoders reads that
## no document of the package decoding it ever selects? It is the sent question
## R-PATH asks of REST against GitLab's OpenAPI record, asked of GraphQL, where
## the eleven GraphQL-only domains contribute nothing to that record because
## their output types pair with no client-go struct. The claim is package-wide
## on purpose: a CE and an EE document of one package differ deliberately, and
## judging each alone reports the sibling's selections as gaps. It REPORTS and
## does not gate: a field GitLab offers and this server does not surface is a
## candidate for the surface, and this dimension has no tier and no deprecation
## oracle to sort the candidates with, both of which the report states. It reads
## ./internal/... like check-graphql-documents, so the operations client-go
## builds are outside it, and the report names that set from the request
## inventory rather than leaving it unsaid. The one sub-class that gates, a
## mutation payload whose errors no field of the decoder reads, gates in the
## shape check above and so on every run. The record is deliberately not
## committed and not freshness-gated: a schema re-pin would churn it every time.
audit-graphql-sent:
	@mkdir -p plan
	go run ./cmd/audit_graphql_shapes/ -report plan/graphql-sent.json

## check-graphql-sdk-shapes: the questions check-graphql-shapes asks (the
## decoder disagreements, and the fields the schema offers that nothing
## selects) asked of the documents client-go builds and the structs it
## decodes them into, for the client-go go.mod requires and the sends this
## server reaches (a client-go function a package under ./internal names,
## through a service interface or not, and whatever client-go runs from
## there). Unlike the report over our own documents it GATES: a decoder that
## disagrees with its document and a reached send whose document cannot be
## read before a request is made each fail unless
## cmd/audit_graphql_shapes/sdk_declarations.go answers it, a field the schema
## offers that no document of the client-go service selects fails unless
## cmd/audit_graphql_shapes/sdk_declarations_sent.go answers it, and so does a
## declaration that answers nothing. That is what keeps the one-time triage of
## issue 1022 true: a client-go bump that starts selecting a declared field
## leaves its declaration stale, and one that stops selecting a field, or a
## GraphQL re-pin that adds one, leaves a finding nothing answers, except on a
## type declared whole rather than field by field, whose new fields that declaration
## already answers. It reads the module cache, which a build of this
## repository has already filled, and needs no network.
check-graphql-sdk-shapes:
	go run ./cmd/audit_graphql_shapes/ -sdk

## audit-graphql-sdk-sent: the client-go run with every answer listed, and its
## record written to plan/graphql-sdk-sent.json: what was reached and from
## where, what was not, and every finding with the declaration answering it.
audit-graphql-sdk-sent:
	@mkdir -p plan
	go run ./cmd/audit_graphql_shapes/ -sdk -v -report plan/graphql-sdk-sent.json

## check-graphql-documents-live: judge every document against a schema fetched
## from a live instance right now rather than the pinned one, and report where
## the pin and that instance disagree about a type or field the documents touch.
## Needs the network, so it is not a CI gate; it is the only thing that reports
## a field GitLab has narrowed since the pin, which is how every defect the pin
## was built for arose. Run it beside the other live suites
## (make test-e2e-gitlab-com). GRAPHQL_LIVE_URL points it somewhere else: the
## scheduled ee-schema workflow points it at an unlicensed GitLab EE, which
## serves the whole Enterprise schema because GitLab builds the schema at boot,
## before any license is applied.
GRAPHQL_LIVE_URL ?= https://gitlab.com/api/graphql
check-graphql-documents-live:
	go run ./cmd/audit_graphql_documents/ -live "$(GRAPHQL_LIVE_URL)"

## record-request-inventory: run the unit suite with request recording on,
## leaving one shard per test process under dist/request-inventory. This is
## where the minutes go; merging them is instant, which is why recording is a
## target of its own and the two targets below consume what it leaves.
## Recording is off unless GITLAB_MCP_TEST_INVENTORY_DIR names an absolute
## directory, so an ordinary `make test` pays nothing for it.
##
## A suite that fails takes the shards with it and says so on the way out.
## That is the whole reason this is written as a shell branch rather than one
## command: `make gen-request-inventory` used to merge only after a passing
## run, so a failure rewrote nothing, `git status` stayed clean, and the tree
## read as already current when nothing had been recorded at all. A benchmark
## test that lost a port it had bound decided whether the inventory was
## regenerated, silently. Removing the shards is what makes the merge that
## follows refuse outright rather than publish half a run as the whole answer.
##
## The R-PATH gate's own unit test skips while that variable is set (see
## TestRun_TheRealTree_PassesItsOwnGate): without that, a new domain package
## could not be recorded, because the gate failed on the package the recording
## was about to add and make stopped before merging.
record-request-inventory:
	$(call RM_RF,$(REQUEST_INVENTORY_SHARDS))
	$(call MKDIR_P,$(REQUEST_INVENTORY_SHARDS))
	@GITLAB_MCP_TEST_INVENTORY_DIR="$(CURDIR)/$(REQUEST_INVENTORY_SHARDS)" go test -count=1 $(PKGS) || { \
		$(call RM_RF,$(REQUEST_INVENTORY_SHARDS)); \
		echo ''; \
		echo 'NOT RECORDED: the unit suite failed, so no request was written down.'; \
		echo 'docs/development/request-inventory.json was left exactly as it was: a clean'; \
		echo 'git status here means nothing ran, not that the inventory is current.'; \
		echo 'Fix the suite and run this again.'; \
		exit 1; \
	}

## gen-request-inventory: record the suite, then rewrite
## docs/development/request-inventory.json from what that run recorded.
gen-request-inventory: record-request-inventory
	go run ./cmd/gen_request_inventory/

## check-request-inventory: fail when the committed request inventory is not
## what the last recorded run says. It merges the shards already under
## dist/request-inventory and compares, so it costs one `go run` instead of a
## suite of its own, and refuses with a message naming the recording target
## when no run has left any. Recording stays opt-in: `make
## record-request-inventory`, or `make gen-request-inventory` to record and
## rewrite in one go.
##
## What it answers is therefore "is the committed inventory what that run
## recorded", which is a statement about this tree only when the recording was
## made from this tree; the summary line prints when the shards were written,
## so an older recording is visible rather than assumed. CI gets both halves
## for nothing: the coverage job records on the suite run it was going to do
## anyway and merges those shards afterwards.
check-request-inventory:
	go run ./cmd/gen_request_inventory/ -check

## audit-request-inventory: merge the shards of the last recorded run and name
## every package the catalog owns actions in that issued no request at all.
audit-request-inventory:
	go run ./cmd/gen_request_inventory/ -v -check

## audit-test-names: audit test function naming convention compliance.
audit-test-names:
	go run ./cmd/audit_test_names/ cmd internal test

## check-test-file-names: fail when a _test.go file is not named after a
## module it tests (export_test.go, build-constrained and external-package
## qualifiers, and test/e2e are the codified exemptions).
check-test-file-names:
	go run ./cmd/audit_test_names/ -check-files cmd internal test

## check-supply-chain: fail when a release-configuration invariant nothing else
## in the pipeline can see has broken — an unpinned uses:, a credentialed job
## that runs code resolved at run time, a dropped Dependabot cooldown, a stale
## security policy, an installer that stopped verifying the signature, a
## VERSION whose release has no written summary in .github/release-notes, or a
## dependency scan (check-dependency-vulns) the required check of ci.yml no
## longer counts, an unpinned scanner, or an osv-scanner.toml entry outside
## the terms SECURITY.md sets.
check-supply-chain:
	go run ./cmd/audit_supply_chain/

## check-em-dash: fail when a line this branch adds carries an em dash
## (U+2014). Scoped to the added lines of EM_DASH_BASE...HEAD, net over the
## branch rather than per commit, so a branch that adds one and cleans it up at
## its tip passes. It has to be scoped: the tree already carries thousands in
## prose written before the rule, so a whole-tree check would be red on its
## first run and switched off on its second. It reads git and nothing else, so
## it is a gate; run it before pushing. EM_DASH_BASE defaults to origin/main.
## The gate is cmd/audit_pr_text, which holds the description half below too.
check-em-dash:
	go run ./cmd/audit_pr_text/ diff $(EM_DASH_BASE)

## check-pr-description: fail when the pull request title or body carries an em
## dash, a command that makes GitHub skip workflows or a reference GitLab
## resolves to another project's or group's item (issue 1477), or when the body
## carries a skip-checks trailer or a block a review bot injected. This is the
## half no later commit can fix: a squash merge copies the description into
## main's history, a skip command there turns off CI on main and the release of
## any tag put on that commit, and the GitLab mirror notes a reference there on
## the item it names for good. A branch with no pull request open passes,
## having no description to land; PR_NUMBER names one explicitly. Without gh it
## fails and says so, because a check that cannot read what it judges must not
## report that it judged it. PR_TITLE_FILE and PR_BODY_FILE judge text from
## disk instead, which needs no gh and is how the gate is rehearsed.
check-pr-description:
	go run ./cmd/audit_pr_text/ description

## check-dco: fail when a commit of DCO_BASE..DCO_HEAD (origin/main..HEAD by
## default) carries no Signed-off-by trailer naming its author, the sign-off
## that certifies the Developer Certificate of Origin for it. A merge commit
## that brings no change of its own is not judged, and a declared bot's commits
## (cmd/audit_dco/bots.go) are exempt in a pull request that bot opened, which
## DCO_OPENED_BY names by its GitHub login. It reads git and nothing else, so run it before pushing; CI's dco job
## runs it on every pull request with the event's base and head, and
## DCO_FLAGS=-annotate.
DCO_BASE ?= origin/main
DCO_HEAD ?= HEAD
check-dco:
	go run ./cmd/audit_dco/ -base "$(DCO_BASE)" -head "$(DCO_HEAD)" -opened-by "$(DCO_OPENED_BY)" $(DCO_FLAGS)

## check-file-headers: fail when a source file of the repository (the files
## git holds and the untracked ones it would add) does not open with the
## copyright and license header cmd/internal/fileheader spells, or carries
## another copyright or license notice. It reads git's file list, so it runs in
## a checkout. Step 34 of make analyze and a CI gate.
check-file-headers:
	go run ./cmd/audit_file_headers/

## fix-file-headers: write the header into every source file that does not
## open with it and carries no other notice, after a shebang, an encoding
## declaration, a Dockerfile parser directive or a CSS @charset rule, and
## inside an Astro component's frontmatter. A file with another notice is left
## for a hand edit.
fix-file-headers:
	go run ./cmd/audit_file_headers/ -fix

## check-plan-untracked: fail when git tracks a file under plan/, a working area
## .gitignore excludes, so a file there is tracked only if it was force-added.
## It reads the index, so a file untracked with git rm --cached passes before
## the commit that removes it. No network, no Go build.
check-plan-untracked:
	@tracked="$$(git ls-files -- plan)"; \
	if [ -n "$$tracked" ]; then \
		echo "plan/ is an untracked working area; untrack these with git rm --cached:"; \
		echo "$$tracked" | sed 's/^/  /'; \
		exit 1; \
	fi; \
	echo "OK: nothing under plan/ is tracked."

## audit-godocs: generate a Godoc compliance report, including test functions.
audit-godocs:
	$(call MKDIR_P,$(ANALYSIS_DIR))
	go run ./cmd/godoc_tool/ audit --include-tests --format=markdown --output="$(ANALYSIS_DIR)/godoc.md"
	@echo "Godoc report saved to $(ANALYSIS_DIR)/godoc.md"

## audit-godocs-check: the audit check-godocs gates, with Test, Benchmark, Fuzz
## and Example functions included, failing while any finding remains. It is not
## a gate: test functions whose comment is missing or does not open with their
## name are still found across the tree.
audit-godocs-check:
	go run ./cmd/godoc_tool/ audit --include-tests --fail-on-findings

## check-godocs: fail when a package comment is missing, malformed, doubled or
## outside doc.go; when an exported function, method or type, or a const or var
## declaring one exported name, has no comment opening with its name (for the
## const or var, on its group or, in a group without one, on its spec); or when
## a const or var group declaring several exported names has no comment on the
## group and leaves a name without one of its own that opens with it. A trailing
## line comment never counts. It is the godoc audit without test functions, and
## it is a gate of its own because golangci-lint cannot ask the question: the
## `comments` exclusion preset silences revive's exported and package-comments
## rules and staticcheck's ST1000 and ST1020 to ST1022. It parses and never
## compiles, so it costs seconds. CI gate, and step 33 of make analyze.
check-godocs:
	go run ./cmd/godoc_tool/ audit --fail-on-findings

## fix-godocs: generate and insert godoc-compliant comments for the given paths.
## Use --dry-run to preview changes without writing (e.g. make fix-godocs ARGS="--dry-run internal/tools/").
fix-godocs:
	go run ./cmd/godoc_tool/ fix $(ARGS)

## docs-local-go: serve local pkg.go.dev-style documentation at http://127.0.0.1:6060.
docs-local-go:
	@if [ ! -x "$(PKGSITE)" ]; then echo "pkgsite not found. Install with: go install golang.org/x/pkgsite/cmd/pkgsite@latest"; exit 1; fi
	@echo "Serving local Go documentation at http://127.0.0.1:6060"
	"$(PKGSITE)" -http=127.0.0.1:6060

# ─── Formatting ──────────────────────────────────────────────────────────────
# Formatting is delegated to golangci-lint formatters configured in .golangci.yml.

## fmt: apply configured Go formatters.
fmt:
	golangci-lint fmt

## release: build release binaries using GoReleaser (local snapshot, no publish).
## Produces flat binaries in dist/ matching GitHub Release asset names, beside
## the THIRD_PARTY_NOTICES GoReleaser's sboms step generates from them.
release:
	goreleaser release --snapshot --clean
	@# Flatten dist/: move binaries out of subdirs, remove GoReleaser metadata
	@for dir in dist/gitlab-mcp-server_*; do \
		if [ -d "$$dir" ]; then \
			os_arch=$$(echo "$$dir" | sed -E 's|dist/gitlab-mcp-server_([^_]+)_([^_]+).*|\1-\2|'); \
			src=$$(find "$$dir" -maxdepth 1 -type f | head -1); \
			if echo "$$src" | grep -q '\.exe$$'; then \
				mv "$$src" "dist/gitlab-mcp-server-$${os_arch}.exe"; \
			else \
				mv "$$src" "dist/gitlab-mcp-server-$${os_arch}"; \
			fi; \
			rm -rf "$$dir"; \
		fi; \
	done
	@rm -f dist/artifacts.json dist/config.yaml dist/metadata.json
	@go run ./cmd/release_checks/ elf-interp dist/gitlab-mcp-server-linux-amd64 dist/gitlab-mcp-server-linux-arm64
	@echo "dist/ contents:" && ls -1 dist/

## release-check: validate .goreleaser.yml configuration
release-check:
	goreleaser check

checksum:
	@cat dist/checksums.txt

# ─── MCP Inspector ───────────────────────────────────────────────────────────
# Requires: Node.js >= 22, npx, .env with GITLAB_TOKEN. Add GITLAB_URL for self-managed instances.
# Compiles a fresh binary to /tmp, launches the Inspector, and cleans up on exit.

INSPECTOR_BIN := /tmp/$(BINARY_NAME)-inspector$(BINARY_EXT)

## inspector: compile the server and launch MCP Inspector UI via stdio.
## Reads credentials from .env. The temporary binary is removed on exit.
inspector:
	@if [ ! -f .env ]; then echo "ERROR: .env file not found. Create it with GITLAB_TOKEN; add GITLAB_URL for self-managed instances."; exit 1; fi
	@echo "Compiling $(BINARY_NAME) to $(INSPECTOR_BIN)..."
	@go build -ldflags="$(LDFLAGS)" -o "$(INSPECTOR_BIN)" $(CMD_PATH)
	@echo "Starting MCP Inspector (stdio) — press Ctrl+C to stop..."
	@trap 'rm -f "$(INSPECTOR_BIN)"; echo "Cleaned up $(INSPECTOR_BIN)"' EXIT INT TERM && \
		set -a && . ./.env && set +a && \
		ALLOWED_ORIGINS="http://localhost:6274,http://127.0.0.1:6274,http://0.0.0.0:6274" \
		HOST=0.0.0.0 \
		npx -y @modelcontextprotocol/inspector \
			-e GITLAB_URL="$${GITLAB_URL:-https://gitlab.com}" \
			-e GITLAB_TOKEN="$$GITLAB_TOKEN" \
			-e GITLAB_MCP_SKIP_TLS_VERIFY="$${GITLAB_MCP_SKIP_TLS_VERIFY:-false}" \
			-e GITLAB_MCP_TOOL_SURFACE=meta \
			-- "$(INSPECTOR_BIN)"

## inspector-stop: stop any running MCP Inspector and server processes.
inspector-stop:
	@pkill -f "@modelcontextprotocol/inspector" 2>/dev/null || true
	@pkill -f "node.*inspector" 2>/dev/null || true
	@rm -f "$(INSPECTOR_BIN)"
	@echo "MCP Inspector stopped."

clean:
	$(call RM_RF,dist)
	$(call RM_F,coverage.out)
	$(call RM_F,coverage.html)

## help: show available targets
help:
	@echo "Available targets:"
	@grep -E '^## ' Makefile | sed 's/## /  /'