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