fix(list): a typed --format beats a config json default (#6278) (#6708)

* fix(list): a typed --format beats a config json default (#6278)

The root pre-run promotes a config-file or env `json: true` into jsonOutput
unless the ROOT --format changed. bd list registers its own --format, which
shadows the root flag, so that check never saw it. `bd list --format
digraph` under `json: true` then took the JSON branch and printed the
listing instead of the graph.

gatherListInput now clears jsonOutput when the caller typed a non-json
--format and did not also pass --json. Flag precedence is unchanged:
explicit --json still beats --format, and --format json still turns JSON
on. Scoped to bd list rather than the global pre-run, because other
commands' local --format flags (export, graph, ...) mean different things.

Agent-Signature: claude-code-opus-5-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(list): stop citing help text that does not state the precedence

Maintainer review fixup for PR #6708 (adopt-pr iteration 1). Synthesis and the
quality scorecard both say approve with no blocker and no major finding and no
required changes; these are two of the three non-gating minors, taken because
both are text-only and sit in the material this PR adds.

- The fix-site comment and the CHANGELOG entry both ended "as the (flag's) help
  says", pointing at a contract that does not exist: list's --format help is
  "Output format: 'digraph' ..., 'dot' (Graphviz), or Go template" and root's is
  "Output format (json). Alias for --json" -- neither states that an explicit
  --json outranks --format. Dropped the false citation and named the conjunct
  that actually preserves that precedence, rather than appending it to the
  --format usage string: touching a Cobra help string implies a CLI-reference
  docs regen, which is more blast radius than a minor readability finding earns.
- Left the shadowing hazard on the record at main.go:1104, the shared
  config-precedence check that by construction cannot see a subcommand's local
  --format. This is the finding's prescribed minimum; reconciling the check
  itself (and bd dep tree's opposite precedence) is explicitly scoped to its own
  PR.

Scope correction to the finding: the synthesis lists the commit message as a
third site carrying the false citation. It does not. The contributor's commit
message says "Flag precedence is unchanged: explicit --json still beats
--format" -- true, and it cites no help text. The PR body does not carry the
clause either (checked both). So the finding's real spread is the two sites
fixed here, and nothing is left for finalize to amend on the GitHub surface.

Deliberately not taken: the third minor, an end-to-end case in
list_embedded_test.go asserting the config-default half of the chain. It is
recommended rather than required, the unit matrix is already proven to fail on
base, and an embedded-gated test is not the cheap, nearby cleanup this step
allows opportunistically. It stays a non-gating follow-up.

Validation: git diff --check clean; gofmt clean; go build ./... clean;
go vet ./cmd/bd/ clean; golangci-lint v2.10.1 (pr.yml's pin) 0 issues;
TestListTypedFormatBeatsAConfigJSONDefault 4/4 and the TestGatherListInput*
family all PASS. Comment-and-prose only -- no behavior change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
This commit is contained in:
Harry Miller 2026-09-26 06:40:44 -07:00 • committed by GitHub
commit 65005f8cbc
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 95 additions and 1 deletions

View file

@ -82,6 +82,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`bd dolt pull`, which is what opting out means). Pulling before the first
open after upgrading avoids the state entirely.
- **A `--format` typed on `bd list` now beats a `json: true` config default**
([#6278](https://github.com/gastownhall/beads/issues/6278)). With `json: true`
in `config.yaml` (or the environment), `bd list --format digraph`, `dot` or a
template printed the JSON listing instead, because `bd list`'s own `--format`
flag shadows the root one the config-precedence check looks at. A typed
`--format` now wins over the config default; an explicit `--json` still wins
over `--format`.
### Added
- **`bd backup` works on a proxied-server workspace bd runs the Dolt server

View file

@ -0,0 +1,70 @@
package main
import (
"testing"
"github.com/spf13/cobra"
)
// TestListTypedFormatBeatsAConfigJSONDefault pins GH#6278. The root pre-run
// promotes a config-file (or env) `json: true` into jsonOutput unless the
// ROOT --format changed, but `bd list` registers its own --format, which
// shadows the root one. So `bd list --format digraph` under `json: true`
// printed the JSON listing instead of the graph. A --format the caller typed
// must win over that default; an explicit --json still wins over --format.
func TestListTypedFormatBeatsAConfigJSONDefault(t *testing.T) {
t.Run("typed format clears a config json default", func(t *testing.T) {
// pinJSONOutput(true) stands in for the pre-run having read json: true.
pinJSONOutput(t, true)
in, err := gatherListInput(newListFlagsCommand(t, "--format", "digraph"))
if err != nil {
t.Fatalf("gatherListInput: %v", err)
}
if in.jsonOutput || jsonOutput {
t.Errorf("jsonOutput = %v (in.jsonOutput = %v), want false: the typed --format must beat the config default", jsonOutput, in.jsonOutput)
}
if in.formatStr != "digraph" {
t.Errorf("formatStr = %q, want %q", in.formatStr, "digraph")
}
})
t.Run("explicit --json still beats --format", func(t *testing.T) {
pinJSONOutput(t, true)
cmd := newListFlagsCommand(t, "--format", "digraph")
root := &cobra.Command{Use: "bd"}
root.PersistentFlags().Bool("json", false, "")
root.AddCommand(cmd)
if err := root.PersistentFlags().Set("json", "true"); err != nil {
t.Fatalf("set --json: %v", err)
}
in, err := gatherListInput(cmd)
if err != nil {
t.Fatalf("gatherListInput: %v", err)
}
if !in.jsonOutput || !jsonOutput {
t.Errorf("jsonOutput = %v, want true: an explicit --json outranks --format", jsonOutput)
}
})
t.Run("no typed format leaves the config default alone", func(t *testing.T) {
pinJSONOutput(t, true)
in, err := gatherListInput(newListFlagsCommand(t))
if err != nil {
t.Fatalf("gatherListInput: %v", err)
}
if !in.jsonOutput {
t.Error("in.jsonOutput = false, want true: without --format the config json default applies")
}
})
t.Run("--format json still turns json on", func(t *testing.T) {
pinJSONOutput(t, false)
in, err := gatherListInput(newListFlagsCommand(t, "--format", "json"))
if err != nil {
t.Fatalf("gatherListInput: %v", err)
}
if !in.jsonOutput || in.formatStr != "" {
t.Errorf("jsonOutput = %v, formatStr = %q, want true and empty", in.jsonOutput, in.formatStr)
}
})
}

View file

@ -65,6 +65,16 @@ func gatherListInput(cmd *cobra.Command) (listInput, error) {
if strings.EqualFold(in.formatStr, "json") {
jsonOutput = true
in.formatStr = ""
} else if in.formatStr != "" && cmd.Flags().Changed("format") && !commandJSONFlagChanged(cmd) {
// A --format the caller typed outranks a json default from config or
// the environment (GH#6278). The root pre-run promotes `json: true`
// into jsonOutput unless the ROOT --format changed, but this command's
// own --format shadows the root one, so that check never sees it and
// the JSON branch would replace the requested graph or template. An
// explicit --json still wins (the !commandJSONFlagChanged conjunct
// above is what preserves it); note no flag's help text states that
// precedence, so this comment is its only record.
jsonOutput = false
}
in.jsonOutput = jsonOutput

View file

@ -1100,7 +1100,13 @@ var rootCmd = &cobra.Command{
jsonOutput = true
}
}
// If flag wasn't explicitly set, use viper value
// If flag wasn't explicitly set, use viper value.
//
// SHADOWING HAZARD (GH#6278): this reads the ROOT persistent --format
// only, so a subcommand that registers its own local --format shadows
// it here and still gets `json: true` promoted over the format it was
// asked for. `bd list` compensates in gatherListInput; any new local
// --format registration needs the same treatment or this fires again.
if !commandJSONFlagChanged(cmd) && !cmd.Root().PersistentFlags().Changed("format") {
jsonOutput = config.GetBool("json")
} else {