beads/internal/workapi/sweep.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

267 lines
9.4 KiB
Go

package workapi
import (
"fmt"
"path/filepath"
"sort"
"strings"
"time"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/issueops"
)
// The shared, DATABASE-FREE half of issueops.Sweeper: what a sweep request
// means, which candidates survive the recheck, and what counts as a citation.
// Every implementation of the role runs these, so `bd purge` and `bd prune`
// have one definition rather than one per backend.
//
// What is NOT here is the sweep itself. Selecting rows and deleting them needs
// one transaction (issueops.Sweeper.Sweep), which no interface above a store
// publishes; the bodies live in internal/storage/issueops/sweep.go and in the
// unit-of-work provider.
// ValidateSweepRequest applies the request rules every Sweeper implementation
// shares, before anything is read.
//
// The require-a-filter refusal for the durable tier is a safety invariant, so
// it lives HERE rather than in a CLI handler: a second front door inherits it
// by calling the role. See issueops.SweepRequest.
func ValidateSweepRequest(in issueops.SweepRequest) error {
switch in.Tier {
case issueops.SweepEphemeral, issueops.SweepDurable:
case "":
return fmt.Errorf("%w: sweep requires a tier (%q or %q), and has no default",
issueops.ErrValidation, issueops.SweepEphemeral, issueops.SweepDurable)
default:
return fmt.Errorf("%w: %q is not a sweep tier; use %q or %q",
issueops.ErrValidation, in.Tier, issueops.SweepEphemeral, issueops.SweepDurable)
}
if in.IDPattern != "" {
// filepath.Match reports a malformed pattern on any subject, so one
// probe against the empty string classifies the pattern itself. The
// front doors used to discard this error, which turned `--pattern '['`
// into "nothing matched" on a command whose job is to delete matches.
if _, err := filepath.Match(in.IDPattern, ""); err != nil {
return fmt.Errorf("%w: --pattern %q is not a valid glob: %v",
issueops.ErrValidation, in.IDPattern, err)
}
}
if in.Tier == issueops.SweepDurable && in.ClosedBefore == nil && in.IDPattern == "" {
return fmt.Errorf("%w: a durable sweep requires a closed-before cutoff or an id pattern; "+
"pass the pattern \"*\" to sweep every closed issue deliberately",
issueops.ErrValidation)
}
return nil
}
// BuildSweepCandidateFilter turns a sweep request into the storage-level
// filter that selects its CANDIDATES: the closed rows of one tier, bounded by
// the cutoff.
//
// The pattern is deliberately NOT in the filter. Globs are matched in Go
// (MatchesSweepPattern) because a LIKE translation would silently disagree with
// filepath.Match on `[...]` and on the escape rules — a disagreement that, on
// this operation, decides which rows are deleted.
//
// Call ValidateSweepRequest first; this builder assumes a validated request
// and does not re-refuse one.
func BuildSweepCandidateFilter(in issueops.SweepRequest) types.IssueFilter {
closed := types.StatusClosed
ephemeral := in.Tier == issueops.SweepEphemeral
filter := types.IssueFilter{
Status: &closed,
Ephemeral: &ephemeral,
}
if in.ClosedBefore != nil {
cutoff := *in.ClosedBefore
filter.ClosedBefore = &cutoff
}
return filter
}
// MatchesSweepPattern reports whether an id is admitted by a request's
// IDPattern. An empty pattern admits everything.
//
// A malformed pattern reports false here; ValidateSweepRequest is what refuses it.
func MatchesSweepPattern(pattern, id string) bool {
if pattern == "" {
return true
}
ok, err := filepath.Match(pattern, id)
return err == nil && ok
}
// FilterSweepCandidates applies the pattern and then the two protections that
// hold a candidate back before any reference scan: the pinned flag, and the
// closed_at recheck.
//
// THE ORDER IS PART OF THE ANSWER, and issueops.Sweeper.Sweep states it: the
// pattern narrows first, so a pinned row the pattern excluded is not counted
// as protected — it was never a candidate. The three closed_at buckets are
// defenses against the tier query returning a row it was not asked for, counted
// rather than dropped so a disagreement between the query and the recheck is
// visible instead of silent.
//
// cutoff is the request's ClosedBefore; a nil cutoff performs the presence
// checks and skips the comparison.
func FilterSweepCandidates(issues []*types.Issue, pattern string, cutoff *time.Time) ([]*types.Issue, issueops.SweepSkips) {
kept := make([]*types.Issue, 0, len(issues))
var skips issueops.SweepSkips
for _, issue := range issues {
if issue == nil {
skips.Unreadable++
continue
}
if !MatchesSweepPattern(pattern, issue.ID) {
continue
}
switch {
case issue.Pinned:
skips.Pinned++
case issue.Status != types.StatusClosed:
skips.NotClosed++
case issue.ClosedAt == nil:
skips.UnknownClosedAt++
case cutoff != nil && !issue.ClosedAt.Before(*cutoff):
skips.ClosedAtOrAfterCutoff++
default:
kept = append(kept, issue)
}
}
return kept, skips
}
// SweepDefenseSkips is how many candidates the recheck rejected as
// self-inconsistent — the three closed_at buckets plus the unreadable row. It
// is separate from the two PROTECTIONS (pinned, referenced) because a non-zero
// value here is a defense firing rather than a normal outcome, and the front
// doors warn on exactly that.
func SweepDefenseSkips(s issueops.SweepSkips) int {
return s.Unreadable + s.NotClosed + s.UnknownClosedAt + s.ClosedAtOrAfterCutoff
}
// NotDoneStatusesForSweep is the status vocabulary a reference scan asks:
// every built-in status that is not "closed", plus every configured custom
// status whose category is not "done".
//
// It is an explicit LIST rather than a not-closed exclusion because that is
// what the storage seam takes reliably on both planes (a Statuses set, not an
// ExcludeStatus). Reading the workspace's custom statuses is required, not
// best-effort: a scan that missed a custom active status would under-protect
// and delete a bead a live bead still cites.
func NotDoneStatusesForSweep(custom []types.CustomStatus) []types.Status {
statuses := []types.Status{
types.StatusOpen,
types.StatusInProgress,
types.StatusBlocked,
types.StatusDeferred,
types.StatusPinned,
types.StatusHooked,
}
for _, cs := range custom {
if cs.Category != types.CategoryDone {
statuses = append(statuses, types.Status(cs.Name))
}
}
return statuses
}
// BuildSweepReferenceScanFilter selects the rows a reference scan reads: the
// not-done set, and nothing else about them.
func BuildSweepReferenceScanFilter(custom []types.CustomStatus) types.IssueFilter {
return types.IssueFilter{Statuses: NotDoneStatusesForSweep(custom)}
}
// CandidateIDMatcher finds literal, word-bounded occurrences of a candidate id
// set in arbitrary text. It is the whole of what "cited" means for
// issueops.SweepRequest.ProtectReferenced.
//
// It is bucketed by FIRST BYTE and each bucket sorted longest-first: the scan
// runs over every not-done bead's description, notes and comments, where a
// naive strings.Contains per candidate is O(candidates x text). Longest-first
// inside a bucket is what makes `be-1.1` win over `be-1` where both are
// candidates and both start at the same offset.
type CandidateIDMatcher struct {
byFirstByte map[byte][]string
}
// NewCandidateIDMatcher builds a matcher over a candidate id set. Empty ids
// are dropped: they would match at every boundary.
func NewCandidateIDMatcher(candidateIDs map[string]bool) CandidateIDMatcher {
byFirstByte := make(map[byte][]string)
for id := range candidateIDs {
if id == "" {
continue
}
byFirstByte[id[0]] = append(byFirstByte[id[0]], id)
}
for first := range byFirstByte {
ids := byFirstByte[first]
sort.Slice(ids, func(i, j int) bool {
if len(ids[i]) == len(ids[j]) {
return ids[i] < ids[j]
}
return len(ids[i]) > len(ids[j])
})
byFirstByte[first] = ids
}
return CandidateIDMatcher{byFirstByte: byFirstByte}
}
// FindAll adds every candidate id occurring in text at ASCII word boundaries
// to found.
func (m CandidateIDMatcher) FindAll(text string, found map[string]bool) {
for i := 0; i < len(text); i++ {
ids := m.byFirstByte[text[i]]
if len(ids) == 0 || !isWordBoundaryAt(text, i) {
continue
}
for _, id := range ids {
end := i + len(id)
if end <= len(text) && strings.HasPrefix(text[i:], id) && isWordBoundaryAt(text, end) {
found[id] = true
break
}
}
}
}
func isWordBoundaryAt(s string, idx int) bool {
var before, after byte
if idx > 0 {
before = s[idx-1]
}
if idx < len(s) {
after = s[idx]
}
return isASCIIWordByte(before) != isASCIIWordByte(after)
}
func isASCIIWordByte(b byte) bool {
return b == '_' ||
('0' <= b && b <= '9') ||
('A' <= b && b <= 'Z') ||
('a' <= b && b <= 'z')
}
// PartitionSweepReferenced splits candidates into the ones no not-done row
// cites and the ones some row does, and returns the bounded sample
// issueops.SweepResult.ReferencedIDs carries. Both the kept slice and the
// sample preserve the candidate order, so two runs over one snapshot report the
// same ids.
func PartitionSweepReferenced(candidates []*types.Issue, referenced map[string]bool) (kept []*types.Issue, referencedCount int, sample []string) {
kept = make([]*types.Issue, 0, len(candidates))
for _, issue := range candidates {
if referenced[issue.ID] {
referencedCount++
if len(sample) < issueops.SweepReferencedSampleLimit {
sample = append(sample, issue.ID)
}
continue
}
kept = append(kept, issue)
}
return kept, referencedCount, sample
}