diff --git a/CHANGELOG.md b/CHANGELOG.md index f95a78ec2..08916be5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -661,6 +661,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 purge that used to delete a closed molecule root under a live step now leaves it. See the `--wisps-plane` entry under Added. +- **`bd status` now discloses the counted rows a default `bd list` will not + show.** `Total Issues` counts the database; `bd list` shows a filtered view of + it, and the two disagreed silently — an operator reconciling a total against + a listing found rows they could not account for. A new line names the + breakdown and the flags that reveal each part: `Not shown by bd list: 2 gates + (--include-gates --all), 1 template (--include-templates --all)`, omitted + entirely when there is nothing to disclose. The counts describe the database, + every status included, which is why the remedy names `--all` beside the type + flag: the default listing hides closed rows independently of what a row is, + so a closed gate is counted here and the type flag alone would not show it. + `gate_issues` and `template_issues` join the `--json` payload and the OpenAPI + `Statistics` schema, additively; they are broken out of `TotalIssues` rather + than removed from it, so the buckets still do not sum to the total in either + direction. `bd status --assigned` gets the same breakdown, which it needs for + the same reason against `bd list --assignee`. Not yet covered: durable rows + carrying a configured infra type (GH#6439), which need the workspace's + `types.infra` set that the portable count has no seam to read. + - **Proxied-server refusals now say *why* they refuse.** The JSON a refused command prints gains a `reason` field next to the existing `code`, `error` and `mutates`: `design` for a refusal that is expected to stay (shared diff --git a/backend/conformance/role_bundle_cases.go b/backend/conformance/role_bundle_cases.go index 0b0725aa4..04586ccf3 100644 --- a/backend/conformance/role_bundle_cases.go +++ b/backend/conformance/role_bundle_cases.go @@ -627,6 +627,8 @@ var roleContractCases = []roleContract{ func(b RoleContractBundle) func(t *testing.T) *StatsReporterFixture { return b.StatsReporter }, RunStatsReporterCountsEveryDurableRowByStatus, RunStatsReporterExcludesTheWispTier, + RunStatsReporterBreaksOutTheRowsTheDefaultListingSuppresses, + RunStatsReporterBreaksOutAGateThatIsAlsoATemplate, RunStatsReporterAStatusOutsideTheTalliesIsCountedOnlyInTotal, RunStatsReporterBlockedCountsTheGraphNotTheStatus, RunStatsReporterBlockedExcludesByStatusNotByThePinnedFlag, @@ -638,6 +640,7 @@ var roleContractCases = []roleContract{ RunStatsReporterAssigneeStatsScopesToOneActor, RunStatsReporterAssigneeBlockedCountsTheStatusNotTheGraph, RunStatsReporterAssigneeStatsMergesTheWispTier, + RunStatsReporterAssigneeStatsBreaksOutTheSuppressedRows, RunStatsReporterAssigneeStatsPopulatesBothPointers, RunStatsReporterAssigneeStatsRefusesAnEmptyAssignee, ), diff --git a/backend/conformance/stats_reporter_contract.go b/backend/conformance/stats_reporter_contract.go index 34a7b3940..071bd1008 100644 --- a/backend/conformance/stats_reporter_contract.go +++ b/backend/conformance/stats_reporter_contract.go @@ -103,6 +103,88 @@ func RunStatsReporterExcludesTheWispTier(t *testing.T, ctx context.Context, fixt assertStatsReporterDelta(t, before, after, statsReporterCounts{total: 1, open: 1}) } +// RunStatsReporterBreaksOutTheRowsTheDefaultListingSuppresses pins the +// GateIssues and TemplateIssues tally: the durable rows a default `bd list` +// will not show, broken out of Total rather than removed from it, so `bd +// status` and `bd list` can be reconciled instead of silently disagreeing. +// +// The two predicates have to be the exact complements of the listing's: +// `issue_type = 'gate'` against list.go's `ExcludeTypes = append(..., "gate")`, +// and `is_template = 1` against sqlbuild's default +// `(is_template = 0 OR is_template IS NULL)`. A backend that spelled either +// one loosely - `is_template <> 0`, or a LIKE on the type - moves the same +// numbers on these seeds, so the case also seeds the NEGATIVE rows: a plain +// task, and a gate-typed row that is not a template, each of which must move +// exactly one of the two counts and not the other. +// +// Both counts overlap the status buckets rather than forming their own, in the +// same way PinnedIssues does; the deltas below assert that by counting the +// gate and proto rows in Total and Open as well. +// +// THE POPULATION IS EVERY STATUS, which the closed pair below is here to +// decide. Open seeds alone cannot: a backend counting these over all statuses +// and one counting them only over the rows a default listing shows report +// identical numbers on every open row, so the contract would leave the +// question to each implementation. A closed gate and a closed proto separate +// the two readings, and this file is where that belongs - it is the axis +// `bd status`'s printed remedy turns on, and all three backends answer it here +// at once. +func RunStatsReporterBreaksOutTheRowsTheDefaultListingSuppresses(t *testing.T, ctx context.Context, fixture StatsReporterFixture) { + t.Helper() + before := statsReporterSummary(t, ctx, fixture, publicops.StatsRequest{}) + + // Neither suppression: the control. A backend that counted every row + // would move both counts by three rather than by one. + seedStatsReporterIssue(t, ctx, fixture, statsReporterSeed(fixture, "suppressed-plain", types.StatusOpen)) + + gate := statsReporterSeed(fixture, "suppressed-gate", types.StatusOpen) + gate.IssueType = types.TypeGate + seedStatsReporterIssue(t, ctx, fixture, gate) + + proto := statsReporterSeed(fixture, "suppressed-proto", types.StatusOpen) + proto.IsTemplate = true + seedStatsReporterIssue(t, ctx, fixture, proto) + + // The status axis. These two are suppressed by the default listing TWICE + // over - once for what they are, once for being closed - and they are + // counted here all the same, because the two counts describe the database + // the way TotalIssues does and not the rows a listing shows. A backend + // that scoped either count to the listing's default population passes + // every seed above and fails on exactly these. + closedGate := statsReporterSeed(fixture, "suppressed-closed-gate", types.StatusClosed) + closedGate.IssueType = types.TypeGate + seedStatsReporterIssue(t, ctx, fixture, closedGate) + + closedProto := statsReporterSeed(fixture, "suppressed-closed-proto", types.StatusClosed) + closedProto.IsTemplate = true + seedStatsReporterIssue(t, ctx, fixture, closedProto) + + after := statsReporterSummary(t, ctx, fixture, publicops.StatsRequest{}) + assertStatsReporterDelta(t, before, after, statsReporterCounts{ + total: 5, open: 3, closed: 2, gates: 2, templates: 2, + }) +} + +// RunStatsReporterBreaksOutAGateThatIsAlsoATemplate pins that the two +// suppressions are independent: a proto's gate step is both a gate and a +// template, and `bd list` hides it for either reason on its own, so it belongs +// in both counts. A backend that treated the two as exclusive arms of one CASE +// reports one of them as zero here while passing the case above. +func RunStatsReporterBreaksOutAGateThatIsAlsoATemplate(t *testing.T, ctx context.Context, fixture StatsReporterFixture) { + t.Helper() + before := statsReporterSummary(t, ctx, fixture, publicops.StatsRequest{}) + + both := statsReporterSeed(fixture, "suppressed-gateproto", types.StatusOpen) + both.IssueType = types.TypeGate + both.IsTemplate = true + seedStatsReporterIssue(t, ctx, fixture, both) + + after := statsReporterSummary(t, ctx, fixture, publicops.StatsRequest{}) + assertStatsReporterDelta(t, before, after, statsReporterCounts{ + total: 1, open: 1, gates: 1, templates: 1, + }) +} + // RunStatsReporterAStatusOutsideTheTalliesIsCountedOnlyInTotal pins the second // half of statsreporter.go:92-98 — the tallies are exact equality against the // stored status, so a row whose status is none of the four lands in Total and @@ -452,6 +534,43 @@ func RunStatsReporterAssigneeStatsMergesTheWispTier(t *testing.T, ctx context.Co } } +// RunStatsReporterAssigneeStatsBreaksOutTheSuppressedRows is the scoped half of +// the pair. `bd status --assigned` reaches a different implementation - the +// fold over one actor's rows in internal/workapi/stats.go, not +// ScanIssueCountsInTx - and its filter sets only Assignee, so the actor's gates +// and protos ARE in these rows while `bd list --assignee` suppresses both. The +// two counts must therefore be populated here too; a zero would be the same +// silent disagreement, one scope down. +func RunStatsReporterAssigneeStatsBreaksOutTheSuppressedRows(t *testing.T, ctx context.Context, fixture StatsReporterFixture) { + t.Helper() + assignee := statsReporterAssignee(fixture, "asuppressed") + + plain := statsReporterSeed(fixture, "asuppressed-plain", types.StatusOpen) + plain.Assignee = assignee + seedStatsReporterIssue(t, ctx, fixture, plain) + + gate := statsReporterSeed(fixture, "asuppressed-gate", types.StatusOpen) + gate.Assignee = assignee + gate.IssueType = types.TypeGate + seedStatsReporterIssue(t, ctx, fixture, gate) + + proto := statsReporterSeed(fixture, "asuppressed-proto", types.StatusOpen) + proto.Assignee = assignee + proto.IsTemplate = true + seedStatsReporterIssue(t, ctx, fixture, proto) + + summary := statsReporterAssigneeSummary(t, ctx, fixture, assignee) + if summary.TotalIssues != 3 { + t.Fatalf("TotalIssues = %d, want 3 (the fixture namespaces this actor, so this is an absolute)", summary.TotalIssues) + } + if summary.GateIssues != 1 { + t.Errorf("GateIssues = %d, want 1 — the actor's gate is in this answer but not in `bd list --assignee`", summary.GateIssues) + } + if summary.TemplateIssues != 1 { + t.Errorf("TemplateIssues = %d, want 1 — the actor's proto is in this answer but not in `bd list --assignee`", summary.TemplateIssues) + } +} + // RunStatsReporterAssigneeStatsPopulatesBothPointers pins the clause // FoldStatsAssigneeSummary exists to guarantee: on this path BlockedIssues and // ReadyIssues are ALWAYS non-nil, including for an actor with no rows at all. @@ -499,6 +618,8 @@ type statsReporterCounts struct { deferred int pinned int blocked int + gates int + templates int } // assertStatsReporterDelta compares two summaries field by field against the @@ -519,6 +640,8 @@ func assertStatsReporterDelta(t *testing.T, before, after types.Statistics, want {"ClosedIssues", before.ClosedIssues, after.ClosedIssues, want.closed}, {"DeferredIssues", before.DeferredIssues, after.DeferredIssues, want.deferred}, {"PinnedIssues", before.PinnedIssues, after.PinnedIssues, want.pinned}, + {"GateIssues", before.GateIssues, after.GateIssues, want.gates}, + {"TemplateIssues", before.TemplateIssues, after.TemplateIssues, want.templates}, } { if got := field.after - field.before; got != field.want { t.Errorf("%s moved by %d (%d -> %d), want %d", field.name, got, field.before, field.after, field.want) diff --git a/cmd/bd/BUILD.bazel b/cmd/bd/BUILD.bazel index ca40a43c9..efd498e15 100644 --- a/cmd/bd/BUILD.bazel +++ b/cmd/bd/BUILD.bazel @@ -1077,6 +1077,7 @@ go_test( "state_test.go", "status_embedded_test.go", "status_proxied_integration_test.go", + "status_suppressed_test.go", "status_test.go", "statuses_types_proxied_integration_test.go", "stdio_race_guard_test.go", diff --git a/cmd/bd/status.go b/cmd/bd/status.go index 20404aa8e..855f67679 100644 --- a/cmd/bd/status.go +++ b/cmd/bd/status.go @@ -3,6 +3,7 @@ package main import ( "fmt" "os" + "strings" "github.com/spf13/cobra" "github.com/steveyegge/beads/internal/metrics" @@ -120,6 +121,70 @@ func openStatsReporter() (issueops.StatsReporter, error) { return store.StatsReporter() } +// suppressedTypeSummary describes the counted rows that a default bd list will +// not show, so the totals above can be reconciled against a listing instead of +// looking like a phantom. +// +// THE REMEDY IT PRINTS NAMES TWO FLAGS, not one, because the default listing +// applies its TYPE and its STATUS suppressions independently. These counts +// come from the same scan as TotalIssues and are status-blind with it: a +// CLOSED gate is in GateIssues. `bd list --include-gates` would still not show +// that row, because the default ExcludeStatus of closed and pinned +// (internal/workapi/list.go) is lifted only by --all - which "replaces the +// status exclusions only" and lifts no type exclusion of its own, pinned as +// that phrase in backend/conformance/reader_contract.go. So the type flag on +// its own is a remedy that reproduces the number only in a workspace whose +// gates and protos all happen to still be open, and gates are closed as the +// work they guard completes. Naming both flags is what makes the printed +// remedy actually reconcile; a hint that does not is the same silent +// disagreement this line exists to remove, one level down. +// +// It names two of the three type-based suppressions a default listing applies. +// The third - the infra types, which applyTypeSuppressions +// (internal/workapi/list.go) adds to ExcludeTypes independently of the wisp +// plane bit - is NOT here, and not because a durable infra row is unreachable. +// It is reachable: the plane routing and the listing's exclusions both read the +// WORKSPACE-CONFIGURED types.infra set, and changing that set only invalidates +// a cache (internal/storage/dolt/config.go) - it never moves rows already +// written. So durable rows created while a type was not infra stay in the +// issues plane once it becomes one, and a type evicted from the set creates +// durable rows outright (pinned by the create contract in +// backend/conformance/issue_operations_contract.go). Counting them therefore +// needs that configured set, which ScanIssueCountsInTx - pure portable SQL with +// no config seam - cannot reach. Tracked separately rather than guessed at +// here with the built-in names, which would be wrong in exactly the workspaces +// where it matters. +func suppressedTypeSummary(stats *types.Statistics) string { + var parts []string + if stats.GateIssues > 0 { + parts = append(parts, fmt.Sprintf("%s (--include-gates --all)", pluralCount(stats.GateIssues, "gate", "gates"))) + } + if stats.TemplateIssues > 0 { + parts = append(parts, fmt.Sprintf("%s (--include-templates --all)", pluralCount(stats.TemplateIssues, "template", "templates"))) + } + return strings.Join(parts, ", ") +} + +// pluralCount renders a count with the right one of two spellings. Both forms +// are passed in rather than derived by appending "s", so a caller with an +// irregular plural is not silently mis-served. +// +// It is not a fourth spelling of the three helpers already in package main: +// pluralIssue, pluralize and plural all DERIVE the "s" and so cannot render a +// caller-chosen pair. The tree's one two-form helper, pluralWord in +// internal/storage/issueops/lease.go, is unexported in a storage package, and +// exporting it so a CLI string could reach it would add exported surface to a +// storage role for a cosmetic. That file's own doc comment records the same +// trade from the other side - it carries whole words because the issueops +// plural() covers only the "s" case - so one two-form helper per package is +// the established shape here. +func pluralCount(n int, singular, plural string) string { + if n == 1 { + return fmt.Sprintf("%d %s", n, singular) + } + return fmt.Sprintf("%d %s", n, plural) +} + func renderStatus(stats *types.Statistics, recentActivity *RecentActivitySummary) error { output := &StatusOutput{ Summary: stats, @@ -155,6 +220,10 @@ func renderStatus(stats *types.Statistics, recentActivity *RecentActivitySummary fmt.Printf(" Ready to Work: %s\n", ui.RenderPass(fmt.Sprintf("%d", *stats.ReadyIssues))) } + if suppressed := suppressedTypeSummary(stats); suppressed != "" { + fmt.Printf(" Not shown by bd list: %s\n", suppressed) + } + // Extended statistics (only show if non-zero) hasExtended := stats.PinnedIssues > 0 || stats.EpicsEligibleForClosure > 0 || stats.AverageLeadTime > 0 diff --git a/cmd/bd/status_suppressed_test.go b/cmd/bd/status_suppressed_test.go new file mode 100644 index 000000000..0c026f64e --- /dev/null +++ b/cmd/bd/status_suppressed_test.go @@ -0,0 +1,161 @@ +package main + +import ( + "os" + "path/filepath" + "strings" + "testing" + + "github.com/steveyegge/beads/internal/types" +) + +func TestSuppressedTypeSummary(t *testing.T) { + tests := []struct { + name string + stats *types.Statistics + want string + }{ + { + name: "nothing suppressed", + stats: &types.Statistics{TotalIssues: 3}, + want: "", + }, + { + name: "one gate", + stats: &types.Statistics{TotalIssues: 2, GateIssues: 1}, + want: "1 gate (--include-gates --all)", + }, + { + name: "gates are pluralized", + stats: &types.Statistics{TotalIssues: 4, GateIssues: 3}, + want: "3 gates (--include-gates --all)", + }, + { + name: "gates and templates", + stats: &types.Statistics{TotalIssues: 5, GateIssues: 1, TemplateIssues: 2}, + want: "1 gate (--include-gates --all), 2 templates (--include-templates --all)", + }, + { + name: "templates only", + stats: &types.Statistics{TotalIssues: 5, TemplateIssues: 1}, + want: "1 template (--include-templates --all)", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if got := suppressedTypeSummary(tt.stats); got != tt.want { + t.Errorf("suppressedTypeSummary() = %q, want %q", got, tt.want) + } + }) + } +} + +// The disclosure exists so the operator can account for a total that no listing +// reproduces; it must name the flags that reveal the rows. Plural, and asserted +// here rather than left to the table above, because the two suppressions are +// independent: these counts span every status, while --include-gates lifts only +// the TYPE exclusion. A Contains check on the type flag alone passes on the +// incomplete hint, which would reproduce the number only in a workspace whose +// gates and protos all happen to still be open. +func TestSuppressedTypeSummaryNamesTheRevealingFlags(t *testing.T) { + for _, tt := range []struct { + name string + stats *types.Statistics + want string + }{ + {"gates", &types.Statistics{TotalIssues: 2, GateIssues: 1}, "--include-gates --all"}, + {"templates", &types.Statistics{TotalIssues: 2, TemplateIssues: 1}, "--include-templates --all"}, + } { + t.Run(tt.name, func(t *testing.T) { + if got := suppressedTypeSummary(tt.stats); !strings.Contains(got, tt.want) { + t.Errorf("suppressedTypeSummary() = %q, want it to name %q", got, tt.want) + } + }) + } +} + +// renderStatusOutput captures what renderStatus writes to stdout. +func renderStatusOutput(t *testing.T, stats *types.Statistics) string { + t.Helper() + + stdioMutex.Lock() + defer stdioMutex.Unlock() + + path := filepath.Join(t.TempDir(), "stdout") + f, err := os.Create(path) + if err != nil { + t.Fatalf("create stdout capture: %v", err) + } + + oldStdout := os.Stdout + oldJSON := jsonOutput + var renderErr error + func() { + defer func() { + os.Stdout = oldStdout + jsonOutput = oldJSON + }() + os.Stdout = f + jsonOutput = false + renderErr = renderStatus(stats, nil) + }() + + if err := f.Close(); err != nil { + t.Fatalf("close stdout capture: %v", err) + } + if renderErr != nil { + t.Fatalf("renderStatus: %v", renderErr) + } + out, err := os.ReadFile(path) + if err != nil { + t.Fatalf("read stdout capture: %v", err) + } + return string(out) +} + +// The summary formatter being right is not the same as the line reaching the +// operator: suppressedTypeSummary is a pure function over a hand-built struct, +// and every assertion above passes with the renderStatus call site deleted. +func TestRenderStatusEmitsTheSuppressedRowsLine(t *testing.T) { + blocked, ready := 0, 2 + stats := &types.Statistics{ + TotalIssues: 9, + OpenIssues: 4, + BlockedIssues: &blocked, + ReadyIssues: &ready, + GateIssues: 2, + TemplateIssues: 1, + } + + out := renderStatusOutput(t, stats) + + if !strings.Contains(out, "Not shown by bd list:") { + t.Fatalf("renderStatus did not emit the disclosure line:\n%s", out) + } + for _, want := range []string{"2 gates (--include-gates --all)", "1 template (--include-templates --all)"} { + if !strings.Contains(out, want) { + t.Errorf("renderStatus output missing %q:\n%s", want, out) + } + } + // The disclosure has to sit with the totals it reconciles, not down in the + // extended block that only renders when other counters are non-zero. + if idx, total := strings.Index(out, "Not shown by bd list:"), strings.Index(out, "Total Issues:"); idx < total { + t.Errorf("disclosure line precedes the totals it reconciles:\n%s", out) + } +} + +// A workspace with neither kind of row must not gain a line that says nothing. +func TestRenderStatusOmitsTheLineWhenNothingIsSuppressed(t *testing.T) { + blocked, ready := 0, 1 + stats := &types.Statistics{ + TotalIssues: 3, + OpenIssues: 1, + BlockedIssues: &blocked, + ReadyIssues: &ready, + } + + if out := renderStatusOutput(t, stats); strings.Contains(out, "Not shown by bd list") { + t.Errorf("renderStatus emitted the disclosure with nothing suppressed:\n%s", out) + } +} diff --git a/internal/httpapi/spec/openapi.v0.yaml b/internal/httpapi/spec/openapi.v0.yaml index ad273a79a..85e55bb1c 100644 --- a/internal/httpapi/spec/openapi.v0.yaml +++ b/internal/httpapi/spec/openapi.v0.yaml @@ -7153,6 +7153,27 @@ components: average_lead_time_hours: type: number description: ALWAYS 0, for the reason above. + gate_issues: + type: integer + description: >- + Gate rows, which the default `bd list` suppresses on account of what + they are rather than on any filter the caller passed. + + + ALREADY INCLUDED in `total_issues`, which counts the database rather + than the listing — so this is a breakdown of that total, never an + addition to it. It is broken out so the two surfaces can be + reconciled instead of silently disagreeing about how many issues + exist. + template_issues: + type: integer + description: >- + Template rows, suppressed by the default `bd list` on the same terms + as `gate_issues` and likewise already counted in `total_issues`. + + + Do not sum the two: a row can be both a gate and a template, and + would be counted once in each. # The two cycle schemas are pinned like the seven above, and to the same end, # but to the canonical types in `issueops` rather than in `internal/types`: # the role's own result IS the CLI's `--json` element, so `bd dep cycles` diff --git a/internal/storage/dolt/stats_reporter_contract_test.go b/internal/storage/dolt/stats_reporter_contract_test.go index 900afc11f..8d578167f 100644 --- a/internal/storage/dolt/stats_reporter_contract_test.go +++ b/internal/storage/dolt/stats_reporter_contract_test.go @@ -27,6 +27,12 @@ func TestStatsReporterContract(t *testing.T) { t.Run("ExcludesTheWispTier", func(t *testing.T) { conformance.RunStatsReporterExcludesTheWispTier(t, ctx, fixture) }) + t.Run("BreaksOutTheRowsTheDefaultListingSuppresses", func(t *testing.T) { + conformance.RunStatsReporterBreaksOutTheRowsTheDefaultListingSuppresses(t, ctx, fixture) + }) + t.Run("BreaksOutAGateThatIsAlsoATemplate", func(t *testing.T) { + conformance.RunStatsReporterBreaksOutAGateThatIsAlsoATemplate(t, ctx, fixture) + }) t.Run("AStatusOutsideTheTalliesIsCountedOnlyInTotal", func(t *testing.T) { conformance.RunStatsReporterAStatusOutsideTheTalliesIsCountedOnlyInTotal(t, ctx, fixture) }) @@ -60,6 +66,9 @@ func TestStatsReporterContract(t *testing.T) { t.Run("AssigneeStatsMergesTheWispTier", func(t *testing.T) { conformance.RunStatsReporterAssigneeStatsMergesTheWispTier(t, ctx, fixture) }) + t.Run("AssigneeStatsBreaksOutTheSuppressedRows", func(t *testing.T) { + conformance.RunStatsReporterAssigneeStatsBreaksOutTheSuppressedRows(t, ctx, fixture) + }) t.Run("AssigneeStatsPopulatesBothPointers", func(t *testing.T) { conformance.RunStatsReporterAssigneeStatsPopulatesBothPointers(t, ctx, fixture) }) diff --git a/internal/storage/embeddeddolt/stats_reporter_contract_test.go b/internal/storage/embeddeddolt/stats_reporter_contract_test.go index 97615535e..cb201ef28 100644 --- a/internal/storage/embeddeddolt/stats_reporter_contract_test.go +++ b/internal/storage/embeddeddolt/stats_reporter_contract_test.go @@ -32,6 +32,12 @@ func TestStatsReporterContract(t *testing.T) { t.Run("ExcludesTheWispTier", func(t *testing.T) { conformance.RunStatsReporterExcludesTheWispTier(t, ctx, fixture) }) + t.Run("BreaksOutTheRowsTheDefaultListingSuppresses", func(t *testing.T) { + conformance.RunStatsReporterBreaksOutTheRowsTheDefaultListingSuppresses(t, ctx, fixture) + }) + t.Run("BreaksOutAGateThatIsAlsoATemplate", func(t *testing.T) { + conformance.RunStatsReporterBreaksOutAGateThatIsAlsoATemplate(t, ctx, fixture) + }) t.Run("AStatusOutsideTheTalliesIsCountedOnlyInTotal", func(t *testing.T) { conformance.RunStatsReporterAStatusOutsideTheTalliesIsCountedOnlyInTotal(t, ctx, fixture) }) @@ -65,6 +71,9 @@ func TestStatsReporterContract(t *testing.T) { t.Run("AssigneeStatsMergesTheWispTier", func(t *testing.T) { conformance.RunStatsReporterAssigneeStatsMergesTheWispTier(t, ctx, fixture) }) + t.Run("AssigneeStatsBreaksOutTheSuppressedRows", func(t *testing.T) { + conformance.RunStatsReporterAssigneeStatsBreaksOutTheSuppressedRows(t, ctx, fixture) + }) t.Run("AssigneeStatsPopulatesBothPointers", func(t *testing.T) { conformance.RunStatsReporterAssigneeStatsPopulatesBothPointers(t, ctx, fixture) }) diff --git a/internal/storage/issueops/statistics.go b/internal/storage/issueops/statistics.go index 280851d9b..907fb6edb 100644 --- a/internal/storage/issueops/statistics.go +++ b/internal/storage/issueops/statistics.go @@ -8,9 +8,10 @@ import ( ) // ScanIssueCountsInTx populates the count fields (TotalIssues, OpenIssues, -// InProgressIssues, ClosedIssues, DeferredIssues, PinnedIssues) of stats from -// the issues table. It does NOT compute BlockedIssues or ReadyIssues — callers -// fill those in using their own blocked-ID computation strategy. +// InProgressIssues, ClosedIssues, DeferredIssues, PinnedIssues, GateIssues, +// TemplateIssues) of stats from the issues table. It does NOT compute +// BlockedIssues or ReadyIssues — callers fill those in using their own +// blocked-ID computation strategy. func ScanIssueCountsInTx(ctx context.Context, tx DBTX, stats *types.Statistics) error { if err := tx.QueryRowContext(ctx, ` SELECT @@ -19,7 +20,9 @@ func ScanIssueCountsInTx(ctx context.Context, tx DBTX, stats *types.Statistics) COALESCE(SUM(CASE WHEN status = 'in_progress' THEN 1 ELSE 0 END), 0), COALESCE(SUM(CASE WHEN status = 'closed' THEN 1 ELSE 0 END), 0), COALESCE(SUM(CASE WHEN status = 'deferred' THEN 1 ELSE 0 END), 0), - COALESCE(SUM(CASE WHEN pinned = 1 THEN 1 ELSE 0 END), 0) + COALESCE(SUM(CASE WHEN pinned = 1 THEN 1 ELSE 0 END), 0), + COALESCE(SUM(CASE WHEN issue_type = 'gate' THEN 1 ELSE 0 END), 0), + COALESCE(SUM(CASE WHEN is_template = 1 THEN 1 ELSE 0 END), 0) FROM issues `).Scan( &stats.TotalIssues, @@ -28,6 +31,8 @@ func ScanIssueCountsInTx(ctx context.Context, tx DBTX, stats *types.Statistics) &stats.ClosedIssues, &stats.DeferredIssues, &stats.PinnedIssues, + &stats.GateIssues, + &stats.TemplateIssues, ); err != nil { return fmt.Errorf("scan issue counts: %w", err) } diff --git a/internal/storage/uow/stats_reporter_contract_test.go b/internal/storage/uow/stats_reporter_contract_test.go index 36f0ed049..327532b6b 100644 --- a/internal/storage/uow/stats_reporter_contract_test.go +++ b/internal/storage/uow/stats_reporter_contract_test.go @@ -27,6 +27,12 @@ func TestStatsReporterContract(t *testing.T) { t.Run("ExcludesTheWispTier", func(t *testing.T) { conformance.RunStatsReporterExcludesTheWispTier(t, ctx, fixture) }) + t.Run("BreaksOutTheRowsTheDefaultListingSuppresses", func(t *testing.T) { + conformance.RunStatsReporterBreaksOutTheRowsTheDefaultListingSuppresses(t, ctx, fixture) + }) + t.Run("BreaksOutAGateThatIsAlsoATemplate", func(t *testing.T) { + conformance.RunStatsReporterBreaksOutAGateThatIsAlsoATemplate(t, ctx, fixture) + }) t.Run("AStatusOutsideTheTalliesIsCountedOnlyInTotal", func(t *testing.T) { conformance.RunStatsReporterAStatusOutsideTheTalliesIsCountedOnlyInTotal(t, ctx, fixture) }) @@ -60,6 +66,9 @@ func TestStatsReporterContract(t *testing.T) { t.Run("AssigneeStatsMergesTheWispTier", func(t *testing.T) { conformance.RunStatsReporterAssigneeStatsMergesTheWispTier(t, ctx, fixture) }) + t.Run("AssigneeStatsBreaksOutTheSuppressedRows", func(t *testing.T) { + conformance.RunStatsReporterAssigneeStatsBreaksOutTheSuppressedRows(t, ctx, fixture) + }) t.Run("AssigneeStatsPopulatesBothPointers", func(t *testing.T) { conformance.RunStatsReporterAssigneeStatsPopulatesBothPointers(t, ctx, fixture) }) diff --git a/internal/types/types.go b/internal/types/types.go index 725d8a01d..127def0ca 100644 --- a/internal/types/types.go +++ b/internal/types/types.go @@ -1915,6 +1915,21 @@ type Statistics struct { PinnedIssues int `json:"pinned_issues"` // Persistent issues EpicsEligibleForClosure int `json:"epics_eligible_for_closure"` AverageLeadTime float64 `json:"average_lead_time_hours"` + + // GateIssues and TemplateIssues count rows the default `bd list` suppresses + // on account of what they are. They are already part of TotalIssues, which + // counts the database rather than the listing; they are broken out so the + // two commands can be reconciled instead of silently disagreeing. + // + // THE POPULATION IS EVERY STATUS, exactly TotalIssues': a CLOSED gate is + // counted in GateIssues, and the two overlap the status buckets the way + // PinnedIssues does rather than partitioning them. They are not scoped to + // the rows a default listing shows. That is why `bd status` prints --all + // beside the type flag - the listing's status exclusion is independent of + // its type exclusions, so the type flag alone would not reveal every row + // counted here (cmd/bd/status.go). + GateIssues int `json:"gate_issues"` + TemplateIssues int `json:"template_issues"` } // IssueFilter is used to filter issue queries diff --git a/internal/workapi/stats.go b/internal/workapi/stats.go index 5ba37e558..24289ea3e 100644 --- a/internal/workapi/stats.go +++ b/internal/workapi/stats.go @@ -57,6 +57,13 @@ func BuildStatsAssigneeWorkFilter(assignee string) types.WorkFilter { // does NOT set is part of that definition: PinnedIssues, // EpicsEligibleForClosure and AverageLeadTime stay zero. // +// GateIssues and TemplateIssues ARE set. They are not workspace-wide numbers +// borrowed into a scoped answer: this route's filter sets only Assignee, so +// IsTemplate stays nil and the actor's gates and protos really are among these +// rows, while `bd list --assignee` suppresses both. Leaving them zero would +// give the scoped answer the same silent disagreement with its own listing +// that the workspace-wide answer had. +// // 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 @@ -75,6 +82,16 @@ func FoldStatsAssigneeSummary(issues []*types.Issue, readyCount int) types.Stati continue } stats.TotalIssues++ + // The rows a default `bd list --assignee` will not show. The same + // reconciliation gap the workspace-wide answer has: this filter sets + // only Assignee, so IsTemplate stays nil and gates and templates ARE + // in these rows, while the listing suppresses both. + if issue.IssueType == types.TypeGate { + stats.GateIssues++ + } + if issue.IsTemplate { + stats.TemplateIssues++ + } switch issue.Status { case types.StatusOpen: stats.OpenIssues++ diff --git a/internal/workapi/stats_test.go b/internal/workapi/stats_test.go index 1cfd73a10..a14b29994 100644 --- a/internal/workapi/stats_test.go +++ b/internal/workapi/stats_test.go @@ -73,6 +73,8 @@ func TestFoldStatsAssigneeSummary(t *testing.T) { blocked int deferred int closed int + gates int + templates int }{ { name: "counts every status and ready work", @@ -101,6 +103,30 @@ func TestFoldStatsAssigneeSummary(t *testing.T) { issues: []*types.Issue{nil, {Status: types.StatusOpen}}, ready: 0, total: 1, open: 1, }, + { + // The rows a default `bd list --assignee` will not show. This + // route's filter sets only Assignee, so IsTemplate stays nil and + // the actor's gates and protos really are in these rows - leaving + // the two counts at zero would give the scoped answer the same + // silent disagreement with its own listing the workspace-wide + // answer had. They overlap the status buckets rather than forming + // their own, exactly as PinnedIssues does workspace-wide. + name: "gates and protos are broken out of the total, not removed from it", + issues: []*types.Issue{ + {Status: types.StatusOpen}, + {Status: types.StatusOpen, IssueType: types.TypeGate}, + {Status: types.StatusClosed, IssueType: types.TypeGate}, + {Status: types.StatusOpen, IsTemplate: true}, + }, + ready: 1, total: 4, open: 3, closed: 1, gates: 2, templates: 1, + }, + { + // A gate that is also a proto is counted in both, since the two + // listing suppressions are independent. + name: "a templated gate is counted in both breakdowns", + issues: []*types.Issue{{Status: types.StatusOpen, IssueType: types.TypeGate, IsTemplate: true}}, + ready: 0, total: 1, open: 1, gates: 1, templates: 1, + }, } for _, tt := range tests { @@ -115,6 +141,9 @@ func TestFoldStatsAssigneeSummary(t *testing.T) { if got.ReadyIssues == nil || *got.ReadyIssues != tt.ready { t.Errorf("ready issues = %v, want %d", got.ReadyIssues, tt.ready) } + if got.GateIssues != tt.gates || got.TemplateIssues != tt.templates { + t.Errorf("gate/template issues = %d/%d, want %d/%d", got.GateIssues, got.TemplateIssues, tt.gates, tt.templates) + } // The three fields AssigneeStats says are always zero here. They // are not "not yet implemented" on this path: the fold has no // input that could produce them. diff --git a/issueops/statsreporter.go b/issueops/statsreporter.go index 1b2d2d889..9444f1515 100644 --- a/issueops/statsreporter.go +++ b/issueops/statsreporter.go @@ -86,19 +86,32 @@ type StatsResult struct { // 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 "six counts of one set" is the mistake this doc is written to +// them as "eight counts of one set" is the mistake this doc is written to // prevent: // -// - TotalIssues, OpenIssues, InProgressIssues, ClosedIssues, DeferredIssues -// and PinnedIssues 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. +// - 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 bullet above describes, and the +// 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 @@ -179,7 +192,10 @@ type StatsReporter interface { // 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 nothing else. + // 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