* fix(cli): emit claim failures as structured JSON under --json (wy-kxgf4)
Protocol v0 §E5 requires that with --json, errors are emitted as a JSON
object carrying at least "error" and schema_version: 1. bd honored that on
the not-found path but not on the claim paths: `bd update <id> --claim
--json` printed
Error claiming t04...-qqr: issue already claimed by alice
as plain text on stderr, so an agent driving bd with --json got an
unparseable line for the single most common contended-write failure it has
to branch on. The §E4 message contract held (the class and the holder/state
are named); the §E5 structured contract did not.
Route both claim paths (the direct-store loop in update.go and the
SQL-server proxied path) through a new reportClaimFailure helper: under
--json it emits {error, schema_version:1} via jsonStderrError, otherwise the
plain-text wording is unchanged, byte for byte, since §E4 tests pin it. The
JSON object goes to stderr so a mixed batch's stdout stays the clean array
of the issues that did update; the stream split itself is proposal OQ-5 and
is not pinned.
Un-skips TestProtocol_ErrorClass_ClaimFailures_StructuredJSON, which was
written against the clause and skipped pending this fix; it now passes and
becomes the guardrail. Full cmd/bd/protocol package green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* test(protocol): pin claim refusals on the single --json batch report (wy-kxgf4)
Adopt-PR review fixup for #4756, iteration 1. It takes option (a) from
the review synthesis, which is also maphew's CHANGES_REQUESTED fix: drop
the eager per-claim JSON object and pin §E4/§E5 on main's centralized
batch report instead.
Major 1 (claude+codex, maphew's blocker). Under --json, a refused claim
printed two JSON documents on stderr: the indented reportClaimFailure
object, then reportUpdateFailures' compact {error, failed,
schema_version} summary. A consumer reading the whole stream, or main's
documented "last stderr line", did not get one document. Main has
already moved on (wy-ghg0d). That summary reports every per-id refusal,
and the refused id's failed[] entry already names the class and the
holder or state:
{"error":"1 of 1 issues failed to update","failed":[{"id":"…",
"error":"updating issue: issue already claimed by alice"}],
"schema_version":1}
So cmd/bd/errors.go, update.go and update_proxied_server.go go back to
base byte for byte. reportClaimFailure and its two call sites are gone,
and text output, stdout and exit codes are main's. That supersedes the
helper the contributor commit describes. The PR now changes only tests,
so its title and squash message should say so at finalize. This also
covers the commit-message nit.
Major 2 (the proxied claim arm was not gated on `claim`, so a proxied
--assignee fence refusal read "failed to claim") is moot: the object it
mislabelled no longer exists. Both routes report through the same
summary. The message-drift minor is moot too. So is the synthesis's
follow-up about the direct route's non-claim fence refusals under
--json: they already land in the same failed[] list. The remaining
"updating issue:" vs "claiming issue:" entry prefixes are pre-existing on
main.
TestProtocol_ErrorClass_ClaimFailures_StructuredJSON stays un-skipped
and is re-pinned. It now requires:
- exactly one top-level JSON error document (the new jsonErrorDocs steps
over each decoded object, so failed[] entries are not counted);
- §E5's error and schema_version on that document;
- a failed[] entry for the refused id that names "already claimed" and
"alice", or "not claimable" and "closed".
TestProxiedServerUpdate gains
claim_conflict_json_reports_holder_in_failed_entry, the proxied
guardrail the review found missing. Two test-gap asks are dropped
because they targeted the claim-only branch, which is gone: the
--assignee --json negative case, and --format json (which reaches the
same jsonOutput-keyed reporter).
Validation (local Dolt 2.2.0 server, scrubbed env):
- cmd/bd/protocol, whole package, with BEADS_PROTOCOL_REQUIRE_DOLT=1:
109 pass, 1 pre-existing PTY skip.
- Mutant (this PR's original errors.go, update.go and
update_proxied_server.go restored): the protocol test and the new
proxied subtest both fail on "2 JSON error documents"; both pass at
this head.
- TestProxiedServerUpdate (proxied-lane env): all subtests pass.
- TestParityUpdate* (including TestParityUpdateJSONFailureReport) and
TestMultiIDUpdate*: pass.
- make ci-pr-lint: 0 issues (native, windows, darwin).
Follow-up, not in this PR: typed claim-conflict fields in failed[]
(issueops.ClaimConflictError's holder and status), so consumers need
not match on message text.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
229 lines
9 KiB
Go
229 lines
9 KiB
Go
// errors_contract_test.go — protocol v0 §E (errors and exit codes), the
|
|
// error-class half.
|
|
//
|
|
// E4 (error classes). Implementations MUST distinguish, in message and
|
|
// structured output (NOT by exit code), at least: not-found, already-claimed
|
|
// (naming the holder), not-claimable (naming the state), and validation. The
|
|
// Go error values (storage.ErrAlreadyClaimed & co.) are accident; what an agent
|
|
// branches on is the message and the --json shape, so that is what these tests
|
|
// pin.
|
|
//
|
|
// E5 (structured errors). With --json, an error is a JSON object carrying at
|
|
// least "error" (message), optionally "hint", and schema_version: 1.
|
|
//
|
|
// E1/E2 (empty is success, failure is nonzero) are pinned in exit_codes_test.go
|
|
// and reinforced here: every error class below exits 1, none exits 0.
|
|
package protocol
|
|
|
|
import (
|
|
"strings"
|
|
"testing"
|
|
)
|
|
|
|
const (
|
|
actorAlice = "BEADS_ACTOR=alice"
|
|
actorBob = "BEADS_ACTOR=bob"
|
|
)
|
|
|
|
// isNotFound reports whether a message expresses the not-found class. The
|
|
// clause requires the CLASS to be recognizable, not one blessed phrase, so this
|
|
// tolerates both spellings an implementation is likely to use ("not found",
|
|
// "no issue found matching …") rather than freezing bd's current wording as
|
|
// though it were the protocol.
|
|
func isNotFound(msg string) bool {
|
|
lower := strings.ToLower(msg)
|
|
if strings.Contains(lower, "not found") {
|
|
return true
|
|
}
|
|
return (strings.Contains(lower, "no issue found") || strings.Contains(lower, "no issues found")) &&
|
|
strings.Contains(lower, "matching")
|
|
}
|
|
|
|
// TestProtocol_ErrorClass_NotFound pins the not-found class: a nonzero exit,
|
|
// a message that expresses not-found, and a structured --json error (§E5).
|
|
func TestProtocol_ErrorClass_NotFound(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
|
|
out, code := w.runExpectError("show", "nonexistent-xyz")
|
|
if code == 0 {
|
|
t.Errorf("exit code = 0, want nonzero (§E2)")
|
|
}
|
|
if !isNotFound(out) {
|
|
t.Errorf("message does not express the not-found class (§E4):\n%s", out)
|
|
}
|
|
if !strings.Contains(out, "nonexistent-xyz") {
|
|
t.Errorf("not-found message does not name the missing id (§E4):\n%s", out)
|
|
}
|
|
|
|
jsonOut, jsonCode := w.runExpectError("show", "nonexistent-xyz", "--json")
|
|
if jsonCode == 0 {
|
|
t.Errorf("--json exit code = 0, want nonzero (§E2)")
|
|
}
|
|
obj := requireJSONError(t, jsonOut, "not-found --json")
|
|
if !isNotFound(errorMessage(obj)) {
|
|
t.Errorf("--json error message does not express the not-found class (§E4/§E5): %q", errorMessage(obj))
|
|
}
|
|
}
|
|
|
|
// TestProtocol_ErrorClass_AlreadyClaimedNamesHolder pins the already-claimed
|
|
// class (§E4, §L2.4): claiming an issue another actor holds must fail with a
|
|
// message that NAMES THE HOLDER — an agent that cannot see who holds the claim
|
|
// cannot decide whether to wait, escalate, or move on.
|
|
func TestProtocol_ErrorClass_AlreadyClaimedNamesHolder(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
id := w.create("Contended issue")
|
|
|
|
w.runEnv([]string{actorAlice}, "update", id, "--claim")
|
|
|
|
out, code := w.runEnvExpectError([]string{actorBob}, "update", id, "--claim")
|
|
if code == 0 {
|
|
t.Errorf("exit code = 0, want nonzero (§L2.4)")
|
|
}
|
|
lower := strings.ToLower(out)
|
|
if !strings.Contains(lower, "already claimed") {
|
|
t.Errorf("message does not identify the already-claimed class (§E4):\n%s", out)
|
|
}
|
|
if !strings.Contains(out, "alice") {
|
|
t.Errorf("message does not name the holder (§E4/§L2.4):\n%s", out)
|
|
}
|
|
}
|
|
|
|
// TestProtocol_ErrorClass_NotClaimableNamesState pins the not-claimable class
|
|
// (§E4): claiming an issue that is in a non-claimable STATE (here: closed) is a
|
|
// different failure from already-claimed, and the message must name the state.
|
|
// Distinguishing the two is the whole point of the clause — "retry later" is
|
|
// right for a contended claim and wrong for a closed issue.
|
|
func TestProtocol_ErrorClass_NotClaimableNamesState(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
id := w.create("Closed issue")
|
|
w.run("close", id)
|
|
|
|
out, code := w.runEnvExpectError([]string{actorBob}, "update", id, "--claim")
|
|
if code == 0 {
|
|
t.Errorf("exit code = 0, want nonzero (§E2)")
|
|
}
|
|
lower := strings.ToLower(out)
|
|
if !strings.Contains(lower, "not claimable") {
|
|
t.Errorf("message does not identify the not-claimable class (§E4):\n%s", out)
|
|
}
|
|
if !strings.Contains(lower, "closed") {
|
|
t.Errorf("message does not name the blocking state (§E4):\n%s", out)
|
|
}
|
|
}
|
|
|
|
// TestProtocol_ErrorClass_ClaimFailures_StructuredJSON is the §E5 half of the
|
|
// claim error classes: a lost claim is the most common contended-write failure
|
|
// an agent driving bd with --json has to branch on, so its class must be
|
|
// readable from a JSON document and not only from a stderr line to scrape. bd
|
|
// update reports per-id refusals in one batch document, so the class and the
|
|
// holder/state live in the refused id's "failed" entry; the top-level "error"
|
|
// is the batch summary. The document count is pinned as well: a second,
|
|
// per-claim object beside the batch report would hand a consumer two
|
|
// concatenated documents (wy-kxgf4). The stream (stdout vs stderr) is
|
|
// deliberately not pinned — that split is proposal OQ-5.
|
|
func TestProtocol_ErrorClass_ClaimFailures_StructuredJSON(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
|
|
claimed := w.create("Held by alice")
|
|
w.runEnv([]string{actorAlice}, "update", claimed, "--claim")
|
|
|
|
closed := w.create("Closed")
|
|
w.run("close", closed)
|
|
|
|
// already-claimed: structured, and still naming the holder.
|
|
out, _ := w.runEnvExpectError([]string{actorBob}, "update", claimed, "--claim", "--json")
|
|
msg := requireFailedEntry(t, out, claimed, "already-claimed --json")
|
|
if !strings.Contains(strings.ToLower(msg), "already claimed") || !strings.Contains(msg, "alice") {
|
|
t.Errorf("--json failed entry does not name class + holder (§E4/§E5): %q", msg)
|
|
}
|
|
|
|
// not-claimable: structured, and still naming the state.
|
|
out, _ = w.runEnvExpectError([]string{actorBob}, "update", closed, "--claim", "--json")
|
|
msg = requireFailedEntry(t, out, closed, "not-claimable --json")
|
|
if lower := strings.ToLower(msg); !strings.Contains(lower, "not claimable") || !strings.Contains(lower, "closed") {
|
|
t.Errorf("--json failed entry does not name class + state (§E4/§E5): %q", msg)
|
|
}
|
|
}
|
|
|
|
// TestProtocol_ErrorClass_Validation pins the validation class (§E4): a
|
|
// malformed argument fails with a message about the argument, and is NOT
|
|
// reported as a not-found.
|
|
func TestProtocol_ErrorClass_Validation(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
id := w.create("Valid issue")
|
|
|
|
out, code := w.runExpectError("update", id, "--status", "not_a_status")
|
|
if code == 0 {
|
|
t.Errorf("exit code = 0, want nonzero (§E2)")
|
|
}
|
|
lower := strings.ToLower(out)
|
|
if !strings.Contains(lower, "status") {
|
|
t.Errorf("validation message does not name the offending input (§E4):\n%s", out)
|
|
}
|
|
if strings.Contains(lower, "not found") {
|
|
t.Errorf("validation failure misreported as not-found (§E4):\n%s", out)
|
|
}
|
|
}
|
|
|
|
// TestProtocol_ErrorClasses_AreDistinguishable is the clause itself (§E4): the
|
|
// three claim-adjacent failures — not-found, already-claimed, not-claimable —
|
|
// must be told apart from the message alone. Exit codes deliberately do NOT
|
|
// distinguish them in v0 (§E2), so if the messages collapse, an agent has
|
|
// nothing left to branch on.
|
|
func TestProtocol_ErrorClasses_AreDistinguishable(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
|
|
claimed := w.create("Held by alice")
|
|
w.runEnv([]string{actorAlice}, "update", claimed, "--claim")
|
|
|
|
closed := w.create("Closed")
|
|
w.run("close", closed)
|
|
|
|
notFoundOut, notFoundCode := w.runExpectError("update", "nonexistent-xyz", "--claim")
|
|
claimedOut, claimedCode := w.runEnvExpectError([]string{actorBob}, "update", claimed, "--claim")
|
|
closedOut, closedCode := w.runEnvExpectError([]string{actorBob}, "update", closed, "--claim")
|
|
|
|
// §E2: all three fail nonzero. §E4: none of them may be told apart by the
|
|
// exit code — the message carries the class.
|
|
for name, code := range map[string]int{
|
|
"not-found": notFoundCode,
|
|
"already-claimed": claimedCode,
|
|
"not-claimable": closedCode,
|
|
} {
|
|
if code == 0 {
|
|
t.Errorf("%s: exit code = 0, want nonzero (§E2)", name)
|
|
}
|
|
}
|
|
|
|
// Each class is recognized by its own predicate, and must be recognized by
|
|
// EXACTLY one: a message that reads as two classes at once (or as none) is
|
|
// as useless to an agent as a shared exit code.
|
|
recognizers := map[string]func(string) bool{
|
|
"not-found": isNotFound,
|
|
"already-claimed": func(s string) bool { return strings.Contains(strings.ToLower(s), "already claimed") },
|
|
"not-claimable": func(s string) bool { return strings.Contains(strings.ToLower(s), "not claimable") },
|
|
}
|
|
outputs := map[string]string{
|
|
"not-found": notFoundOut,
|
|
"already-claimed": claimedOut,
|
|
"not-claimable": closedOut,
|
|
}
|
|
for class, out := range outputs {
|
|
var matched []string
|
|
for name, recognize := range recognizers {
|
|
if recognize(out) {
|
|
matched = append(matched, name)
|
|
}
|
|
}
|
|
if len(matched) != 1 || matched[0] != class {
|
|
t.Errorf("%s failure is recognized as %v, want exactly [%s] — the classes are not distinguishable from the message (§E4):\n%s",
|
|
class, matched, class, out)
|
|
}
|
|
}
|
|
}
|