# 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: lint lint-changed vet .PHONY: check check-go test-go check-docs-go .PHONY: ci-pr-core ci-pr-lint ci-complexity ci-complexity-diff ci-complexity-check ci-package-mcp ci-package-npm nogo-ownership .PHONY: api-gen api-check .PHONY: bazel-sync bazel-sync-check # Default target all: build # Build and test engine. Bazel is what CI gates on: .github/workflows/bazel.yml # runs `bazel test` lanes on rbe-west, and nogo (lint + vet), formatting and # the repository guards are Bazel targets there. The primary targets (test, # check, check-docs) run the same `bazel test` commands as those lanes, so a # local run shares CI's action keys and its remote cache (engdocs/TESTING.md # "Building and testing"). Each keeps a plain go twin under an explicit -go # name (test-go, check-go, check-docs-go) for offline work and hosts Bazel does # not serve; that twin is an inner-loop convenience, not what CI enforces. # GitHub Actions jobs that still run Go-native suites call the -go names. BAZEL ?= bazel # Extra flags for every `bazel test` below: --config=fork-cache (contributors: # the anonymous read-only cache) or --config=remote-exec (maintainers with an # rbe-west client certificate). Hosts whose ~/.bazelrc names the executor need # neither. Better: put `build --config=...` in the gitignored .bazelrc.local. BAZEL_FLAGS ?= BAZEL_TEST = $(BAZEL) test $(BAZEL_FLAGS) 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:-}"; \ 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 # bazel.yml's test lane (`bazel test //... --config=ci`): every untagged # go_test with PR Core's selection (race, -short, skips), plus nogo lint/vet, # formatting and the repository guards. The other lanes' commands are in # engdocs/TESTING.md "Building and testing". test: $(BAZEL_TEST) //... --config=ci # Plain go test (skips known broken tests listed in .test-skip): an inner-loop # convenience without Bazel; CI does not run it. test-go: @echo "Running tests..." @TEST_COVER=1 ./scripts/test.sh # Fast quality gates: the testing.Short policy, the full nogo lint gate # (native plus the windows/darwin passes) and `make test`. check: check-testing-short ci-pr-lint test # The same gates without Bazel where they have a Go form: gofmt and go test. # nogo has no go twin, so this is a convenience CI does not enforce. check-go: fmt-check check-testing-short test-go # 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 # Lint and vet are nogo (//tools/nogo): go test's vet checks plus the # golangci-lint linters .golangci.yml enables, validated beside every Go # compile, so any `bazel build`/`bazel test` (local or on rbe-west) fails on a # finding. These targets ask Bazel for the analysis alone (.bazelrc's # --config=nogo; nothing is linked). ci-pr-lint: @./scripts/ci/pr-lint.sh # nogo-ownership is a dynamic, advisory cross-check (not part of the required # //scripts static suite, which cannot shell out to Bazel): it asks real # `bazel aquery` whether the nogo owner lane for each configuration group # (today: race, bazel-test/--config=ci) really does validate every file a # non-owner lane (embedded, doltserver, doltserver-proxied, dolt-race, which # pass --norun_validations) compiles. See tools/bazel/nogo_ownership.py and # scripts/nogo_lint_policy_test.go's nogoConfigurations table. nogo-ownership: @python3 tools/bazel/nogo_ownership.py # The CI lint gate: native, plus //tools/bazel:release_cross for windows/amd64 # and darwin/arm64 (BD_LINT_TARGETS selects; scripts/pr-lint). lint: ci-pr-lint # go test's vet checks run inside nogo; same as lint. vet: lint # nogo over the Bazel packages of changed Go files, natively (the pre-commit # hook's lint). LINT_CHANGED_SCOPE: staged, or worktree (changed against # LINT_CHANGED_REF, staged, and untracked). LINT_CHANGED_SCOPE ?= worktree LINT_CHANGED_REF ?= HEAD lint-changed: @case "$(LINT_CHANGED_SCOPE)" in \ staged) files="$$(git diff --cached --name-only --diff-filter=ACMRT -- '*.go')" ;; \ worktree) files="$$( \ git diff --name-only --diff-filter=ACMRT "$(LINT_CHANGED_REF)" -- '*.go'; \ git diff --cached --name-only --diff-filter=ACMRT -- '*.go'; \ git ls-files --others --exclude-standard -- '*.go')" ;; \ *) echo "unknown LINT_CHANGED_SCOPE=$(LINT_CHANGED_SCOPE); expected staged or worktree" >&2; exit 2 ;; \ esac; \ packages=""; missing=""; \ for file in $$files; do \ dir="$$(dirname "$$file")"; \ case "/$$dir/" in */testdata/*) continue ;; esac; \ if [ -f "$$dir/BUILD.bazel" ]; then packages="$$packages //$${dir#.}:all"; else missing="$$missing $$dir"; fi; \ done; \ if [ -n "$$missing" ]; then \ echo "lint-changed: no BUILD.bazel in$$missing; run 'make bazel-sync'" >&2; exit 1; \ fi; \ packages="$$(printf '%s\n' $$packages | sort -u | sed 's#^///#//#; s#^//\.:#//:#')"; \ if [ -z "$$packages" ]; then echo "lint-changed: no changed Go packages"; exit 0; fi; \ echo "lint-changed:" $$packages; \ $(BAZEL) build --config=nogo -- $$packages # 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. CI runs the drift half as # //scripts/repochecks:types_gen_drift_test. # # 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 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 # Docs checks: docsync and doc freshness as bazel.yml's test lane runs them, # then the CLI flag check, which validates against bd built from the release in # docs/cli-docs.pin (so it stays a script, like pr.yml's check-doc-flags job). check-docs: $(BAZEL_TEST) //test/docsync:docsync_test //scripts/repochecks:doc_freshness_test --config=ci @./scripts/check-doc-flags.sh # The same docs checks with plain go test and a go-built bd. check-docs-go: @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/.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 # 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-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 - bazel test //... --config=ci (bazel.yml's test lane; BAZEL_FLAGS adds flags)" @echo " make test-go - Plain go test via scripts/test.sh (inner loop; not what CI enforces)" @echo " make check - testing.Short policy + nogo lint gate + make test" @echo " make check-go - gofmt + testing.Short policy + make test-go (no Bazel)" @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-lint - Run the required lint gate: nogo (vet + golangci-lint's linters) under Bazel, native + windows/darwin" @echo " make lint - Same as ci-pr-lint (make vet too)" @echo " make lint-changed - nogo over the Bazel packages of changed Go files (LINT_CHANGED_SCOPE=staged|worktree)" @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 - Bazel docsync + doc freshness tests, then the CLI flag check" @echo " make check-docs-go - The same docs checks with plain go test" @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"