From fd5286884e6adf0ad7bca2126c5840fb82781e96 Mon Sep 17 00:00:00 2001
From: Jakub Zych <jakub@keios.eu>
Date: Wed, 21 Oct 2026 19:22:00 +0200
Subject: [PATCH] test(docsite): command word with global flags

- the docs checker finds the command behind -v, -q, -qn, --env X, --env=X
- gate: bonfire and docsite names in the go stage, docsite in the race run
---
 internal/docsite/check_commands_test.go | 43 +++++++++++++++++++++++++
 scripts/check-phase19.8.sh              | 22 +++++++++++--
 2 files changed, 62 insertions(+), 3 deletions(-)
 create mode 100644 internal/docsite/check_commands_test.go

diff --git a/internal/docsite/check_commands_test.go b/internal/docsite/check_commands_test.go
new file mode 100644
index 00000000..c94ff655
--- /dev/null
+++ b/internal/docsite/check_commands_test.go
@@ -0,0 +1,43 @@
+package docsite
+
+import "testing"
+
+// TestCommandWordGlobals: the docs checker finds the command word behind
+// the console's global options (D-13), in every form a page may use them.
+func TestCommandWordGlobals(t *testing.T) {
+	tool, app := true, false
+	cases := []struct {
+		in   string
+		name string
+		tool bool
+	}{
+		{"bin/acme -v serve", "serve", app},
+		{"bin/acme -vv serve", "serve", app},
+		{"./bin/acme -vvv serve --port 8080", "serve", app},
+		{"summer -q migrate", "migrate", tool},
+		{"summer --quiet migrate", "migrate", tool},
+		{"summer -qn migrate", "migrate", tool},
+		{"bin/acme --env staging migrate", "migrate", app},
+		{"bin/acme --env=staging migrate", "migrate", app},
+		{"bin/acme --no-ansi --env=staging -n migrate --force", "migrate", app},
+		{"bin/acme --ansi -v queue:work", "queue:work", app},
+		{"summer list", "list", tool},
+		{"summer -v list --format=json", "list", tool},
+		{"bin/acme help migrate", "help", app},
+		{"bin/acme -n help migrate", "help", app},
+		{"$ SUMMER_ENV=dev bin/acme --env dev -q migrate:status", "migrate:status", app},
+		{"go run ./cmd/summer -v docs:build --check", "docs:build", tool},
+	}
+	for _, tc := range cases {
+		name, isTool, ok := commandWord(tc.in)
+		if !ok || name != tc.name || isTool != tc.tool {
+			t.Errorf("commandWord(%q) = %q, %v, %v; want %q, %v, true", tc.in, name, isTool, ok, tc.name, tc.tool)
+		}
+	}
+	// Only global options and no command word.
+	for _, in := range []string{"summer -v", "bin/acme --env staging", "summer -q --no-ansi -n", "bin/acme --env"} {
+		if name, _, ok := commandWord(in); ok {
+			t.Errorf("commandWord(%q) found %q, want no command", in, name)
+		}
+	}
+}
diff --git a/scripts/check-phase19.8.sh b/scripts/check-phase19.8.sh
index 14580d10..f25f4c3a 100755
--- a/scripts/check-phase19.8.sh
+++ b/scripts/check-phase19.8.sh
@@ -85,6 +85,21 @@ BONFIRE_TESTS=(
 	# Plan 02.
 	TestListTracerSmoke TestHelpSmoke TestListJSONSmoke TestErrorRenderSmoke
 	TestWidgetMatrixSmoke
+	# Plan 04: global options, duplicates, Call (SC-2, D-13).
+	TestPeekGlobals TestGlobalsArgs TestGlobalFlagsAgree
+	TestReservedFlags TestDuplicateNames TestCallNoGlobalsHook
+	# Plan 04: goldens for list, help and errors (D-13, D-14, D-16, D-18).
+	TestListGolden TestListAllGolden TestListJSONGolden TestListStyledGolden
+	TestHelpGolden TestHelpPassthroughGolden TestHelpEqualsHelpFlag
+	TestErrorGolden TestExitCodes TestReportedSilent TestErrorScrubbed
+	TestWrongDirectoryHint TestCheckDocs TestVersionHeader
+	# Plan 04: widgets, live views and prompts (D-03, D-27, D-28).
+	TestWidgetMatrix TestLiveModels TestPromptsNoInteraction
+	TestSecretWithNoInteraction TestConfirmProceed TestPrintAbove
+)
+DOCSITE_TESTS=(
+	# Plan 04: the docs checker reads past the global options.
+	TestCommandWord TestCommandWordGlobals
 )
 CONGA_TESTS=(
 	# Plan 01.
@@ -316,17 +331,18 @@ run_go() {
 	go_named "$ROOT" ./modules/diary -short "${DIARY_TESTS[@]}"
 	go_named "$ROOT" ./modules/sunscreen -short "${SUNSCREEN_TESTS[@]}"
 	go_named "$ROOT" ./modules/bonfire -short "${BONFIRE_TESTS[@]}"
+	go_named "$ROOT" ./internal/docsite -short "${DOCSITE_TESTS[@]}"
 	go_named "$ROOT" ./modules/conga -short "${CONGA_TESTS[@]}"
 	go_named "$ROOT" ./modules/lagoon -short "${LAGOON_TESTS[@]}"
 	go_named "$ROOT" ./modules/surf -short "${SURF_TESTS[@]}"
 	go_named "$ROOT" ./cmd/summer -short "${SUMMER_TESTS[@]}"
 	local out
-	if ! out="$(cd "$ROOT" && go test -count=1 -race -short ./modules/diary/... ./modules/sunscreen/... ./modules/bonfire/... 2>&1)"; then
+	if ! out="$(cd "$ROOT" && go test -count=1 -race -short ./modules/diary/... ./modules/sunscreen/... ./modules/bonfire/... ./internal/docsite/... 2>&1)"; then
 		printf '%s\n' "$out" | tail -n 60 >&2
-		echo "refuse: go test -race -short of diary, sunscreen and bonfire" >&2
+		echo "refuse: go test -race -short of diary, sunscreen, bonfire and docsite" >&2
 		return 1
 	fi
-	echo "race: modules/diary, modules/sunscreen, modules/bonfire"
+	echo "race: modules/diary, modules/sunscreen, modules/bonfire, internal/docsite"
 	echo "phase19.8 go passed"
 }