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

97 lines
3.7 KiB
Go

package workapi
import (
"fmt"
"strings"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/issueops"
)
// The shared half of issueops.StatsReporter: the assignee-scoped question,
// which every implementation answers by asking storage two questions and
// folding the answers, rather than by running one aggregate.
//
// The workspace-wide question needs nothing here — it is a single seam call on
// every backend. This file exists because the assignee-scoped answer is
// ASSEMBLED, and assembling it twice is how the two front doors would come to
// disagree about what "your work" means.
// ValidateStatsAssignee resolves the actor an assignee-scoped summary answers
// for, refusing an empty or whitespace-only one with ErrValidation.
//
// It returns the value UNCHANGED when it accepts: an assignee is an opaque
// identifier this layer has no vocabulary for, so trimming it would silently
// answer for a different actor than the caller named.
func ValidateStatsAssignee(assignee string) (string, error) {
if strings.TrimSpace(assignee) == "" {
return "", fmt.Errorf("assignee must not be empty for an assignee-scoped summary%.0w", issueops.ErrValidation)
}
return assignee, nil
}
// BuildStatsAssigneeIssueFilter is the predicate that selects one actor's rows
// for the fold below.
//
// It carries the assignee and NOTHING else, which is a decision and not an
// omission: no status restriction (the fold tallies every status, including
// closed), no limit (a capped scan would silently under-report a busy actor's
// total), and no wisp suppression — the search seam merges the ephemeral tier
// unless told not to.
func BuildStatsAssigneeIssueFilter(assignee string) types.IssueFilter {
return types.IssueFilter{Assignee: &assignee}
}
// BuildStatsAssigneeWorkFilter is the ready-work predicate for the same actor.
// It is a second filter type because ready work is a different question with
// its own exclusions — which is why AssigneeStats can report a ready count the
// workspace-wide answer's subtraction would not produce.
func BuildStatsAssigneeWorkFilter(assignee string) types.WorkFilter {
return types.WorkFilter{Assignee: &assignee}
}
// FoldStatsAssigneeSummary turns one actor's rows and their ready-work count
// into the summary both front doors print.
//
// It is the single definition of what `bd status --assigned` means. What it
// does NOT set is part of that definition: PinnedIssues,
// EpicsEligibleForClosure and AverageLeadTime stay zero.
//
// BlockedIssues and ReadyIssues are always non-nil here, including for an actor
// with no rows at all. The nil pointers are the workspace-wide answer's
// skipped-scan signal (issueops.StatsRequest.SkipBlocked) and mean "not
// computed"; this path always computes both, so leaving them nil would render
// as "(skipped)" on a summary that skipped nothing.
//
// A nil element is skipped and counted nowhere, TotalIssues included: counting
// a row the seam failed to hydrate while it lands in no status bucket would
// publish an inconsistency as data.
func FoldStatsAssigneeSummary(issues []*types.Issue, readyCount int) types.Statistics {
stats := types.Statistics{}
blocked := 0
for _, issue := range issues {
if issue == nil {
continue
}
stats.TotalIssues++
switch issue.Status {
case types.StatusOpen:
stats.OpenIssues++
case types.StatusInProgress:
stats.InProgressIssues++
case types.StatusBlocked:
// The STATUS, not the transitive is_blocked flag the
// workspace-wide answer counts. The two disagree in both
// directions and AssigneeStats says so.
blocked++
case types.StatusDeferred:
stats.DeferredIssues++
case types.StatusClosed:
stats.ClosedIssues++
}
}
stats.BlockedIssues = &blocked
stats.ReadyIssues = &readyCount
return stats
}