From 2e7637757faecaf81f198301122bd50afea681bc Mon Sep 17 00:00:00 2001 From: Bee Date: Tue, 6 Oct 2026 22:46:47 +0000 Subject: [PATCH] fix(ready): --explain sorts a ready issue's blocking edges by status instead of calling a pinned dependency resolved (#7124) * fix(ready): --explain sorts a ready issue's blocking edges by status instead of calling a pinned dependency resolved (wy-0h6t03) The ready query skips a pinned target exactly as it skips a closed one, so a blocks edge onto a pinned bead never fences its dependent. The explanation never read the target's status: every blocking edge of a ready issue was appended to ResolvedBlockers, so a bead wired behind a long-lived pinned bring-up reported "1 blocker(s) resolved" while its precondition was unmet. Two trials sat on a takeable front for days that way. BuildReadyExplanation now sorts each blocks / conditional-blocks / waits-for edge by the target's status in blockerMap: closed stays under ResolvedBlockers, pinned goes to PinnedDependencies (never block), any other status to OpenDependencies (not blocking; the #6066 shape, now visible). A target without a status in the map keeps the old treatment. Reason keeps its "N blocker(s) resolved" lead and appends the other two counts as clauses. Both explain routes previously fetched only the blockers of blocked issues, so no ready target ever had a status; explainBlockerIDs now adds the ready issues' blocking-dependency targets to that one batch fetch, once each, and printReadyItemDependencies prints the three lines for both routes. Pinned-never-blocks itself is unchanged. Co-Authored-By: Claude Fable 5.1 * build(bazel): list ready_explain_ids_test.go in the cmd/bd go_test srcs (wy-0h6t03) The equivalence gate named TestExplainBlockerIDs and TestExplainBlockerIDs_Empty as tests go test runs that Bazel did not: the new test file was never added to BUILD.bazel. Co-Authored-By: Claude Fable 5.1 --------- Co-authored-by: Claude Fable 5.1 --- CHANGELOG.md | 16 +++++ cmd/bd/BUILD.bazel | 1 + cmd/bd/ready.go | 65 ++++++++++++++----- cmd/bd/ready_explain_ids_test.go | 50 +++++++++++++++ cmd/bd/ready_proxied_server.go | 15 +---- internal/types/explain_test.go | 103 +++++++++++++++++++++++++++++++ internal/types/types.go | 84 +++++++++++++++++++------ 7 files changed, 289 insertions(+), 45 deletions(-) create mode 100644 cmd/bd/ready_explain_ids_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 6f9d51dab..66ce69feb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -144,6 +144,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 is still ridden out within one command. A backend that drops a connection after the greeting, a dial timeout, and every refusal from a managed (local sidecar) backend keep the full transient retry. +- **`bd ready --explain` no longer reports a pinned dependency as a resolved + blocker.** The ready query skips a pinned target exactly as it skips a closed + one, so a `blocks` edge onto a pinned bead never fences its dependent — but + the explanation listed every blocking edge of a ready issue under + `Resolved blockers`, status unread, and a bead wired behind a long-lived + pinned bring-up reported itself satisfied while its precondition was unmet. + Each blocking edge is now sorted by the target's status: closed under + `Resolved blockers` (and `resolved_blockers`), pinned under + `Pinned dependencies (never block)` (`pinned_dependencies`), and any other + status under `Open dependencies (not blocking)` (`open_dependencies`) — the + shape #6066 reports for a foreign-prefix blocker, now visible instead of + passing as resolved. `Reason` keeps its `N blocker(s) resolved` lead and + appends the pinned and open counts as clauses. Both routes fetch the ready + issues' dependency targets alongside the blockers they already fetched. + Pinned-never-blocks itself is unchanged. + - **`bd list` no longer silently drops all but the last repeated filter flag.** `--status`, `--state`, and `--id` were plain string flags, so `bd list --status open --status closed --status pinned` kept only `pinned` — diff --git a/cmd/bd/BUILD.bazel b/cmd/bd/BUILD.bazel index 4305927a5..765e55702 100644 --- a/cmd/bd/BUILD.bazel +++ b/cmd/bd/BUILD.bazel @@ -1026,6 +1026,7 @@ go_test( "readonly_policy_test.go", "readonly_test.go", "ready_embedded_test.go", + "ready_explain_ids_test.go", "ready_input_test.go", "ready_max_rows_proxied_test.go", "ready_max_rows_test.go", diff --git a/cmd/bd/ready.go b/cmd/bd/ready.go index 71b1e8f22..babcefa35 100644 --- a/cmd/bd/ready.go +++ b/cmd/bd/ready.go @@ -554,17 +554,11 @@ func runReadyExplain(_ *cobra.Command) error { debug.Logf("warning: failed to detect cycles: %v", err) } - // Collect all blocker IDs to batch-fetch blocker details - allBlockerIDs := make(map[string]bool) - for _, bi := range blockedIssues { - for _, blockerID := range bi.BlockedBy { - allBlockerIDs[blockerID] = true - } - } - blockerIDList := make([]string, 0, len(allBlockerIDs)) - for id := range allBlockerIDs { - blockerIDList = append(blockerIDList, id) - } + // Collect all blocker IDs to batch-fetch blocker details: the blockers + // of blocked issues, plus the blocking-dependency targets of the ready + // issues, whose status decides whether --explain reports each as + // resolved, pinned or open. + blockerIDList := explainBlockerIDs(blockedIssues, readyIssues, allDeps) // Build ready items with explanations // TODO(batchgetter): unbounded id list; see issueops.BatchGetter's doc and @@ -596,9 +590,7 @@ func runReadyExplain(_ *cobra.Command) error { ui.RenderPriority(item.Priority), item.Title) fmt.Printf(" Reason: %s\n", item.Reason) - if len(item.ResolvedBlockers) > 0 { - fmt.Printf(" Resolved blockers: %s\n", strings.Join(item.ResolvedBlockers, ", ")) - } + printReadyItemDependencies(item) if item.DependentCount > 0 { fmt.Printf(" Unblocks: %d issue(s)\n", item.DependentCount) } @@ -808,3 +800,48 @@ func init() { blockedCmd.Flags().StringSlice("exclude-label", []string{}, "Exclude issues that have ANY of these labels") rootCmd.AddCommand(blockedCmd) } + +// explainBlockerIDs collects, once each, the ids whose status --explain +// needs: every blocker of a blocked issue, and the target of every blocking +// dependency (blocks, conditional-blocks, waits-for) of a ready issue. The +// ready targets matter because the ready query admits an issue whose blocking +// targets are closed OR pinned, and only the target's status tells the +// explanation which of the two it saw. +func explainBlockerIDs(blockedIssues []*types.BlockedIssue, readyIssues []*types.Issue, allDeps map[string][]*types.Dependency) []string { + seen := make(map[string]bool) + var ids []string + add := func(id string) { + if id == "" || seen[id] { + return + } + seen[id] = true + ids = append(ids, id) + } + for _, bi := range blockedIssues { + for _, blockerID := range bi.BlockedBy { + add(blockerID) + } + } + for _, issue := range readyIssues { + for _, dep := range allDeps[issue.ID] { + if dep.Type == types.DepBlocks || dep.Type == types.DepConditionalBlocks || dep.Type == types.DepWaitsFor { + add(dep.DependsOnID) + } + } + } + return ids +} + +// printReadyItemDependencies prints the three dependency lines of a ready +// item in --explain's text form, each only when non-empty. +func printReadyItemDependencies(item types.ReadyItem) { + if len(item.ResolvedBlockers) > 0 { + fmt.Printf(" Resolved blockers: %s\n", strings.Join(item.ResolvedBlockers, ", ")) + } + if len(item.PinnedDependencies) > 0 { + fmt.Printf(" Pinned dependencies (never block): %s\n", strings.Join(item.PinnedDependencies, ", ")) + } + if len(item.OpenDependencies) > 0 { + fmt.Printf(" Open dependencies (not blocking): %s\n", strings.Join(item.OpenDependencies, ", ")) + } +} diff --git a/cmd/bd/ready_explain_ids_test.go b/cmd/bd/ready_explain_ids_test.go new file mode 100644 index 000000000..fddac35a8 --- /dev/null +++ b/cmd/bd/ready_explain_ids_test.go @@ -0,0 +1,50 @@ +package main + +import ( + "testing" + + "github.com/steveyegge/beads/internal/types" +) + +// explainBlockerIDs must hand the explanation every id whose status it +// reads: the blockers of blocked issues AND the blocking-dependency targets of +// ready issues (the ones whose closed-or-pinned status the ready query +// collapsed), once each, and no parent-child or related target. +func TestExplainBlockerIDs(t *testing.T) { + blocked := []*types.BlockedIssue{ + {Issue: types.Issue{ID: "bd-b1"}, BlockedBy: []string{"bd-x", "bd-y"}}, + {Issue: types.Issue{ID: "bd-b2"}, BlockedBy: []string{"bd-y", ""}}, + } + ready := []*types.Issue{{ID: "bd-r1"}, {ID: "bd-r2"}} + allDeps := map[string][]*types.Dependency{ + "bd-r1": { + {IssueID: "bd-r1", DependsOnID: "bd-pinned", Type: types.DepBlocks}, + {IssueID: "bd-r1", DependsOnID: "bd-x", Type: types.DepConditionalBlocks}, + {IssueID: "bd-r1", DependsOnID: "bd-epic", Type: types.DepParentChild}, + }, + "bd-r2": { + {IssueID: "bd-r2", DependsOnID: "bd-spawner", Type: types.DepWaitsFor}, + {IssueID: "bd-r2", DependsOnID: "bd-rel", Type: types.DepRelated}, + }, + "bd-not-ready": { + {IssueID: "bd-not-ready", DependsOnID: "bd-elsewhere", Type: types.DepBlocks}, + }, + } + + got := explainBlockerIDs(blocked, ready, allDeps) + want := []string{"bd-x", "bd-y", "bd-pinned", "bd-spawner"} + if len(got) != len(want) { + t.Fatalf("explainBlockerIDs = %v, want %v", got, want) + } + for i := range want { + if got[i] != want[i] { + t.Fatalf("explainBlockerIDs = %v, want %v", got, want) + } + } +} + +func TestExplainBlockerIDs_Empty(t *testing.T) { + if got := explainBlockerIDs(nil, nil, nil); len(got) != 0 { + t.Fatalf("expected no ids, got %v", got) + } +} diff --git a/cmd/bd/ready_proxied_server.go b/cmd/bd/ready_proxied_server.go index 97180dee8..30a815f32 100644 --- a/cmd/bd/ready_proxied_server.go +++ b/cmd/bd/ready_proxied_server.go @@ -320,16 +320,7 @@ func runReadyProxiedExplain(ctx context.Context, uw uow.UnitOfWork, _ readyInput debug.Logf("warning: failed to detect cycles: %v", err) } - allBlockerIDs := make(map[string]bool) - for _, bi := range blockedIssues { - for _, blockerID := range bi.BlockedBy { - allBlockerIDs[blockerID] = true - } - } - blockerIDList := make([]string, 0, len(allBlockerIDs)) - for id := range allBlockerIDs { - blockerIDList = append(blockerIDList, id) - } + blockerIDList := explainBlockerIDs(blockedIssues, readyIssues, allDeps) // TODO(batchgetter): unbounded id list; see issueops.BatchGetter's doc and // the importIssueLookup TODO in import_shared.go for why this is not yet // routed through GetMany. @@ -365,9 +356,7 @@ func runReadyProxiedExplain(ctx context.Context, uw uow.UnitOfWork, _ readyInput ui.RenderPriority(item.Priority), item.Title) fmt.Printf(" Reason: %s\n", item.Reason) - if len(item.ResolvedBlockers) > 0 { - fmt.Printf(" Resolved blockers: %s\n", strings.Join(item.ResolvedBlockers, ", ")) - } + printReadyItemDependencies(item) if item.DependentCount > 0 { fmt.Printf(" Unblocks: %d issue(s)\n", item.DependentCount) } diff --git a/internal/types/explain_test.go b/internal/types/explain_test.go index bd8c2b0ee..bf1500bc0 100644 --- a/internal/types/explain_test.go +++ b/internal/types/explain_test.go @@ -62,6 +62,9 @@ func TestBuildReadyExplanation_ReadyWithResolvedBlockers(t *testing.T) { }, } + // A nil blockerMap supplies no statuses: the ready set's verdict is the + // only word, so every blocking edge counts as resolved (the pre-#6066 + // shape, kept for callers that fetch nothing). result := BuildReadyExplanation(issues, nil, depCounts, allDeps, nil, nil) if len(result.Ready) != 1 { @@ -75,6 +78,9 @@ func TestBuildReadyExplanation_ReadyWithResolvedBlockers(t *testing.T) { if len(item.ResolvedBlockers) != 2 { t.Errorf("expected 2 resolved blockers, got %d", len(item.ResolvedBlockers)) } + if len(item.PinnedDependencies) != 0 || len(item.OpenDependencies) != 0 { + t.Errorf("expected no pinned/open dependencies without statuses, got %v / %v", item.PinnedDependencies, item.OpenDependencies) + } if item.DependencyCount != 2 { t.Errorf("expected DependencyCount=2, got %d", item.DependencyCount) } @@ -83,6 +89,103 @@ func TestBuildReadyExplanation_ReadyWithResolvedBlockers(t *testing.T) { } } +// A ready issue's blocking edges are sorted by the target's status: closed is +// a resolved blocker, pinned never blocked (the ready query skips pinned +// targets as it skips closed ones), anything else is an open dependency the +// ready set admitted anyway. Before this every edge printed as "resolved", +// so a dependency wired onto a pinned bead reported itself satisfied. +func TestBuildReadyExplanation_ReadyDependencyStatuses(t *testing.T) { + issues := []*Issue{ + {ID: "bd-1", Title: "Ready", Priority: 1, Status: StatusOpen}, + } + allDeps := map[string][]*Dependency{ + "bd-1": { + {IssueID: "bd-1", DependsOnID: "bd-closed", Type: DepBlocks}, + {IssueID: "bd-1", DependsOnID: "bd-pinned", Type: DepBlocks}, + {IssueID: "bd-1", DependsOnID: "bd-open", Type: DepBlocks}, + {IssueID: "bd-1", DependsOnID: "bd-spawner", Type: DepWaitsFor}, + {IssueID: "bd-1", DependsOnID: "bd-unknown", Type: DepConditionalBlocks}, + {IssueID: "bd-1", DependsOnID: "bd-epic", Type: DepParentChild}, + {IssueID: "bd-1", DependsOnID: "bd-related", Type: DepRelated}, + }, + } + blockerMap := map[string]*Issue{ + "bd-closed": {ID: "bd-closed", Status: StatusClosed}, + "bd-pinned": {ID: "bd-pinned", Status: StatusPinned}, + "bd-open": {ID: "bd-open", Status: StatusOpen}, + "bd-spawner": {ID: "bd-spawner", Status: StatusInProgress}, + "bd-epic": {ID: "bd-epic", Status: StatusOpen}, + } + + result := BuildReadyExplanation(issues, nil, nil, allDeps, blockerMap, nil) + if len(result.Ready) != 1 { + t.Fatalf("expected 1 ready item, got %d", len(result.Ready)) + } + item := result.Ready[0] + + // bd-unknown has no status in the map and so joins the resolved set. + assertIDs(t, "ResolvedBlockers", item.ResolvedBlockers, "bd-closed", "bd-unknown") + assertIDs(t, "PinnedDependencies", item.PinnedDependencies, "bd-pinned") + assertIDs(t, "OpenDependencies", item.OpenDependencies, "bd-open", "bd-spawner") + want := "2 blocker(s) resolved; 1 pinned dependency(ies), never blocking; 2 open dependency(ies), not blocking" + if item.Reason != want { + t.Errorf("reason:\n got %q\nwant %q", item.Reason, want) + } + if item.Parent == nil || *item.Parent != "bd-epic" { + t.Errorf("expected Parent=bd-epic, got %v", item.Parent) + } +} + +// Only pinned edges: the reason must not claim anything was resolved. +func TestBuildReadyExplanation_ReadyWithOnlyPinnedDependency(t *testing.T) { + issues := []*Issue{{ID: "bd-1", Title: "Ready", Priority: 1, Status: StatusOpen}} + allDeps := map[string][]*Dependency{ + "bd-1": {{IssueID: "bd-1", DependsOnID: "bd-pinned", Type: DepBlocks}}, + } + blockerMap := map[string]*Issue{"bd-pinned": {ID: "bd-pinned", Status: StatusPinned}} + + item := BuildReadyExplanation(issues, nil, nil, allDeps, blockerMap, nil).Ready[0] + if item.Reason != "1 pinned dependency(ies), never blocking" { + t.Errorf("unexpected reason %q", item.Reason) + } + if len(item.ResolvedBlockers) != 0 { + t.Errorf("expected no resolved blockers, got %v", item.ResolvedBlockers) + } + assertIDs(t, "PinnedDependencies", item.PinnedDependencies, "bd-pinned") +} + +func TestReadyReason(t *testing.T) { + cases := []struct { + resolved, pinned, open int + want string + }{ + {0, 0, 0, "no blocking dependencies"}, + {2, 0, 0, "2 blocker(s) resolved"}, + {0, 1, 0, "1 pinned dependency(ies), never blocking"}, + {0, 0, 3, "3 open dependency(ies), not blocking"}, + {1, 1, 1, "1 blocker(s) resolved; 1 pinned dependency(ies), never blocking; 1 open dependency(ies), not blocking"}, + } + for _, c := range cases { + if got := readyReason(c.resolved, c.pinned, c.open); got != c.want { + t.Errorf("readyReason(%d,%d,%d) = %q, want %q", c.resolved, c.pinned, c.open, got, c.want) + } + } +} + +func assertIDs(t *testing.T, field string, got []string, want ...string) { + t.Helper() + if len(got) != len(want) { + t.Errorf("%s = %v, want %v", field, got, want) + return + } + for i := range want { + if got[i] != want[i] { + t.Errorf("%s = %v, want %v", field, got, want) + return + } + } +} + func TestBuildReadyExplanation_ReadyWithParent(t *testing.T) { issues := []*Issue{ {ID: "bd-child", Title: "Child task", Priority: 2, Status: StatusOpen}, diff --git a/internal/types/types.go b/internal/types/types.go index d92838761..88a276cb2 100644 --- a/internal/types/types.go +++ b/internal/types/types.go @@ -1869,13 +1869,26 @@ type ReadyExplanation struct { } // ReadyItem explains why a specific issue is ready for work. +// +// The issue's blocking dependencies (blocks, conditional-blocks, waits-for) +// are sorted by the target's status as the caller supplied it in blockerMap: +// ResolvedBlockers holds closed targets, PinnedDependencies holds pinned ones +// (a pinned bead never blocks, so a dependency on one never fenced this +// issue — it is reported as what it is, not as a blocker that was resolved), +// and OpenDependencies holds targets in any other status — a blocks edge +// here means the ready set and the edge disagree (foreign-prefix ids, #6066); +// a waits-for edge here is the ordinary spawner-still-open case. A target the +// caller did not supply a status for is counted under ResolvedBlockers, the +// ready set's own verdict being the only word available. type ReadyItem struct { *Issue - Reason string `json:"reason"` - ResolvedBlockers []string `json:"resolved_blockers"` - DependencyCount int `json:"dependency_count"` - DependentCount int `json:"dependent_count"` - Parent *string `json:"parent,omitempty"` + Reason string `json:"reason"` + ResolvedBlockers []string `json:"resolved_blockers"` + PinnedDependencies []string `json:"pinned_dependencies,omitempty"` + OpenDependencies []string `json:"open_dependencies,omitempty"` + DependencyCount int `json:"dependency_count"` + DependentCount int `json:"dependent_count"` + Parent *string `json:"parent,omitempty"` } // BlockedItem explains why a specific issue is blocked. @@ -1918,18 +1931,29 @@ func BuildReadyExplanation( counts = &DependencyCounts{} } - // Find resolved blockers (closed issues that this depended on) - var resolvedBlockers []string - reason := "no blocking dependencies" + // Sort the blocking dependencies by the target's status. Before this + // every blocking edge of a ready issue was printed as a resolved + // blocker, which is wrong for a pinned target: the ready query skips + // pinned targets exactly as it skips closed ones, so a dependency on + // a pinned bead never blocked anything and nothing about it was + // resolved. --explain is the one place a reader can see that. + var resolvedBlockers, pinnedDeps, openDeps []string deps := allDeps[issue.ID] for _, dep := range deps { - if dep.Type == DepBlocks || dep.Type == DepConditionalBlocks || dep.Type == DepWaitsFor { + if dep.Type != DepBlocks && dep.Type != DepConditionalBlocks && dep.Type != DepWaitsFor { + continue + } + target, known := blockerMap[dep.DependsOnID] + switch { + case !known || target == nil || target.Status == StatusClosed: resolvedBlockers = append(resolvedBlockers, dep.DependsOnID) + case target.Status == StatusPinned: + pinnedDeps = append(pinnedDeps, dep.DependsOnID) + default: + openDeps = append(openDeps, dep.DependsOnID) } } - if len(resolvedBlockers) > 0 { - reason = fmt.Sprintf("%d blocker(s) resolved", len(resolvedBlockers)) - } + reason := readyReason(len(resolvedBlockers), len(pinnedDeps), len(openDeps)) // Compute parent var parent *string @@ -1941,12 +1965,14 @@ func BuildReadyExplanation( } readyItems = append(readyItems, ReadyItem{ - Issue: issue, - Reason: reason, - ResolvedBlockers: resolvedBlockers, - DependencyCount: counts.DependencyCount, - DependentCount: counts.DependentCount, - Parent: parent, + Issue: issue, + Reason: reason, + ResolvedBlockers: resolvedBlockers, + PinnedDependencies: pinnedDeps, + OpenDependencies: openDeps, + DependencyCount: counts.DependencyCount, + DependentCount: counts.DependentCount, + Parent: parent, }) } @@ -1992,6 +2018,28 @@ func BuildReadyExplanation( } } +// readyReason words a ReadyItem's Reason from the three dependency counts. +// "no blocking dependencies" is kept verbatim for the no-edge case; a resolved +// count keeps the historical "N blocker(s) resolved" lead so scripts that +// match on it still do; pinned and open counts are appended as clauses rather +// than folded into the resolved count. +func readyReason(resolved, pinned, open int) string { + var parts []string + if resolved > 0 { + parts = append(parts, fmt.Sprintf("%d blocker(s) resolved", resolved)) + } + if pinned > 0 { + parts = append(parts, fmt.Sprintf("%d pinned dependency(ies), never blocking", pinned)) + } + if open > 0 { + parts = append(parts, fmt.Sprintf("%d open dependency(ies), not blocking", open)) + } + if len(parts) == 0 { + return "no blocking dependencies" + } + return strings.Join(parts, "; ") +} + // TreeNode represents a node in a dependency tree type TreeNode struct { Issue