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 <noreply@anthropic.com>
This commit is contained in:
Vishnu J 2026-09-28 14:14:28 -07:00 • committed by GitHub
commit 9c94613b2b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 60 additions and 1 deletions

View file

@ -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)")

View file

@ -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)
}
})
}
}