* 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>
488 lines
22 KiB
Makefile
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"
|