From 9c94613b2b560185ba8a25db8ea9778d461740fc Mon Sep 17 00:00:00 2001 From: Vishnu J Date: Mon, 28 Sep 2026 14:14:28 -0700 Subject: [PATCH] fix(list): correct --limit help for piped-output default (#6276) bd list --help claimed an unconditional default of 50 for --limit, but gatherListInput (cmd/bd/list_input.go) resolves effectiveLimit through a switch: an explicit --limit wins, then --all is unlimited, then a configured list.limit applies, then piped stdout (not a terminal) is unlimited (GH#4094, #4158), then agent mode (BD_AGENT_MODE=1 or CLAUDE_CODE set) at a terminal is 20, and only then 50. Neither the piped nor the agent-mode arm was documented, so a script piping bd list --json | ... or an agent at an interactive terminal could not tell its actual limit from --help alone. Reworded the --limit usage string to state those arms in the switch's order, each with its precondition: an explicit --limit always wins (so --all --limit 5 is 5, and 0 means unlimited); otherwise --all is unlimited; otherwise a configured list.limit applies; otherwise unlimited when piped, else 20 in agent mode at a terminal, else 50. Added TestListLimitHelpDescribesPipedBehavior, which pins the usage string verbatim (a substring check would accept a clause scoped wider than its arm) and, with list.limit configured to 7, checks that --all --limit 5 resolves to 5, --all to 0, and piped output to 7. The flag keeps registering workapi.DefaultListLimit, so cobra still appends "(default 50)" to the line: the registered value is never consumed at runtime (list_input.go overwrites it with config.GetInt("list.limit") when the flag is unset), but internal/httpapi/apigen/types.gen.go documents it as the value the flag registers, so changing it is out of scope here. Fixes gastownhall/beads#6069 Co-authored-by: Claude Fable 5.1 --- cmd/bd/list.go | 2 +- cmd/bd/list_limit_policy_test.go | 59 ++++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+), 1 deletion(-) diff --git a/cmd/bd/list.go b/cmd/bd/list.go index ca75bcf27..cb1fa12fd 100644 --- a/cmd/bd/list.go +++ b/cmd/bd/list.go @@ -420,7 +420,7 @@ func init() { listCmd.Flags().String("title", "", "Filter by title text (case-insensitive substring match)") listCmd.Flags().String("spec", "", "Filter by spec_id prefix") listCmd.Flags().String("id", "", "Filter by specific issue IDs (comma-separated, e.g., bd-1,bd-5,bd-10)") - listCmd.Flags().IntP("limit", "n", workapi.DefaultListLimit, "Limit results (default 50, use 0 for unlimited)") + listCmd.Flags().IntP("limit", "n", workapi.DefaultListLimit, "Limit results (an explicit --limit always wins, 0 meaning unlimited; otherwise --all is unlimited; otherwise a configured list.limit applies; otherwise unlimited when piped, else 20 in agent mode at a terminal, else 50)") listCmd.Flags().Int("offset", 0, "Skip the first N matching results (0-based). Only supported under --proxied-server.") listCmd.Flags().String("format", "", "Output format: 'digraph' (for golang.org/x/tools/cmd/digraph), 'dot' (Graphviz), or Go template") listCmd.Flags().Bool("all", false, "Show all issues including closed (overrides default filter)") diff --git a/cmd/bd/list_limit_policy_test.go b/cmd/bd/list_limit_policy_test.go index ec8b79c3d..39272059b 100644 --- a/cmd/bd/list_limit_policy_test.go +++ b/cmd/bd/list_limit_policy_test.go @@ -91,3 +91,62 @@ func TestListLimitPolicyIsResolvedBeforeTheRequest(t *testing.T) { }) } } + +// GH#6069: the --limit flag help must describe the switch pinned above, in +// the switch's own order, not claim an unconditional "default 50". The whole +// usage string is pinned verbatim: a substring check would accept a clause +// scoped wider than its arm (an earlier draft's "--all is always unlimited" +// contained every needle and was still false, because an explicit --limit +// outranks --all). The cases below tie the three claims a reader is most +// likely to get wrong back to the switch, each with list.limit configured. +func TestListLimitHelpDescribesPipedBehavior(t *testing.T) { + flag := listCmd.Flags().Lookup("limit") + if flag == nil { + t.Fatal("listCmd has no --limit flag registered") + } + const want = "Limit results (an explicit --limit always wins, 0 meaning unlimited; otherwise --all is unlimited; otherwise a configured list.limit applies; otherwise unlimited when piped, else 20 in agent mode at a terminal, else 50)" + if flag.Usage != want { + t.Errorf("--limit help = %q\nwant %q", flag.Usage, want) + } + + t.Chdir(t.TempDir()) + config.ResetForTesting() + t.Cleanup(config.ResetForTesting) + if err := config.Initialize(); err != nil { + t.Fatalf("config.Initialize: %v", err) + } + config.Set("list.limit", 7) + if got := config.GetValueSource("list.limit"); got == config.SourceDefault { + t.Fatal("precondition: config.Set did not make list.limit count as configured") + } + for _, tc := range []struct { + name string + args []string + want int + needsPipe bool + }{ + // limitChanged is the first arm, so --all does not make an explicit + // --limit unlimited. Holds at a terminal or a pipe alike. + {"an explicit --limit outranks --all", []string{"--all", "--limit", "5"}, 5, false}, + // The AllFlag arm precedes listLimitConfigured and !IsTerminal, so + // this holds at a terminal too and never needs to skip. + {"--all is unlimited even with list.limit configured", []string{"--all"}, 0, false}, + // listLimitConfigured precedes the !IsTerminal arm. Only a piped + // stdout can show that ordering; at a terminal the same 7 would + // prove nothing about the piped arm. + {"piped output takes a configured list.limit", nil, 7, true}, + } { + t.Run(tc.name, func(t *testing.T) { + if tc.needsPipe && ui.IsTerminal() { + t.Skip("this case shows a configured list.limit outranking the piped-stdout arm, so stdout must be a pipe; go test's is, this run's is not") + } + in, err := gatherListInput(newListLimitCommand(t, tc.args...)) + if err != nil { + t.Fatalf("gatherListInput(%v): %v", tc.args, err) + } + if in.effectiveLimit != tc.want { + t.Errorf("effectiveLimit = %d, want %d", in.effectiveLimit, tc.want) + } + }) + } +}