beads/issueops/reader_ready_scope.go
Vishnu J f5a20fb66b
fix(list): honor --status when combined with --ready (#5924)
* fix(list): honor --status when combined with --ready (#5832)

`bd list --status X --ready` silently dropped --status and returned the
unfiltered ready set (typically open issues). BuildListFilter pinned
StatusOpen whenever ReadyFlag was set, and ReadyFilterFromIssueFilter
hard-coded the same pin, so a custom status or in_progress selector
never reached GetReadyWork.

--ready without --status still defaults to open. An explicit --status
is now the ready-work status selector, matching how other list filters
already compose with --ready. `--status all` remains the no-filter
spelling and keeps the open default.

* fix(list): status-aware --ready footer and honor-path contract docs (#5832)

The query intersection from the prior commit is unchanged. Round-1
review asked the ReadyFlag/Statuses contract comments and the text
footer to describe the honor path: default --ready is still open,
an explicit --status is named instead of "excludes in_progress".
2026-09-02 18:12:07 -07:00

133 lines
7.3 KiB
Go

package issueops
import (
"fmt"
"strings"
)
// readyScopeField is one ListRequest field the ReadyFlag arm cannot carry,
// paired with the `bd list` flag that sets it. Naming both is the point of the
// refusal: a library caller looks for the struct field and a CLI caller for
// the flag, and neither should have to map one onto the other to learn which
// part of their request could not be honored.
type readyScopeField struct {
name string
flag string
set func(ListRequest) bool
}
// readyScopeFields is the drop set: every field a list request can set that
// does not survive the trip to the blocker-aware ready query.
//
// It was read off the two functions between this request and that query —
// internal/workapi.BuildListFilter, which turns the request into a storage
// filter, and internal/workapi.ReadyFilterFromIssueFilter, which projects that
// filter onto the narrower ready-work filter — and it is exactly the
// intersection: fields the builder copies onto the filter and the projection
// then discards.
//
// Four groups are deliberately ABSENT, because listing them here would refuse
// requests that are answered correctly today:
//
// - What the projection carries: Status/Statuses (GH#5832), IssueType, all five label forms, Assignee,
// NoAssignee, the exact Priority, ParentID, MolType, WispType,
// MetadataFields, HasMetadataKey, ExcludeTypes (and with it IncludeGates
// and IncludeInfra's type suppression), IncludeEphemeral (and with it
// IncludeInfra's plane half, which the ready query admits through its own
// ephemeral gate), Limit, Offset, and the MaxRows cap with its
// attribution.
//
// - THE HYDRATION KNOBS, SkipLabels and SkipCounts. They are the one group
// the "exactly the intersection" rule above would otherwise sweep in: the
// builder does copy them onto the filter and the projection does discard
// them. They stay out because they select what is HYDRATED rather than
// which rows match, so a ReadyFlag request that sets one is answered with
// the rows it asked for and merely pays for a column it did not want.
// Refusing that would be refusing a correct answer over its cost, and the
// promise is already stated where a caller reads it (ListRequest.ReadyFlag).
//
// - AllFlag, and `--status all`. The builder resolves both to "open" under
// ReadyFlag before the projection ever runs (`all` is the no-filter
// spelling). An explicit --status is carried: BuildListFilter writes it
// onto IssueFilter and ReadyFilterFromIssueFilter copies Status/Statuses
// onto the ready-work filter, so `bd list --status X --ready` is the
// intersection rather than the unfiltered ready set (GH#5832). Status is
// therefore ABSENT from this drop set because it is honored, not because
// it is overridden. The default-open pin is the golden
// `ready_flag` case; the honor path is `ready_flag_honors_status`.
//
// - NoPinnedFlag. Pinned is dropped by the projection, but the ready-work
// WHERE clause excludes pinned rows unconditionally
// (internal/storage/sqlbuild/ready.go), so a caller who asks for the
// pinned rows to be left out gets exactly that. The opposite request,
// PinnedFlag, asks for pinned rows only and would be answered with a set
// that can never contain one — it is in the list below.
var readyScopeFields = []readyScopeField{
{"IDFilter", "--id", func(r ListRequest) bool { return r.IDFilter != "" }},
{"TitleSearch", "--title", func(r ListRequest) bool { return r.TitleSearch != "" }},
{"SpecPrefix", "--spec", func(r ListRequest) bool { return r.SpecPrefix != "" }},
{"TitleContains", "--title-contains", func(r ListRequest) bool { return r.TitleContains != "" }},
{"DescContains", "--desc-contains", func(r ListRequest) bool { return r.DescContains != "" }},
{"NotesContains", "--notes-contains", func(r ListRequest) bool { return r.NotesContains != "" }},
{"ExternalContains", "--external-contains", func(r ListRequest) bool { return r.ExternalContains != "" }},
{"ExternalRef", "--external-ref", func(r ListRequest) bool { return r.ExternalRef != "" }},
{"CreatedAfter", "--created-after", func(r ListRequest) bool { return r.CreatedAfter != nil }},
{"CreatedBefore", "--created-before", func(r ListRequest) bool { return r.CreatedBefore != nil }},
{"UpdatedAfter", "--updated-after", func(r ListRequest) bool { return r.UpdatedAfter != nil }},
{"UpdatedBefore", "--updated-before", func(r ListRequest) bool { return r.UpdatedBefore != nil }},
{"ClosedAfter", "--closed-after", func(r ListRequest) bool { return r.ClosedAfter != nil }},
{"ClosedBefore", "--closed-before", func(r ListRequest) bool { return r.ClosedBefore != nil }},
{"DeferAfter", "--defer-after", func(r ListRequest) bool { return r.DeferAfter != nil }},
{"DeferBefore", "--defer-before", func(r ListRequest) bool { return r.DeferBefore != nil }},
{"DueAfter", "--due-after", func(r ListRequest) bool { return r.DueAfter != nil }},
{"DueBefore", "--due-before", func(r ListRequest) bool { return r.DueBefore != nil }},
{"DeferredFlag", "--deferred", func(r ListRequest) bool { return r.DeferredFlag }},
{"OverdueFlag", "--overdue", func(r ListRequest) bool { return r.OverdueFlag }},
{"EmptyDesc", "--empty-description", func(r ListRequest) bool { return r.EmptyDesc }},
{"NoLabels", "--no-labels", func(r ListRequest) bool { return r.NoLabels }},
{"NoParent", "--no-parent", func(r ListRequest) bool { return r.NoParent }},
{"PinnedFlag", "--pinned", func(r ListRequest) bool { return r.PinnedFlag }},
{"PriorityMin", "--priority-min", func(r ListRequest) bool { return r.PriorityMin != nil }},
{"PriorityMax", "--priority-max", func(r ListRequest) bool { return r.PriorityMax != nil }},
// The keyset position is a tuple and only the timestamp half decides
// whether one was supplied; neither AfterID nor AfterPriority alone is a
// position. All three are named in the refusal because a caller who dropped
// only the ones named would still be sending part of a position.
{"AfterCreatedAt/AfterID/AfterPriority", "cursor", func(r ListRequest) bool { return r.AfterCreatedAt != nil }},
}
// ValidateReadyFlagScope refuses a list request that combines ReadyFlag with a
// filter the blocker-aware ready query cannot carry, naming every field it
// could not honor. A generic refusal would leave the caller to bisect their
// own request.
//
// This is the enforcement half of ListRequest.ReadyFlag's promise; the other
// half is the doc comment there. It lives beside that promise rather than in
// any implementation, and it is called from the single builder every
// implementation of Reader runs (internal/workapi.BuildListFilter), so no
// backend can be missing it — a per-backend copy is the drift this role exists
// to remove.
//
// A request without ReadyFlag is never refused here: every field below is
// honored by the ordinary listing.
func ValidateReadyFlagScope(req ListRequest) error {
if !req.ReadyFlag {
return nil
}
var named []string
for _, f := range readyScopeFields {
if f.set(req) {
named = append(named, f.name+" ("+f.flag+")")
}
}
if len(named) == 0 {
return nil
}
return fmt.Errorf("%w: --ready cannot filter on %s; the blocker-aware ready query carries only part of the list vocabulary, so answering would return every ready issue rather than the ones asked for — drop --ready, or drop what it cannot carry",
ErrValidation, strings.Join(named, ", "))
}