* feat(stats): count the rows the default listing suppresses
bd status counts the issues table; bd list hides gates and templates on
account of what they are. The two therefore disagree, and nothing
reconciles them: a teardown driven by bd list leaves a gate behind and
status reports a total the operator cannot account for from any listing.
Break the suppressed rows out as their own counts. TotalIssues keeps
counting the database, which is what a command titled "Issue Database
Status" should report; these say how much of that total no default
listing will show. Every backend's statistics path funnels through
ScanIssueCountsInTx, so one query serves all of them.
Infra types need no counterpart here: they live on the wisp plane, which
this query does not read.
* fix(status): disclose the counted rows bd list will not show
bd status reported "Total Issues: 2" for a workspace whose every listing
showed one, because gates and templates are suppressed from a default
bd list. Nothing connected the two numbers, so the remainder read as a
phantom -- most visibly after a teardown driven by bd list, which leaves
its gates behind and then cannot see them.
Report the suppressed rows under the summary they qualify, naming the
flag that reveals each kind. The breakdown is printed rather than a
single hidden-total, since a template gate would otherwise be counted
twice. Nothing is printed when there is nothing suppressed.
Stacked on the statistics counts that make this reportable.
* docs(api): put gate_issues and template_issues on the Statistics schema
The Statistics schema is pinned to types.Statistics, so the two new
counts were on the wire the moment the struct grew them, and
TestWireTagBijection fails the openapi gate until the spec says so:
Go fields with no spec property: [gate_issues template_issues]
Document both as a breakdown of total_issues rather than an addition to
it — they count rows the default `bd list` suppresses, which
total_issues already includes — and warn against summing them, since a
row can be both a gate and a template.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(status): give --assigned the same disclosure, and test the behavior
Three points from review.
1. `bd status --assigned` never printed the line. AssigneeStats does not
go through ScanIssueCountsInTx - it folds one actor's rows through
workapi.FoldStatsAssigneeSummary, which left both new fields zero. That
route's filter sets only Assignee, so IsTemplate stays nil and the
actor's gates and protos really ARE in those rows while
`bd list --assignee` suppresses both: the same reconciliation gap, one
scope down. The fold now counts them, and its doc says they are set
deliberately rather than borrowed from a workspace-wide answer.
2. The infra-type suppression is now explained rather than asserted away,
and the answer is that a durable infra row is NOT unreachable, so the
third breakdown is filed as GH#6439 rather than dismissed. Both the
plane routing and the listing's exclusions read the workspace-configured
types.infra set, and writing that key only invalidates a cache
(dolt/config.go) - it never moves rows already written. So durable rows
created while a type was not infra stay durable once it becomes one, and
a type evicted from the set creates durable rows outright, which the
create contract already pins ("evicted infra type",
issue_operations_contract.go). Counting them needs that configured set,
which ScanIssueCountsInTx - portable SQL with no config seam, called
from six backend sites - cannot reach; guessing with the built-in names
would be wrong in exactly the workspaces where it matters.
suppressedTypeSummary's doc now carries that reasoning.
3. The behavior itself had no test - both existing cases exercised a pure
string formatter, and would pass with the render call site deleted. Now:
- TestRenderStatusEmitsTheSuppressedRowsLine captures renderStatus's
stdout, asserts the line and both parts, and asserts it sits after the
totals it reconciles rather than in the extended block. It fails with
the call site removed ("renderStatus did not emit the disclosure
line"), plus a companion asserting the line is absent when there is
nothing to disclose.
- Three conformance cases in stats_reporter_contract.go, wired into all
three role wirings (dolt, embeddeddolt, uow), so the new SQL is
checked cross-backend rather than at one call site:
BreaksOutTheRowsTheDefaultListingSuppresses (with the negative rows a
loose predicate would also move), BreaksOutAGateThatIsAlsoATemplate
(the two suppressions are independent, so a proto's gate step counts
in both), and AssigneeStatsBreaksOutTheSuppressedRows for the fold.
statsReporterCounts and assertStatsReporterDelta carry the two fields.
All three are behavioral reds against zeroed counts, not compile
errors:
GateIssues moved by 0 (0 -> 0), want 1
TemplateIssues moved by 0 (0 -> 0), want 1
GateIssues = 0, want 1 - the actor's gate is in this answer but
not in `bd list --assignee`
4. Nit: pluralCount takes both spellings instead of appending "s", so a
caller with an irregular plural is not silently mis-served.
Also adds the CHANGELOG entry the behavior change was missing, including
the GH#6439 gap.
Reported-by: bee-ghosttrack
Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(conformance): declare the new stats cases in the order the table runs them
TestRoleContractCasesCoverEveryContractCase checks more than coverage: the
roleContractCases table has to list cases in the order their contract file
DECLARES them, because that is the order the unit-of-work leg's runners use
and the order its config-writing cases depend on.
I declared all three new cases together, then registered the assignee one
with the other assignee cases in the table, so the two orders disagreed:
roleContractCases is out of declaration order at position 449: table
has RunStatsReporterAStatusOutsideTheTalliesIsCountedOnlyInTotal,
source has RunStatsReporterAssigneeStatsBreaksOutTheSuppressedRows
Fixed by moving the declaration rather than the table entry, since the
assignee case belongs beside the other assignee-scoped ones anyway - the
grouping the table already had was the correct one. Caught by CI because I
ran go vet over backend/conformance but not its tests; both now pass.
Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs(changelog): move this PR's entry under [Unreleased]
The 1.3.0 cut renamed the old [Unreleased] block, so the entry this branch
added there now merges cleanly into the released [1.3.0] section (#6643).
Agent-Signature: claude-code-opus-5-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(status): complete the disclosure's remedy and pin its population
Maintainer review fixes for PR #5763 (adopt-pr iteration 1). Four of the
five review findings taken; the nit is declined with its measurement.
Finding 2 (minor, gate impact minor) - the printed remedy was incomplete.
The two counters come from the same scan as TotalIssues and are status-blind
with it, but the flags they named lift only the TYPE exclusion, so a CLOSED
gate was counted while `bd list --include-gates` still would not show it.
Gates are closed as the work they guard completes, so that is the ordinary
case rather than an edge.
Took the "complete the hint" arm over the "scope the counters" arm. Every
other field ScanIssueCountsInTx fills is workspace-wide; the disclosure
exists to account for TotalIssues, a database number printed three lines
above it; and scoping these two to the listing's population would leave them
explaining nothing about the total they are broken out of. `--all` "replaces
the status exclusions only" and lifts no type exclusion of its own
(backend/conformance/reader_contract.go:487), so the two flags together are
exactly the remedy. Recorded the population in the types.go field comment,
the status.go doc, and the CHANGELOG, which printed the old example verbatim.
Finding 3 (minor) - the three new conformance cases seeded only open rows,
so a backend counting over every status and one counting only the listing's
population returned identical numbers on all of them. Added a closed gate and
a closed proto to the first case. Proved it now decides the question: scoping
both SQL SUMs with `AND status <> 'closed'` reds exactly that case
("GateIssues moved by 1 (0 -> 1), want 2") while the all-open sibling
BreaksOutAGateThatIsAlsoATemplate stays green.
Finding 4 (minor) - the normative role doc in issueops/statsreporter.go
enumerated only the six prior counts. Added the two to that scan's bullet and
corrected two statements this PR had falsified: the headline "six counts of
one set", and the AssigneeStats bullet's "the fold ... tallies the five
statuses and nothing else", which stopped being true when the fold gained the
two increments.
Finding 1 (minor, gate impact minor) - ran `make bazel-sync`. It proposed
exactly one line, `+ "status_suppressed_test.go"` in cmd/bd/BUILD.bazel, and
nothing else, confirmed by porcelain rather than by bazel-sync-check.
Generator-owned, not hand-edited.
Finding 5 (nit) - declined. The three helpers already in package main
(pluralIssue, pluralize, plural) all DERIVE the "s" and cannot render a
caller-chosen pair; the tree's one two-form helper, pluralWord, is unexported
in internal/storage/issueops, and exporting it so a CLI string could reach it
would add exported surface to a storage role for a cosmetic. Recorded that
trade in pluralCount's doc comment instead.
Validation: `go build ./...` and `go vet` (6 pkgs) clean, gofmt clean,
`git diff --check` clean; cmd/bd 4/4 named PASS, internal/httpapi
TestWireTagBijection|TestSpec* PASS, internal/workapi PASS,
internal/storage/uow TestStatsReporterContract 18/18 subtests PASS. Both new
pins are mutation-proved: reverting `--all` reds all four table cases, both
flag subtests and the render-path pin, while the absence assertion stays
green.
Not done here: the PR body carries the same stale example line
("1 gate (--include-gates)"). Review iterations do not touch the PR surface,
so that correction is stamped for finalize.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
212 lines
12 KiB
Go
212 lines
12 KiB
Go
package issueops
|
|
|
|
import (
|
|
"context"
|
|
|
|
"github.com/steveyegge/beads/internal/types"
|
|
)
|
|
|
|
// StatsRequest asks for the workspace's summary statistics. It carries no
|
|
// predicate at all, and that absence is the type's whole shape: this is a
|
|
// question about the WORKSPACE, not about a set the caller picked out.
|
|
//
|
|
// A caller that wants a number about a set it described calls Counter. The two
|
|
// roles are told apart by exactly this: CountRequest has thirty filter fields
|
|
// and no dependency-aware number in its answer; StatsRequest has one
|
|
// performance knob and every number in its answer is either a status tally of
|
|
// the whole durable plane or derived from the dependency graph.
|
|
type StatsRequest struct {
|
|
// SkipBlocked asks the implementation to answer WITHOUT the blocked-set
|
|
// scan, which is the expensive half of this query on a large workspace.
|
|
//
|
|
// It is a HINT, and the promise is stated from the answer's side rather
|
|
// than the request's: see StatsReporter.Stats. When it is honored,
|
|
// StatsResult.Summary.BlockedIssues and .ReadyIssues are both nil; when the
|
|
// implementation has no cheaper path it answers exactly as if this field
|
|
// were unset. Nothing else in the result changes either way, so a caller
|
|
// that does not read the two pointers cannot tell the difference — which is
|
|
// the point of it being a hint.
|
|
SkipBlocked bool
|
|
}
|
|
|
|
// AssigneeStatsRequest asks for one actor's summary statistics.
|
|
//
|
|
// It is a separate request type, answered by a separate method, rather than an
|
|
// Assignee field on StatsRequest. That is not ceremony: the two questions
|
|
// return the same struct and fill FOUR of its fields by different definitions
|
|
// (see StatsReporter.AssigneeStats). A single request with an optional
|
|
// Assignee would have made those definitions depend on whether a string was
|
|
// empty, which is the shape that makes a reader trust a number that means
|
|
// something else.
|
|
type AssigneeStatsRequest struct {
|
|
// Assignee is the actor to answer for, used AS WRITTEN: there is no
|
|
// trimming, no case folding and no alias expansion, because an assignee is
|
|
// an opaque identifier this layer has no vocabulary for.
|
|
//
|
|
// An empty or whitespace-only value is ErrValidation rather than a query.
|
|
// An empty assignee would otherwise select the rows whose assignee column
|
|
// is empty and report them as one actor's workload, and there is no caller
|
|
// that means that: `bd status --assigned` resolves an actor before it asks,
|
|
// and an HTTP caller that omits the parameter is asking the workspace-wide
|
|
// question and gets Stats.
|
|
Assignee string
|
|
}
|
|
|
|
// StatsResult carries the summary.
|
|
//
|
|
// It wraps the CANONICAL struct rather than redeclaring its ten fields, and
|
|
// that is load-bearing rather than lazy. types.Statistics is what `bd status
|
|
// --json` marshals under "summary" and what the HTTP operation's `summary`
|
|
// object is pinned to with x-go-type, so both front doors serialize ONE struct
|
|
// and neither performs a Go-to-Go mapping on the way to the wire. A result type
|
|
// of this role's own would have put a translation step between the role and
|
|
// both surfaces, which is precisely the second wire struct that
|
|
// internal/httpapi/pinning.go exists to forbid.
|
|
//
|
|
// The summary is a VALUE, not a pointer. A role that answered with a pointer
|
|
// would let a nil-with-nil-error reach a front door that dereferences it — the
|
|
// hazard internal/httpapi/roles.go wraps checkedReader around Get for — and
|
|
// there is nothing this role could mean by "no summary": an empty workspace has
|
|
// statistics, and they are zeros.
|
|
type StatsResult struct {
|
|
Summary types.Statistics
|
|
}
|
|
|
|
// StatsReporter describes the summary statistics `bd status` prints and its
|
|
// `bd stats` alias reprints — and, like Lifecycle, Reader, ReadyClaimer,
|
|
// BatchCloser, DependencyEditor, Commenter, Relations and Counter, a role with
|
|
// its own accessor. A new capability gets a new role interface and its own
|
|
// accessor; never append a method here.
|
|
//
|
|
// IT IS ITS OWN ROLE RATHER THAN A SIXTH CountGroup because its numbers are
|
|
// DEPENDENCY-AWARE. A grouped count partitions rows by a column; two of the
|
|
// numbers here — the blocked count and the ready count derived from it — come
|
|
// from the denormalized transitive is_blocked flag the dependency graph
|
|
// maintains, and no predicate over the issues table can describe them. Counter
|
|
// says the same thing from its side, and this is the role it points at.
|
|
//
|
|
// WHAT THE NUMBERS ARE, and they are not all the same kind of number. Reading
|
|
// them as "eight counts of one set" is the mistake this doc is written to
|
|
// prevent:
|
|
//
|
|
// - TotalIssues, OpenIssues, InProgressIssues, ClosedIssues, DeferredIssues,
|
|
// PinnedIssues, GateIssues and TemplateIssues are one scan of the DURABLE
|
|
// issues plane. Every row is in Total, including closed and pinned ones;
|
|
// the status tallies are exact equality against the stored status, so a
|
|
// workspace with a custom status has rows that appear in Total and in none
|
|
// of the four buckets, and the buckets do not sum to Total. PinnedIssues
|
|
// counts the pinned FLAG and overlaps every status bucket.
|
|
// - GateIssues and TemplateIssues are the last two of that scan and are
|
|
// NOT a third kind of bucket either. They count what a default `bd list`
|
|
// suppresses on account of WHAT THE ROW IS - gate-typed rows, and rows
|
|
// carrying the template flag - so that the two commands can be reconciled
|
|
// rather than silently disagree about how many issues exist. Like
|
|
// PinnedIssues they overlap every status bucket, and being a scan of the
|
|
// database rather than of a listing they span every status: a CLOSED gate
|
|
// is in GateIssues. They also overlap EACH OTHER - a proto's gate step is
|
|
// both, and is counted once in each - so summing them double-counts. Both
|
|
// are populated on BOTH methods, each with that method's own plane
|
|
// semantics: durable-plane only on Stats, wisp tier merged on
|
|
// AssigneeStats, exactly as the paragraph below describes for the rest of
|
|
// the scan.
|
|
// - BlockedIssues counts rows whose transitive is_blocked flag is set,
|
|
// excluding those whose STATUS is "closed" or "pinned". The exclusion is
|
|
// by status, NOT by the pinned flag the first bullet describes, and the
|
|
// two are different rows: a flag-pinned OPEN row with an unfinished
|
|
// blocker IS counted here. It is also not the count of rows whose status
|
|
// is "blocked" — an open row with an unfinished blocker is counted here
|
|
// and its status is still "open".
|
|
// - ReadyIssues is ARITHMETIC, not a query: OpenIssues minus BlockedIssues,
|
|
// clamped at zero. It is therefore not the cardinality of `bd ready`, which
|
|
// applies type exclusions, the deferral window, assignee filters and a
|
|
// limit that none of this touches. A caller that needs the ready-work count
|
|
// asks the ready-work question; this field is the headline number
|
|
// `bd status` prints and nothing more.
|
|
// - EpicsEligibleForClosure and AverageLeadTime are ALWAYS ZERO. No shipped
|
|
// implementation computes either, on any backend or either front door.
|
|
// They are carried because types.Statistics is the struct both surfaces
|
|
// serialize and dropping a field from it is a wire change; they are named
|
|
// here so a caller does not read a zero as an answer — and so a reader
|
|
// knows why `bd status`'s "Extended:" branch has never once printed.
|
|
//
|
|
// THE WISP TIER IS NOT MERGED into the workspace-wide answer: Stats counts the
|
|
// durable plane only, which is why an empty workspace full of wisps reports
|
|
// zero. AssigneeStats does merge it, and says so — one of the four places the
|
|
// two methods differ.
|
|
//
|
|
// Reporting is a READ. Nothing here records a history entry, fires a completion
|
|
// hook or changes a row, and a refusal changes nothing either. Deterministic
|
|
// request-validation failures match ErrValidation; result values are
|
|
// unspecified when error is non-nil. Implementations never mutate caller-owned
|
|
// request values.
|
|
//
|
|
// THE PER-ROLE COST of adding a role like this one is written down in
|
|
// engdocs/ADDING_AN_ISSUEOPS_ROLE.md.
|
|
type StatsReporter interface {
|
|
// Stats returns the workspace summary.
|
|
//
|
|
// EMPTY IS ZEROS, NOT AN ERROR. A workspace with no issues answers with a
|
|
// zero-valued summary and a nil error; there is no ErrNotFound on this
|
|
// role, for the reason Counter gives — a question about a set has an
|
|
// answer when the set is empty, and a caller polling a fresh workspace
|
|
// would otherwise have to classify an error to read a zero.
|
|
//
|
|
// SkipBlocked IS A HINT, and this is the whole of its promise:
|
|
//
|
|
// - BlockedIssues and ReadyIssues are nil TOGETHER or populated
|
|
// TOGETHER, never one of each. Readiness is derived from the blocked
|
|
// count, so there is no state in which one is knowable and the other
|
|
// is not, and every front door renders on exactly that pairing.
|
|
// - Nothing else in the summary changes. The other counts are the same
|
|
// numbers a full call returns.
|
|
// - Whether the hint was TAKEN is reported by BlockedIssues being nil,
|
|
// and that is the only report. An implementation with no cheaper path
|
|
// answers with the full numbers rather than discarding two it already
|
|
// computed: nilling them to match a stricter contract would trade a
|
|
// real answer for a slower lie.
|
|
//
|
|
// The store-backed implementations take the hint; the unit-of-work seam has
|
|
// no no-blocked variant and does not. That difference is deliberate,
|
|
// observable and stated here rather than left for a caller to discover.
|
|
Stats(ctx context.Context, req StatsRequest) (StatsResult, error)
|
|
|
|
// AssigneeStats returns the summary restricted to one actor's rows.
|
|
//
|
|
// IT IS THE SAME STRUCT WITH FOUR FIELDS DEFINED DIFFERENTLY, and the
|
|
// differences are the shipped behavior of `bd status --assigned` rather
|
|
// than a design anyone would choose fresh:
|
|
//
|
|
// - THE SET IS WIDER. It is the actor's rows across the durable plane AND
|
|
// the ephemeral wisps tier, because the search seam merges the two
|
|
// unless told not to, where the workspace-wide answer counts the
|
|
// durable plane only. So this Total is NOT a subset of that one: an
|
|
// actor holding wisps can report more rows here than Stats reports for
|
|
// the entire workspace.
|
|
// - BlockedIssues COUNTS STATUS. Here it is the number of the actor's
|
|
// rows whose stored status is "blocked" — not the is_blocked flag Stats
|
|
// reports. The two answer different questions and can disagree in both
|
|
// directions.
|
|
// - ReadyIssues IS THE READY-WORK QUERY. Here it is the cardinality of
|
|
// the actor's ready work — the real dependency-aware question, with its
|
|
// exclusions — where Stats subtracts two numbers. This one is the
|
|
// stronger answer, and it is the narrower one.
|
|
// - PinnedIssues IS ALWAYS ZERO, along with the two fields that are
|
|
// always zero everywhere. The fold that produces this summary tallies
|
|
// the five statuses and the two suppressed-row counts, and nothing
|
|
// else. GateIssues and TemplateIssues ARE populated here — over the
|
|
// wider merged set the first bullet describes, which is this method's
|
|
// own plane semantics rather than a second definition of the counts.
|
|
//
|
|
// A FAILED READY-WORK QUERY IS REPORTED AS ZERO READY WORK, not as an
|
|
// error: the other five numbers are still right and the summary is still
|
|
// returned. That is the shipped behavior of both `bd status --assigned`
|
|
// routes, published here rather than quietly tightened, and it is the one
|
|
// place this role can hand back a number that is not an answer. A caller
|
|
// that must not confuse "none ready" with "could not tell" asks the
|
|
// ready-work question directly, where the failure is its own.
|
|
//
|
|
// An empty or whitespace-only Assignee is ErrValidation. An assignee that
|
|
// matches nothing is a zero-valued summary and a nil error, not a miss:
|
|
// "this actor has no work" is an answer.
|
|
AssigneeStats(ctx context.Context, req AssigneeStatsRequest) (StatsResult, error)
|
|
}
|