beads/Makefile
mtccressall 1f7a5f1eaf
fix(ci): resolve gofmt from go.mod's toolchain, not PATH (be-gx8) (#6294)
* fix(ci): resolve gofmt from go.mod's toolchain, not PATH (be-gx8)

gofmt's output is not stable across Go releases, so whichever binary runs
decides the formatting verdict. Three sites reached for a bare `gofmt` on
PATH -- scripts/ci/fmt-check.sh, the Makefile fmt target, and
.githooks/pre-commit -- and PATH belongs to whatever Go is installed
locally. CI has no such freedom: actions/setup-go installs exactly the
go.mod version via go-version-file.

GOTOOLCHAIN=auto does not correct for this, which is why `go env GOROOT`
or `go fmt` would not have been a fix either. The toolchain switch only
ever moves UP to satisfy the go directive, never down, so a host running
a newer Go keeps formatting with the newer gofmt. Measured against
go.mod's go 1.26.5 on a go1.27.0 host: 1.27 flags three
role_fixture_kit_test.go files that 1.26.5 calls clean, and no branch
touches them.

The failure ran in the dangerous direction. The required lint gate went
red on untouched code, which reads as "main's lint is broken" and poisons
the pre-existing-on-main judgement every PR author uses to decide whether
a red gate is theirs. Its own advice -- "Run 'make fmt' to fix
formatting" -- then rewrote those files into a form CI's pinned gofmt
rejects. The pre-commit hook did that same rewrite and re-staged it
silently on every Go commit, with nobody choosing it.

Route all three through one resolver rather than patch three sites, so
the next gofmt call site cannot drift. scripts/ci/gofmt-bin.sh names
go.mod's toolchain explicitly and reads GOROOT from it, short-circuiting
to a plain `go env GOROOT` when the host go already is the pinned version
(the CI case, so nothing is fetched where nothing needs fetching). A
fallback to the PATH binary stays available but warns loudly on stderr:
silently falling back is indistinguishable from resolving correctly, and
reintroduces exactly this skew. fmt-check.sh now prints the gofmt version
it used, so a skew presents as a skew instead of as a repo defect.

The new tests pin the resolution, not the reporting, because the
resolution is where the bug lived: every output assertion around the bare
gofmt stayed green. Reverting gofmt-bin.sh to `command -v gofmt` fails
all three. The pre-existing fmt-check tests move their shim from PATH to
GOFMT -- a PATH shim is now correctly ignored, so leaving them there
would have made them grade the real toolchain instead of the case they
name.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PoN7f9TMmGTCLRpDPzSH4y

Executed-By: beadsrig/polecats/nux

* fix(ci): resolve gofmt from go.mod's toolchain directive, and declare it to Bazel

Maintainer review fixes for #6294 (adoption iterations 1 and 2, one squashed
commit). Sections 1-6 address all six findings in the attempt-1 synthesis; the
two majors are the substantive ones. Sections 7-8 address the two minors the
attempt-2 synthesis left (it decided approve, 1000/1000, no blocker or major).

1. Contract & Interface Fidelity (major, the scorecard's only Required Change).
   gofmt-bin.sh read the `go` directive (1.26.5) while go.mod also carries
   `toolchain go1.26.7`, and toolchain-first is the repo's own declared
   precedence -- Makefile:85-90 exports GOTOOLCHAIN from the same pair for
   every make target, and scripts/bazel_policy_test.go's goModToolchainVersion
   is the same rule in Go. The consequence was not cosmetic: `go env GOVERSION`
   at the repo root is go1.26.7 (the directive auto-switches), so the fast-path
   test compared go1.26.7 against go1.26.5 and was false by construction on
   every route, sending each required fmt-check run down the elif arm to fetch
   a second, older toolchain. Parse `toolchain go<version>` first, fall back to
   the `go` directive. Measured after the change: pinned=1.26.7, the fast path
   fires (`go env GOVERSION` then `go env GOROOT`, no GOTOOLCHAIN= prefix and
   nothing fetched), and `make fmt-check` now reports
   `Using gofmt go1.26.7 (.../toolchain@v0.0.1-go1.26.7.../bin/gofmt)`.
   .githooks/pre-commit:24's `go`-directive read is deliberately left alone --
   its comment explains it is a golangci-lint pin for a different reason.

   gofmtbin_test.go's helper now implements the same precedence, and
   TestGofmtBinMatchesGoModDirective is renamed TestGofmtBinMatchesGoModToolchain
   so the pinned contract is legible from the test name.

   Deviation from the prescription, recorded deliberately: the review asked for
   a helper "name" change as well. The name goModToolchainVersion already
   described toolchain-first semantics; it was the implementation that did not.
   Correcting the semantics is what removes the collision with
   scripts/bazel_policy_test.go's identically-named, opposite-behaving helper,
   so the name is kept and the doc comment now states the precedence and cites
   both in-repo sources of it.

2. Release Safety (major). fmt-check.sh now execs a sibling script
   unconditionally under `set -euo pipefail`. Live origin/main gives
   //scripts/prlintmake a `data` list containing exactly ci/fmt-check.sh, so on
   merge all three TestFmtCheck* cases would have died at rc 127 in the Bazel
   runfiles sandbox -- the GOFMT short-circuit cannot rescue them because it
   lives inside the missing script. Export ci/gofmt-bin.sh to
   //scripts/prlintmake and put it in the target's `data`, and add
   gofmtbin_test.go to `srcs` (it carries no build tag, so its omission was not
   explained away).

   Only ci/gofmt-bin.sh is exported here, not ci/fmt-check.sh: main already
   exports that one for this same package, and a second exports_files call
   naming the same file in one package is an error. This base predates both of
   main's additions, which is also why editing the three-line go_test rule
   conflicts with main's independent edit of it. Verified by materialising the
   merge: every other file auto-merges and the resolution is the union of the
   two attribute sets (srcs = both test files; data = both scripts plus
   //:go.mod per section 7; keep main's deps on //internal/testutil/bazeltest).
   That deps edge is load-bearing at main even though it was stale at this base:
   main rewrote sourceRepoRoot to bazeltest.CallerDir, so the union must keep it.

3. Test Evidence Quality (minor). environment() starts from os.Environ(), so
   deleting GOFMT from the override map did not unset it. Export it empty
   instead -- gofmt-bin.sh reads `[[ -n "${GOFMT:-}" ]]`, so empty already is
   its "not set" case, and the override test stays distinguishable by setting a
   non-empty value.

4. Architectural Consistency (minor). "Every gofmt invocation in this repo goes
   through here" was false at authoring: cmd/bd/preflight.go's doctor check is
   a fourth front door on bare PATH gofmt. Scope the claim to the repo's
   shell-side call sites (re-censused: fmt-check.sh, the Makefile fmt target,
   and .githooks/pre-commit are the complete set; the two workflow "Check
   gofmt" steps and scripts/ci/pr-lint.sh reach them through make fmt-check),
   and name the in-binary exception with the reason it is one -- bd runs
   against whatever project the user points it at, so it has no scripts/ci/ to
   call. preflight.go is byte-identical at base, at HEAD and at origin/main, so
   nothing in this PR widens it; converting it is a separate change.

5. Test Evidence Quality (minor). describe_gofmt's version-bearing arm had zero
   coverage -- all three existing cases inject a bash script, for which
   `go version` errors and only the bare-path arm can run. Add
   TestFmtCheckReportsGofmtVersion against a real Go-built no-op binary, which
   is the only shim shape `go version` can report on.

6. Error Handling & Resilience (nit). Warn (without refusing) when GOFMT names
   something non-executable, so a typo is reported by the resolver that
   accepted it rather than as a "not found" from whichever call site ran it;
   and guard the fields index in the resolver test.

Mutation proofs, each red isolated to the intended test with the other six
green (7/7 pass unmutated, `go test ./scripts/prlintmake/`):

  - revert the toolchain-first parse -> resolver returns the 1.26.5 gofmt and
    TestGofmtBinMatchesGoModToolchain alone fails.
  - delete describe_gofmt's `if command -v go` block (codex's own mutation,
    previously all-green) -> TestFmtCheckReportsGofmtVersion alone fails, the
    three incumbents stay green. That asymmetry is both the coverage-hole proof
    and the proof the new case is not a duplicate.
  - ambient GOFMT, two values x two arms: with the fix both /nonexistent and a
    correctly-pinned gofmt leave all three resolver tests passing; with the
    delete restored, /nonexistent fails TestGofmtBinMatchesGoModToolchain with a
    message blaming the script, and a correctly-pinned value turns all three
    green vacuously without the resolver ever running.

7. Release Safety (minor, iteration 2). The target now reads go.mod at run
   time -- the resolver opens "$REPO_ROOT/go.mod" and the test helper opens
   filepath.Join(sourceRepoRoot(), "go.mod"), where the base test read it not at
   all -- but go.mod appeared in no `data` list, so the rule declared strictly
   less than it uses. Add //:go.mod to //scripts/prlintmake's `data`. No new
   export is needed: //:BUILD.bazel already exports go.mod publicly, and
   //internal/storage/dolt and //internal/testutil/integration already consume
   it as "//:go.mod" in `data`, so this is the sanctioned shape rather than a
   new one.

8. Contract & Interface Fidelity (minor, iteration 2). `toolchain default` is a
   legal go.mod directive value, and the parse matched on the field name alone,
   so sub(/^go/, "", "default") no-opped and left pinned=default. Because that
   is non-empty, neither the `go`-directive fallback nor the "no toolchain or go
   directive" guard could fire, and the script degraded to the bare PATH gofmt
   it exists to eliminate while a usable `go 1.26.5` sat two lines above. The
   mangled "godefault" in the warning was the tell. Require the literal `go`
   prefix, which is exactly what the repo's two other readers of this pair
   already do (Makefile:85's `s/^toolchain go//p` and bazel_policy_test.go's
   `^toolchain\s+go(\S+)\s*$`), so `default` falls through to the `go`
   directive.

   The same guard is added to gofmtbin_test.go's goModToolchainVersion, and that
   is not redundant: strings.TrimPrefix("default", "go") returns "default"
   unchanged and withPatchComponent leaves a dotless string alone, so the helper
   mirrored the bug exactly and the test could never have caught it. Guarding
   only the script would have left the test agreeing with a buggy resolver.

   Measured on a synthetic tree, five arms (the script resolves REPO_ROOT from
   its own location, so each arm is a copied script beside a written go.mod):

     - `toolchain default` + `go 1.26.5`: before, /usr/local/go/bin/gofmt with
       the "godefault" warning; after, the go1.26.5 toolchain gofmt -- i.e. the
       `go` directive, identical to the arm where no toolchain line exists.
     - `toolchain go1.26.7`: unchanged before and after (no regression).
     - `go 1.26.5` alone: unchanged before and after (no regression).
     - `toolchain default` with no `go` directive: now reaches the previously
       bypassed "no toolchain or go directive" guard and falls back loudly, with
       the correct message rather than the mangled one.
     - `toolchain default` written before `go`: also resolves 1.26.5, so the
       fallthrough is order-independent.

   The Go helper's parse was checked over the same six inputs and now agrees
   with the shell on every one.

   No regression test is added for this case. Doing so would need a new
   synthetic-go.mod fixture -- every existing case runs the real script against
   the real repo go.mod through sourceRepoRoot() -- which is a new test
   instrument rather than the prescribed remedy, on a finding whose gate impact
   is none (go.mod carries `toolchain go1.26.7`, so nothing can fire today).

Iteration 2 validation: go test ./scripts/prlintmake/ -count=1 -v 7/7 PASS
(same roster as iteration 1, no test added or removed), go vet rc 0,
go test ./scripts/ -run 'Bazel|BUILD' 11/11 PASS (the BUILD-policy gate, run
because this touches a BUILD file), python3 tools/bazel/go_srcs.py --check
rc 0 (`srcs` is unchanged; only `data` moved), make fmt-check rc 0 still
reporting go1.26.7, shellcheck clean, git diff --check clean.

Also run: go vet ./scripts/prlintmake, go test ./scripts/... (all packages ok),
make fmt-check (rc 0), python3 tools/bazel/go_srcs.py --check (rc 0),
shellcheck on both changed scripts.

---------

Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
2026-09-30 18:38:46 -07:00

488 lines
22 KiB
Makefile

# Makefile for beads project
# Native Windows GNU Make needs Git for Windows' bash for the POSIX shell
# syntax used throughout this Makefile. MSYS2 and Cygwin Make already provide
# POSIX shell semantics, despite inheriting OS=Windows_NT, so leave them alone.
ifeq ($(OS),Windows_NT)
ifneq ($(filter Windows32 mingw32 %-mingw32,$(MAKE_HOST)),)
override BASH_ENV :=
unexport BASH_ENV
unexport GIT_EXEC_PATH
unexport BASHOPTS
unexport SHELLOPTS
SHELL := cmd.exe
.SHELLFLAGS := /d /c
GIT_WINDOWS_EXEC_PATH := $(strip $(shell set "GIT_EXEC_PATH=" && git.exe --exec-path))
ifeq ($(GIT_WINDOWS_EXEC_PATH),)
$(error Git for Windows is required to run this Makefile)
endif
GIT_WINDOWS_ROOT := $(strip $(shell cd /d "$(GIT_WINDOWS_EXEC_PATH)/../../.." && cd))
ifeq ($(GIT_WINDOWS_ROOT),)
$(error Could not resolve the Git for Windows installation from $(GIT_WINDOWS_EXEC_PATH))
endif
GIT_WINDOWS_BASH := $(GIT_WINDOWS_ROOT)/bin/bash.exe
GIT_WINDOWS_SED := $(GIT_WINDOWS_ROOT)/usr/bin/sed.exe
GIT_WINDOWS_ENV := $(GIT_WINDOWS_ROOT)/usr/bin/env.exe
ifneq ($(strip $(shell if exist "$(GIT_WINDOWS_BASH)" echo ready)),ready)
$(error Could not find Git for Windows' bash at $(GIT_WINDOWS_BASH))
endif
ifneq ($(strip $(shell if exist "$(GIT_WINDOWS_SED)" echo ready)),ready)
$(error Could not find Git for Windows' sed at $(GIT_WINDOWS_SED))
endif
ifneq ($(strip $(shell if exist "$(GIT_WINDOWS_ENV)" echo ready)),ready)
$(error Could not find Git for Windows' env at $(GIT_WINDOWS_ENV))
endif
SHELL := $(GIT_WINDOWS_BASH)
.SHELLFLAGS := -c
ifneq ($(strip $(shell printf '%s' ready;)),ready)
$(error Could not start Git for Windows' bash at $(SHELL))
endif
# GNU Make may launch simple commands and shebang interpreters directly instead
# of through SHELL, so expose Git's POSIX tools to those process lookups too.
export PATH := $(GIT_WINDOWS_ROOT)/usr/bin;$(PATH)
endif
endif
.PHONY: all build doctor-build test test-icu-path test-full-cgo test-regression test-upgrade test-cross-version test-migration corpus-regen githooks-regen bench bench-quick clean clean-test-tmp install install-force help check-up-to-date fmt fmt-check check-testing-short
.PHONY: ci-pr-core ci-pr-policy ci-pr-lint ci-complexity ci-complexity-diff ci-complexity-check ci-package-mcp ci-package-npm
.PHONY: api-gen api-check
.PHONY: bazel-sync bazel-sync-check
# Default target
all: build
BUILD_DIR := .
BD_BUILD_OUTPUT := $(BUILD_DIR)/bd$(if $(filter Windows_NT,$(OS)),.exe)
GIT_BUILD := $(shell git rev-parse --short HEAD)
ifeq ($(OS),Windows_NT)
INSTALL_DIR := $(USERPROFILE)/.local/bin
WINDOWS_MINGW_BIN ?= /c/ProgramData/mingw64/mingw64/bin
WINDOWS_MINGW_GCC := $(WINDOWS_MINGW_BIN)/gcc.exe
WINDOWS_CGO_BINS ?= $(WINDOWS_MINGW_BIN) /c/msys64/clangarm64/bin /c/msys64/ucrt64/bin /c/msys64/mingw64/bin /c/msys64/clang64/bin
else
INSTALL_DIR := $(HOME)/.local/bin
endif
# Dolt backend requires CGO for embedded database support.
# Without CGO, builds will fail with "dolt backend requires CGO".
#
# Windows notes:
# - ICU is NOT required. go-icu-regex has a pure-Go fallback (regex_windows.go)
# and gms_pure_go tag tells go-mysql-server to use pure-Go regex too.
# - CGO_ENABLED=1 needs a GCC-compatible Windows CGO compiler but does NOT
# need ICU. Supported local toolchains include MinGW-w64/MSYS2 gcc and
# MSYS2 clang/LLVM targeting windows-gnu.
export CGO_ENABLED := 1
# When go.mod requires a newer Go version than the locally installed one,
# GOTOOLCHAIN=auto downloads the right compiler but coverage instrumentation
# may still use the local toolchain's compile tool, causing version mismatch.
# Force one exact version so all tools match.
#
# The `toolchain` directive wins over the `go` directive when present: `go` is
# the floor we promise importers, `toolchain` is what we actually build with,
# and reading `go` here would silently downgrade every make target below the
# toolchain the release binaries are built with.
GO_VERSION := $(shell sed -n 's/^toolchain go//p' go.mod)
ifeq ($(GO_VERSION),)
GO_VERSION := $(shell sed -n 's/^go //p' go.mod)
endif
ifneq ($(GO_VERSION),)
export GOTOOLCHAIN := go$(GO_VERSION)
endif
# gms_pure_go tells go-mysql-server to use Go's stdlib regex instead of
# ICU-backed go-icu-regex. This eliminates the ICU shared-library runtime
# dependency, making release binaries portable across Linux distros.
# ICU flags are only needed for scripts/test-icu-path.sh (which exercises the
# opt-in ICU regex path).
BUILD_TAGS := gms_pure_go
REGRESSION_TIMEOUT ?= 20m
# Build the bd binary
build:
@echo "Building bd..."
ifeq ($(OS),Windows_NT)
@if [ -n "$$CC" ]; then \
echo "Using CC=$$CC"; \
go build -tags "$(BUILD_TAGS)" -ldflags="-X main.Build=$(GIT_BUILD)" -o "$(BD_BUILD_OUTPUT)" ./cmd/bd; \
elif command -v gcc >/dev/null 2>&1; then \
CC=gcc go build -tags "$(BUILD_TAGS)" -ldflags="-X main.Build=$(GIT_BUILD)" -o "$(BD_BUILD_OUTPUT)" ./cmd/bd; \
elif command -v clang >/dev/null 2>&1 && clang -dumpmachine 2>/dev/null | grep -qi 'windows.*gnu'; then \
CC=clang go build -tags "$(BUILD_TAGS)" -ldflags="-X main.Build=$(GIT_BUILD)" -o "$(BD_BUILD_OUTPUT)" ./cmd/bd; \
else \
for bin in $(WINDOWS_CGO_BINS); do \
if [ -x "$$bin/gcc.exe" ]; then \
echo "Using Windows CGO gcc from $$bin"; \
PATH="$$bin:$$PATH" CC=gcc go build -tags "$(BUILD_TAGS)" -ldflags="-X main.Build=$(GIT_BUILD)" -o "$(BD_BUILD_OUTPUT)" ./cmd/bd; \
exit $$?; \
fi; \
if [ -x "$$bin/clang.exe" ] && "$$bin/clang.exe" -dumpmachine 2>/dev/null | grep -qi 'windows.*gnu'; then \
echo "Using Windows CGO clang from $$bin"; \
PATH="$$bin:$$PATH" CC=clang go build -tags "$(BUILD_TAGS)" -ldflags="-X main.Build=$(GIT_BUILD)" -o "$(BD_BUILD_OUTPUT)" ./cmd/bd; \
exit $$?; \
fi; \
done; \
echo "ERROR: Windows CGO builds require a GCC-compatible compiler." >&2; \
echo " Install MinGW-w64/MSYS2 gcc or MSYS2 clang/LLVM targeting windows-gnu." >&2; \
echo " Put it on PATH, set CC, or set WINDOWS_CGO_BINS=/path/to/toolchain/bin." >&2; \
exit 1; \
fi
else
go build -tags "$(BUILD_TAGS)" -ldflags="-X main.Build=$(GIT_BUILD)" -o "$(BD_BUILD_OUTPUT)" ./cmd/bd
ifeq ($(shell uname),Darwin)
@codesign -s - -f "$(BD_BUILD_OUTPUT)" 2>/dev/null || true
@echo "Signed bd for macOS"
endif
endif
# Diagnose the local build environment for the gms_pure_go/CGO build trap
# (mybd-t7mk.1). A bare `CGO_ENABLED=1 go build ./cmd/bd` without
# -tags=gms_pure_go fails with a C-linker error from go-icu-regex
# (unicode/uregex.h: No such file or directory) because go-mysql-server
# links ICU by default under cgo; CGO_ENABLED=0 avoids that but can't open
# embedded Dolt at runtime. See engdocs/ICU-POLICY.md.
doctor-build:
@echo "Build environment diagnostic (doctor-build):"
@GOFLAGS_VAL="$$(go env GOFLAGS)"; \
CGO_VAL="$$(go env CGO_ENABLED)"; \
CC_VAL="$$(go env CC)"; \
echo " GOFLAGS: $${GOFLAGS_VAL:-<empty>}"; \
echo " CGO_ENABLED: $$CGO_VAL"; \
echo " CC: $$CC_VAL"; \
if command -v "$$CC_VAL" >/dev/null 2>&1; then \
echo " CC on PATH: yes ($$(command -v "$$CC_VAL"))"; \
else \
echo " CC on PATH: NO - $$CC_VAL not found"; \
fi; \
echo ""; \
EFFECTIVE_TAGS="$$(printf '%s\n' "$$GOFLAGS_VAL" | tr ' ' '\n' | sed -n 's/^-tags=//p' | tail -n 1)"; \
case ",$$EFFECTIVE_TAGS," in \
*,gms_pure_go,*) \
echo "PASS: GOFLAGS carries -tags=gms_pure_go; bare 'go build'/'go test' are safe." ;; \
*) \
echo "WARN: GOFLAGS is missing -tags=gms_pure_go."; \
echo " A bare 'CGO_ENABLED=1 go build ./cmd/bd' will fail with a C-linker error"; \
echo " (unicode/uregex.h: No such file or directory) from go-icu-regex, because"; \
echo " go-mysql-server links ICU by default under cgo."; \
echo ""; \
echo " Remedy - persist the tag so bare go commands pick it up:"; \
echo " go env -w GOFLAGS=-tags=gms_pure_go"; \
echo " Or build explicitly this once (CGO_ENABLED=1 is required for"; \
echo " embedded Dolt at runtime; CGO_ENABLED=0 cannot open it):"; \
echo " CGO_ENABLED=1 go build -tags gms_pure_go ./cmd/bd" ;; \
esac
# Run all tests (skips known broken tests listed in .test-skip)
test:
@echo "Running tests..."
@TEST_COVER=1 ./scripts/test.sh
# Run the opt-in ICU regex path test suite (no skip list).
# This is a local developer workflow for intentionally exercising the leftover
# ICU path; it is not part of normal validation.
test-icu-path:
@echo "Running opt-in ICU regex path tests..."
@./scripts/test-icu-path.sh ./...
# Deprecated compatibility alias. Keep forwarding so old local notes still work,
# but make the opt-in ICU nature explicit.
test-full-cgo:
@echo "WARNING: make test-full-cgo is deprecated; use make test-icu-path for the explicit ICU-only path." >&2
@$(MAKE) test-icu-path
ci-pr-core:
@./scripts/ci/pr-core.sh
ci-pr-policy:
@./scripts/ci/pr-policy.sh
ci-pr-lint:
@./scripts/ci/pr-lint.sh
# Opt-in architecture experiment. Install gocyclo v0.6.0 first;
# report is advisory while check exercises the local baseline guard.
ci-complexity:
@./scripts/ci/complexity.sh report
ci-complexity-diff:
@./scripts/ci/complexity.sh diff
ci-complexity-check:
@./scripts/ci/complexity.sh check
# The generated half of the wire contract. The document is hand-written and is
# the source of truth; this file is its output.
API_GEN_FILE := internal/httpapi/apigen/types.gen.go
# Regenerate the wire types from internal/httpapi/spec/openapi.v0.yaml.
api-gen:
go generate -tags "$(BUILD_TAGS)" ./internal/httpapi/apigen
# Two-part spec drift gate: regenerate and fail if regeneration CHANGED
# anything, then run the spec tests. Runs in the PR workflow's policy job
# (scripts/ci/pr-policy.sh), on every pull request, never only on
# push-to-main.
#
# The drift question is "do the checked-out types already match the checked-out
# spec", so the comparison is before-vs-after regeneration rather than
# working-tree-vs-HEAD. A `git status` check answers a different question: a
# contributor mid-edit has a dirty spec AND a dirty generated file and is
# perfectly in sync, and calling that drift sends them to run a command that
# changes nothing.
#
# The test leg runs the whole package with no -run filter on purpose. A
# hand-maintained list of test names degrades silently: rename one and `go test
# -run` matches nothing, prints "no tests to run" and exits 0, so the step still
# reports success while enforcing nothing.
api-check:
@pre=$$(git hash-object $(API_GEN_FILE)) || exit 1; \
$(MAKE) --no-print-directory api-gen || exit 1; \
post=$$(git hash-object $(API_GEN_FILE)) || exit 1; \
if [ "$$pre" != "$$post" ]; then \
git --no-pager diff -- $(API_GEN_FILE); \
echo "openapi drift: $(API_GEN_FILE) is stale for the current spec (regenerating it changed it)."; \
echo "run 'make api-gen' and commit the result."; \
exit 1; \
fi
go test -tags "$(BUILD_TAGS)" ./internal/httpapi/... -count=1
ci-package-mcp:
@./scripts/ci/package-mcp.sh
ci-package-npm:
@./scripts/ci/package-npm.sh
# Run differential regression tests (baseline v0.49.6 vs current worktree).
# Downloads baseline binary on first run; cached in ~/Library/Caches/beads-regression/.
# Override baseline: BD_REGRESSION_BASELINE_BIN=/path/to/bd make test-regression
test-regression:
@echo "Running regression tests (baseline vs candidate)..."
go test -tags=regression,$(BUILD_TAGS) -timeout=$(REGRESSION_TIMEOUT) -v ./tests/regression/...
# Run upgrade smoke tests (release stability gate).
# Tests that upgrading from previous release preserves data, role, and mode.
# Override version: ./scripts/upgrade-smoke-test.sh v0.62.0
test-upgrade: build
@echo "Running upgrade smoke tests..."
@CANDIDATE_BIN="$(BD_BUILD_OUTPUT)" ./scripts/upgrade-smoke-test.sh
# Run cross-version smoke tests (last 30 tags → candidate).
# Creates epic, issues, and dependencies with old versions, upgrades, verifies.
# Specific versions: ./scripts/cross-version-smoke-test.sh v0.55.0 v0.56.1
# All from v0.30.0: ./scripts/cross-version-smoke-test.sh --from v0.30.0
test-cross-version: build
@echo "Running cross-version smoke tests..."
@CANDIDATE_BIN="$(BD_BUILD_OUTPUT)" ./scripts/cross-version-smoke-test.sh
# Run the authenticated historical upgrade corpus with strict fidelity checks.
# All qualified versions: ./scripts/migration-test/run.sh
# Single version: ./scripts/migration-test/run.sh --version v0.49.6
test-migration: build
@echo "Running migration test harness..."
@CANDIDATE_BIN="$(BD_BUILD_OUTPUT)" ./scripts/migration-test/run.sh
# Regenerate the golden-JSON contract corpus (cmd/bd/protocol/testdata/corpus/).
# Run after any deliberate bd --json wire change; review the diff, then commit.
# A downstream consumer vendors this corpus to detect cross-version drift. Needs Docker (Dolt).
corpus-regen:
@echo "Regenerating contract corpus..."
go test -tags "$(BUILD_TAGS)" ./cmd/bd/protocol -run TestCorpusGolden -corpus.update -count=1
# The tracked .githooks/* carry the managed section cmd/bd/hooks.go generates;
# TestTrackedManagedHookSectionsMatchGenerator holds them byte-equal. Run this
# after changing the generator or after bumping Version in cmd/bd/version.go
# (the section markers carry the version), then commit the regenerated hooks
# alongside it.
githooks-regen:
@echo "Regenerating managed sections in .githooks/*..."
BD_UPDATE_HOOKS_GOLDEN=1 go test -tags "$(BUILD_TAGS)" ./cmd/bd -run TestTrackedManagedHookSectionsMatchGenerator -count=1
# Run performance benchmarks against Dolt storage backend
# Requires CGO and Dolt; generates CPU profile files
# View flamegraph: go tool pprof -http=:8080 <profile-file>
bench:
@echo "Running performance benchmarks (Dolt backend)..."
@echo ""
go test -tags "$(BUILD_TAGS)" -bench=. -benchtime=1s -benchmem -run=^$$ ./internal/storage/dolt/ -timeout=30m
@echo ""
@echo "Benchmark complete."
# Run quick benchmarks (shorter benchtime for faster feedback)
bench-quick:
@echo "Running quick performance benchmarks..."
go test -tags "$(BUILD_TAGS)" -bench=. -benchtime=100ms -benchmem -run=^$$ ./internal/storage/dolt/ -timeout=15m
# Check that local branch is up to date with origin/main
check-up-to-date:
ifndef SKIP_UPDATE_CHECK
@# Skip check on detached HEAD (tag checkouts, CI builds)
@if ! git symbolic-ref HEAD >/dev/null 2>&1; then exit 0; fi
@git fetch origin main --quiet 2>/dev/null || true
@LOCAL=$$(git rev-parse HEAD 2>/dev/null); \
REMOTE=$$(git rev-parse origin/main 2>/dev/null); \
if [ -n "$$REMOTE" ] && [ "$$LOCAL" != "$$REMOTE" ]; then \
echo "ERROR: Local branch is not up to date with origin/main"; \
echo " Local: $$(git rev-parse --short HEAD)"; \
echo " Remote: $$(git rev-parse --short origin/main)"; \
echo "Run 'git pull' first, or use 'make install-force' to override"; \
exit 1; \
fi
endif
# Install bd to ~/.local/bin (builds, signs on macOS, then renames into place)
# Also creates 'beads' symlink as an alias for bd
# Use install-force to skip the origin/main update check
#
# The install stages to a temp name inside INSTALL_DIR and rename(2)s over the
# final path: the live path must never hold a partial binary. A plain cp onto
# bd leaves a truncated (on macOS: signature-invalid) binary for the whole
# ~200MB copy, and any bd exec'd in that window dies at exec with rc 137 and
# zero bytes of output — indistinguishable from an empty result set to callers.
# The old rm-first shape added an ENOENT window on top. Same treatment for the
# beads symlink.
#
# On Git for Windows, `rm path/bd` can resolve and delete `path/bd.exe` when no
# literal extensionless entry exists. Replace bd.exe first, then enumerate real
# legacy aliases (including case variants and redirected install directories)
# so cleanup cannot remove the executable or weaken a failed install. Keep
# directories named bd; the Windows PATH above supplies MSYS find, not System32 find.
# find -H follows the install-directory argument; internal aliases are selected by
# ! -type d, without assuming how this find implementation classifies junctions.
install install-force: build
@mkdir -p "$(INSTALL_DIR)"
ifeq ($(OS),Windows_NT)
@cp "$(BD_BUILD_OUTPUT)" "$(INSTALL_DIR)/.bd.exe.install.tmp.$$$$" && mv -f "$(INSTALL_DIR)/.bd.exe.install.tmp.$$$$" "$(INSTALL_DIR)/bd.exe"
@find -H "$(INSTALL_DIR)" -mindepth 1 -maxdepth 1 -iname bd ! -type d -exec rm -f -- {} +
@echo "Installed bd.exe to $(INSTALL_DIR)/bd.exe"
else
@cp "$(BD_BUILD_OUTPUT)" "$(INSTALL_DIR)/.bd.install.tmp.$$$$" && mv -f "$(INSTALL_DIR)/.bd.install.tmp.$$$$" "$(INSTALL_DIR)/bd"
@echo "Installed bd to $(INSTALL_DIR)/bd"
@ln -sfn bd "$(INSTALL_DIR)/.beads.install.tmp.$$$$" && mv -f "$(INSTALL_DIR)/.beads.install.tmp.$$$$" "$(INSTALL_DIR)/beads"
@echo "Created 'beads' alias -> bd"
endif
@git config core.hooksPath .githooks 2>/dev/null && echo "Configured git hooks (.githooks/)" || true
install: check-up-to-date
# Format all Go files.
# Through the go.mod-pinned gofmt, never a bare PATH one: a newer local Go
# formats differently from CI, so a bare gofmt -w here rewrites files into a
# form CI's gofmt then rejects. See scripts/ci/gofmt-bin.sh.
fmt:
@echo "Formatting Go files..."
@gofmt_bin="$$(./scripts/ci/gofmt-bin.sh)" && "$$gofmt_bin" -w .
@echo "Done"
# Check that all Go files are properly formatted (for CI)
fmt-check:
@./scripts/ci/fmt-check.sh
# Validate documentation references against actual CLI flags
check-docs:
@echo "Building bd for docs checks..."
@CGO_ENABLED=0 go build -tags "$(BUILD_TAGS)" -ldflags="-X main.Build=$(GIT_BUILD)" -o "$(BUILD_DIR)/bd" ./cmd/bd
@./scripts/check-doc-flags.sh "$(BUILD_DIR)/bd"
@./scripts/check-doc-freshness.sh
@go test -tags=gms_pure_go ./test/docsync
# Render committed Excalidraw diagram sources to SVG (idempotent; only
# re-renders when the .excalidraw source is newer than its .svg). Both the
# source and the rendered SVG are committed; docs pages embed
# /diagrams/excalidraw-rendered/<name>.svg. Rendered images must be looked
# at before committing — layout problems are invisible in a text diff.
diagrams-excalidraw:
@set -e; \
src_dir=docs/diagrams/excalidraw; \
out_dir=docs/diagrams/excalidraw-rendered; \
mkdir -p "$$out_dir"; \
shopt -s nullglob 2>/dev/null || true; \
rendered=0; \
for f in "$$src_dir"/*.excalidraw; do \
[ -e "$$f" ] || continue; \
base=$$(basename "$$f" .excalidraw); \
out="$$out_dir/$$base.svg"; \
if [ ! -e "$$out" ] || [ "$$f" -nt "$$out" ]; then \
echo "excalidraw -> $$out"; \
npx -y @swiftlysingh/excalidraw-cli convert "$$f" --format svg --padding 16 --output "$$out"; \
rendered=$$((rendered+1)); \
fi; \
done; \
echo "excalidraw: rendered $$rendered file(s)"
# Live preview of the Mintlify docs site (docs/) at http://localhost:3000
docs-dev:
./mint.sh dev
# Bazel (side-by-side with the Go toolchain; `go build`/`go test` do not need
# it). Regenerate BUILD.bazel files with gazelle and refresh the MODULE.bazel
# use_repo list + MODULE.bazel.lock, then refresh the go_srcs filegroups that
# source-scanning tests declare as data (tools/bazel/go_srcs.py). Run after
# changing Go imports, go.mod, or packages.
BAZEL ?= bazel
bazel-sync:
$(BAZEL) run //:gazelle
python3 tools/bazel/go_srcs.py
$(BAZEL) mod tidy
# Fail (printing a diff) when a go_srcs block that tools/bazel/go_srcs.py
# manages is stale, e.g. after gazelle added a package under a scanned tree.
# Needs no Bazel; scripts/bazel_policy_test.go runs the same check.
bazel-sync-check:
python3 tools/bazel/go_srcs.py --check
# Ensure -short is not used as an implicit CI tier boundary.
check-testing-short:
@./scripts/check-testing-short.sh
# Clean build artifacts and benchmark profiles
clean:
@echo "Cleaning..."
rm -f bd
rm -f bd.exe
rm -f internal/storage/dolt/bench-cpu-*.prof
rm -f beads-perf-*.prof
# Sweep orphaned cmd/bd test temp dirs (e.g. when a test run was SIGKILLed
# before its TestMain cleanup ran). Safe to run between test runs; will
# skip dirs in use by a live test process. See bd-3q2u.
clean-test-tmp:
@echo "Sweeping orphaned cmd/bd test temp dirs from $${TMPDIR:-/tmp}..."
@./scripts/clean-test-tmp.sh
# Show help
help:
@echo "Beads Makefile targets:"
@echo " make build - Build the bd binary"
@echo " make doctor-build - Diagnose build env (GOFLAGS/CGO/CC) for the ICU build trap"
@echo " make test - Run all tests"
@echo " make test-icu-path - Run opt-in ICU regex path tests (maintainer-only)"
@echo " make test-full-cgo - Deprecated alias for make test-icu-path"
@echo " make ci-pr-core - Run required PR core Go test wrapper"
@echo " make ci-pr-policy - Run required PR policy wrapper"
@echo " make ci-pr-lint - Run required PR formatting and lint wrapper"
@echo " make ci-complexity - Report production cyclomatic complexity (advisory)"
@echo " make ci-complexity-diff - Compare complexity with COMPLEXITY_BASE_REF"
@echo " make ci-complexity-check - Check complexity against the local baseline"
@echo " make ci-package-mcp - Run MCP Python package gate"
@echo " make ci-package-npm - Run npm package gate"
@echo " make test-regression - Run differential regression tests (baseline vs candidate)"
@echo " make test-upgrade - Run upgrade smoke tests (release stability gate)"
@echo " make test-cross-version - Run cross-version smoke tests (last 30 tags)"
@echo " make test-migration - Run authenticated historical upgrade tests"
@echo " make bench - Run performance benchmarks (generates CPU profiles)"
@echo " make bench-quick - Run quick benchmarks (shorter benchtime)"
@echo " make install - Install bd to ~/.local/bin (with codesign on macOS, includes 'beads' alias)"
@echo " make install-force - Install bd, skipping the origin/main update check"
@echo " make fmt - Format all Go files with gofmt"
@echo " make fmt-check - Check Go formatting (for CI)"
@echo " make check-docs - Validate docs against CLI flags"
@echo " make api-gen - Regenerate HTTP API types from the OpenAPI spec"
@echo " make api-check - OpenAPI drift gate (regenerate, diff-or-fail, spec tests)"
@echo " make bazel-sync - Regenerate Bazel BUILD files and tidy MODULE.bazel (gazelle + mod tidy)"
@echo " make bazel-sync-check - Fail if generated go_srcs Bazel filegroups are stale"
@echo " make clean - Remove build artifacts and profile files"
@echo " make clean-test-tmp - Sweep orphaned cmd/bd test temp dirs from \$$TMPDIR"
@echo " make help - Show this help message"