beads/cmd/bd/protocol/json_contract_test.go
Athos Bernardes 3102cbd4d4
fix(show): flag comment_count as omitted when comments are not streamed (#4865)
* fix(show): flag comment_count as omitted when comments are not streamed

bd show --json's count-only default (be-ijck6q, pinned by
TestJSONContract_ShowOmitsOptInPayloadsByDefault) returns comment_count
with no comments key unless --include-comments is passed. A caller that
checks only `.comments` reads absence as "no comments" — wrong whenever
comment_count > 0. A caller that reads comment_count has no signal that
the array was left out on purpose rather than omitted by a client bug.

Add comments_omitted (bool, omitempty) to IssueDetails, set true only
when CommentCount > 0 and Comments was not populated. Leaves the
count-only default and its perf rationale untouched — this does not
revert cfcc95799/e538f2881, it makes the partial representation
self-announcing. Symmetric dependent_count/dependents case is a known,
separate gap left for a follow-up (not reported by ga-clgh, out of
scope here).

Did not bump JSONSchemaVersion / regen the golden corpus: this adds an
optional field via omitempty (no existing consumer's parse breaks,
no existing corpus fixture has comment_count > 0 for `show`), and
corpus-regen needs a live Dolt+Docker this sandbox doesn't have to
verify. Deferring that call to whoever can run `make corpus-regen` and
review the diff.

Fixes ga-clgh.

* fix(show): set comments_omitted on the proxied path too

The direct path flags comment_count as omitted when comments are not
streamed (ga-clgh); the proxied path silently left the flag unset. Mirror
the else-branch in proxiedBuildDetails, add proxied-path coverage for
present/included/zero cases, and document comments_omitted in the JSON
schema reference. No schema version bump: additive optional field already
emitted by the direct path.

Addresses the 2026-07-23 review on gastownhall/beads#4865.

Agent-Signature: claude-sonnet-5-medium on behalf of maphew

---------

Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-25 16:16:41 -07:00

412 lines
14 KiB
Go

// json_contract_test.go — CI regression tests for --json output contracts.
//
// These tests verify that commands with --json always produce valid JSON
// and include required fields. Regressions like GH#2492, GH#2465, GH#2407,
// GH#2395 are prevented by these tests.
package protocol
import (
"encoding/json"
"strings"
"testing"
)
// TestJSONContract_ListOutputIsValidJSON verifies bd list --json always
// produces valid JSON (not mixed with tree-renderer text).
func TestJSONContract_ListOutputIsValidJSON(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
w.create("JSON contract test issue")
out := w.run("list", "--json")
items := parseJSONOutput(t, out)
if len(items) == 0 {
t.Fatal("bd list --json returned no items")
}
}
// TestJSONContract_ShowOutputHasRequiredFields verifies bd show --json
// includes all required issue fields, including the relational counts that
// stand in for the opt-in comment and dependent payloads.
//
// schema_version is deliberately NOT required here: show is an array-returning
// command (see TestJSONContract_ShowOutputIsArray), and wrapWithSchemaVersion
// only injects the field into object-shaped output.
func TestJSONContract_ShowOutputHasRequiredFields(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
id := w.create("Required fields test")
out := w.run("show", id, "--json")
items := parseJSONOutput(t, out)
if len(items) == 0 {
t.Fatal("bd show --json returned no items")
}
issue := items[0]
requiredFields := []string{
"id", "title", "status", "priority", "issue_type", "created_at",
"dependency_count", "dependent_count", "comment_count",
}
for _, field := range requiredFields {
if _, ok := issue[field]; !ok {
t.Errorf("bd show --json missing required field %q", field)
}
}
}
// TestJSONContract_ShowOmitsOptInPayloadsByDefault pins the NEGATIVE half of the
// count-only contract (be-ijck6q): by default, bd show --json must OMIT the
// "comments" and "dependents" arrays entirely, and each --include-* flag must
// populate its own array and only its own.
//
// Every other test that touches comments or dependents asks for them with
// showJSONFull, so all of them would stay green if the default silently went
// back to materializing both lists eagerly — which is precisely the pathological
// hub-bead slowness cfcc95799 removed. Omission is the invariant with no other
// witness, so it needs one of its own: a perf contract that nothing asserts is a
// perf contract that will be regressed.
func TestJSONContract_ShowOmitsOptInPayloadsByDefault(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
parent := w.create("--title", "Count-only parent", "--type", "epic", "--priority", "1")
child := w.create("--title", "Count-only child", "--type", "task", "--parent", parent)
w.run("comments", "add", parent, "First note")
// showOnce runs show --json with the given extra flags and returns the issue.
showOnce := func(flags ...string) map[string]any {
t.Helper()
out := w.run(append([]string{"show", parent, "--json"}, flags...)...)
items := parseJSONOutput(t, out)
if len(items) == 0 {
t.Fatalf("bd show %s --json %v returned no items", parent, flags)
}
return items[0]
}
// The arrays must be absent, not merely empty: an empty array would still
// mean the rows were materialized, which is the cost the flag exists to avoid.
assertAbsent := func(t *testing.T, issue map[string]any, key, context string) {
t.Helper()
if v, present := issue[key]; present {
t.Errorf("%s: show --json must omit %q, got %v", context, key, v)
}
}
t.Run("default_omits_both_arrays", func(t *testing.T) {
issue := showOnce()
assertAbsent(t, issue, "comments", "default payload")
assertAbsent(t, issue, "dependents", "default payload")
// The counts are what the default carries instead.
assertFieldFloat(t, issue, "comment_count", 1)
assertFieldFloat(t, issue, "dependent_count", 1)
})
t.Run("include_comments_does_not_drag_in_dependents", func(t *testing.T) {
issue := showOnce("--include-comments")
requireCommentTextsEqual(t, getObjectSlice(issue, "comments"),
[]string{"First note"}, "comments under --include-comments")
assertAbsent(t, issue, "dependents", "--include-comments")
})
t.Run("include_dependents_does_not_drag_in_comments", func(t *testing.T) {
issue := showOnce("--include-dependents")
dependents := getObjectSlice(issue, "dependents")
found := false
for _, dep := range dependents {
if id, _ := dep["id"].(string); id == child {
found = true
}
}
if !found {
t.Errorf("--include-dependents: parent %s does not list child %s (got %d dependents)",
parent, child, len(dependents))
}
assertAbsent(t, issue, "comments", "--include-dependents")
})
}
// TestJSONContract_ShowCommentsOmittedFlag pins the fix for ga-clgh: a positive
// comment_count with no "comments" key is a third state that neither of the two
// natural readings gets right — `.comments` absent reads as "none" (false), and
// comment_count alone gives no way to know the array was left out on purpose.
// comments_omitted closes that gap without touching the count-only default
// TestJSONContract_ShowOmitsOptInPayloadsByDefault protects.
func TestJSONContract_ShowCommentsOmittedFlag(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
withComments := w.create("--title", "Has comments")
w.run("comments", "add", withComments, "First note")
w.run("comments", "add", withComments, "Second note")
w.run("comments", "add", withComments, "Third note")
empty := w.create("--title", "No comments")
showOnce := func(id string, flags ...string) map[string]any {
t.Helper()
out := w.run(append([]string{"show", id, "--json"}, flags...)...)
items := parseJSONOutput(t, out)
if len(items) == 0 {
t.Fatalf("bd show %s --json %v returned no items", id, flags)
}
return items[0]
}
assertAbsent := func(t *testing.T, issue map[string]any, key, context string) {
t.Helper()
if v, present := issue[key]; present {
t.Errorf("%s: expected %q to be absent, got %v", context, key, v)
}
}
t.Run("mutation_default_flags_the_omission", func(t *testing.T) {
issue := showOnce(withComments)
assertAbsent(t, issue, "comments", "default payload")
assertFieldFloat(t, issue, "comment_count", 3)
omitted, present := issue["comments_omitted"]
if !present {
t.Fatal("default payload with comment_count=3: comments_omitted must be present and true")
}
if omitted != true {
t.Errorf("default payload with comment_count=3: comments_omitted = %v, want true", omitted)
}
})
t.Run("include_comments_clears_the_flag", func(t *testing.T) {
issue := showOnce(withComments, "--include-comments")
requireCommentTextsEqual(t, getObjectSlice(issue, "comments"),
[]string{"First note", "Second note", "Third note"}, "comments under --include-comments")
assertAbsent(t, issue, "comments_omitted", "--include-comments (nothing was left out)")
})
t.Run("regression_true_empty_stays_unflagged", func(t *testing.T) {
issue := showOnce(empty)
assertFieldFloat(t, issue, "comment_count", 0)
assertAbsent(t, issue, "comments", "zero-comment default payload")
assertAbsent(t, issue, "comments_omitted", "zero-comment payload (nothing was omitted)")
})
}
// TestJSONContract_ShowOutputIsArray pins the shape of bd show --json: a
// top-level JSON array with one element per requested ID, NOT a schema_version
// envelope. This is what the golden corpus commits (CATALOG.md: show =
// "array-of-one") and what wrapWithSchemaVersion does with a slice — it returns
// it bare, injecting schema_version only into object output.
//
// The shape is load-bearing for every consumer that parses show --json, so a
// change here is a breaking wire change, not a cleanup.
func TestJSONContract_ShowOutputIsArray(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
id1 := w.create("Array shape one")
id2 := w.create("Array shape two")
out := w.run("show", id1, id2, "--json")
var arr []map[string]any
if err := json.Unmarshal([]byte(out), &arr); err != nil {
t.Fatalf("bd show --json is not a top-level JSON array: %v\nOutput:\n%s", err, out)
}
if len(arr) != 2 {
t.Fatalf("bd show <id1> <id2> --json returned %d items, want 2\nOutput:\n%s", len(arr), out)
}
gotIDs := make([]string, 0, len(arr))
for _, item := range arr {
id, _ := item["id"].(string)
gotIDs = append(gotIDs, id)
if _, ok := item["schema_version"]; ok {
t.Errorf("bd show --json item %s carries schema_version; array-returning commands do not", id)
}
}
requireStringSetEqual(t, gotIDs, []string{id1, id2}, "bd show <id1> <id2> --json ids")
}
// TestJSONContract_ReadyOutputIsValidJSON verifies bd ready --json produces
// valid JSON even when no issues are ready.
func TestJSONContract_ReadyOutputIsValidJSON(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
out := w.run("ready", "--json")
var arr []map[string]any
if err := json.Unmarshal([]byte(out), &arr); err != nil {
t.Fatalf("bd ready --json produced invalid JSON: %v\nOutput:\n%s", err, out)
}
}
// TestJSONContract_CreateOutputHasID verifies bd create --json returns
// the created issue with its ID.
func TestJSONContract_CreateOutputHasID(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
out := w.run("create", "Create contract test", "--description=test", "--json")
var issue map[string]any
if err := json.Unmarshal([]byte(out), &issue); err != nil {
t.Fatalf("bd create --json produced invalid JSON: %v\nOutput:\n%s", err, out)
}
assertSchemaVersion(t, issue, "bd create --json")
if _, ok := issue["id"]; !ok {
t.Error("bd create --json output missing 'id' field")
}
}
// TestJSONContract_ErrorOutputIsValidJSON verifies that errors with --json
// produce valid JSON with schema_version to stderr (not mixed text).
func TestJSONContract_ErrorOutputIsValidJSON(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
// Try to show a nonexistent issue with --json
out, _ := w.runExpectError("show", "nonexistent-xyz-999", "--json")
// The output (stderr) should be valid JSON or empty
trimmed := strings.TrimSpace(out)
if trimmed == "" {
return // Empty is acceptable for errors
}
// Try to parse as JSON object
var errObj map[string]any
if err := json.Unmarshal([]byte(trimmed), &errObj); err != nil {
// Try each line — error JSON may be mixed with other stderr output
for _, line := range strings.Split(trimmed, "\n") {
line = strings.TrimSpace(line)
if line == "" {
continue
}
var lineObj map[string]any
if json.Unmarshal([]byte(line), &lineObj) == nil {
if _, hasError := lineObj["error"]; hasError {
assertSchemaVersion(t, lineObj, "bd error JSON line")
return
}
}
}
t.Logf("Note: error output not fully JSON — this is acceptable for some error paths")
} else {
if _, hasError := errObj["error"]; hasError {
assertSchemaVersion(t, errObj, "bd show error --json")
}
}
}
// TestJSONContract_CloseOutputHasStatus verifies bd close --json returns
// the updated issue with closed status.
func TestJSONContract_CloseOutputHasStatus(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
id := w.create("Close contract test")
out := w.run("close", id, "--json")
items := parseJSONOutput(t, out)
if len(items) == 0 {
t.Fatal("bd close --json returned no items")
}
assertField(t, items[0], "status", "closed")
}
// TestJSONContract_ReadyOutputHasFullObjects verifies bd ready --json returns
// full issue objects with dependency counts, not just IDs (beads-clt).
func TestJSONContract_ReadyOutputHasFullObjects(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
w.create("Ready full object test")
out := w.run("ready", "--json")
items := parseJSONOutput(t, out)
if len(items) == 0 {
t.Skip("no ready issues — create returned non-ready issue")
}
issue := items[0]
requiredFields := []string{"id", "title", "status", "priority", "dependency_count", "dependent_count"}
for _, field := range requiredFields {
if _, ok := issue[field]; !ok {
t.Errorf("bd ready --json item missing required field %q", field)
}
}
}
// TestJSONContract_BlockedOutputHasBlockedBy verifies bd blocked --json returns
// full issue objects with blocked_by field (beads-clt).
func TestJSONContract_BlockedOutputHasBlockedBy(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
blocker := w.create("Blocker issue")
blocked := w.create("Blocked issue")
w.run("dep", "add", blocked, blocker, "--type", "blocks")
out := w.run("blocked", "--json")
items := parseJSONOutput(t, out)
var found map[string]any
for _, item := range items {
if id, ok := item["id"].(string); ok && id == blocked {
found = item
break
}
}
if found == nil {
t.Fatalf("blocked issue %s not found in bd blocked --json output", blocked)
}
requiredFields := []string{"id", "title", "status", "blocked_by_count", "blocked_by"}
for _, field := range requiredFields {
if _, ok := found[field]; !ok {
t.Errorf("bd blocked --json item missing required field %q", field)
}
}
}
// TestJSONContract_PingOutputIsValidJSON verifies bd ping --json returns
// structured health check output with timing info.
func TestJSONContract_PingOutputIsValidJSON(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
out := w.run("ping", "--json")
var obj map[string]any
if err := json.Unmarshal([]byte(out), &obj); err != nil {
t.Fatalf("bd ping --json produced invalid JSON: %v\nOutput:\n%s", err, out)
}
assertSchemaVersion(t, obj, "bd ping --json")
if status, ok := obj["status"].(string); !ok || status != "ok" {
t.Errorf("bd ping --json status = %v, want ok", obj["status"])
}
if _, ok := obj["total_ms"]; !ok {
t.Error("bd ping --json missing total_ms field")
}
}
// TestJSONContract_SchemaVersionPresent verifies that schema_version is
// present in object-returning --json commands (create, ping).
// Array-returning commands (list, ready, show) do not include schema_version —
// see TestJSONContract_ShowOutputIsArray.
func TestJSONContract_SchemaVersionPresent(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
tests := []struct {
name string
args []string
}{
{"create", []string{"create", "Schema version test", "--json"}},
{"ping", []string{"ping", "--json"}},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
out := w.run(tt.args...)
var obj map[string]any
if err := json.Unmarshal([]byte(out), &obj); err != nil {
t.Fatalf("bd %s produced invalid JSON: %v\nOutput:\n%s",
tt.name, err, out)
}
assertSchemaVersion(t, obj, "bd "+tt.name+" --json")
})
}
}