From 0080bcbf3361340d8c0f610a2fe634258934d3e5 Mon Sep 17 00:00:00 2001
From: Ethan <39577870+ethanndickson@users.noreply.github.com>
Date: Wed, 15 Apr 2026 12:59:07 +1000
Subject: [PATCH] fix(Makefile): rebuild clidocgen when Go sources or template
 change (#24302)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The `_gen/bin/clidocgen` binary only declared `scripts/clidocgen/*.go`
as prerequisites. Since it reflects over the full CLI tree (227
transitive internal packages via `enterprise/cli` → `cli/` → `codersdk/`
→ …), any change to CLI flags, SDK structs, or command definitions could
alter its output — but Make would keep serving the stale binary until it
was manually deleted (or `-B` was passed).

This caused a recurring developer-facing bug: after merging main (or
rebasing onto new CLI/SDK changes), the pre-commit hook would use the
stale binary, commit wrong docs, `make gen` would see no diff (same
stale binary), and CI would fail because it builds fresh.

Add `$(GO_SRC_FILES)` and the embedded `command.tpl` to the prerequisite
list so Make invalidates the binary whenever its inputs change. Move
`FIND_EXCLUSIONS` and `GO_SRC_FILES` above the helper-binary block so
the variable is defined before first use.
---
 Makefile | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index dec026a700..1e51438858 100644
--- a/Makefile
+++ b/Makefile
@@ -91,6 +91,19 @@ define atomic_write
 		mv "$$tmpfile" "$@" && rm -rf "$$tmpdir"
 endef
 
+# CLI doc generation reflects over the assembled CLI tree. Track command
+# definitions plus the top-level SDK types they expose in help text and flag
+# values, without pulling in unrelated generated sources.
+CLIDOC_SRC_FILES := \
+	$(shell find ./cli ./enterprise/cli -type f -name '*.go' -not -name '*_test.go') \
+	$(wildcard codersdk/*.go) \
+	$(wildcard buildinfo/*.go)
+
+CLIDOCGEN_INPUTS := \
+	$(wildcard scripts/clidocgen/*.go) \
+	scripts/clidocgen/command.tpl \
+	$(CLIDOC_SRC_FILES)
+
 # Helper binary targets. Built with go build -o to avoid caching
 # link-stage executables in GOCACHE. Each binary is a real Make
 # target so parallel -j builds serialize correctly instead of
@@ -108,7 +121,9 @@ _gen/bin/check-scopes: $(wildcard scripts/check-scopes/*.go) | _gen
 	@mkdir -p _gen/bin
 	go build -o $@ ./scripts/check-scopes
 
-_gen/bin/clidocgen: $(wildcard scripts/clidocgen/*.go) | _gen
+# clidocgen reflects over the full CLI tree, so it must rebuild when its
+# command definitions, flag types, or embedded template change.
+_gen/bin/clidocgen: $(CLIDOCGEN_INPUTS) | _gen
 	@mkdir -p _gen/bin
 	go build -o $@ ./scripts/clidocgen
 
@@ -1190,7 +1205,7 @@ docs/admin/integrations/prometheus.md: node_modules/.installed scripts/metricsdo
 		pnpm exec markdown-table-formatter "$$tmpfile" && \
 		mv "$$tmpfile" "$@" && rm -rf "$$tmpdir"
 
-docs/reference/cli/index.md: node_modules/.installed scripts/clidocgen/main.go examples/examples.gen.json $(GO_SRC_FILES) | _gen _gen/bin/clidocgen
+docs/reference/cli/index.md: node_modules/.installed examples/examples.gen.json _gen/bin/clidocgen | _gen
 	tmpdir=$$(mktemp -d -p _gen) && \
 		tmpdir=$$(realpath "$$tmpdir") && \
 		mkdir -p "$$tmpdir/docs/reference/cli" && \