beads/internal/workapi/ready.go
CI Bot 67d38d2620 Trim this series' comments toward the repo's own density
Ten agents over 216 files, one directory-balanced group each, working to a
rubric that named what to cut (duplication narration, restatement of the next
line, the governing rule echoed in every command file, throat-clearing) and
what to keep (traps, invariants, security, tracker ids, behaviour changes, and
the "why a naive simplification destroys this assertion" rationale).

Net 1,523 lines. Density against this repo's own per-directory norm on main:

  cmd/bd              33.6% -> 27.3%   (main 10.7%)
  internal/storage    26.1% -> 23.1%   (main 14.1%)
  backend/conformance 34.0% -> 29.6%   (main 22.8%)
  internal/httpapi    30.9% -> 27.8%   (main 30.6%, now below)
  overall             34.7% -> 31.6%

Every agent landed at 18-25% rather than the 30% asked for, and every one gave
the same reason independently: what remained was on the keep list. Ten separate
judgements agreeing is the most useful result here — the prose is dense, but it
is mostly load-bearing, and the shortfall is the honest answer rather than a
failure to try.

TWO REVERTS, both to protect something worth more than the lines.

issueops/ is back to its pre-trim state, giving up 610 lines. The conformance
contracts cite the leaf docs BY LINE — "pins treewalker.go:52-66" — 155 times.
Trimming the cited files silently repointed those at whatever text moved into
those numbers, across agent boundaries so no agent could see it. A semantic
remapper recovered 141 of them, but 23 needed judgement and several landed on
struct fields. The leaf docs are the spec the contracts are written against;
they are the one place in this change where dense prose IS the deliverable, and
keeping them stable is worth more than the 610 lines. tree_walker_contract.go
and version_reconciler_contract.go went back for the same reason: an agent had
deleted a paragraph containing a citation, so positional restoration could not
align them.

After the reverts, exactly 5 citations point into a still-trimmed file and 2 of
those are weak — both in cmd/bd/config_guard_test.go, which this series never
touched and whose citations were already wrong on main (init.go:361 pointed at
a closing brace; the guard it names is at init.go:1499).

VERIFICATION. A guard strips every comment and all whitespace from each of the
193 modified files at HEAD and in the worktree and requires the two to be
byte-identical, so a code change cannot hide in a comment diff. It handles `//`
inside string and raw-string literals, and was tested against a deliberate code
change before being trusted. gofmt clean, go build, go vet, golangci-lint 0
issues, and the two AST-based tests that PARSE trimmed files — the timed
provider binding pin over claim.go and the serve database-source gate over
serve.go — both pass.

One real defect found while trimming: checkDatabaseSource's doc block ran into
`// sourceRoles is ...` with no blank line, so godoc attached thirty-one lines
of the wrong prose to func sourceRoles and left checkDatabaseSource
undocumented. Fixed by separating them.
2026-08-06 08:06:59 +00:00

137 lines
5.3 KiB
Go

package workapi
import (
"fmt"
"strings"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/utils"
"github.com/steveyegge/beads/issueops"
)
// DefaultReadyLimit is the default number of rows a ready-work query returns
// when the caller does not ask for a specific limit. Every frontend registers
// its limit knob from this constant so the surfaces cannot drift apart; 0
// still means unlimited.
const DefaultReadyLimit = 100
// LimitOr resolves a request's optional limit: nil takes the surface's shared
// default, and an explicit 0 stays 0, which means unlimited at both storage
// seams. The pointer is what keeps "unset" and "explicitly unlimited"
// distinguishable — collapsing them would make one constant unable to serve
// both surfaces.
func LimitOr(limit *int, fallback int) int {
if limit == nil {
return fallback
}
return *limit
}
// BuildReadyFilter turns a ready request into the storage-level work filter.
// It is the single definition of what `bd ready` means: open issues only (an
// empty WorkFilter would default to open plus in_progress), issue-type alias
// expansion, label and exclude-type normalization, limit defaulting, and the
// assignee rule that lets Unassigned win over a stale Assignee.
//
// Labels, LabelsAny and ExcludeLabels are normalized here, so a caller can
// pass raw user input. A caller that has to decide something from the label
// sets - the CLI's directory-label default is the one such case - reads them
// back off the returned filter, where they are already normalized, rather than
// normalizing its own copy: a value it then puts on the filter itself is its
// own to shape, and running it through here would change it.
func BuildReadyFilter(in issueops.ReadyRequest) (types.WorkFilter, error) {
filter := types.WorkFilter{
// Open only, not in_progress - the same set `bd list --ready` shows.
Status: types.StatusOpen,
Type: utils.NormalizeIssueType(in.IssueType),
Limit: LimitOr(in.Limit, DefaultReadyLimit),
Offset: in.Offset,
Unassigned: in.Unassigned,
SortPolicy: types.SortPolicy(in.Sort),
Labels: utils.NormalizeLabels(in.Labels),
LabelsAny: utils.NormalizeLabels(in.LabelsAny),
ExcludeLabels: utils.NormalizeLabels(in.ExcludeLabels),
LabelPattern: in.LabelPattern,
LabelRegex: in.LabelRegex,
IncludeDeferred: in.IncludeDeferred,
IncludeEphemeral: in.IncludeEphemeral,
ExcludeTypes: normalizeExcludeTypes(in.ExcludeTypes),
HasMetadataKey: in.HasMetadataKey,
}
if in.Priority != nil {
p := *in.Priority
filter.Priority = &p
}
if in.Assignee != "" && !in.Unassigned {
a := in.Assignee
filter.Assignee = &a
}
if in.ParentID != "" {
pid := in.ParentID
filter.ParentID = &pid
}
if in.MolType != nil {
filter.MolType = in.MolType
}
if len(in.MetadataFields) > 0 {
filter.MetadataFields = in.MetadataFields
}
if err := ValidateMetadataFilters(in.MetadataFields, in.HasMetadataKey); err != nil {
return filter, err
}
if !filter.SortPolicy.IsValid() {
// A deterministic request-validation failure, so it matches
// ErrValidation: every role whose filter vocabulary this builds —
// Reader.Ready, ReadyClaimer.ClaimNext and BatchCloser's ClaimNext —
// promises a caller can classify one with errors.Is rather than by
// reading prose. The wrap is %.0w rather than a "%w: " prefix because
// this text is what `bd ready --sort bogus` prints verbatim behind
// "Error: "; prefixing it would change user-visible copy to say
// something the reader already knows.
return filter, fmt.Errorf("invalid sort policy '%s'. Valid values: hybrid, priority, oldest%.0w", in.Sort, issueops.ErrValidation)
}
return filter, nil
}
// BuildReadyCountFilter turns a ready request into the storage-level filter a
// COUNT of the ready set runs against: BuildReadyFilter's filter with the page
// removed, and the single definition of what `bd ready`'s published total means.
//
// It refuses a request carrying a page. issueops.ReadyCounter.CountReady
// promises its answer equals len(Reader.Ready(r with Limit=0).Items), and a
// Limit would make that "how many of the first N" while an Offset would
// subtract the rows it skipped from the size of a set that still holds them.
//
// The zeroed limit is set on a LOCAL copy: a nil Limit means the shared ready
// default at BuildReadyFilter, so an unlimited count has to say so explicitly.
func BuildReadyCountFilter(in issueops.ReadyRequest) (types.WorkFilter, error) {
if in.Limit != nil {
return types.WorkFilter{}, fmt.Errorf("%w: a ready count does not take a limit", issueops.ErrValidation)
}
if in.Offset != 0 {
return types.WorkFilter{}, fmt.Errorf("%w: a ready count does not take an offset", issueops.ErrValidation)
}
unlimited := 0
counted := in
counted.Limit = &unlimited
return BuildReadyFilter(counted)
}
// normalizeExcludeTypes splits comma-separated exclusions and expands type
// aliases, so --exclude-type=mr,epic and --exclude-type mr --exclude-type epic
// mean the same thing.
func normalizeExcludeTypes(raw []string) []types.IssueType {
var out []types.IssueType
for _, group := range raw {
for _, t := range strings.Split(group, ",") {
t = strings.TrimSpace(t)
if t != "" {
out = append(out, types.IssueType(utils.NormalizeIssueType(t)))
}
}
}
return out
}