* feat(count): --include-ephemeral, the plane knob `bd count` never had `bd count` can admit the wisps table only through `--include-infra`, which makes four changes at once. This adds the flag that makes just the first one, mirroring the `--include-ephemeral` that `bd list` gained in #6098. ## Why the plane is unreachable on its own The write path routes on STORAGE CLASS, not type — dolt's `useWispsTable` is `Ephemeral || NoHistory || WispType != "" || IsInfraType`. So a `no_history` task lives in the wisps TABLE while remaining ordinary durable work, and a default `bd count` never sees it. Recovering it today means `--include-infra`, which this repo's own doc calls "FOUR changes at once and not one": it admits the plane, drops the infra-type exclusions, changes the template treatment, and reconciles cardinality with `bd list --all`. Its template exclusion then silently drops template rows of the named type — so a caller who wanted the plane trades one silent undercount for another. `ListRequest.IncludeEphemeral` has been the narrow answer on the listing side since #5476, and #6098 gave it a CLI flag. `CountRequest` had no equivalent field at all. This is the missing half of that pair. ## The change - `issueops.CountRequest.IncludeEphemeral` — the plane knob alone: exactly the first of `IncludeInfra`'s four changes, with none of the other three. - `internal/workapi/count.go` — one line, `} else if !in.IncludeEphemeral {`. - `cmd/bd/count.go` — flag registration, matching `bd list`'s wording. - `internal/httpapi` — `include_ephemeral` on `countIssues`, in the spec; the generated `types.gen.go` is `make api-gen` output, not hand-edited. Unset, the count is durable-plane only: the historical answer, unchanged. Every default is untouched. It does NOT promise a count and a listing agree. They already differ on TEMPLATES without this flag and still do with it — a count includes template rows unless `IncludeInfra` excludes them, a listing excludes them unless `IncludeTemplates` admits them. That predates this and is unchanged by it; only `IncludeInfra` sets out to reconcile cardinality, and it pays with three changes beyond the plane. ## Verification ok github.com/steveyegge/beads/internal/workapi ok github.com/steveyegge/beads/internal/httpapi ok github.com/steveyegge/beads/issueops --- PASS: TestEmbeddedCountIncludeEphemeral (39.71s) --- PASS: TestCountIncludeInfraFlagShape --- PASS: TestParseCountRequestCarriesEveryFilterFlag `TestEmbeddedCountIncludeEphemeral` was run with `BEADS_TEST_EMBEDDED_DOLT=1` and really executed — 39.71s, not a skip. The default fast tier would have skipped it and reported `ok`. `make api-gen` reproduces `types.gen.go` byte-for-byte from the spec hunk, so the two cannot drift apart in review. `go build ./...`, `go vet` and `gofmt` clean. Claude-Session: https://claude.ai/code/session_01X1jMLQTSrCwtzFRS1xeUC6 * count: reframe the comments for this repo, not the fork they came from Review on #6240 (bee-ghosttrack): five comment blocks were written from the fork's point of view and become false once merged here — "belongs upstream", "the half that still has to go upstream", "the fork's old wide default", and "upstream's default" meaning the current default. Find-and-replace, as asked: the reasoning is kept, only the frame of reference changes. "upstream's default" -> "the default before this change"; the bd list sibling "landed in #6098"; the infra-type divergence is "pinned, not fixed, here" with the reason; the embedded test's fork-maintenance history is replaced by what it actually pins. No code changes. * build(bazel): list the two test files this PR adds in their go_test srcs Maintainer review fixes for #6240, review iteration 1. The synthesis and the quality scorecard both returned approve with no required changes; this commit takes the one minor whose subject is the PR's own added files. Taken: - Change Impact / Blast Radius (minor, gate impact minor). The PR adds cmd/bd/count_include_ephemeral_embedded_test.go and internal/workapi/count_skipwisps_test.go, but neither was listed in its package's explicit go_test srcs, so the PR's own assertions were invisible to `bazel test`. Both rows are now listed. Gazelle's verdict, not a hand-guess: `make bazel-sync` was run (bazel 9.2.0 is available here) and it produced exactly these two entries. Its full output also rewrote 12 other BUILD.bazel files -- pre-existing base drift from other PRs' files, plus dep/select churn -- which is out of scope for this PR, so the generated result was reverted and only the two rows this PR is responsible for were re-applied, at the slots gazelle chose. Both srcs lists remain sorted with no duplicates (cmd/bd bd_test 637 entries, internal/workapi workapi_test 24 entries). The cgo build tag on count_include_ephemeral_embedded_test.go does not exempt it: the repo lists tag-gated *_embedded_test.go files anyway (99 of the 101 in cmd/bd are listed, and the sampled ones are simultaneously listed and tagged). Declined: - Test Evidence Quality (nit, gate impact none). The filing lane itself marked it optional and explicitly said not to gate on it, and its own reasoning holds: internal/storage/dolt/counts.go and internal/storage/embeddeddolt/counts.go both delegate to the same issueops.CountIssuesInTx, differing only in transaction acquisition. Validation: go build ./... and CGO_ENABLED=1 go vet on cmd/bd, internal/workapi and issueops all clean; go test ./internal/workapi/ ./issueops/ ok. No production code changed -- the commit is two generated-list rows. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
280 lines
14 KiB
Go
280 lines
14 KiB
Go
package issueops
|
|
|
|
import (
|
|
"context"
|
|
"time"
|
|
)
|
|
|
|
// CountGroup names a bucketing dimension for a grouped count. The set is
|
|
// closed: a value outside it is ErrValidation rather than an empty answer,
|
|
// because a caller that misspelled a dimension and got zero buckets back has
|
|
// no way to tell that from a store with nothing in it.
|
|
type CountGroup string
|
|
|
|
const (
|
|
CountGroupStatus CountGroup = "status"
|
|
CountGroupPriority CountGroup = "priority"
|
|
CountGroupType CountGroup = "type"
|
|
CountGroupAssignee CountGroup = "assignee"
|
|
CountGroupLabel CountGroup = "label"
|
|
)
|
|
|
|
// CountRequest describes one issue-count query: the predicate, and nothing
|
|
// about a page.
|
|
//
|
|
// It is a HIGH-LEVEL request in the sense ReadyRequest and ListRequest are —
|
|
// label normalization, id splitting and the wisp-tier policy all happen inside
|
|
// — but it is NOT a ListRequest with the paging fields removed, and the
|
|
// difference is the whole reason this is a separate type. A default `bd list`
|
|
// hides closed, pinned, template and gate rows; a default `bd count` hides
|
|
// none of them and answers for every durable row that matches. Sharing
|
|
// ListRequest would have made the two questions look interchangeable at the
|
|
// call site while their answers differed by every one of those exclusions.
|
|
//
|
|
// THERE IS NO Limit AND NO Offset, deliberately. A count is a cardinality:
|
|
// bounding the scan would answer "how many of the first N" and there is no
|
|
// front door that wants that. The storage seam ignores both fields on the
|
|
// count path, so accepting them here would be accepting two knobs that do
|
|
// nothing.
|
|
//
|
|
// THERE IS NO FREE-TEXT QUERY either. The count seam takes one — the same
|
|
// full-text argument search does — and both front doors have always passed the
|
|
// empty string. A field no caller sets is a field whose behavior nothing
|
|
// checks, so it is left off rather than published untested; TitleSearch and
|
|
// the three *Contains fields are the substring matches that ARE reachable.
|
|
type CountRequest struct {
|
|
// Status restricts to one stored status. Empty and the literal "all" both
|
|
// mean every status, which is what makes a bare count answer for closed
|
|
// rows as well as open ones.
|
|
//
|
|
// It is NOT validated against the workspace vocabulary and NOT a
|
|
// comma-separated OR set: an unrecognized name matches nothing and returns
|
|
// zero rather than failing, exactly as ReadyRequest.IssueType does. That is
|
|
// the shipped behavior of both front doors and it is stated here rather
|
|
// than quietly tightened, because a scripted caller that counts a status
|
|
// its workspace has since dropped currently reads 0 and would start reading
|
|
// an error.
|
|
Status string
|
|
// IssueType restricts the type, with the same match-nothing-rather-than-fail
|
|
// treatment Status gets and no alias expansion at all.
|
|
//
|
|
// It has a SECOND effect under IncludeInfra: an infra type routes the count
|
|
// to the ephemeral tier. See that field.
|
|
IssueType string
|
|
// Assignee restricts to one actor's rows; NoAssignee restricts to rows with
|
|
// none. Setting both is not refused — they are handed to the filter as
|
|
// written and answer with the empty intersection.
|
|
Assignee string
|
|
|
|
// Priority is an exact priority; PriorityMin and PriorityMax bound a range
|
|
// inclusively. All three are pointers because 0 is a real priority, for the
|
|
// reason ReadyRequest.Priority gives.
|
|
Priority *int
|
|
PriorityMin *int
|
|
PriorityMax *int
|
|
|
|
// Labels must ALL be present; LabelsAny requires at least one. Both are
|
|
// raw: entries are trimmed and de-duplicated INSIDE, and a slice whose
|
|
// entries are all blank is the same as an unset one.
|
|
Labels []string
|
|
LabelsAny []string
|
|
|
|
// TitleSearch is a case-insensitive substring match on the title.
|
|
TitleSearch string
|
|
// IDFilter is a comma-separated id set. Splitting, trimming and
|
|
// de-duplication happen inside, so a caller passes the string it was given
|
|
// rather than a slice it had to prepare.
|
|
IDFilter string
|
|
|
|
// TitleContains, DescContains and NotesContains are substring matches on
|
|
// the three long fields, spelled as ListRequest spells them so the two
|
|
// requests cannot drift apart in naming while meaning the same thing.
|
|
TitleContains string
|
|
DescContains string
|
|
NotesContains string
|
|
// MetadataFields requires equality for every top-level key/value pair and
|
|
// HasMetadataKey is a top-level key-presence filter, spelled as
|
|
// ListRequest and ReadyRequest spell them. Keys are validated inside.
|
|
MetadataFields map[string]string
|
|
HasMetadataKey string
|
|
|
|
CreatedAfter *time.Time
|
|
CreatedBefore *time.Time
|
|
UpdatedAfter *time.Time
|
|
UpdatedBefore *time.Time
|
|
ClosedAfter *time.Time
|
|
ClosedBefore *time.Time
|
|
|
|
// EmptyDesc, NoAssignee and NoLabels restrict to rows missing each of those.
|
|
EmptyDesc bool
|
|
NoAssignee bool
|
|
NoLabels bool
|
|
|
|
// IncludeInfra switches the count from the durable plane to the cardinality
|
|
// of `bd list --include-infra --all`, which is FOUR changes at once and not
|
|
// one (GH#4387):
|
|
//
|
|
// - the ephemeral wisps tier is merged in, picking up both wisps and the
|
|
// no_history beads that are durable work stored in that tier;
|
|
// - template molecules are excluded, which a default count includes;
|
|
// - gate beads are excluded, unless IssueType asks for gates by name;
|
|
// - an IssueType the workspace calls infra routes the count to the
|
|
// ephemeral tier instead of the durable one.
|
|
//
|
|
// The infra vocabulary is the WORKSPACE's, read from configuration inside
|
|
// the implementation. A caller does not supply it and cannot: that is the
|
|
// config load this role exists to keep off both front doors.
|
|
//
|
|
// Unset, the count is durable-plane only and applies none of those four —
|
|
// the historical `bd count` answer, kept exactly so a scripted caller reads
|
|
// the same number it read yesterday.
|
|
IncludeInfra bool
|
|
|
|
// IncludeEphemeral admits the EPHEMERAL PLANE — the wisps TABLE — and
|
|
// admits nothing else. It is the plane knob on its own: exactly the first
|
|
// of IncludeInfra's four changes, with none of the other three.
|
|
//
|
|
// It exists because there was no way to ask for that one thing. The write
|
|
// path routes on STORAGE CLASS, not type (dolt's useWispsTable is
|
|
// `Ephemeral || NoHistory || WispType != "" || IsInfraType`), so a
|
|
// no_history task lives in the wisps table while remaining ordinary durable
|
|
// work. Counting it needed IncludeInfra, which ALSO drops template rows of
|
|
// the named type — a silent undercount traded for a silent undercount.
|
|
//
|
|
// Same meaning as ListRequest.IncludeEphemeral (see issueops/reader.go):
|
|
// both admit the same PLANE under the same filters. It does NOT promise the
|
|
// two answers are equal — a count and a listing already differ on TEMPLATES
|
|
// without this flag, and still do with it. A count includes template rows
|
|
// unless IncludeInfra excludes them; a listing excludes them unless
|
|
// IncludeTemplates admits them. That predates this field and is unchanged by
|
|
// it; only IncludeInfra sets out to reconcile cardinality, and it pays for
|
|
// that with three changes beyond the plane.
|
|
//
|
|
// Unset, the count is durable-plane only: the historical answer, unchanged.
|
|
IncludeEphemeral bool
|
|
}
|
|
|
|
// CountResult is the cardinality of the matching set.
|
|
type CountResult struct {
|
|
// Total is the number of matching rows. It is an int64 because the storage
|
|
// seam counts in one, not because a workspace is expected to hold four
|
|
// billion beads.
|
|
Total int64
|
|
}
|
|
|
|
// CountByGroupRequest describes one bucketed count.
|
|
type CountByGroupRequest struct {
|
|
// Filter is the same predicate a scalar count takes, so the two questions
|
|
// cannot be asked of different sets. It is embedded by NAME rather than
|
|
// anonymously: a grouped count is a scalar count plus a dimension, and
|
|
// spelling the dimension beside the whole filter says that, where promoted
|
|
// fields would have made GroupBy look like one more predicate.
|
|
Filter CountRequest
|
|
// GroupBy is the bucketing dimension and must be one of the five
|
|
// CountGroup constants. An empty or unknown value is ErrValidation, not a
|
|
// scalar count in disguise: a caller that wanted a number calls Count.
|
|
GroupBy CountGroup
|
|
}
|
|
|
|
// CountByGroupResult is one bucketed count.
|
|
type CountByGroupResult struct {
|
|
// Groups maps each bucket's DISPLAY key to its cardinality. The keys are
|
|
// normalized, and the normalization is part of this contract because both
|
|
// front doors print them unmodified:
|
|
//
|
|
// - a priority bucket is "P" followed by the number, so priority 1 is
|
|
// "P1";
|
|
// - the assignee bucket for unassigned rows is "(unassigned)", never the
|
|
// empty string, which would be indistinguishable from a store whose
|
|
// assignee column holds one;
|
|
// - the label bucket for rows carrying no label at all is "(no labels)",
|
|
// and it is ABSENT rather than zero when every matching row has one;
|
|
// - status and type buckets are the stored value verbatim.
|
|
//
|
|
// A dimension with no matching rows yields an empty map, never nil.
|
|
Groups map[string]int
|
|
// Total is the cardinality of the whole matching set — the SAME number a
|
|
// scalar Count of Filter returns, and NOT the sum of Groups.
|
|
//
|
|
// The two differ for exactly one dimension, and it is the reason this field
|
|
// exists rather than being left to the caller to add up: label buckets
|
|
// OVERLAP. An issue carrying three labels is one row in Total and one row
|
|
// in each of three buckets, so a caller that summed them would report a
|
|
// workspace three times its size. Every front door that prints a grouped
|
|
// count prints a total above it, and deriving that total is a decision this
|
|
// role makes once instead of each surface making it again.
|
|
//
|
|
// It is NOT promised to be one snapshot with Groups. The store-backed
|
|
// implementation runs the scalar and the grouped query separately, so a
|
|
// concurrent write between them can leave Total disagreeing with the
|
|
// buckets by that write. Nothing here is transactional across the two, and
|
|
// a caller reconciling them under load should not expect it to be.
|
|
Total int64
|
|
}
|
|
|
|
// Counter describes counting issues: the operation `bd count` performs, and —
|
|
// like Lifecycle, Reader, ReadyClaimer, BatchCloser, DependencyEditor,
|
|
// Commenter and Relations — 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 COUNTED VARIANT OF Reader because it
|
|
// answers a different question. Reader answers with PAGES OF ISSUES: its
|
|
// requests carry a limit, an offset, a keyset position, a sort and a has-more
|
|
// verdict, and every one of those describes which rows come back and in what
|
|
// order. A count has no rows and therefore no order, no page and no cursor —
|
|
// it is a number about a set. Folding it into Reader would have meant a
|
|
// request type carrying paging fields that a count must ignore, which is the
|
|
// shape that makes a caller believe `--limit 10` bounded the answer.
|
|
//
|
|
// BOTH METHODS BELONG TO THE ONE ROLE, and that is not the rule bending. The
|
|
// governing rule forbids APPENDING to an existing role, not a role being born
|
|
// with the two shapes of one question: a scalar count and a bucketed count ask
|
|
// the same predicate of the same set and differ only in whether the answer is
|
|
// one number or a number per bucket. They also cannot be separated in
|
|
// practice — a grouped answer carries the scalar Total, because label buckets
|
|
// overlap and the sum is wrong (see CountByGroupResult.Total) — so splitting
|
|
// them would put one role's promise inside another role's result.
|
|
//
|
|
// WHAT IS NOT HERE. `bd status` and its `bd stats` alias look like counts and
|
|
// are not: their numbers are dependency-aware (ready work, blocked work,
|
|
// staleness) and are not expressible as a predicate over one table, so they
|
|
// get a role of their own rather than a sixth CountGroup. The count of READY
|
|
// work is likewise a different question — the ready predicate is not a filter
|
|
// this request can describe — and is its own role for the same reason.
|
|
//
|
|
// Implementations never mutate caller-owned request values, snapshot the
|
|
// request at method entry, and apply normalization only to attempt-local
|
|
// clones. That promise is load-bearing here and not merely conventional:
|
|
// CountRequest carries two slices, and label normalization is the step that
|
|
// would otherwise write through them.
|
|
//
|
|
// Counting 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.
|
|
//
|
|
// THE PER-ROLE COST of adding a role like this one — the accessor, the two
|
|
// decorator wrappers, the unit-of-work source and the three conformance
|
|
// wirings — is written down in engdocs/ADDING_AN_ISSUEOPS_ROLE.md. Counter is
|
|
// the role that checklist was derived from.
|
|
type Counter interface {
|
|
// Count returns how many issues match the request. An empty request counts
|
|
// every durable row in the workspace, including closed ones: a count
|
|
// applies none of the listing's default exclusions.
|
|
//
|
|
// A predicate that matches nothing is 0 and a nil error. That is the whole
|
|
// of the "not found" story for this role — there is no ErrNotFound here,
|
|
// because a question about a set has an answer even when the set is empty,
|
|
// and a caller polling for work would otherwise have to classify an error
|
|
// to read a zero.
|
|
Count(ctx context.Context, req CountRequest) (CountResult, error)
|
|
|
|
// CountByGroup returns the same count bucketed by one dimension, plus the
|
|
// scalar Total of the whole matching set.
|
|
//
|
|
// An unknown GroupBy is ErrValidation. Buckets with no rows are absent
|
|
// rather than present at zero: the dimensions are open-ended (any assignee,
|
|
// any label, any custom status), so there is no closed set of keys to
|
|
// enumerate and a caller reads absence as zero.
|
|
CountByGroup(ctx context.Context, req CountByGroupRequest) (CountByGroupResult, error)
|
|
}
|