beads/cmd/bd/max_rows_test.go
Jim Wordelman a9a48d6e36
test(cli,storage): BEADS_MAX_ROWS behavioral + opt-out gate tests (be-x42v) (#4160)
* feat(storage): be-x42v.1 BEADS_MAX_ROWS defensive cap foundation

Add IssueFilter.MaxRows + IssueFilter.MaxRowsSource and a typed
issueops.ErrTooManyRows error. searchTableInTx routes its LIMIT through
EffectiveSearchLimit (LIMIT MaxRows+1 when MaxRows>0, with Limit
preserved otherwise); SearchIssuesInTx checks EnforceMaxRowsCap after
the issues+wisps merge so the cap reflects the count returned to the
caller. Both helpers are exported so future PG-backend support can
reuse the same logic.

Default MaxRows=0 disables the cap and is byte-identical to today at
every existing call site. Limit semantics are unchanged: Limit=0 still
means unlimited at the contract level.

PG backend is not on origin/main yet; PG cap support is a follow-up
when the postgres backend merges. Validator's per-backend bead exercises
the issueops path via Dolt/embedded fixtures.

Refs: be-x42v (designer §3/§6.2), be-jp5s (architecture D1/R-03).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(cli): be-x42v.2 wire --max-rows / BEADS_MAX_ROWS on CLI surface

Adds cmd/bd/max_rows.go with three helpers: addMaxRowsFlag registers
--max-rows int with the designer's spec help text, resolveMaxRows
picks flag > env > 0 (negative flag → exit 1, bad env → warn-and-ignore),
and handleMaxRowsError pattern-matches *issueops.ErrTooManyRows to
emit the two-line stderr message and exit 2 with stdout empty.

The flag is wired on bd list, bd ready, bd dep tree, bd find-duplicates,
and bd graph (designer §4). The env-only resolveMaxRowsEnvOnly variant
is wired on bd lint and the SearchIssues paths inside bd doctor
(conventions + pollution checks). bd cleanup, bd gc, bd export,
bd export --auto, bd migrate-issues, and bd jira explicitly set
MaxRows=0 / MaxRowsSource="" in code so a misconfigured env can't
abort a data-integrity sweep partway through.

bd ready needed storage-layer support too: WorkFilter gains MaxRows +
MaxRowsSource and GetReadyWorkInTx routes its LIMIT through
EffectiveSearchLimit and enforces the cap via EnforceMaxRowsCap on
the row count returned to the caller. bd dep tree applies the cap at
the CLI layer on the TreeNode count since the tree walk doesn't go
through IssueFilter.

bd config show gains a standalone-env collector so BEADS_MAX_ROWS
shows up alongside BEADS_DIR etc. when set. The Viper-managed env
detection skips it because BEADS_MAX_ROWS isn't bound to a config key.

Adds a CONTRIBUTING.md section documenting the opt-out rule for new
IssueFilter sites that aren't on designer §4's wired-up list, with a
pointer to the validator's opt-out test gates (be-x42v.4).

Smoke-tested against the rig database (298 issues):
- bd list --max-rows 5 → exit 2, "--max-rows=5"
- BEADS_MAX_ROWS=5 bd list → exit 2, "BEADS_MAX_ROWS=5"
- BEADS_MAX_ROWS=banana bd list --limit 3 → warn + exit 0
- BEADS_MAX_ROWS=5 bd list --max-rows 0 --limit 3 → exit 0
- bd list --max-rows -1 → exit 1, "must be non-negative"
- bd ready --max-rows 5 → exit 2 (storage layer fires)
- bd dep tree be-jp5s --max-rows 1 → exit 2 (CLI-layer count)
- bd find-duplicates --max-rows 5 → exit 2
- bd graph --all --max-rows 5 → exit 2
- BEADS_MAX_ROWS=5 bd lint → exit 2 (env-only)
- BEADS_MAX_ROWS=5 bd export → exit 0, 299 lines (opt-out)
- BEADS_MAX_ROWS=10 bd config show → lists BEADS_MAX_ROWS

The 10 CLI behavioral test scenarios for bd list are owned by
be-x42v.3 (validator). Coverage for the non-list paths, the env-only
doctor family, and config show is filed as be-u8z9 (needs-tests,
routed to validator).

Refs: be-x42v (designer §2-§5), be-x42v.1 (foundation).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: release gate PASS for be-x42v.1 + be-x42v.2 (BEADS_MAX_ROWS)

Documents PASS evaluation across the six gate criteria for the
storage foundation (be-x42v.1, 3900c1bdc) and the CLI wiring
(be-x42v.2, dea537c56) shipping together. Review verdicts: be-xf0o
(foundation) and be-2p12 (CLI), both PASS from Opus 4.7 reviewer.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: regenerate CLI reference for --max-rows flag

* docs: revert federation to pure-go stub in CLI_REFERENCE.md

CI's check-doc-flags freshness check runs generate-cli-docs.sh with
CGO_ENABLED=0. The previous regeneration used a CGO binary, expanding
the federation section with subcommands. Revert to the requires-CGO
stub that the pure-go binary produces.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: revert website federation.md pages to pure-go stub (be-x42v)

Three website cli-reference/federation.md files still had CGO-enabled
content after CLI_REFERENCE.md was reverted. This commit brings them
into sync with the pure-go stub, resolving the Check doc flags freshness
CI failure on PR #3908.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(cli): be-u8z9 BEADS_MAX_ROWS non-list command paths + config show

Locks down the manually-verified behavior shipped in be-x42v.2 across the
CLI surface beyond `bd list`.

cmd/bd/max_rows_test.go (new):
  - ReadyMaxRows_FlagOverCap_Exits2  - bd ready --max-rows N → exit 2
  - ReadyMaxRows_EnvOverCap_Exits2   - BEADS_MAX_ROWS=N bd ready → exit 2
  - DepTreeMaxRows_TreeNodes_Exits2  - tree-node count cap in dep tree
  - FindDuplicatesMaxRows_Exits2     - find-duplicates --max-rows N
  - GraphAllMaxRows_Exits2           - graph --all --max-rows N
  - LintMaxRows_EnvOnly_Exits2       - bd lint with BEADS_MAX_ROWS=N
  - LintMaxRows_NoFlagAccepted       - cobra rejects --max-rows on lint
  - ConfigShow_ListsBeadsMaxRows     - bd config show surfaces the env var
  - ConventionsMaxRows_EnvOnly       - skipped (bd doctor needs server mode,
                                       follow-up filed as be-pc8c)
  - PollutionMaxRows_EnvOnly         - skipped (same reason)

cmd/bd/ready_max_rows_test.go (new):
  - TestGetReadyWork_MaxRowsSuite — exercises WorkFilter.MaxRows in
    GetReadyWork (under cap / over cap / zero disabled / with Limit
    matrix), via newTestStore. Companion to the SearchIssues parity
    work in be-x42v.3.

Refs: be-u8z9 (this bead), be-x42v.2 (builder), be-pc8c (follow-up).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(cli,storage): be-x42v.3 BEADS_MAX_ROWS bd list scenarios + backend parity

Covers the 10 CLI scenarios from designer §6.1 against `bd list` and the
5 storage scenarios from designer §6.2 against both Dolt-server and
embedded backends.

cmd/bd/max_rows_test.go (extended):
  TestEmbeddedMaxRowsList — 10 subtests on a shared 21-issue rig:
    - Disabled_NoEnv             (baseline, no cap)
    - Flag_UnderCap              (--max-rows 100 over 21 rows → success)
    - Flag_OverCap               (--max-rows 5 → exit 2, source attribution, empty stdout)
    - Env_OverCap                (BEADS_MAX_ROWS=5 → exit 2, env source)
    - Flag_OverridesEnv          (env=5 flag=100 → success)
    - Flag_Zero_OverridesEnv     (env=5 --max-rows 0 → success, explicit disable)
    - BadEnv_LogsAndIgnores      (env=banana → warning + normal output, exit 0)
    - Negative_FlagRejected      (--max-rows -1 → "must be non-negative", exit 1)
    - LimitSet_CapTighter        (--limit 100 --max-rows 5 → exit 2)
    - LimitSet_CapLooser         (--limit 5 --max-rows 100 → 5 rows, exit 0)

internal/storage/embeddeddolt/search_max_rows_test.go (new):
  TestSearchIssues_MaxRows_{NotExceeded,Exceeded,Zero_NoCap,WithLimit}
  Exercises SearchIssues end-to-end against the embedded backend on a
  6-row fixture, including the four-quadrant (Limit, MaxRows) matrix.

internal/storage/dolt/search_max_rows_test.go (new):
  Identical scenarios against the dolt-server backend. Per-backend
  parity is implicit: both SearchIssues entry points wrap
  issueops.SearchIssuesInTx, so cap behavior is shared by construction.
  Same fixture + same assertions ensures divergence cannot ship silently.

PG backend coverage is deferred until the postgres-backend branch lands
(per PR #3908 description and parent designer notes).

Refs: be-x42v.3 (this bead), be-x42v.2 (builder), be-u8z9 (sibling validator for non-list paths).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(cli): be-x42v.4 opt-out gate tests for data-integrity commands

Add filterCapturingStore spy and four MaxRows=0 gate tests asserting
that bd export, bd export --auto, bd jira sync, and bd migrate-issues
always construct IssueFilter with MaxRows=0 / MaxRowsSource="" per
designer §4.1 opt-out rule. A BEADS_MAX_ROWS env var on these paths
would corrupt backups, sync state, or migration runs mid-flight.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(cli): be-x42v.4 add TestExport_BypassesBeadsMaxRows behavioral gate

End-to-end belt-and-suspenders test (designer §6.4): sets BEADS_MAX_ROWS=1,
seeds 5 task issues, runs runExport, and asserts 5 JSONL lines in the output.
Completes the be-x42v.4 acceptance criteria for the bypass behavioral test
alongside the filter-spy gate already committed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(cli): be-pc8c server-mode BEADS_MAX_ROWS gate for bd doctor --check={conventions,pollution}

TestDoctorConventionsMaxRows_EnvOnly_Exits2 and TestDoctorPollutionMaxRows_EnvOnly_Exits2
cover the two subtests that were skipped in max_rows_test.go because bd doctor refuses
to run in embedded mode (doctor.go:188). Both tests seed 6 open issues against the
Dolt test server with BEADS_MAX_ROWS=3, assert exit 2, and confirm BEADS_MAX_ROWS=3
in the combined output.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(search): enforce MaxRows cap when wisps table is empty

SearchIssuesInTx skipped EnforceMaxRowsCap on the common empty-wisps
path: when filter.Ephemeral is nil/false and the wisps table is empty,
the early `return results, nil` returned before the post-merge cap check.
The issues-only result set (LIMIT cap+1) could exceed MaxRows yet never
trip ErrTooManyRows. Enforce the cap before the early return.

Fixes TestSearchIssues_MaxRows_Exceeded_ReturnsErrTooManyRows and
TestSearchIssues_MaxRows_WithLimit (internal/storage/embeddeddolt).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(rebase): re-home BEADS_MAX_ROWS enforcement onto post-rebase seams

Fixes gaps exposed by rebasing PR #4160 onto current upstream/main,
found by actually running the PR's own gate tests rather than just
resolving textual conflicts:

- internal/storage/issueops/search.go: the Q2 perf-escape-hatch
  SkipWisps early return (added by main's search perf work, landed
  after this PR's original design) skipped EnforceMaxRowsCap entirely.
  bd list sets SkipWisps=true by default, so `bd list --max-rows N`
  silently ignored the cap. Enforce the cap on that return path too,
  mirroring the existing empty-wisps-table fix alongside it.

- internal/storage/issueops/search_counts.go: SearchIssuesWithCountsInTx
  (the `--json` query path, already present at the PR's merge-base but
  never wired for MaxRows by the original be-x42v.1/.2 commits) neither
  sized its SQL LIMIT off the cap nor enforced it on the merged result.
  Thread filter.MaxRows through EffectiveSearchLimit for the query LIMIT
  and check EnforceMaxRowsCap in the shared finishSearchIssuesWithCounts
  terminal helper (now returns an error), which every exit path already
  routed through. Fixes be-x42v.3's TestEmbeddedMaxRowsList/Flag_OverCap
  (`bd list --json --max-rows 5`), which failed after the rebase.

- cmd/bd/jira_max_rows_gate_test.go,
  cmd/bd/migrate_issues_max_rows_gate_test.go: seed INSERTs predate
  migration 0049 (LONGTEXT NOT NULL on issues.description/design/
  acceptance_criteria/notes, no default) that landed on main after
  this branch's merge-base. Provide empty-string values for the
  now-required columns.

Not fixed (separate, pre-existing gap; no gate test in this PR
exercises it): GetReadyWorkWithCountsInTx (`bd ready --json` /
`bd list --ready --json`) also doesn't thread MaxRows. Left alone to
keep this rebase to conflict resolution rather than expanding scope;
worth a follow-up bead.

Agent-Signature: claude-sonnet-medium on behalf of maphew

* fix(review): address adjudicated cross-vendor review follow-up (be-x42v.4)

Works the MUST-FIX / SHOULD-FIX list from the adjudicated claude-opus +
codex-gpt-5.6-sol review on the rebase (25e35cc3e), landing coverage gaps
the vendors found in the feature's own promise rather than the rebase
mechanics.

MUST-FIX:

1. internal/storage/issueops/claim.go: ClaimReadyIssueInTx forwarded the
   caller's MaxRows/MaxRowsSource into its internal unbounded
   GetReadyWorkInTx scan, so a rig-wide cap (e.g. BEADS_MAX_ROWS=100 with
   150 ready issues) hard-failed a claim that only ever consumes one row.
   Bound the internal scan via Limit instead, then clear the cap fields.

2. cmd/bd/ready.go, internal/storage/issueops/ready_work_counts.go:
   GetReadyWorkWithCountsInTx (ready --json / list --ready --json) never
   enforced MaxRows at all — a pre-existing gap in the original PR (the
   function predates this branch's merge-base), not something the rebase
   introduced. Threaded EffectiveSearchLimit into its query LIMIT and added
   EnforceMaxRowsCap via a new finishReadyWorkWithCounts terminal helper,
   mirroring finishSearchIssuesWithCounts. Wired handleMaxRowsError on the
   bd ready --json error branch.

3. cmd/bd/max_rows.go + list/ready/graph/dep/find-duplicates: proxied-server
   mode silently ignored the cap (the proxied repository doesn't thread
   MaxRows through the UOW pipeline). Added rejectMaxRowsUnderProxiedServer,
   called on every command that registers --max-rows before it diverts to
   its *ProxiedServer path — an explicit --max-rows or BEADS_MAX_ROWS now
   errors out under --proxied-server instead of no-oping.

4. cmd/bd/list.go: `--limit N --max-rows N` errored instead of truncating.
   withFetchOneExtra unconditionally bumped Limit to N+1 for its own
   >N-matches truncation-hint probe, which then crossed EffectiveSearchLimit's
   `limit > maxRows` branch and tripped the cap on the probe row alone, even
   though the delivered set is always trimmed back to N. withFetchOneExtra
   now skips the bump when MaxRows is active and no looser than Limit;
   >N-matches semantics for limit<maxRows are unaffected.

5. cmd/bd/list.go: `bd list --watch` swallowed the initial-query cap error
   (logged to stderr, returned void, exited 0). watchIssues now returns the
   initial-query error instead of handling it itself; runListCore routes it
   through handleMaxRowsError for exit-code-2 semantics. Mid-poll refresh
   failures still just log and continue (interactive command, not a reason
   to kill the watch loop).

6. cmd/bd/max_rows.go + every call site: handleMaxRowsError and the
   --max-rows usage-error path in resolveMaxRows called os.Exit directly
   from deep inside RunE, bypassing both the command's own metrics defer
   and main()'s post-ExecuteC metrics.CloseAndFlush(). Converted both to
   return errors: resolveMaxRows now returns (int, string, error) and
   handleMaxRowsError returns error, both following the exact &exitError{Code:
   N}-via-RunE precedent already used elsewhere in this package (e.g.
   list_input.go's skip-labels-conflict check, HandleErrorRespectJSON).
   doctor_conventions.go's runConventionsLint (called from a "()
   []doctorCheck" advisory-checks aggregator with no error channel) needed
   its own (([]doctorCheck, error) signature to propagate the one non-advisory
   failure mode; every other call site was already RunE-adjacent.

SHOULD-FIX (both mechanical, done):

7. cmd/bd/graph.go: `bd graph <issue>` (no --all) never resolved the cap.
   loadGraphSubgraph is a BFS over per-ID GetDependents/GetDependencies
   lookups with no IssueFilter to thread MaxRows through, so — mirroring
   dep tree — the cap is now checked post-hoc against the final
   connected-component node count. Documented both graph's per-status
   (--all) and post-hoc (single-issue) cap semantics, and dep tree's
   post-hoc semantics, in their flag help text.

8. internal/storage/issueops/ready_work.go: getReadyWispsInTx's unbounded
   (Limit<=0) branch queried and hydrated the *entire* wisps table before
   the post-merge cap check in GetReadyWorkInTx ever ran, defeating the
   "circuit breaker against pathological queries" purpose for
   --include-ephemeral. readyWorkWispIssueFilter now propagates
   MaxRows/MaxRowsSource so EffectiveSearchLimit bounds that query to
   cap+1 up front.

Tests added: TestClaimReadyIssue_MaxRows_LargePoolUnderLowCap (1),
ReadyMaxRowsJSON_FlagOverCap_Exits2 + ListReadyMaxRowsJSON_FlagOverCap_Exits2
(2), reject_max_rows_flag + reject_max_rows_env + allow_max_rows_zero under
TestProxiedServerList (3), LimitEqualsCap_TruncatesNotErrors +
LimitEqualsCap_JSON_TruncatesNotErrors (4), Watch_FlagOverCap_Exits2 (5),
GraphSingleIssueMaxRows_NodeCount_Exits2 + _UnderCap_NoError (7),
ReadyIncludeEphemeralMaxRows_FlagOverCap_Exits2 (8).

Verified: go build/vet clean; full MaxRows-named + FilterHasZeroMaxRows +
BypassesBeadsMaxRows sweep passes in both dolt-server and
BEADS_TEST_EMBEDDED_DOLT=1 modes (one dolt-testcontainer flake observed and
confirmed non-reproducing on retry, consistent with prior sessions);
TestProxiedServerList passes with BEADS_TEST_PROXIED_SERVER=1.

Agent-Signature: claude-sonnet-medium on behalf of maphew

* fix(review): address round-2 delta review regressions (be-x42v.4 round 3)

opus verified all eight round-2 items as implemented, but codex found three
regressions those fixes introduced, confirmed on adjudication. Common
thread: enforce the cap on the DELIVERED result, not on fetched/merged
intermediates, and don't let the safety rejection block one-row operations.

1. cmd/bd/ready.go: proxied `bd ready --claim` was rejected by
   rejectMaxRowsUnderProxiedServer before it could dispatch to
   runReadyProxiedClaim, even though --claim always delivers exactly one
   row and the direct-path fix (claim.go, round 2) already exempts claim
   from cap enforcement for that exact reason. Moved the claimReady flag
   parse before the proxied branch and exempt --claim from the rejection;
   bulk (non-claim) proxied `bd ready` still rejects an active cap. Added
   claim_succeeds_under_env_max_rows_cap plus
   reject_bulk_ready_under_max_rows_{flag,env} to
   ready_proxied_integration_test.go.

2. internal/storage/issueops/ready_work_counts.go: with --include-ephemeral,
   GetReadyWorkWithCountsInTx's issues and wisps queries are each
   independently bounded by EffectiveSearchLimit(filter.Limit,
   filter.MaxRows), so the merged pre-trim slice can hold up to ~2x that
   per-table bound even when filter.Limit <= filter.MaxRows (e.g. limit=2,
   cap=3, 2 rows/table -> merged 4 -> false "too many rows" even though the
   delivered page, trimmed to 2, is well within the cap). Reordered
   finishReadyWorkWithCounts to trim to Limit before checking the cap,
   mirroring GetReadyWorkInTx's non-counts path (mergeReadyWisps already
   trims before its caller's EnforceMaxRowsCap runs). Verified this
   reproduces "4 found, --max-rows=3 exceeded" on the pre-fix code and is
   fixed after. Added ReadyIncludeEphemeralMaxRowsJSON_MergedUnderLimit_NoError.

3. cmd/bd/list.go: round-2's fix for `--limit N --max-rows N` (skip the
   withFetchOneExtra probe-row bump entirely when Limit>=MaxRows) stopped
   the false cap error but also stopped fetching the extra row, so
   len(results) could never exceed effectiveLimit and the GH#3212
   truncation notice silently stopped firing — a partial result started
   presenting as complete. Restored the probe-row fetch (Limit still bumps
   to N+1) and instead bump MaxRows to N+1 in lockstep, but only in the
   exact Limit==MaxRows case: this keeps the probe row inside the
   (temporarily N+1) cap so EnforceMaxRowsCap doesn't trip on it, while the
   CLI's own len(results)>effectiveLimit check still sees the extra row and
   correctly reports truncated=true. Tighter-cap (Limit>MaxRows) and
   looser-cap (Limit<MaxRows) cases are unaffected — MaxRows is left
   unbumped there, so a genuine violation still reports the true cap value.
   printTruncationHint's text is gated on ui.IsStderrTerminal() and
   unconditionally suppressed for this subprocess test harness's piped
   stderr (matches the existing limit_truncation_hint subtest's documented
   constraint), so the fix is verified via 4 new unit tests asserting
   withFetchOneExtra's exact bump values directly
   (TestWithFetchOneExtra_LimitEqualsCap_BumpsBothForTruncationProbe et al.)
   rather than the unobservable hint text; extended
   LimitEqualsCap_TruncatesNotErrors's comment to document this and point
   to the unit tests.

Opus nits:

4. internal/storage/issueops/claim.go: bounding the claim scan at
   Limit=MaxRows (round 2) meant a BEADS_MAX_ROWS=1 rig would only attempt
   the single top-of-queue ready row and return "nothing to claim" if it
   was transiently unclaimable (e.g. a race with another agent), even with
   plenty of other ready work available. Restored the unbounded scan
   (Limit=0); the breaker's job is to bound delivered payloads, and a
   claim's payload is always exactly one row regardless of scan size.

5. cmd/bd/find_duplicates.go: replaced the inlined proxied-server rejection
   check with a call to rejectMaxRowsUnderProxiedServer so the message
   can't drift from the other 4 commands that use it.

Verified: go build/vet clean; full MaxRows-named + FilterHasZeroMaxRows +
BypassesBeadsMaxRows + WithFetchOneExtra sweep passes in both dolt-server
and BEADS_TEST_EMBEDDED_DOLT=1 modes; TestProxiedServerList +
TestProxiedServerReady (full suites, ~200s) pass with
BEADS_TEST_PROXIED_SERVER=1; broader TestList|TestWatch|TestGraph|
TestDepTree|TestReady|TestClaim|TestFindDuplicates sweep clean except the
same pre-existing unrelated ICU-header build failure noted in the round-2
commit (confirmed via stash-based control test to reproduce identically
without this round's changes).

Agent-Signature: claude-sonnet-medium on behalf of maphew

* fix(review): address round-3 delta review items (be-x42v.4 round 4)

Converging: four small items adjudicated from round-3 delta reviews.

1. internal/storage/issueops/search.go, search_counts.go: round 3's
   trim-before-cap fix landed in finishReadyWorkWithCounts but not on the
   sibling bd list search paths. `bd list --include-infra --limit 2
   --max-rows 5` (3 durable + 3 wisps) exited 2 in both output modes even
   though the delivered page is 2 rows, since --include-infra disables the
   default SkipWisps escape hatch so the wisps merge actually runs.
   Reproduced live: "6 found, --max-rows=5 exceeded" on the pre-fix code.
   Mirrored the ready remedy: trim to filter.Limit (guarded by Limit>0)
   before EnforceMaxRowsCap in searchInTx's four exit points (added a
   trimToSearchLimit helper) and in finishSearchIssuesWithCounts (swapped
   the cap/trim order). Fixed search_counts.go's doc comment, which still
   asserted the old cap-before-trim rationale and directly contradicted
   ready_work_counts.go's. Single-source results are unaffected (a lone
   query never exceeds Limit when Limit>0, so the trim there is a no-op);
   Limit=0 and genuine Limit>MaxRows overage still error. Added
   IncludeInfraMergedUnderLimit_NoError (both bd list output modes) to
   TestEmbeddedMaxRowsList.

2. cmd/bd/ready.go: the round-3 fix that exempts proxied `ready --claim`
   from rejectMaxRowsUnderProxiedServer also skipped resolveMaxRows
   entirely for that branch, so `--max-rows -1` was silently accepted
   under proxied claim (every other command, direct or proxied, rejects
   it with exit 1). Still call resolveMaxRows in the claim-exempt branch
   for its validation side effect, ignoring the resolved cap for the
   claim itself. Reproduced live (claim succeeded instead of failing) on
   the pre-fix code. Added claim_rejects_invalid_max_rows_flag to
   ready_proxied_integration_test.go.

3. cmd/bd/find_duplicates.go, cmd/bd/max_rows.go: find-duplicates resolved
   --max-rows twice under proxied mode (once to build its filter, again
   inside rejectMaxRowsUnderProxiedServer), doubling the malformed-env
   stderr warning. Split rejectMaxRowsUnderProxiedServer into itself plus
   a new rejectResolvedMaxRowsUnderProxiedServer(maxRows int) that takes
   an already-resolved value; find_duplicates.go now calls the latter with
   its existing resolved maxRows instead of re-resolving.

4. internal/storage/issueops/claim.go: added a comment sentence noting the
   unbounded-scan trade-off per the adjudication note — parity with
   pre-PR main and correctness-first (preserves claim's existing
   fairness/ordering across the ready set); a bounded, paged scan is a
   deliberate follow-up, not folded in here.

Verified: go build/vet clean; full MaxRows-named + FilterHasZeroMaxRows +
BypassesBeadsMaxRows + WithFetchOneExtra sweep passes in both dolt-server
and BEADS_TEST_EMBEDDED_DOLT=1 modes (including the two new regression
tests); full TestProxiedServerReady suite (~211s) passes with
BEADS_TEST_PROXIED_SERVER=1; internal/storage/issueops unit tests pass;
broader TestList|TestWatch|TestGraph|TestDepTree|TestReady|TestClaim|
TestFindDuplicates sweep clean except the same pre-existing unrelated
ICU-header build failure noted in prior rounds. Both new regression tests
(item 1 and item 2) reproduce the reported failure on the pre-fix code via
git-stash and pass after.

Agent-Signature: claude-sonnet-medium on behalf of maphew

* fix(review): sort merged issues+wisps before trim in searchInTx (be-x42v.4 round 5)

codex P1, confirmed live: searchInTx's merge branch concatenates two
independently ORDER BY'd legs (`results = append(filtered,
wispResults...)`), and round-4's trimToSearchLimit then sliced that
UNSORTED concatenation. With Limit=N and durable rows alone filling N, a
higher-ranked wisp (per filter.SortBy/SortDesc) was silently dropped from
the page — before round 4 the CLI received the full merged set and its own
sort-then-trim produced correct page membership; round 4 moved a naive
prefix-trim into storage ahead of any global re-sort.

Fix: added a `less func(a, b T, sortBy string, sortDesc bool) bool` field
to searchProjection[T], populated for issueProjection via sqlbuild.Less
(the existing Go-side mirror of the SQL ORDER BY, already used correctly
by search_counts.go's sortSearchIssuesWithCounts). searchInTx's merge
branch now re-sorts the concatenation via a new sortMergedResults helper
before trimToSearchLimit runs, mirroring how finishSearchIssuesWithCounts
already orders before its own trim. idProjection (bare-ID search, no
sortable payload) leaves less nil — sortMergedResults no-ops in that case;
documented why this is safe today (no current caller combines Limit>0 with
a merged, non-SkipWisps ID-only search — see id_parser.go, which always
passes Limit=0) and where to look if that changes. The other three
trimToSearchLimit call sites in searchInTx are single-source (already
SQL-ordered), so they don't need this.

Checked the two round-3/round-4-cited "mirror" precedents per the
adjudication note, since this bug's shape (unsorted-concat-then-trim) could
plausibly recur there: GetReadyWorkInTx's mergeReadyWisps already calls
sortReadyIssues(kept, filter.SortPolicy) before its own Limit trim, and
GetReadyWorkWithCountsInTx / SearchIssuesWithCountsInTx both already sort
(sortIssuesWithCountsByPolicy / sortSearchIssuesWithCounts) before their
finish* trim-then-cap helpers. All three were already globally ordered
before trimming; only searchInTx had the bug.

Added IncludeInfraMerged_WispOutranksDurable_InDeliveredPage to
TestEmbeddedMaxRowsList: 3 durable P2 issues + 1 wisp at P0 (outranks under
the default priority-ASC sort), --limit 1 in both bd list output modes —
asserts the P0 wisp is the delivered row, not an arbitrary P2 durable row.
Reproduces exactly against 77227aa67 (the durable row is returned instead
of the wisp) and passes after the fix.

Verified: go build/vet clean; full MaxRows-named + FilterHasZeroMaxRows +
BypassesBeadsMaxRows + WithFetchOneExtra + Search sweep passes in both
dolt-server and BEADS_TEST_EMBEDDED_DOLT=1 modes (including the new
regression test); internal/storage/issueops unit tests pass.

Agent-Signature: claude-sonnet-medium on behalf of matt wilkie

* docs: remove --max-rows lines from pinned-generator CLI docs (be-x42v.4 CI fix)

CI's "Check doc flags freshness" job compares docs/CLI_REFERENCE.md and
docs/cli-reference/*.md against bd built from the pin in
docs/cli-docs.pin (v1.1.0), which predates --max-rows/BEADS_MAX_ROWS —
the same pinned-doc-generator trap that hit PRs 3920 and 4022 in this
sweep. Any doc lines this PR added for the new flag are flagged stale
against that older pinned build, and the failure cascades into "PR
Policy (wrapper timing)" via make ci-pr-policy.

Applied CI's own generated fix verbatim (downloaded the
cli-docs-freshness-patch artifact from the failing job
https://github.com/gastownhall/beads/actions/runs/30067827283/job/89403539322,
git apply --check passed cleanly, applied as-is — no manual edits).
Removes the six --max-rows generated-doc lines (bd list, bd ready, bd dep
tree, bd find-duplicates, bd graph — CLI_REFERENCE.md and the matching
cli-reference/*.md) plus the incidental column-width realignment in the
bd graph flag tables that removing the widest flag name triggers.

The flag help strings themselves (cmd/bd/max_rows.go's addMaxRowsFlag)
are untouched — those are the source of truth for docs generation and
will regenerate correctly once docs/cli-docs.pin advances past this
PR's merge. This is a pinned-generator artifact of the CI pipeline, not
a statement that the flag is undocumented.

Agent-Signature: claude-sonnet-medium on behalf of maphew

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-24 01:40:36 -07:00

764 lines
32 KiB
Go

//go:build cgo
// be-u8z9: CLI-layer behavioral tests for BEADS_MAX_ROWS / --max-rows on the
// command paths beyond `bd list`. Each subtest:
// - inits a fresh rig (own DB so the row counts are exact)
// - exercises the command via exec.Command(bd, ...)
// - asserts the process exited with code 2 (cap exceeded) and that stderr
// names the source ("--max-rows=N" or "BEADS_MAX_ROWS=N").
//
// The doctor-family commands (lint, doctor-conventions, doctor-pollution)
// are env-only by design (designer §4); they do NOT register --max-rows
// as a flag. A separate subtest asserts cobra rejects the flag.
//
// Gating matches the other embedded-dolt CLI tests: requires
// BEADS_TEST_EMBEDDED_DOLT=1 to opt in.
package main
import (
"fmt"
"os"
"os/exec"
"strings"
"testing"
"github.com/steveyegge/beads/internal/types"
)
// bdRunRaw runs bd with the given args and env extras (appended to bdEnv(dir)).
// Returns combined stdout+stderr and the process exit code. Unlike the other
// helpers in this package it does not call t.Fatal on non-zero exits — that's
// the success case for the max-rows tests.
func bdRunRaw(t *testing.T, bd, dir string, envExtras []string, args ...string) (string, int) {
t.Helper()
cmd := exec.Command(bd, args...)
cmd.Dir = dir
env := bdEnv(dir)
env = append(env, envExtras...)
cmd.Env = env
out, err := cmd.CombinedOutput()
if err == nil {
return string(out), 0
}
if exitErr, ok := err.(*exec.ExitError); ok {
return string(out), exitErr.ExitCode()
}
t.Fatalf("bd %s unexpected non-exit error: %v\n%s", strings.Join(args, " "), err, out)
return string(out), -1
}
// seedReadyIssues creates n top-level (no-dep, no-blocker) issues that all
// appear in `bd ready`. Useful for tests that need exactly n ready rows.
func seedReadyIssues(t *testing.T, bd, dir string, n int) []string {
t.Helper()
ids := make([]string, n)
for i := 0; i < n; i++ {
iss := bdCreate(t, bd, dir, fmt.Sprintf("max-rows seed %d", i), "--type", "task")
ids[i] = iss.ID
}
return ids
}
// TestEmbeddedMaxRowsNonListPaths covers the non-list CLI paths wired up in
// be-x42v.2: ready, dep tree, find-duplicates, graph --all, plus the env-only
// doctor family (lint, doctor --check=conventions, doctor --check=pollution),
// and config show emission of BEADS_MAX_ROWS.
func TestEmbeddedMaxRowsNonListPaths(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests")
}
t.Parallel()
bd := buildEmbeddedBD(t)
// ----------- bd ready -----------
t.Run("ReadyMaxRows_FlagOverCap_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrrdf")
seedReadyIssues(t, bd, dir, 6)
out, code := bdRunRaw(t, bd, dir, nil, "ready", "--max-rows", "3")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("stderr missing 'too many rows':\n%s", out)
}
if !strings.Contains(out, "--max-rows=3") {
t.Errorf("stderr missing source --max-rows=3:\n%s", out)
}
})
t.Run("ReadyMaxRows_EnvOverCap_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrrde")
seedReadyIssues(t, bd, dir, 6)
out, code := bdRunRaw(t, bd, dir, []string{"BEADS_MAX_ROWS=3"}, "ready")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "BEADS_MAX_ROWS=3") {
t.Errorf("stderr missing source BEADS_MAX_ROWS=3:\n%s", out)
}
})
// `bd ready --json` and `bd list --ready --json` route through
// GetReadyWorkWithCountsInTx, a separate query path from the plain
// `bd ready` above (GetReadyWorkInTx). Mirrors
// TestEmbeddedMaxRowsList/Flag_OverCap's --json coverage for `bd list`.
t.Run("ReadyMaxRowsJSON_FlagOverCap_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrrjf")
seedReadyIssues(t, bd, dir, 6)
out, code := bdRunRaw(t, bd, dir, nil, "ready", "--json", "--max-rows", "3")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("stderr missing 'too many rows':\n%s", out)
}
if !strings.Contains(out, "--max-rows=3") {
t.Errorf("stderr missing source --max-rows=3:\n%s", out)
}
if idx := strings.Index(out, "Error: too many rows"); idx >= 0 {
if strings.Contains(out[:idx], "[") {
t.Errorf("stdout JSON output leaked before error message:\nfull=%s", out)
}
}
})
t.Run("ListReadyMaxRowsJSON_FlagOverCap_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrrjl")
seedReadyIssues(t, bd, dir, 6)
out, code := bdRunRaw(t, bd, dir, nil, "list", "--ready", "--json", "--max-rows", "3")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("stderr missing 'too many rows':\n%s", out)
}
if !strings.Contains(out, "--max-rows=3") {
t.Errorf("stderr missing source --max-rows=3:\n%s", out)
}
})
// be-x42v.4 follow-up (review SHOULD-FIX 8): confirms the cap still
// fires end-to-end for --include-ephemeral after propagating MaxRows
// into getReadyWispsInTx's wisp query (internal/storage/issueops/
// ready_work.go) — that change bounds the query itself but must not
// change whether the post-merge cap check in GetReadyWorkInTx trips.
t.Run("ReadyIncludeEphemeralMaxRows_FlagOverCap_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrre")
for i := 0; i < 6; i++ {
bdCreate(t, bd, dir, fmt.Sprintf("Ephemeral ready %d", i), "--type", "task", "--ephemeral")
}
out, code := bdRunRaw(t, bd, dir, nil, "ready", "--include-ephemeral", "--max-rows", "3")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("stderr missing 'too many rows':\n%s", out)
}
if !strings.Contains(out, "--max-rows=3") {
t.Errorf("stderr missing source --max-rows=3:\n%s", out)
}
})
// be-x42v.4 round-3 follow-up: GetReadyWorkWithCountsInTx (the `--json`
// path) independently bounds each of the issues and wisps queries by
// EffectiveSearchLimit(Limit, MaxRows), so with --include-ephemeral the
// PRE-TRIM merge of two tables can hold up to ~2x that per-table bound
// even though the caller's own --limit already keeps the DELIVERED page
// well within the cap. limit=2, cap=3, 2 ready rows in each table: each
// table's query returns 2 (2<=limit, no overage sniff at the per-table
// level — EffectiveSearchLimit(2,3)=2), the pre-trim merge is 4>cap=3,
// but the page actually handed back to the caller is trimmed to 2<=cap.
// Must exit 0, not trip the cap on the untrimmed merge.
t.Run("ReadyIncludeEphemeralMaxRowsJSON_MergedUnderLimit_NoError", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrrm")
for i := 0; i < 2; i++ {
bdCreate(t, bd, dir, fmt.Sprintf("Plain ready %d", i), "--type", "task")
}
for i := 0; i < 2; i++ {
bdCreate(t, bd, dir, fmt.Sprintf("Ephemeral ready %d", i), "--type", "task", "--ephemeral")
}
out, code := bdRunRaw(t, bd, dir, nil, "ready", "--json", "--include-ephemeral",
"--limit", "2", "--max-rows", "3")
if code != 0 {
t.Fatalf("expected exit 0 (delivered page under cap despite pre-trim merge overage), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("delivered-page-under-cap should not emit cap error:\n%s", out)
}
})
// ----------- bd dep tree -----------
t.Run("DepTreeMaxRows_TreeNodes_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrdt")
// All tasks: default "blocks" dep type rejects epic→task, but task→task
// is fine and produces a tree with the same shape for cap purposes.
root := bdCreate(t, bd, dir, "Tree root", "--type", "task")
// Add 5 children so the dep tree has 6 nodes total (root + 5).
for i := 0; i < 5; i++ {
child := bdCreate(t, bd, dir, fmt.Sprintf("Tree dep %d", i), "--type", "task")
// `bd dep add A B` makes A depend on B (default dep type is "blocks").
bdDepAdd(t, bd, dir, root.ID, child.ID)
}
// Sanity: tree of size 6, cap of 2 → must exit 2 with source attribution.
out, code := bdRunRaw(t, bd, dir, nil, "dep", "tree", root.ID, "--max-rows", "2")
if code != 2 {
t.Fatalf("expected exit 2 (tree size > cap), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("stderr missing 'too many rows':\n%s", out)
}
if !strings.Contains(out, "--max-rows=2") {
t.Errorf("stderr missing source --max-rows=2:\n%s", out)
}
})
// ----------- bd find-duplicates -----------
t.Run("FindDuplicatesMaxRows_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrfd")
seedReadyIssues(t, bd, dir, 6)
out, code := bdRunRaw(t, bd, dir, nil, "find-duplicates", "--max-rows", "3")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "--max-rows=3") {
t.Errorf("stderr missing source --max-rows=3:\n%s", out)
}
})
// ----------- bd graph --all -----------
t.Run("GraphAllMaxRows_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrgr")
seedReadyIssues(t, bd, dir, 6)
out, code := bdRunRaw(t, bd, dir, nil, "graph", "--all", "--max-rows", "3")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "--max-rows=3") {
t.Errorf("stderr missing source --max-rows=3:\n%s", out)
}
})
// be-x42v.4 follow-up (review SHOULD-FIX 7): `bd graph <issue>` without
// --all never resolved the cap at all before the fix — loadGraphSubgraph
// is a BFS over per-ID GetDependents/GetDependencies lookups with no
// IssueFilter to thread MaxRows through, so this checks the final
// connected-component node count post-hoc, mirroring dep tree.
t.Run("GraphSingleIssueMaxRows_NodeCount_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrgs")
root := bdCreate(t, bd, dir, "Graph root", "--type", "task")
for i := 0; i < 5; i++ {
child := bdCreate(t, bd, dir, fmt.Sprintf("Graph dep %d", i), "--type", "task")
bdDepAdd(t, bd, dir, root.ID, child.ID)
}
// Connected component of size 6 (root + 5), cap of 2 → exit 2.
out, code := bdRunRaw(t, bd, dir, nil, "graph", root.ID, "--max-rows", "2")
if code != 2 {
t.Fatalf("expected exit 2 (subgraph size > cap), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("stderr missing 'too many rows':\n%s", out)
}
if !strings.Contains(out, "--max-rows=2") {
t.Errorf("stderr missing source --max-rows=2:\n%s", out)
}
})
t.Run("GraphSingleIssueMaxRows_UnderCap_NoError", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrgu")
root := bdCreate(t, bd, dir, "Graph root under cap", "--type", "task")
out, code := bdRunRaw(t, bd, dir, nil, "graph", root.ID, "--max-rows", "5")
if code != 0 {
t.Fatalf("expected exit 0 (single-node subgraph under cap), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("under-cap single-issue graph should not emit cap error:\n%s", out)
}
})
// ----------- bd lint (env-only) -----------
t.Run("LintMaxRows_EnvOnly_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrln")
seedReadyIssues(t, bd, dir, 6)
out, code := bdRunRaw(t, bd, dir, []string{"BEADS_MAX_ROWS=3"}, "lint")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded via env), got %d\n%s", code, out)
}
if !strings.Contains(out, "BEADS_MAX_ROWS=3") {
t.Errorf("stderr missing source BEADS_MAX_ROWS=3:\n%s", out)
}
})
t.Run("LintMaxRows_NoFlagAccepted", func(t *testing.T) {
// Designer §4: doctor family is env-opt-in only. The --max-rows
// flag must NOT be registered on `bd lint`; cobra should reject
// it as unknown.
dir, _, _ := bdInit(t, bd, "--prefix", "mrlnf")
out, code := bdRunRaw(t, bd, dir, nil, "lint", "--max-rows", "1")
if code == 0 {
t.Fatalf("expected non-zero exit (cobra rejects unknown flag), got 0\n%s", out)
}
if !strings.Contains(out, "unknown flag") {
t.Errorf("stderr missing 'unknown flag' rejection:\n%s", out)
}
// Defense against false positives: if `--max-rows` is wired on lint
// by mistake, this assertion would not trip — but the unknown-flag
// check above already covers it.
})
// ----------- bd doctor --check=conventions (env-only) -----------
//
// bd doctor is hard-gated to server mode (doctor.go:188 prints "not yet
// supported in embedded mode" and exits 0 before reaching the check
// dispatch). The embedded-Dolt test rig used here cannot exercise those
// code paths. The cap logic itself runs through the shared SearchIssues +
// EnforceMaxRowsCap path already covered by:
// - TestEnforceMaxRowsCap_* (internal/storage/issueops/search_test.go)
// - TestGetReadyWork_MaxRowsSuite (cmd/bd/ready_max_rows_test.go)
// - be-x42v.3 storage parity tests (bd list/search backend matrix)
// What's _not_ covered without server mode is the env-only resolver
// (resolveMaxRowsEnvOnly) on these specific commands. doctor_conventions.go
// and doctor_pollution.go both call it and pipe through handleMaxRowsError
// identically to lint.go, which IS covered above by LintMaxRows_EnvOnly_Exits2.
// A server-mode follow-up should add behavioral coverage here.
t.Run("ConventionsMaxRows_EnvOnly_Exits2", func(t *testing.T) {
t.Skip("bd doctor requires server mode (doctor.go:188); server-mode parity covered by separate validator bead")
})
t.Run("PollutionMaxRows_EnvOnly_Exits2", func(t *testing.T) {
t.Skip("bd doctor requires server mode (doctor.go:188); server-mode parity covered by separate validator bead")
})
// ----------- bd config show -----------
t.Run("ConfigShow_ListsBeadsMaxRows", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrcs")
// When BEADS_MAX_ROWS is set in the environment, `bd config show`
// must surface it in the standalone-env entries (config_show.go
// collectStandaloneEnvEntries).
out, code := bdRunRaw(t, bd, dir, []string{"BEADS_MAX_ROWS=42"}, "config", "show")
if code != 0 {
t.Fatalf("expected exit 0 from `bd config show`, got %d\n%s", code, out)
}
if !strings.Contains(out, "BEADS_MAX_ROWS") {
t.Errorf("expected `bd config show` to list BEADS_MAX_ROWS in output:\n%s", out)
}
if !strings.Contains(out, "42") {
t.Errorf("expected `bd config show` to display the value 42:\n%s", out)
}
// When the env var is unset, the entry must be absent (designer §4:
// opt-in only; default-disabled).
out2, code2 := bdRunRaw(t, bd, dir, nil, "config", "show")
if code2 != 0 {
t.Fatalf("expected exit 0 from `bd config show` (unset), got %d\n%s", code2, out2)
}
if strings.Contains(out2, "BEADS_MAX_ROWS") {
t.Errorf("expected BEADS_MAX_ROWS to be absent when env is unset:\n%s", out2)
}
})
}
// countListIDs returns the number of issue IDs of the form "<prefix>-<n>"
// observed in the combined `bd list` output. Used to verify that --limit
// actually clipped the result set without depending on JSON parsing of the
// pretty-printed array (which spans many lines).
func countListIDs(out, prefix string) int {
// Each list row prints the issue ID once; counting prefix occurrences in
// raw stdout is a robust enough check for our small fixtures.
return strings.Count(out, prefix+"-")
}
// TestEmbeddedMaxRowsList covers the 10 designer §6.1 behavioral scenarios
// for `bd list`. Builder bead: be-x42v.2 (CLI wiring). All subtests share a
// single rig of 21 open task issues — the dataset size from the designer's
// fixture.
func TestEmbeddedMaxRowsList(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests")
}
t.Parallel()
bd := buildEmbeddedBD(t)
dir, _, _ := bdInit(t, bd, "--prefix", "mrl")
const totalRows = 21
for i := 0; i < totalRows; i++ {
bdCreate(t, bd, dir, fmt.Sprintf("List max-rows %d", i), "--type", "task")
}
t.Run("Disabled_NoEnv", func(t *testing.T) {
// Baseline: with no flag and no env var, `bd list` returns all rows.
out, code := bdRunRaw(t, bd, dir, nil, "list")
if code != 0 {
t.Fatalf("expected exit 0 (no cap), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("baseline `bd list` should not emit cap error:\n%s", out)
}
if got := countListIDs(out, "mrl"); got < totalRows {
t.Errorf("expected at least %d rows in output, got %d", totalRows, got)
}
})
t.Run("Flag_UnderCap", func(t *testing.T) {
// 21 rows under cap=100: success.
out, code := bdRunRaw(t, bd, dir, nil, "list", "--max-rows", "100")
if code != 0 {
t.Fatalf("expected exit 0 (under cap), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("under-cap `bd list` should not emit cap error:\n%s", out)
}
})
t.Run("Flag_OverCap", func(t *testing.T) {
// 21 rows over cap=5: exit 2, stderr includes --max-rows=5, stdout
// empty (designer §2.3: stdout is suppressed so `jq` downstream
// doesn't trip on partial JSON).
out, code := bdRunRaw(t, bd, dir, nil, "list", "--json", "--max-rows", "5")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("expected 'too many rows' in stderr:\n%s", out)
}
if !strings.Contains(out, "--max-rows=5") {
t.Errorf("expected source `--max-rows=5` in stderr:\n%s", out)
}
// stdout-emptiness check: there should be no JSON `[` array opener
// in the merged output before the error. Cap-exceeded must not emit
// a partial array.
if idx := strings.Index(out, "Error: too many rows"); idx >= 0 {
before := out[:idx]
if strings.Contains(before, "[") {
t.Errorf("stdout JSON output leaked before error message:\nbefore=%q\nfull=%s", before, out)
}
}
})
t.Run("Env_OverCap", func(t *testing.T) {
out, code := bdRunRaw(t, bd, dir, []string{"BEADS_MAX_ROWS=5"}, "list")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded via env), got %d\n%s", code, out)
}
if !strings.Contains(out, "BEADS_MAX_ROWS=5") {
t.Errorf("expected source `BEADS_MAX_ROWS=5` in stderr:\n%s", out)
}
})
t.Run("Flag_OverridesEnv", func(t *testing.T) {
// env says cap=5, flag says cap=100 — flag wins, expect success.
out, code := bdRunRaw(t, bd, dir, []string{"BEADS_MAX_ROWS=5"},
"list", "--max-rows", "100")
if code != 0 {
t.Fatalf("expected exit 0 (flag overrides env), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("flag-override should not emit cap error:\n%s", out)
}
})
t.Run("Flag_Zero_OverridesEnv", func(t *testing.T) {
// Explicit `--max-rows 0` disables the cap even when env is set
// (designer §2.1: ops shells with a global env can run a known-
// unbounded query without unsetting).
out, code := bdRunRaw(t, bd, dir, []string{"BEADS_MAX_ROWS=5"},
"list", "--max-rows", "0")
if code != 0 {
t.Fatalf("expected exit 0 (--max-rows 0 disables), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("explicit `--max-rows 0` should disable the cap:\n%s", out)
}
})
t.Run("BadEnv_LogsAndIgnores", func(t *testing.T) {
// env=banana → warning to stderr, normal output, exit 0
// (designer §2.1: fail-open on bad env so a typo in a global shell
// doesn't break automation).
out, code := bdRunRaw(t, bd, dir, []string{"BEADS_MAX_ROWS=banana"}, "list")
if code != 0 {
t.Fatalf("expected exit 0 (bad env ignored), got %d\n%s", code, out)
}
// max_rows.go:79 emits a "Warning: BEADS_MAX_ROWS=\"banana\" is not
// a non-negative integer; ignoring." line.
if !strings.Contains(out, "Warning") || !strings.Contains(out, "BEADS_MAX_ROWS") {
t.Errorf("expected warning about bad env in stderr:\n%s", out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("bad env should not trigger cap error:\n%s", out)
}
})
t.Run("Negative_FlagRejected", func(t *testing.T) {
// max_rows.go:55 calls FatalError on negative — exit 1 with message.
out, code := bdRunRaw(t, bd, dir, nil, "list", "--max-rows", "-1")
if code != 1 {
t.Fatalf("expected exit 1 (usage error), got %d\n%s", code, out)
}
if !strings.Contains(out, "must be non-negative") {
t.Errorf("expected 'must be non-negative' in stderr:\n%s", out)
}
})
t.Run("LimitSet_CapTighter", func(t *testing.T) {
// limit=100, cap=5: 21 rows are scanned (LIMIT cap+1=6 sniffs
// overage), cap fires, exit 2. The --limit flag does not protect
// callers who set a generous limit but also opt into the cap.
out, code := bdRunRaw(t, bd, dir, nil, "list",
"--limit", "100", "--max-rows", "5")
if code != 2 {
t.Fatalf("expected exit 2 (cap tighter than limit), got %d\n%s", code, out)
}
if !strings.Contains(out, "--max-rows=5") {
t.Errorf("expected source `--max-rows=5` in stderr:\n%s", out)
}
})
t.Run("LimitSet_CapLooser", func(t *testing.T) {
// limit=5, cap=100: EffectiveSearchLimit returns 5 (limit wins when
// under cap), no overage detection, 5 rows returned, exit 0.
out, code := bdRunRaw(t, bd, dir, nil, "list",
"--limit", "5", "--max-rows", "100")
if code != 0 {
t.Fatalf("expected exit 0 (limit under cap), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("limit-under-cap should not emit cap error:\n%s", out)
}
if got := countListIDs(out, "mrl"); got != 5 {
t.Errorf("expected exactly 5 issue IDs in output, got %d:\n%s", got, out)
}
})
// be-x42v.4 follow-up (review MUST-FIX 4, revised round-3): --limit N
// --max-rows N with more than N matches must truncate to N and exit 0
// (the standard >N-matches truncation semantics), not error.
//
// Round-2 fix (regressed, since replaced): unconditionally skipped the
// withFetchOneExtra probe-row bump when Limit>=MaxRows. That avoided
// the false cap error but also stopped fetching the extra row entirely,
// so len(results) could never exceed effectiveLimit and the GH#3212
// truncation notice silently stopped firing for this case — a partial
// result started presenting as complete.
//
// Round-3 fix: still fetch the probe row (Limit bumps to N+1 as
// normal), but when Limit==MaxRows exactly, bump MaxRows to N+1 too, in
// lockstep, so EnforceMaxRowsCap's comparison excludes the probe row
// from the cap check while the CLI's own len(results)>effectiveLimit
// truncation detection still sees it. See withFetchOneExtra's doc
// comment in list.go for why this can't false-negative a real
// violation. Covered directly (bump values, not exit behavior) by
// TestWithFetchOneExtra_LimitEqualsCap_BumpsBothForTruncationProbe
// below, since printTruncationHint's text is gated on
// ui.IsStderrTerminal() and unconditionally suppressed for this
// subprocess harness's piped stderr (see list_embedded_test.go's
// limit_truncation_hint subtest) — these end-to-end subtests can only
// assert the absence of the false cap error and the delivered count.
t.Run("LimitEqualsCap_TruncatesNotErrors", func(t *testing.T) {
out, code := bdRunRaw(t, bd, dir, nil, "list",
"--limit", "5", "--max-rows", "5")
if code != 0 {
t.Fatalf("expected exit 0 (limit==cap truncates, does not error), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("limit==cap should not emit cap error:\n%s", out)
}
if got := countListIDs(out, "mrl"); got != 5 {
t.Errorf("expected exactly 5 issue IDs in output, got %d:\n%s", got, out)
}
})
t.Run("LimitEqualsCap_JSON_TruncatesNotErrors", func(t *testing.T) {
out, code := bdRunRaw(t, bd, dir, nil, "list", "--json",
"--limit", "5", "--max-rows", "5")
if code != 0 {
t.Fatalf("expected exit 0 (limit==cap truncates under --json), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("limit==cap under --json should not emit cap error:\n%s", out)
}
})
// be-x42v.4 round-4 follow-up: the round-3 fix to
// finishReadyWorkWithCounts (trim to Limit before EnforceMaxRowsCap)
// wasn't mirrored onto the sibling bd list search paths
// (searchInTx in search.go, finishSearchIssuesWithCounts in
// search_counts.go), which still capped the pre-trim merged
// issues+wisps set. `--include-infra` disables the default SkipWisps
// escape hatch, so the wisps merge actually runs. limit=2, cap=5, 3
// durable + 3 wisp issues: each leg's query is independently bounded
// by EffectiveSearchLimit, so the merge can produce up to 6 rows
// pre-trim (>cap=5) even though the delivered page (trimmed to 2) is
// well within the cap. Covers both bd list output modes (opus's live
// repro found both non-JSON and --json tripping the false cap error).
t.Run("IncludeInfraMergedUnderLimit_NoError", func(t *testing.T) {
mDir, _, _ := bdInit(t, bd, "--prefix", "mrii")
for i := 0; i < 3; i++ {
bdCreate(t, bd, mDir, fmt.Sprintf("Durable infra %d", i), "--type", "task")
}
for i := 0; i < 3; i++ {
bdCreate(t, bd, mDir, fmt.Sprintf("Wisp infra %d", i), "--type", "task", "--ephemeral")
}
out, code := bdRunRaw(t, bd, mDir, nil, "list", "--include-infra",
"--limit", "2", "--max-rows", "5")
if code != 0 {
t.Fatalf("expected exit 0 (delivered page under cap despite pre-trim merge overage), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("delivered-page-under-cap should not emit cap error:\n%s", out)
}
outJSON, codeJSON := bdRunRaw(t, bd, mDir, nil, "list", "--include-infra", "--json",
"--limit", "2", "--max-rows", "5")
if codeJSON != 0 {
t.Fatalf("expected exit 0 under --json (delivered page under cap despite pre-trim merge overage), got %d\n%s", codeJSON, outJSON)
}
if strings.Contains(outJSON, "too many rows") {
t.Errorf("delivered-page-under-cap under --json should not emit cap error:\n%s", outJSON)
}
})
// be-x42v.4 round-5 follow-up: searchInTx's merge branch concatenates
// two independently ORDER BY'd legs (`append(filtered, wispResults...)`)
// and round-4's trimToSearchLimit then sliced that unsorted
// concatenation — with Limit small enough that durable rows alone fill
// it, a higher-ranked wisp was silently dropped from the page even
// though the CLI's pre-round-4 behavior (return the full merged set,
// let the caller sort-then-trim) surfaced it correctly. Default sort is
// priority ASC: 3 durable issues at P2, one wisp at P0 (highest rank)
// — with --limit 1 the P0 wisp must be the sole delivered row, not one
// of the P2 durable rows the unsorted concatenation happened to put
// first. Must fail against 77227aa67.
t.Run("IncludeInfraMerged_WispOutranksDurable_InDeliveredPage", func(t *testing.T) {
mDir, _, _ := bdInit(t, bd, "--prefix", "mrwo")
for i := 0; i < 3; i++ {
bdCreate(t, bd, mDir, fmt.Sprintf("Durable p2 %d", i), "--type", "task", "--priority", "2")
}
wisp := bdCreate(t, bd, mDir, "Wisp p0 outranks", "--type", "task", "--priority", "0", "--ephemeral")
out, code := bdRunRaw(t, bd, mDir, nil, "list", "--include-infra", "--limit", "1")
if code != 0 {
t.Fatalf("expected exit 0, got %d\n%s", code, out)
}
if !strings.Contains(out, wisp.ID) {
t.Errorf("P0 wisp %s must be the sole row in a --limit 1 page (default sort is priority ASC), got:\n%s", wisp.ID, out)
}
outJSON, codeJSON := bdRunRaw(t, bd, mDir, nil, "list", "--include-infra", "--json", "--limit", "1")
if codeJSON != 0 {
t.Fatalf("expected exit 0 under --json, got %d\n%s", codeJSON, outJSON)
}
if !strings.Contains(outJSON, wisp.ID) {
t.Errorf("P0 wisp %s must be the sole row in a --limit 1 --json page, got:\n%s", wisp.ID, outJSON)
}
})
// be-x42v.4 follow-up (review MUST-FIX 5): the initial query under
// `bd list --watch` must surface a cap violation with exit 2, same as
// non-watch `bd list`. Before the fix, watchIssues logged the error to
// stderr itself and returned void, so the process always exited 0 —
// the failure never reached RunE/handleMaxRowsError. This subprocess
// exercises only the initial-query failure path (returns before
// entering the polling loop), so it terminates without needing Ctrl+C.
t.Run("Watch_FlagOverCap_Exits2", func(t *testing.T) {
out, code := bdRunRaw(t, bd, dir, nil, "list", "--watch", "--max-rows", "5")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded under --watch), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("expected 'too many rows' in stderr:\n%s", out)
}
if !strings.Contains(out, "--max-rows=5") {
t.Errorf("expected source `--max-rows=5` in stderr:\n%s", out)
}
})
}
// TestWithFetchOneExtra_LimitEqualsCap_BumpsBothForTruncationProbe verifies
// the exact bump mechanism withFetchOneExtra uses to reconcile the
// >N-matches truncation probe (GH#3212) with a MaxRows cap equal to the
// user's --limit (be-x42v.4 round-3 follow-up).
//
// The end-to-end LimitEqualsCap_TruncatesNotErrors subprocess test in
// TestEmbeddedMaxRowsList can only assert the *absence* of the false cap
// error and the trimmed row count — it can't observe the truncation
// *notice* text, which printTruncationHint gates on ui.IsStderrTerminal()
// and is unconditionally suppressed for a subprocess's piped stderr (see
// list_embedded_test.go's limit_truncation_hint subtest, which documents
// the same TTY constraint). This unit test instead asserts the underlying
// signal directly: with Limit==MaxRows, both must bump by one so the query
// still over-fetches by one row (restoring len(results) > effectiveLimit
// detection) while EnforceMaxRowsCap doesn't trip on that extra row.
func TestWithFetchOneExtra_LimitEqualsCap_BumpsBothForTruncationProbe(t *testing.T) {
got := withFetchOneExtra(types.IssueFilter{Limit: 5, MaxRows: 5, MaxRowsSource: "--max-rows"})
if got.Limit != 6 {
t.Errorf("Limit == MaxRows: Limit = %d, want 6 (bumped so the query still fetches the truncation-detection probe row)", got.Limit)
}
if got.MaxRows != 6 {
t.Errorf("Limit == MaxRows: MaxRows = %d, want 6 (bumped in lockstep so the probe row alone doesn't trip EnforceMaxRowsCap)", got.MaxRows)
}
if got.MaxRowsSource != "--max-rows" {
t.Errorf("MaxRowsSource must be preserved unchanged, got %q", got.MaxRowsSource)
}
}
// TestWithFetchOneExtra_LimitOverCap_OnlyBumpsLimit covers the tighter-cap
// case (--limit 100 --max-rows 5, LimitSet_CapTighter): MaxRows must NOT
// bump, or a genuine cap violation would report the wrong Cap value (N+1
// instead of the user's true --max-rows=N) in the error message.
func TestWithFetchOneExtra_LimitOverCap_OnlyBumpsLimit(t *testing.T) {
got := withFetchOneExtra(types.IssueFilter{Limit: 100, MaxRows: 5})
if got.Limit != 101 {
t.Errorf("Limit = %d, want 101", got.Limit)
}
if got.MaxRows != 5 {
t.Errorf("MaxRows must stay unbumped so a real cap violation reports the true cap; got %d, want 5", got.MaxRows)
}
}
// TestWithFetchOneExtra_LimitUnderCap_OnlyBumpsLimit covers the
// looser-cap case (--limit 5 --max-rows 100, LimitSet_CapLooser): the
// probe-row bump alone never crosses EffectiveSearchLimit's `limit >
// maxRows` branch here, so no MaxRows adjustment is needed.
func TestWithFetchOneExtra_LimitUnderCap_OnlyBumpsLimit(t *testing.T) {
got := withFetchOneExtra(types.IssueFilter{Limit: 5, MaxRows: 100})
if got.Limit != 6 {
t.Errorf("Limit = %d, want 6", got.Limit)
}
if got.MaxRows != 100 {
t.Errorf("MaxRows must stay unbumped, got %d, want 100", got.MaxRows)
}
}
// TestWithFetchOneExtra_NoLimit_Unaffected covers the unlimited case
// (Limit == 0): withFetchOneExtra is a no-op regardless of MaxRows.
func TestWithFetchOneExtra_NoLimit_Unaffected(t *testing.T) {
got := withFetchOneExtra(types.IssueFilter{Limit: 0, MaxRows: 5})
if got.Limit != 0 || got.MaxRows != 5 {
t.Errorf("unlimited Limit must pass through unchanged, got Limit=%d MaxRows=%d", got.Limit, got.MaxRows)
}
}