beads/issueops/querier.go
Harry Miller 0e317c4fc0
fix(query): apply bd list's piped-output limit policy to bd query (#6229) (#6744)
* fix(query): apply bd list's piped-output limit policy to bd query (#6229)

Root cause: bd list resolves an unflagged --limit through a policy that
treats piped stdout as unlimited (GH#4094), but bd query read its --limit
flag straight through, so its default of workapi.DefaultQueryLimit (50)
applied to piped output too. `bd query '...' | consumer` silently dropped
every row past 50; the truncation hint did not fire either, because it only
prints when stderr is a terminal.

Fix: factor the unflagged tail of bd list's policy into unflaggedLimit /
resolveUnflaggedLimit in list_input.go and call it from both commands, so
they cannot drift. bd list's switch is unchanged in behavior; bd query's
change is a single localized branch in gatherQueryInput.

Precedence for bd query, mirroring bd list:
  1. explicit --limit (including 0) wins
  2. piped stdout -> 0 (unlimited)
  3. agent mode on a terminal -> 20
  4. otherwise the 50 default
bd list keeps its own --all and list.limit branches ahead of step 2; bd
query has neither (its --all means "include closed", and there is no
query.limit config key), so none was invented.

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>

* review: document the query path's absent defensive cap; unstale a reachability comment

Maintainer review fixes for PR #6744 (GH#6229). Both are comment-only; no
behavior changes.

issueops.QueryRequest.Limit now states that nothing backstops it. ListRequest
pairs its Limit with MaxRows, a circuit breaker for an oversized answer, and
neither knob that sets that one (--max-rows, BEADS_MAX_ROWS) is read anywhere
on the query path, so an unlimited query is unbounded in the plain sense. That
was already reachable via `--limit 0`; this PR makes a piped `bd query` reach
it without asking, which is what makes it worth writing down. Recording the
absence is the documented half of the reviewers' choice — threading a MaxRows
twin onto QueryRequest stays available as a follow-up.

unionCountsGoSideSortKeepsTheRightSubset's comment justified its case with
"DefaultQueryLimit means a limit is always set", which this PR falsified for
the CLI half: an unflagged piped `bd query '<expr>' --sort id` now arrives on
the IsGoSideSort path with Limit 0 and no bound. The HTTP surface still brings
a bound, because an absent `limit` parameter resolves to DefaultQueryLimit, so
the clause is requalified rather than dropped. The assertions were never
affected — they pass an explicit Limit: 5.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
2026-09-26 02:50:09 -07:00

159 lines
8.5 KiB
Go

package issueops
import (
"context"
)
// QueryRequest describes one boolean-expression query: the question `bd query`
// asks, plus the page it wants back.
//
// THE EXPRESSION IS THE PREDICATE, and that is what makes this request unlike
// every other one here. CountRequest, ListRequest and ReadyRequest spell their
// predicate as FIELDS — one per filter, ANDed together — and a caller composes
// them by setting more of them. This request carries a SENTENCE, in the query
// mini-language `bd query` publishes, and that language has OR, NOT and
// parentheses, which no conjunction of fields can express. Parsing, evaluation
// and the choice of how to execute the result all happen inside; a caller says
// what it wants matched and never how the match is shaped.
type QueryRequest struct {
// Expression is the query, in the language `bd query --help` documents:
// field comparisons (`status=open`, `priority>1`, `created>7d`) combined
// with AND, OR, NOT and parentheses.
//
// It is parsed INSIDE. An expression that is blank, unparseable, or that
// names a field or operator the language does not have is ErrValidation
// naming the fault, never an empty page: a caller that misspelled a field
// and got zero rows back has no way to tell that from a store with nothing
// in it.
Expression string
// IncludeClosed admits closed issues, which the query otherwise hides.
//
// THE HIDING IS CONDITIONAL, and the condition is part of this contract
// because both front doors have always applied it: closed rows are
// excluded UNLESS this is set, or unless the expression itself compares
// `status`. So `status=closed` answers with closed rows on its own, and
// `NOT status=open` does too — an expression that has an opinion about
// status keeps it, and only an expression with none gets the default. The
// flag `bd query --all` sets is this one.
IncludeClosed bool
// SortBy names the display order and Reverse inverts it, over the same
// vocabulary ListRequest.SortBy takes. Empty leaves the rows in the order
// the query returned them.
//
// WHAT THE ORDER IS APPLIED TO depends on what bounded the query, and the
// difference is worth stating because it is observable. The order is
// applied to the rows the QUERY bounded, then the page is cut from them —
// the epilogue `bd list` runs (workapi.FinishPage). For a
// filter-expressible query the database applied Limit, so the order sorts
// the page. For a PREDICATE query nothing bounded the query — see
// Querier.Query — so the order sorts the whole matching set and the page
// is its head. `bd list` has the same split for the same reason: a sort
// SQL cannot express fetches everything and trims afterwards.
SortBy string
Reverse bool
// Limit bounds the page the caller RECEIVES. Nil means the shared query
// default; 0 means unlimited. It is a pointer so that "unset" and
// "explicitly unlimited" stay distinguishable, which is what lets one
// constant serve both surfaces. A negative Limit is ErrValidation rather
// than a synonym for unlimited: two spellings of "no bound" is one more
// than a caller can check for.
//
// NOTHING BACKSTOPS IT. ListRequest pairs its Limit with MaxRows, a
// circuit breaker that refuses an oversized answer outright; this request
// has no twin to it by design, and neither knob that sets that one
// (`--max-rows`, BEADS_MAX_ROWS) is read anywhere on the query path. So an
// unlimited query is unbounded in the plain sense: it reads every row the
// expression matches, however many that is, and a caller who asked for one
// gets it rather than an ErrTooManyRows. The ceiling here is Limit itself.
// This is reachable without asking: a piped `bd query` resolves its
// unflagged limit to 0 before the request, the same policy `bd list` has
// applied to piped output since GH#4094.
Limit *int
// Offset skips the first N MATCHING rows, on EVERY implementation and for
// EVERY shape of expression, exactly as ListRequest.Offset does. A
// negative Offset is ErrValidation everywhere.
//
// IT IS UNIFORM, not per-expression, and that is a decision rather than an
// accident of the seams. One body renders SQL OFFSET for a
// filter-expressible query and the other reaches past the skipped rows and
// drops them in Go; both skip in Go for a predicate query, which is
// unbounded and has nothing to push down. Which shape an expression takes
// is decided by the evaluator, not by the caller, so an Offset that
// behaved differently for `type=bug OR type=task` than for `type=bug`
// would be unpredictable from the outside. One answer everywhere is the
// only checkable promise.
//
// IT SKIPS MATCHES — never candidate rows. A skip
// applied before the predicate would discard rows the predicate would have
// rejected anyway and hand back a short page, which is the failure that
// made `bd query --offset` refuse OR queries outright.
//
// AN OFFSET WITH A SortBy IS ErrValidation, at every backend. The order is
// applied to the rows the query BOUNDED (see SortBy), so under a page
// bound each page is sorted for itself: a walk with an offset would neither
// visit every row nor visit any row once. Refusing the combination is the
// only answer that is true on both shapes of query; accepting it would mean
// publishing a walk that silently is not one.
Offset int
}
// Querier answers boolean-expression queries: the operation `bd query`
// performs, and — like Counter, Reader and ReadyCounter — 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 SHAPE OF Reader.List because the two take
// predicates that are not the same KIND of thing. A ListRequest is a
// conjunction: every field it carries narrows the answer, and there is no
// arrangement of them that expresses "type=bug OR label=urgent", let alone
// "NOT (priority<2 AND assignee=none)". Handing this expression to List would
// mean either adding a free-text member to ListRequest — a field the other
// eleven callers must ignore, on the request type this library's largest
// surface already shares — or teaching List a second execution mode. The
// question is different, so the role is.
//
// EQUALLY, IT IS NOT A RAW QUERY PASSTHROUGH. The language has no SQL in it:
// no table names, no joins, no ORDER BY, no way to name a column the
// vocabulary does not publish. It is a closed set of fields over one row
// shape, which is why a role can promise anything about it at all.
type Querier interface {
// Query returns the page of issues the expression matches.
//
// THE PREDICATE IS EVALUATED AGAINST THE WHOLE CANDIDATE SET. That
// sentence is the point of this method and the fix it shipped with.
//
// An expression the storage filter vocabulary can express — a comparison,
// a chain of ANDs, a NOT over status or type, an OR over labels — is
// executed by the database, which applies Limit itself. Every other
// expression is a PREDICATE query: the database is asked for the base
// filters the expression implies and the predicate is applied to the rows
// in Go. For those, the query is issued UNBOUNDED and the predicate sees
// every candidate row, so the page is the first Limit MATCHES of the
// complete matching set.
//
// It was not always. Both front doors used to bound that query at
// max(3*Limit, 100) rows and filter what came back, so a match beyond that
// window was absent from the page AND unreported by has-more: an OR query
// over a workspace of any size returned an arbitrary prefix of its answer
// and called it complete. The window is gone. What it cost is stated
// rather than hidden: a predicate query reads every row its base filters
// admit, so a broad expression over a large workspace is a large read.
//
// HasMore is true exactly when the page is shorter than the matching set,
// which for a predicate query it can now compute rather than guess.
//
// An expression that matches nothing is an empty page and a nil error —
// Items is never nil on a successful call. There is no ErrNotFound here:
// a question about a set has an answer even when the set is empty.
//
// Querying 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, and
// result values are unspecified when error is non-nil. Implementations
// never mutate caller-owned request values.
Query(ctx context.Context, req QueryRequest) (IssuePage, error)
}