beads/issueops/reader_ready_scope.go
Julian Knutsen d801ec43dc
feat(issueops): put every issue capability behind one library surface
Beads had two implementations of most issue verbs: one for the direct route
(the CLI talking to a store it opened itself) and one for the proxied-server
route (the CLI talking through a unit of work over a running Dolt server).
They drifted — different commit messages, different transaction boundaries,
different refusals, occasionally different answers.

Seven role interfaces now live in the leaf package issueops: Lifecycle,
Reader, ReadyClaimer, BatchCloser, DependencyEditor, Commenter and Relations.
Each is reached only through a store accessor, never a constructor, because
the accessor is where the hook and telemetry decorators add their layers.
Three implementations back every role — dolt, embeddeddolt, and the
unit-of-work provider the proxied route uses. Both routes call the same role
for close, dep add/remove/list, comment, ready --claim and update.

A depguard rule (httpapi-domain-boundary) denies internal/storage/domain from
internal/httpapi, so a handler cannot reach uw.IssueUseCase() past the roles
and open a second front door one lint-clean commit at a time.

Behaviour users will notice, all in the CHANGELOG:
  - bd close a b c is one Dolt commit, not three, and --claim-next moved
    inside that transaction so it fires only when something landed
  - the open-children guard moved into the transaction and its hand-rolled
    cmd/bd copy is gone, removing a read-then-write window that made
    bd close <child> <parent> depend on argument order
  - bd dep add --file honours deferred version commit
  - embedded bd comment writes the role's message and author
  - dep verb commit messages are the role's on the direct route

Wisp-sourced dependency edges are restored. Moving bd dep add onto the role
had pinned an edge's SOURCE to the issues plane, and the two routes did not
even fail alike: direct refused with "issue <id> not found", proxied threw an
fk_dep_issue violation. The comment justifying the pin claimed the issues
plane was "the only one its unit-of-work sibling can reach" — that was false;
domain.DependencyUseCase declared a full set of wisp twins with no production
caller. All three implementations now route per edge by the edge's own
source. A mixed request stays one transaction: parent-child-first ordering
and the whole-graph cycle gate span both planes, and a refusal rolls back
both. Behind the role, three bulk add verbs collapsed into one source-routed
AddDependencies, so no plane-pinned variant is left to reach for by mistake.

Six Provenance fields with no production caller were deleted rather than
wired — CloseRequest, CloseBatchRequest, ClaimNextRequest, AddCommentRequest,
AddDependenciesRequest, RemoveDependencyRequest. Each role already composes an
id-bearing message, so a caller could only restate the default and make it
unreachable from production. Two are not caller-settable even in principle:
CloseBatchCommitMessage names what LANDED and ClaimNextCommitMessage names the
id the claim WON. UpdateRequest and ReopenRequest keep theirs; commit messages
users see are unchanged.

Verified: build, vet and gofmt clean; golangci-lint 0 issues; protocol corpus
byte-identical under BEADS_PROTOCOL_REQUIRE_DOLT=1; all twelve
DependencyEditor conformance wirings green (four contract functions against
each implementation); TestEmbeddedDepAddWispSource runs bd dep add <wisp-id>
at the front door and was demonstrated RED against the pinned routing first.
Three internal/storage/dolt failures reproduce on pristine origin/main.

Known gaps are enumerated in the PR description rather than left to be found:
comment listing is on no role, bd dep tree and bd dep cycles have no role,
bd create and bd reopen are on Lifecycle only on the direct route, per-edge
line attribution is lost in bd dep add --file, multi-store bd close
--claim-next rides only the first store's batch, and the is_blocked staging gap
(bd-2y9ke, predates this change). Seven of the eight role interfaces now have a
shared conformance contract in backend/conformance, run at all three
implementations; main's Claimer, added in parallel by #5334, is the eighth and
has none yet.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 12:27:56 -07:00

116 lines
6.1 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.
//
// Three groups are deliberately ABSENT, because listing them here would refuse
// requests that are answered correctly today:
//
// - What the projection carries: 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), Limit, Offset and MaxRows.
//
// - Status and AllFlag. The builder resolves both to "open" under ReadyFlag
// before the projection ever runs, so IssueFilter.Statuses is never
// populated on this path and there is nothing for the projection to drop.
// Ready work is open work; that override is pinned by the builder's golden
// file (internal/workapi/testdata/list_filter_golden.json,
// ready_flag_overrides_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 pair and only the timestamp half decides
// whether one was supplied; AfterID alone is not a position.
{"AfterCreatedAt/AfterID", "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, ", "))
}