beads/internal/workapi/storereader/reader.go
mtccressall d14ed67f71
fix(list): expose comment bodies in bd list/show --json (be-73x) (#6473)
* fix(list): expose comment bodies and mark the omission in bd list --json (be-73x)

`bd list --json` reported comment_count and carried no comment text and no sign
that any was missing. The consequence is not a missing field: a content search
over a listing answers with a well-formed, NON-EMPTY result set whose matching
rows are absent, and nothing about that answer invites a second look. An empty
result invites suspicion; eight rows do not.

Two halves, and the second is the one that fixes what was actually reported:

  1. --include-comments on `bd list` populates each row's comments with the
     full bodies, the list twin of `bd show --include-comments`. Opt-in: it
     costs one query per row that has comments.
  2. Every row with a nonzero comment_count whose bodies were NOT hydrated now
     carries comments_omitted=true, by default, with no flag. A flag nobody
     knows to pass does not fix a silent hole; a marker on the row does.

The bodies ride on types.Issue.Comments, which already carried the `comments`
key for export/import and was simply never populated on this path, so the only
new field is the marker.

Hydration is one shared body (workapi.HydrateListComments) called from BOTH
issueops.Reader.List implementations, the store-backed and the unit-of-work
one. Those are separate bodies that have answered one contract method
differently before; it runs in the page epilogue beside FinishPageAt, after the
trim, so a page never pays for rows it is about to drop.

The source parameter is a CONSTRUCTOR rather than a source, and that is
load-bearing. Building the unit-of-work comment source eagerly made a
capability only the opt-in path uses into a requirement every caller had to
satisfy, and turned `GET /v0/beads/issues` into a 500 on a provider without a
comment use case — on requests that had asked for no comments. A count-only
listing now constructs nothing, pinned by a test that fails if the constructor
is called.

Tests pin each implementation separately rather than duplicating: unit tests
over a fake source, an embedded-dolt test over the real CLI on the direct
route, and a proxied-server test over the real CLI on the unit-of-work route.
Sabotage-controlled three ways — no-op the shared body and all three suites go
red; unwire either reader alone and only that reader's CLI test fails, which is
what proves neither integration test is redundant.

Not addressed, deliberately: gt-mfp5 (bd comment does not advance updated_at,
the orthogonal recency axis) and be-ozp (bd ready --json carries no marker; it
does not route through Reader.Ready).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XK4B7N2CrgfKGEQvDTPM4D

Executed-By: beadsrig/polecats/dag

* fix(list): do not read a skipped comment count as proof of no comments (be-73x)

Codex review of the parent commit, correctly.

`IncludeComments: true` combined with `SkipCounts: true` returned a page with
no comment bodies at all — no error, no marker, nothing — while
`IncludeComments` documents a guarantee to populate them. The hydration loop
skipped any row whose CommentCount was zero as an optimisation, and SkipCounts
zeroes every count: `issueops.ListRequest.SkipCounts` says in its own doc that
a zero then means UNKNOWN rather than none.

That is this bead's own failure mode reintroduced one layer down by the fix for
it: a silent, well-formed, empty answer to a request that asked for content.

I had considered the interaction and resolved it wrongly, in a comment reading
"the count is authoritative here because the JSON route never sets SkipCounts".
True of today's CLI callers, and not a property of the contract — issueops
.ListRequest is a PUBLIC request type and permits both fields at once. A
comment saying "X cannot happen because of how callers behave today" on a
public type is a bug with a justification attached, and worse than no comment,
because it tells the next reader the case was checked.

countsKnown is now a parameter rather than an assumption; call sites pass
!req.SkipCounts.

  countsKnown true   a zero count proves a row has nothing; skip its query.
  countsKnown false  query every row, because nothing proves otherwise, and
                     mark no row omitted, because comments_omitted asserts a
                     nonzero count the page cannot support.

The second half is the mirror defect on the marker path — the same conflation,
the other direction — which the review did not name.

No behaviour change on any current CLI path: the JSON route never sets
SkipCounts, so it passes countsKnown true, and the text route asks for no
comments and marked nothing before either. Verified: `bd list --json` output
identical, and text output identical with and without the flag.

Regression tests HonorsIncludeWhenCountsAreSkipped and
MarksNothingWhenCountsAreSkipped. Sabotage-controlled: restoring the
count-authoritative skip fails the first with "issued 0 comment reads, want 2".

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XK4B7N2CrgfKGEQvDTPM4D

Executed-By: beadsrig/polecats/dag

* fix(list): resolve the comment plane by residence, not by the row's flags (be-73x)

Maintainer review fixup for #6473, iteration 1. Both review lanes reached the
same major independently and the synthesizer re-verified it against the tree.

The new list hydration derived the comment table from the row's own
Ephemeral/NoHistory flags - issueops.IsWisp's rule, which is right for routing a
record being WRITTEN and wrong on a read. `bd import` pins a `no_history` record
to the DURABLE table while preserving the flag on the row, because clearing it
would change the content hash and break export->import->export byte-identity,
and every clone materializes its database by importing JSONL. So a promoted
no-history bead that has been through a round-trip is a durable row whose flags
say wisp:

  bd list --json --include-comments   read wisp_comments, found nothing, and
                                      returned comment_count=N beside an empty
                                      `comments`, with no marker and no error
  bd comment, bd show                 write and read that same row's comments on
                                      the issues plane, by found-table

That is be-73x's own failure mode reintroduced under the flag whose contract is
"gets them or gets an error", and a cross-role divergence: `bd list` and
`bd show` disagreed about one row. The mirror case is real too - an import
record whose `wisp_plane` key pins it to the wisps table with neither flag set
reads back as durable - so no flag-based rule gets both directions right.

The plane now comes from the seam that knows it. HydrateListComments takes a
CommentPlanes lookup instead of inferring; the unit-of-work reader answers it
from the wisps TABLE (IssueUseCase.GetWispsByIDs, the call edgeReader.ReadEdges
already makes for the same question), once per page, inside the page's own read
transaction. The store-backed seam passes SourceRoutesCommentPlanes because its
source routes ids itself (DoltStore.GetIssueComments picks the table from
isActiveWisp) and would buy a lookup for an argument it ignores. isWispPlane is
deleted: nothing on this path infers a plane any more. A nil lookup is an error
rather than a silent "durable", so a third seam has to answer the question
rather than inherit the default this bug was.

A MISSING WISPS TABLE STAYS "NO WISPS" rather than a failed listing, classified
through the same two helpers the counts query that produced the page uses
(dberrors.MissingTableName + sqlbuild.OptionalWispTable). Any other failure of
the lookup fails the call: a guessed plane answers with the wrong table's
contents and nothing in the response shows it.

Tests. The unit table now asserts residence AGAINST the flags, with each row's
comments present only on the plane it lives on, so a wrong-table read shows up
as missing TEXT and not merely as a wrong flag in a recorded call. Restoring the
flag inference reds exactly the two rows where flags and table disagree
(durable-carrying-no_history, wisp-table-carrying-no-flags) and leaves the two
agreeing rows green. The old `override_wins_over_flags` case is gone:
WispPlaneOverride is `json:"-"` and set only by import, in memory, so no scanned
row can carry it and that branch was unreachable on this path - which is what
made the suite look sufficient (Codex's separate minor, folded in here as the
same root cause). New seam-level tests drive the real uow Reader.List over both
shapes, and pin that a listing without the flag resolves no planes at all, that
a missing wisps table is tolerated, and that any other lookup failure
propagates; emptying the residence answer reds the wisp-row leg.

Also from the review, non-gating:

- types.IssueWithCounts.CommentsOmitted and the OpenAPI property stated the
  marker rule unconditionally on a type Reader.Ready and the claim response also
  return, neither of which calls the epilogue. Both now scope the rule to the
  List surfaces and cite be-ozp, which is where the parent commit deliberately
  left the ready surfaces. (`bd ready --json` does not route through
  Reader.Ready; GET /v0/beads/ready and ClaimNextResponse.claimed do.)
- GET /v0/beads/issues gained no `include_comments` parameter, so its
  description now says so and points at the detail read, in the idiom the
  `revision` paragraph above it already uses.
- One internal/httpapi list test for the new wire field: the marker present for
  a commented row, absent for an uncommented one. It was asserted only by the
  spec file; the detail twin has get_issue_test.go. Neutering
  markCommentsOmitted reds it.

Validation: go build ./...; go vet over the changed packages and again with
CGO_ENABLED=0; make api-check clean, so the spec edits oblige no regeneration;
go test ./internal/workapi/... ./issueops/... ./internal/types/;
TestBothReaderImplementationsAgreeOnTheListEpilogue plus the new plane tests in
./internal/storage/uow/; BEADS_TEST_PROXIED_SERVER=1
TestProxiedServerListComments 3 PASS and BEADS_TEST_EMBEDDED_DOLT=1
TestEmbeddedListComments 4 PASS.

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

---------

Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-27 02:12:13 -07:00

155 lines
7.3 KiB
Go

// Package storereader holds the store-backed implementation of
// issueops.Reader: one shared body that every store-shaped backend's
// IssueReader accessor hands back.
//
// It is a package of its own rather than a file in internal/workapi for one
// reason. internal/workapi is the builders' home and 22 cmd/bd files import
// it, so a constructor living there was a one-line drop-in replacement for
// store.IssueReader() from any front door — and one that silently skips the
// telemetry decorator's reader-level spans, because a decorator adds its layer
// in its own accessor. Down here the only importers are the two Dolt store
// packages, and the cmd-bd-role-constructors depguard rule in .golangci.yml
// makes a front door importing it a lint failure rather than a review comment.
//
// The accessor is the door. This is the thing behind it.
package storereader
import (
"context"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/workapi"
"github.com/steveyegge/beads/issueops"
)
// New returns the issue-query surface backed by a store handle. *DoltStore and
// *EmbeddedDoltStore answer identically because the difference between them is
// below storage.DoltStorage, not above it.
//
// The reader supplies its own ConfigSource from the store it already holds, so
// a caller ON THE ROLE cannot half-perform the "load config, build filter,
// execute" ritual: it has no way to reach the pieces.
//
// THE BOUNDARY, stated once here because this is where the constructor lives:
// the store-backed role answers `bd show --json` and `bd list` on the DIRECT
// route, and the HTTP surface and both commands' proxied routes reach the
// uow-backed one. List below is therefore a traveled path on the most-run
// command in the tree, which it was not before: `bd list` used to build the
// filter and run this body's steps longhand.
//
// Ready below is still reached only by tests and by the HTTP surface. `bd
// ready` calls the workapi builders directly because it consumes the FILTER
// for --claim, --gated, --explain and --mol; see issueops.Reader's doc comment
// for why routing only its JSON path through the role would be worse.
func New(store storage.DoltStorage) (issueops.Reader, error) {
if store == nil {
return nil, &issueops.ErrUnsupported{Op: "storereader.New", Backend: "nil"}
}
return &storeReader{store: store}, nil
}
type storeReader struct{ store storage.DoltStorage }
var _ issueops.Reader = (*storeReader)(nil)
// OFFSET IS PAGED HERE, NOT IN THE QUERY. The store seam renders LIMIT without
// OFFSET (internal/storage/issueops/ready_work.go, search_counts.go), so this
// body reaches past the skipped rows and drops them after the display order —
// workapi.WithRowsBeforeThePage onto the filter, workapi.FinishPageAt at the
// end. Its unit-of-work sibling does exactly the same thing, and FinishPageAt
// says why it does it there too rather than pushing a skip its seam could
// render: the rows have to be dropped in the caller's order, and a MaxRows cap
// has to count them.
func (r *storeReader) Ready(ctx context.Context, req issueops.ReadyRequest) (issueops.IssuePage, error) {
filter, err := workapi.BuildReadyFilter(req)
if err != nil {
return issueops.IssuePage{}, err
}
limit := filter.Limit
filter = workapi.WithReadyRowsBeforeThePage(filter, req.Offset)
if filter.Limit > 0 {
// The store seam has no HasMore of its own, so ask for one row past the
// page — which the line above has already widened to cover the rows the
// epilogue skips — and let the extra row's presence be the answer.
filter.Limit++
}
items, err := r.store.GetReadyWorkWithCounts(ctx, filter)
if err != nil {
return issueops.IssuePage{}, err
}
// Ready has no display order to apply — the ordering is the sort POLICY
// the query ran under — so the epilogue's sort is a no-op here and only
// its skip, its trim and its verdict do any work. It is still the shared
// one: a second trim written out longhand is how the two arms of List came
// apart.
items, hasMore := workapi.FinishPageAt(items, "", false, req.Offset, limit, false)
return issueops.IssuePage{Items: items, HasMore: hasMore}, nil
}
// List answers one issue listing.
//
// The two knobs this body and its unit-of-work sibling once answered opposite
// ways are both honored here now, and neither is honored by anything written
// below. MaxRows rides on the filter the shared builder produces and the search
// path enforces it after the scan (internal/storage/issueops,
// EnforceMaxRowsCap), so the answer is *ErrTooManyRows instead of a page.
// Offset rides on the two workapi calls this method already made for the
// has-more probe row — one widens the bound, the other cuts the page.
func (r *storeReader) List(ctx context.Context, req issueops.ListRequest) (issueops.IssuePage, error) {
cfg, err := workapi.LoadStoreListConfig(ctx, r.store)
if err != nil {
return issueops.IssuePage{}, err
}
filter, err := workapi.BuildListFilter(req, cfg)
if err != nil {
return issueops.IssuePage{}, err
}
// Reach past the rows the epilogue skips before the probe row is sized, so
// the cap the seam enforces counts every row the query matched.
filter = workapi.WithFetchOneExtra(workapi.WithRowsBeforeThePage(filter, req.Offset))
var items []*types.IssueWithCounts
if req.ReadyFlag {
items, err = r.store.GetReadyWorkWithCounts(ctx, workapi.ReadyFilterFromIssueFilter(filter))
} else {
items, err = r.store.SearchIssuesWithCounts(ctx, "", filter)
}
if err != nil {
return issueops.IssuePage{}, err
}
// The sort, the skip, the trim and the HasMore verdict are
// workapi.FinishPageAt's, not this implementation's: `bd list` on both its
// routes and the uow-backed sibling of this method call the same function,
// so the only thing left that can differ between a CLI listing and an HTTP
// one is presentation. This seam reports no HasMore of its own, so the
// over-fetched row above is what speaks.
items, hasMore := workapi.FinishPageAt(items, req.SortBy, req.Reverse, req.Offset, workapi.PageLimit(req), false)
// Comment hydration is the second shared epilogue step, and it runs AFTER
// the trim so a page never pays for rows it is about to drop. Its source is
// the detail view's, which routes an id to the right comment table on this
// seam without being told — so this seam answers the plane question by
// declining it, and buys no lookup for an argument its source ignores. The
// unit-of-work sibling is the one that must resolve residence, and it does
// (workapi.CommentPlanes).
newComments := func() workapi.CommentStreamer { return workapi.NewStoreDetailSource(r.store) }
if err := workapi.HydrateListComments(ctx, newComments, workapi.SourceRoutesCommentPlanes, items, req.IncludeComments, !req.SkipCounts); err != nil {
return issueops.IssuePage{}, err
}
return issueops.IssuePage{Items: items, HasMore: hasMore}, nil
}
func (r *storeReader) Get(ctx context.Context, req issueops.GetRequest) (*issueops.IssueDetails, error) {
src := workapi.NewStoreDetailSource(r.store)
issue, isWisp, err := workapi.GetIssueOrWisp(ctx, src, req.ID)
if err != nil {
return nil, err
}
return workapi.BuildIssueDetails(ctx, src, issue, isWisp, workapi.DetailOptions{
IncludeDependents: req.IncludeDependents,
IncludeComments: req.IncludeComments,
BriefDeps: req.BriefDeps,
})
}