feat(count): accept --has-metadata-key (#6282)

bd list, bd ready and bd search all take --has-metadata-key. bd count did
not, so counting the rows that merely carry a key meant listing them and
measuring the page. This is the last metadata-filter parity gap between
count and the listings.

The storage layer already carries the filter: types.IssueFilter has
HasMetadataKey and sqlbuild.AppendMetadataClauses consumes it. What was
missing is the role field, the builder wiring, the CLI flag and the HTTP
contract, so this is one change rather than a stack.

Parsing matches list_input.go and ready_input.go, including the key
validation. BuildCountFilter now passes the key to ValidateMetadataFilters
instead of the empty string it passed before, which makes the role's
existing refusal reachable from the count surface; failReadErr already
classifies that error as a 400 on has_metadata_key.

apigen types are regenerated from the spec via go:generate, not hand
edited. The pinned CLI docs are untouched.

Fixes #6160

Co-authored-by: postoso <postoso@users.noreply.github.com>
Co-authored-by: Gas City Adopt-PR <noreply@example.com>
This commit is contained in:
postoso 2026-09-29 16:16:37 -04:00 • committed by GitHub
commit 9017d33745
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
14 changed files with 97 additions and 15 deletions

View file

@ -393,6 +393,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`--json` are unchanged; silence it with `--quiet` or
`BD_NO_PARTIAL_ID_NOTICE=1`.
- **`bd count` accepts `--has-metadata-key`**
([#6160](https://github.com/gastownhall/beads/issues/6160)), closing the last
metadata-filter gap against `bd list`, `bd ready` and `bd search`. A caller
counting rows that merely carry a key no longer has to list them and measure
the page.
- **`bd count` supports repeatable `--metadata-field key=value` filters**
([#6023](https://github.com/gastownhall/beads/issues/6023)), so callers can
count the same metadata-scoped set `bd list` returns without fetching every

View file

@ -121,6 +121,12 @@ func parseCountRequest(cmd *cobra.Command) (issueops.CountRequest, issueops.Coun
request.MetadataFields[k] = v
}
}
if k, _ := cmd.Flags().GetString("has-metadata-key"); k != "" {
if err := storage.ValidateMetadataKey(k); err != nil {
return issueops.CountRequest{}, "", HandleErrorRespectJSON("invalid --has-metadata-key: %v", err)
}
request.HasMetadataKey = k
}
if cmd.Flags().Changed("priority") {
priority, _ := cmd.Flags().GetInt("priority")
@ -279,6 +285,7 @@ func registerCountFlags(cmd *cobra.Command) {
cmd.Flags().Bool("no-assignee", false, "Filter issues with no assignee")
cmd.Flags().Bool("no-labels", false, "Filter issues with no labels")
cmd.Flags().StringArray("metadata-field", nil, "Filter by metadata field (key=value, repeatable)")
cmd.Flags().String("has-metadata-key", "", "Filter issues that have this metadata key set")
// Priority ranges
cmd.Flags().Int("priority-min", 0, "Filter by minimum priority (inclusive)")

View file

@ -90,12 +90,16 @@ func TestEmbeddedCount(t *testing.T) {
bdCreate(t, bd, dir, "Count labeled two", "--type", "task", "--label", "backend")
bdCreate(t, bd, dir, "Count notes issue", "--type", "task", "--description", "notes keyword here")
bdCreate(t, bd, dir, "Count metadata issue", "--type", "task", "--metadata", `{"count_scope":"matching"}`)
// The same key with a different value: --has-metadata-key matches both
// fixtures where --metadata-field matches one, so the two filters cannot
// pass by answering the same number.
bdCreate(t, bd, dir, "Count metadata key issue", "--type", "task", "--metadata", `{"count_scope":"other"}`)
// ===== Basic count =====
t.Run("basic_count_no_filters", func(t *testing.T) {
out := strings.TrimSpace(bdCount(t, bd, dir))
// Should return a number >= 9 (we created 9 issues)
// Should return a number >= 10 (we created 10 issues)
if out == "0" {
t.Error("expected non-zero count")
}
@ -179,6 +183,14 @@ func TestEmbeddedCount(t *testing.T) {
}
})
t.Run("filter_by_has_metadata_key", func(t *testing.T) {
got := int(bdCountJSON(t, bd, dir, "--has-metadata-key", "count_scope")["count"].(float64))
want := len(bdListJSON(t, bd, dir, "--all", "--limit", "0", "--has-metadata-key", "count_scope"))
if got != want || got != 2 {
t.Errorf("count --has-metadata-key = %d, want list cardinality %d and fixture count 2", got, want)
}
})
// ===== Title filter =====
t.Run("filter_by_title", func(t *testing.T) {

View file

@ -65,6 +65,7 @@ func TestParseCountRequestCarriesEveryFilterFlag(t *testing.T) {
"no-assignee": "true",
"no-labels": "true",
"metadata-field": "team=platform",
"has-metadata-key": "audit_ref",
"priority": "1",
"priority-min": "0",
"priority-max": "4",
@ -118,6 +119,7 @@ func TestParseCountRequestCarriesEveryFilterFlag(t *testing.T) {
NoAssignee: true,
NoLabels: true,
MetadataFields: map[string]string{"team": "platform"},
HasMetadataKey: "audit_ref",
IncludeInfra: true,
}
if !reflect.DeepEqual(request, want) {
@ -139,6 +141,16 @@ func TestParseCountRequestRejectsInvalidMetadataField(t *testing.T) {
}
}
func TestParseCountRequestRejectsInvalidHasMetadataKey(t *testing.T) {
flags := newCountFlagSet(t)
if err := flags.Flags().Set("has-metadata-key", "1bad"); err != nil {
t.Fatalf("set --has-metadata-key: %v", err)
}
if _, _, err := parseCountRequest(flags); err == nil {
t.Fatal("parseCountRequest accepted --has-metadata-key 1bad")
}
}
// TestParseCountRequestResolvesTheGroupingFlags pins each --by-* flag to its
// dimension and the refusal for two at once. The exclusivity check cannot live
// behind the role — by then only one dimension is left — so it is checked here.

View file

@ -31,6 +31,9 @@ func TestProxiedServerCount(t *testing.T) {
bdProxiedCreate(t, bd, p.dir, "Count labeled two", "--type", "task", "--label", "backend")
bdProxiedCreate(t, bd, p.dir, "Count notes issue", "--type", "task", "--description", "notes keyword here")
bdProxiedCreate(t, bd, p.dir, "Count metadata issue", "--type", "task", "--metadata", `{"count_scope":"matching"}`)
// The same key with a different value, so --has-metadata-key and
// --metadata-field cannot pass by answering the same number.
bdProxiedCreate(t, bd, p.dir, "Count metadata key issue", "--type", "task", "--metadata", `{"count_scope":"other"}`)
// countInt runs "count <args>" and parses the plain integer stdout.
countInt := func(t *testing.T, args ...string) int {
@ -129,6 +132,13 @@ func TestProxiedServerCount(t *testing.T) {
}
})
t.Run("filter_by_has_metadata_key", func(t *testing.T) {
got := countJSONInt(t, "--has-metadata-key", "count_scope")
if want := listCount("--has-metadata-key", "count_scope"); got != want || got != 2 {
t.Errorf("count --has-metadata-key = %d, want list cardinality %d and fixture count 2", got, want)
}
})
// ===== Priority filter =====
t.Run("filter_by_priority", func(t *testing.T) {

View file

@ -2363,6 +2363,9 @@ type CountIssuesParams struct {
// MetadataField Top-level metadata equality filter as `key=value`, split on the first `=`. Repeatable. An invalid key is a 400.
MetadataField *[]string `form:"metadata_field,omitempty" json:"metadata_field,omitempty"`
// HasMetadataKey Only issues carrying this top-level metadata key.
HasMetadataKey *string `form:"has_metadata_key,omitempty" json:"has_metadata_key,omitempty"`
// IncludeInfra Count the cardinality of `bd list --include-infra --all` instead of the durable plane. IT CHANGES FOUR THINGS AT ONCE, and they are listed rather than summarized because a caller reading "include infra" would expect one:
//
// 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 `type=gate` asks for them by name; and a `type` this workspace calls infra ROUTES the count to the ephemeral tier instead of the durable one.

View file

@ -114,6 +114,7 @@ func TestCountForwardsEveryDocumentedParameter(t *testing.T) {
"no_assignee": {"true"},
"no_labels": {"true"},
"metadata_field": {"team=platform", "env=prod"},
"has_metadata_key": {"audit_ref"},
"include_infra": {"true"},
}.Encode())
if resp.StatusCode != http.StatusOK {
@ -163,6 +164,7 @@ func TestCountForwardsEveryDocumentedParameter(t *testing.T) {
NoAssignee: true,
NoLabels: true,
MetadataFields: map[string]string{"team": "platform", "env": "prod"},
HasMetadataKey: "audit_ref",
IncludeInfra: true,
}
@ -540,9 +542,10 @@ func TestCountParametersMatchTheHandler(t *testing.T) {
// It also keeps the role's group refusal unreachable from the wire: the
// handler refuses an unknown group at the edge. Metadata validation is a
// separate path. An invalid key reaches BuildCountFilter, whose role refusal
// failReadErr classifies as a 400 on `metadata_field`. This test guards only the
// group vocabulary; if that enum and the role's constants diverged, a value the
// server accepted and the role refused would arrive as an unclassified 500.
// failReadErr classifies as a 400 on `metadata_field` or `has_metadata_key`.
// This test guards only the group vocabulary; if that enum and the role's
// constants diverged, a value the server accepted and the role refused would
// arrive as an unclassified 500.
func TestCountGroupEnumMatchesTheRolesVocabulary(t *testing.T) {
doc := loadSpec(t)
so := specOps(t, doc)["countIssues"]
@ -568,7 +571,7 @@ func TestCountGroupEnumMatchesTheRolesVocabulary(t *testing.T) {
// The other two are already mechanical: TestCountParametersMatchTheHandler ties
// the parameter names to the DOCUMENT, and TestCountForwardsEveryDocumentedParameter
// ties each parameter's VALUE to the field it lands in. Neither can see a role
// field that no parameter reaches — a 24th filter added to CountRequest and left
// field that no parameter reaches — a 25th filter added to CountRequest and left
// unpublished turns nothing red, and the wire silently stops being able to ask
// a question the role can answer. That is the failure this map closes, and it is
// the one that matters for an HTTP-backed store: it is how the wire becomes
@ -600,11 +603,12 @@ var countFieldForParameter = map[string]string{
"no_assignee": "NoAssignee",
"no_labels": "NoLabels",
"metadata_field": "MetadataFields",
"has_metadata_key": "HasMetadataKey",
"include_infra": "IncludeInfra",
}
// TestEveryCountRequestFieldIsPublished: the role publishes 24 filters and the
// wire publishes all 24. A field added to issueops.CountRequest fails here and
// TestEveryCountRequestFieldIsPublished: the role publishes 25 filters and the
// wire publishes all 25. A field added to issueops.CountRequest fails here and
// NAMES itself, so the choice is made deliberately — publish it, or record why
// it is withheld — rather than by nobody noticing.
//

View file

@ -720,9 +720,10 @@ var operationCodes = map[string][]Code{
// malformed values, repeated single-valued parameters and a `group_by`
// outside the closed set. countGroupOf stops that last case at the edge.
// The role has exactly one reachable refusal: BuildCountFilter rejects an
// invalid metadata key. failReadErr classifies it through invalidFilterParam
// as a 400 on `metadata_field`. An unrecognized status or type is not a
// refusal; the role promises it matches nothing and answers 0.
// invalid metadata key, from `metadata_field` or `has_metadata_key`.
// failReadErr classifies it through invalidFilterParam as a 400 naming the
// parameter it came from. An unrecognized status or type is not a refusal;
// the role promises it matches nothing and answers 0.
OpCountIssues: {CodeInvalidArgument, CodeUnauthenticated, CodeBusy, CodeDBUnavailable, CodeInternal},
// The listing's vocabulary minus the cursor: this operation has none, so
// invalid_cursor cannot arise. An unparseable EXPRESSION is an

View file

@ -217,6 +217,7 @@ func countFilters(q *query) issueops.CountRequest {
NoAssignee: q.boolean("no_assignee"),
NoLabels: q.boolean("no_labels"),
MetadataFields: q.metadataFields("metadata_field"),
HasMetadataKey: q.str("has_metadata_key"),
// The plane switch, forwarded as the boolean the caller sent. What it
// MEANS — merge the wisps tier, drop templates, drop gates, and route an

View file

@ -160,6 +160,7 @@ func TestABuilderRefusalIsTheDocumentedBadRequest(t *testing.T) {
{"a metadata field key on the ready surface", "/v0/beads/ready?metadata_field=1bad=x", "metadata_field"},
{"a has-metadata key on the ready surface", "/v0/beads/ready?has_metadata_key=1bad", "has_metadata_key"},
{"a metadata field key on the count surface", "/v0/beads/issues:count?metadata_field=1bad=x", "metadata_field"},
{"a has-metadata key on the count surface", "/v0/beads/issues:count?has_metadata_key=1bad", "has_metadata_key"},
} {
t.Run(tc.name, func(t *testing.T) {
ts, _ := newReadServer(t, Config{})

View file

@ -1977,6 +1977,11 @@ paths:
type: array
items:
type: string
- name: has_metadata_key
in: query
description: Only issues carrying this top-level metadata key.
schema:
type: string
- name: include_infra
in: query
description: >-
@ -2050,9 +2055,9 @@ paths:
A malformed `metadata_field` shape and an unknown `group_by` are
transport refusals. An invalid metadata key passes query decoding,
then `BuildCountFilter` rejects it and `failReadErr` classifies the
role's error as a `400` on `metadata_field`. An unrecognized
`status` or `type` is not a refusal; it matches nothing and answers
`0`.
role's error as a `400` naming the parameter it came from —
`metadata_field` or `has_metadata_key`. An unrecognized `status` or
`type` is not a refusal; it matches nothing and answers `0`.
x-bd-codes: [invalid_argument]
content:
application/problem+json:

View file

@ -67,7 +67,10 @@ func BuildCountFilter(in issueops.CountRequest, cfg ListConfig) (types.IssueFilt
if len(in.MetadataFields) > 0 {
filter.MetadataFields = in.MetadataFields
}
if err := ValidateMetadataFilters(in.MetadataFields, ""); err != nil {
if in.HasMetadataKey != "" {
filter.HasMetadataKey = in.HasMetadataKey
}
if err := ValidateMetadataFilters(in.MetadataFields, in.HasMetadataKey); err != nil {
return types.IssueFilter{}, err
}

View file

@ -173,6 +173,20 @@ func TestBuildCountFilterCarriesMetadataFields(t *testing.T) {
}
}
func TestBuildCountFilterCarriesHasMetadataKey(t *testing.T) {
got, err := BuildCountFilter(issueops.CountRequest{HasMetadataKey: "audit_ref"}, ListConfig{})
if err != nil {
t.Fatalf("BuildCountFilter: %v", err)
}
if got.HasMetadataKey != "audit_ref" {
t.Errorf("HasMetadataKey = %q, want %q", got.HasMetadataKey, "audit_ref")
}
if _, err := BuildCountFilter(issueops.CountRequest{HasMetadataKey: "1bad"}, ListConfig{}); err == nil {
t.Fatal("BuildCountFilter accepted an invalid has-metadata key")
}
}
// TestBuildCountFilterTakesStatusAndTypeAsWritten pins the deliberate absence
// of validation: an unrecognized status or type reaches the filter as written
// and matches nothing, rather than failing. A scripted caller counting a

View file

@ -92,8 +92,11 @@ type CountRequest struct {
TitleContains string
DescContains string
NotesContains string
// MetadataFields requires equality for every top-level key/value pair.
// 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