diff --git a/cmd/bd/list.go b/cmd/bd/list.go index 3542920d4..ca75bcf27 100644 --- a/cmd/bd/list.go +++ b/cmd/bd/list.go @@ -296,6 +296,10 @@ func runListCore(cmd *cobra.Command, _ []string) error { // for three aggregate joins on the most-run command in the tree. textRequest := in.ListRequest textRequest.SkipCounts = true + // No text rendering prints a comment body, so the per-row comment reads are + // not merely unused here, they are unpayable: SkipCounts above already + // zeroes the count this hydration would key on. + textRequest.IncludeComments = false page, err := reader.List(ctx, textRequest) if err != nil { if capErr := handleMaxRowsError(err); capErr != nil { @@ -453,6 +457,16 @@ func init() { // Projection toggle. Like --skip-labels it trades data for bytes, and // unlike it the dropped fields leave a mark on the row (IsLitePartial). + // Hydration toggle, the list twin of `bd show --include-comments`. Like + // --skip-labels and --brief it changes what is HYDRATED and never which + // rows match. It costs a query per row that has comments, which is why it + // is opt-in on the most-run command in the tree. + listCmd.Flags().Bool("include-comments", false, + "Populate each row's comments field with full comment bodies in JSON output "+ + "(--json only; costs one query per row that has comments). Without it, a row "+ + "with comments carries comments_omitted=true, so an absent comments field is "+ + "never mistaken for having none. Text output is unaffected either way.") + listCmd.Flags().Bool("brief", false, "Omit the free-form text (description, design, acceptance criteria, notes, "+ "payload, waiters) from each row. Filters that read those fields, such as "+ diff --git a/cmd/bd/list_comments_embedded_test.go b/cmd/bd/list_comments_embedded_test.go new file mode 100644 index 000000000..c1b105495 --- /dev/null +++ b/cmd/bd/list_comments_embedded_test.go @@ -0,0 +1,158 @@ +//go:build cgo + +package main + +import ( + "encoding/json" + "os" + "strings" + "testing" +) + +// TestEmbeddedListComments drives `bd list --json` end to end, which is the +// entry point be-73x is about: the town-wide duplicate/prior-art search this +// repo's consumers run is a `bd list --json` piped to jq, and until this +// change it could not see a comment body at all. +// +// IT RUNS THE REAL COMMAND ON PURPOSE. internal/workapi's unit tests cover the +// same hydration against a fake source with rows the test builds itself, and a +// fixture a test constructs proves what the test constructed. The rows here +// are produced by `bd create` and `bd comment` and read back by `bd list`, so +// a hydration wired to the wrong reader, a flag that never reaches the +// request, or a marshaling tag that drops the field all fail here and none of +// them fail upstairs. +func TestEmbeddedListComments(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", "lc") + + // The phrase lives ONLY in a comment. That is the whole point: title, + // description and notes are the fields a listing already carried, so a + // term found in any of them would pass with or without this change. + const commentOnlyPhrase = "zzzcommentonlyphrasezzz" + + commented := bdCreate(t, bd, dir, "Row with comments", "--type", "task") + bare := bdCreate(t, bd, dir, "Row with no comments", "--type", "task") + + if out, err := bdRunWithFlockRetry(t, bd, dir, "comment", commented.ID, "ROOT CAUSE: "+commentOnlyPhrase); err != nil { + t.Fatalf("bd comment: %v\n%s", err, out) + } + if out, err := bdRunWithFlockRetry(t, bd, dir, "comment", commented.ID, "second comment"); err != nil { + t.Fatalf("bd comment: %v\n%s", err, out) + } + + rowsByID := func(t *testing.T, args ...string) map[string]map[string]any { + t.Helper() + out, err := bdRunWithFlockRetry(t, bd, dir, append([]string{"list", "--json", "--status", "all"}, args...)...) + if err != nil { + t.Fatalf("bd list --json %s: %v\n%s", strings.Join(args, " "), err, out) + } + s := string(out) + start := strings.Index(s, "[") + if start < 0 { + t.Fatalf("no JSON array in list output:\n%s", s) + } + var rows []map[string]any + if err := json.Unmarshal([]byte(s[start:]), &rows); err != nil { + t.Fatalf("parse list JSON: %v\n%s", err, s[start:]) + } + byID := make(map[string]map[string]any, len(rows)) + for _, r := range rows { + id, _ := r["id"].(string) + byID[id] = r + } + // A denominator, so a vacuous pass is visible: every assertion below + // reads a specific row, and a page that lost the rows would otherwise + // look like a page that merely lacks the field. + if len(byID) < 2 { + t.Fatalf("list returned %d rows, want at least the 2 seeded", len(byID)) + } + return byID + } + + t.Run("default_marks_the_hole_instead_of_hiding_it", func(t *testing.T) { + byID := rowsByID(t) + + row := byID[commented.ID] + if _, present := row["comments"]; present { + t.Error("default listing carried a comments field; comment bodies are opt-in") + } + if omitted, _ := row["comments_omitted"].(bool); !omitted { + t.Errorf("comments_omitted = %v on a row with comments, want true: an absent comments field must not read as none", row["comments_omitted"]) + } + if count, _ := row["comment_count"].(float64); count != 2 { + t.Errorf("comment_count = %v, want 2", row["comment_count"]) + } + + // The control. A marker on every row would carry no information. + if _, present := byID[bare.ID]["comments_omitted"]; present { + t.Errorf("comments_omitted present on a row with no comments: a true empty stays plain omission") + } + }) + + t.Run("include_comments_makes_the_bodies_searchable", func(t *testing.T) { + byID := rowsByID(t, "--include-comments") + + row := byID[commented.ID] + comments, _ := row["comments"].([]any) + if len(comments) != 2 { + t.Fatalf("hydrated %d comments, want 2: %v", len(comments), row["comments"]) + } + // Assert on the TEXT, not the length. The defect was that the bodies + // were unreachable, and a count cannot tell a populated slice from a + // slice of empty ones. + var joined strings.Builder + for _, c := range comments { + m, _ := c.(map[string]any) + text, _ := m["text"].(string) + joined.WriteString(text) + } + if !strings.Contains(joined.String(), commentOnlyPhrase) { + t.Errorf("hydrated comment text %q does not contain %q", joined.String(), commentOnlyPhrase) + } + if _, present := row["comments_omitted"]; present { + t.Error("comments_omitted present beside populated comments: the two fields must read as one answer") + } + if _, present := byID[bare.ID]["comments"]; present { + t.Error("a row with no comments carried a comments field") + } + }) + + // The acceptance test as an agent actually runs it: grep the serialized + // page for a phrase that exists only in a comment. This is the assertion + // that fails on today's binary, and it fails with a plausible non-zero + // hit count elsewhere in the page rather than with an error, which is why + // it is worth pinning rather than trusting the field checks above. + t.Run("a_content_search_over_the_page_finds_a_comment_only_phrase", func(t *testing.T) { + withoutFlag, err := bdRunWithFlockRetry(t, bd, dir, "list", "--json", "--status", "all") + if err != nil { + t.Fatalf("bd list --json: %v\n%s", err, withoutFlag) + } + if strings.Contains(string(withoutFlag), commentOnlyPhrase) { + t.Error("default listing leaked comment text; bodies are supposed to be opt-in") + } + + withFlag, err := bdRunWithFlockRetry(t, bd, dir, "list", "--json", "--status", "all", "--include-comments") + if err != nil { + t.Fatalf("bd list --json --include-comments: %v\n%s", err, withFlag) + } + if !strings.Contains(string(withFlag), commentOnlyPhrase) { + t.Errorf("a search over the whole page missed a phrase that exists only in a comment; this is be-73x") + } + }) + + t.Run("text_output_is_untouched", func(t *testing.T) { + plain := bdList(t, bd, dir, "--status", "all") + withFlag := bdList(t, bd, dir, "--status", "all", "--include-comments") + if plain != withFlag { + t.Errorf("--include-comments changed text output.\nwithout:\n%s\nwith:\n%s", plain, withFlag) + } + if strings.Contains(withFlag, commentOnlyPhrase) { + t.Error("text listing printed a comment body") + } + }) +} diff --git a/cmd/bd/list_comments_proxied_integration_test.go b/cmd/bd/list_comments_proxied_integration_test.go new file mode 100644 index 000000000..ad0a16318 --- /dev/null +++ b/cmd/bd/list_comments_proxied_integration_test.go @@ -0,0 +1,113 @@ +//go:build cgo + +package main + +import ( + "encoding/json" + "strings" + "testing" +) + +// TestProxiedServerListComments is the second half of the be-73x coverage, and +// it exists because the fix has TWO implementations rather than one. +// +// `bd list --json` reaches issueops.Reader.List through the store-backed +// reader on the direct route and through the unit-of-work reader here. Those +// are separate bodies, and this repo has already had them answer one contract +// method differently (see the epilogue comments in both). The embedded test +// covers the first; removing the wiring from the second changes nothing there +// and everything here, so a green suite without this case would say the fix +// landed when half of it had not. +// +// The wisp-plane argument is also live only on this seam: the store-backed +// detail source routes an id to the right comment table itself and ignores the +// flag, while this one is told. +func TestProxiedServerListComments(t *testing.T) { + requireSharedProxiedServer(t) + t.Parallel() + bd := buildEmbeddedBD(t) + p := newSharedProxiedProject(t, bd, "plc") + + const commentOnlyPhrase = "zzzproxiedcommentphrasezzz" + + commented := bdProxiedCreate(t, bd, p.dir, "Proxied row with comments", "--type", "task") + bare := bdProxiedCreate(t, bd, p.dir, "Proxied row with no comments", "--type", "task") + + if out, err := bdProxiedRun(t, bd, p.dir, "comment", commented.ID, "ROOT CAUSE: "+commentOnlyPhrase); err != nil { + t.Fatalf("bd comment: %v\n%s", err, out) + } + + rowsByID := func(t *testing.T, args ...string) map[string]map[string]any { + t.Helper() + full := append([]string{"list", "--json", "--status", "all"}, args...) + stdout, stderr, err := bdProxiedRunBuffers(t, bd, p.dir, full...) + if err != nil { + t.Fatalf("bd list --json %s: %v\nstdout:\n%s\nstderr:\n%s", strings.Join(args, " "), err, stdout, stderr) + } + start := strings.Index(stdout, "[") + if start < 0 { + t.Fatalf("no JSON array in list output:\n%s", stdout) + } + var rows []map[string]any + if err := json.Unmarshal([]byte(stdout[start:]), &rows); err != nil { + t.Fatalf("parse list JSON: %v\n%s", err, stdout[start:]) + } + byID := make(map[string]map[string]any, len(rows)) + for _, r := range rows { + id, _ := r["id"].(string) + byID[id] = r + } + // The denominator, so a page that lost its rows cannot pass as a page + // that merely lacks the field. + if len(byID) < 2 { + t.Fatalf("list returned %d rows, want at least the 2 seeded", len(byID)) + } + return byID + } + + t.Run("default_marks_the_hole", func(t *testing.T) { + byID := rowsByID(t) + if omitted, _ := byID[commented.ID]["comments_omitted"].(bool); !omitted { + t.Errorf("comments_omitted = %v on a row with comments, want true", byID[commented.ID]["comments_omitted"]) + } + if _, present := byID[commented.ID]["comments"]; present { + t.Error("default listing carried comment bodies; they are opt-in") + } + if _, present := byID[bare.ID]["comments_omitted"]; present { + t.Error("comments_omitted present on a row with no comments") + } + }) + + t.Run("include_comments_hydrates_through_the_unit_of_work_reader", func(t *testing.T) { + byID := rowsByID(t, "--include-comments") + comments, _ := byID[commented.ID]["comments"].([]any) + if len(comments) != 1 { + t.Fatalf("hydrated %d comments, want 1: %v", len(comments), byID[commented.ID]["comments"]) + } + m, _ := comments[0].(map[string]any) + text, _ := m["text"].(string) + if !strings.Contains(text, commentOnlyPhrase) { + t.Errorf("comment text = %q, want it to contain %q", text, commentOnlyPhrase) + } + if _, present := byID[commented.ID]["comments_omitted"]; present { + t.Error("comments_omitted present beside populated comments") + } + }) + + t.Run("a_content_search_over_the_page_finds_a_comment_only_phrase", func(t *testing.T) { + without, _, err := bdProxiedRunBuffers(t, bd, p.dir, "list", "--json", "--status", "all") + if err != nil { + t.Fatalf("bd list --json: %v", err) + } + if strings.Contains(without, commentOnlyPhrase) { + t.Error("default listing leaked comment text") + } + with, _, err := bdProxiedRunBuffers(t, bd, p.dir, "list", "--json", "--status", "all", "--include-comments") + if err != nil { + t.Fatalf("bd list --json --include-comments: %v", err) + } + if !strings.Contains(with, commentOnlyPhrase) { + t.Error("a search over the whole page missed a comment-only phrase on the proxied route; this is be-73x") + } + }) +} diff --git a/cmd/bd/list_input.go b/cmd/bd/list_input.go index 9ffac554e..fa867ce88 100644 --- a/cmd/bd/list_input.go +++ b/cmd/bd/list_input.go @@ -101,6 +101,7 @@ func gatherListInput(cmd *cobra.Command) (listInput, error) { in.NoLabels, _ = cmd.Flags().GetBool("no-labels") in.Brief, _ = cmd.Flags().GetBool("brief") + in.IncludeComments, _ = cmd.Flags().GetBool("include-comments") in.SkipLabels, _ = cmd.Flags().GetBool("skip-labels") if in.SkipLabels { conflicts := skipLabelsConflicts(in.Labels, in.LabelsAny, in.LabelPattern, in.LabelRegex, in.ExcludeLabels, in.NoLabels) diff --git a/cmd/bd/list_proxied_server.go b/cmd/bd/list_proxied_server.go index c0f790b59..d4bb38858 100644 --- a/cmd/bd/list_proxied_server.go +++ b/cmd/bd/list_proxied_server.go @@ -101,6 +101,8 @@ func runListProxiedPage(ctx context.Context, out io.Writer, in listInput) error // none. textRequest := in.ListRequest textRequest.SkipCounts = true + // And no comment hydration, for the reason the direct route drops it. + textRequest.IncludeComments = false page, err := rd.List(ctx, textRequest) if err != nil { return err diff --git a/internal/httpapi/list_comments_omitted_test.go b/internal/httpapi/list_comments_omitted_test.go new file mode 100644 index 000000000..6e7815115 --- /dev/null +++ b/internal/httpapi/list_comments_omitted_test.go @@ -0,0 +1,55 @@ +package httpapi + +import ( + "net/http" + "testing" + + "github.com/steveyegge/beads/internal/types" +) + +// TestListRowsSayWhenCommentTextIsMissing is the HTTP half of be-73x's marker. +// +// `GET /v0/beads/issues` hydrates no comment bodies, so on this surface the +// marker IS the answer: it is the only thing that tells a caller whether an +// absent `comments` key means "this issue has none" or "this response does not +// carry them". The detail route's twin is pinned in get_issue_test.go; nothing +// asserted the list route's wire shape, which is the one route the field was +// added for. +// +// Driven through the server rather than over the epilogue directly, because the +// property at risk here is the SERIALIZATION: the marker rides a *bool with +// omitempty on the shared interchange struct, so a row that was never marked +// and a row marked false are both "absent", and only a response body shows +// which absence a client sees. +func TestListRowsSayWhenCommentTextIsMissing(t *testing.T) { + ts, rec := newReadServer(t, Config{}) + rec.items = []*types.IssueWithCounts{ + {Issue: &types.Issue{ID: "bd-1", Title: "has comments"}, CommentCount: 2}, + {Issue: &types.Issue{ID: "bd-2", Title: "has none"}, CommentCount: 0}, + } + + resp := ts.get(t, "/v0/beads/issues") + if resp.StatusCode != http.StatusOK { + t.Fatalf("GET /v0/beads/issues: status = %d, want 200", resp.StatusCode) + } + body := decodeBody(t, resp) + items, _ := body["items"].([]any) + if len(items) != 2 { + t.Fatalf("items = %v, want the two rows the fixture serves", body["items"]) + } + + withComments, _ := items[0].(map[string]any) + if got, ok := withComments["comments_omitted"]; !ok || got != true { + t.Errorf("comments_omitted = %v (present %v) on a row with comment_count 2, want true: an absent key would read as \"no comments\"", got, ok) + } + if _, ok := withComments["comments"]; ok { + t.Errorf("the list route sent `comments`, which it never hydrates: %v", withComments["comments"]) + } + + // The zero-count row is the control, and it is what makes the marker + // informative: if every row carried it, it would say nothing about any row. + withoutComments, _ := items[1].(map[string]any) + if got, ok := withoutComments["comments_omitted"]; ok { + t.Errorf("comments_omitted = %v on a row with no comments, want the key absent", got) + } +} diff --git a/internal/httpapi/spec/openapi.v0.yaml b/internal/httpapi/spec/openapi.v0.yaml index 953206fec..be43c5df4 100644 --- a/internal/httpapi/spec/openapi.v0.yaml +++ b/internal/httpapi/spec/openapi.v0.yaml @@ -1098,6 +1098,20 @@ paths: token here (a legacy row backfilled and not mutated since), so a client that defaulted a missing `revision` to 0 would compose guards that match exactly the rows it is most dangerous to be wrong about. + + + THE ROWS CARRY NO COMMENT BODIES, AND THE DETAIL READ DOES. This + operation has no `include_comments`: `comments` is always absent here + and `comments_omitted` is how a row says that its comment text exists + and was not sent, so a caller reads the bodies it wants one detail read + each (`GET /v0/beads/issues/{id}?include_comments=true`), as it does for + `revision` above. `bd list --include-comments` hydrates a whole page + because a CLI listing is one command's whole answer; the cost is a query + per commented row, which is a choice a local invocation makes for itself + and a served endpoint should not make on a caller's behalf by default. + Growing the parameter here is a later revision's call, and until it + happens the marker is this operation's answer rather than a hole it + cannot describe. parameters: - name: status in: query @@ -6465,6 +6479,11 @@ components: items: { $ref: '#/components/schemas/Dependency' } comments: type: array + description: >- + The issue's comment bodies. On a listing they are populated only + when the caller opts in (`bd list --include-comments`); absent + otherwise, which is what `comment_count` and `comments_omitted` + report about. items: { $ref: '#/components/schemas/Comment' } sender: { type: string } ephemeral: { type: boolean } @@ -6497,6 +6516,23 @@ components: description: Number of issues that depend on this one. comment_count: type: integer + comments_omitted: + type: boolean + description: >- + True when `comment_count` is nonzero and `comments` was left out — + every such row of a LIST response (`GET /v0/beads/issues`, and `bd + list --json` without `--include-comments`). Without it, an absent + `comments` key is ambiguous between "no comments" and "comments not + included in this response", and on a listing that ambiguity is what + makes a content search over the page answer with a plausible + non-empty result whose matching rows are missing. + + + IT IS SET BY THE LIST SURFACES ONLY. `GET /v0/beads/ready` and the + claim response carry this same schema and do not set it, so an + absent marker there says nothing about whether a row's comments + exist — read `comment_count`. Extending the marker to them is + tracked as be-ozp. parent: type: string description: Parent issue id, computed from the parent-child edge. diff --git a/internal/storage/uow/issue_reader.go b/internal/storage/uow/issue_reader.go index c600114d9..5f9bcc147 100644 --- a/internal/storage/uow/issue_reader.go +++ b/internal/storage/uow/issue_reader.go @@ -4,7 +4,9 @@ import ( "context" "fmt" + "github.com/steveyegge/beads/internal/storage/dberrors" "github.com/steveyegge/beads/internal/storage/domain" + "github.com/steveyegge/beads/internal/storage/sqlbuild" "github.com/steveyegge/beads/internal/workapi" publicops "github.com/steveyegge/beads/issueops" ) @@ -131,10 +133,57 @@ func (r *issueReader) List(ctx context.Context, req publicops.ListRequest) (publ // between this implementation and its store-backed sibling, and it is // an argument to the shared function rather than a second copy of it. items, hasMore := workapi.FinishPageAt(page.Items, req.SortBy, req.Reverse, req.Offset, workapi.PageLimit(req), page.HasMore) + // The same shared hydration step the store-backed sibling runs, through + // the same function and after the same trim. This seam's detail source + // is the one that needs the wisp plane told to it, and the plane it is + // told is the TABLE THE ROW IS IN, resolved here in the page's own + // transaction — never the row's flags, which a durable row can carry + // wrongly (see workapi.CommentPlanes). + newComments := func() workapi.CommentStreamer { return workapi.NewUOWDetailSource(uw) } + planes := func(ctx context.Context, ids []string) (map[string]bool, error) { + return wispPlanesByResidence(ctx, uw, ids) + } + if err := workapi.HydrateListComments(ctx, newComments, planes, items, req.IncludeComments, !req.SkipCounts); err != nil { + return publicops.IssuePage{}, err + } return publicops.IssuePage{Items: items, HasMore: hasMore}, nil }) } +// wispPlanesByResidence reports which of ids live in the WISPS TABLE, which is +// what decides where their comments are. +// +// It is the page-sized form of the question workapi.GetIssueOrWisp answers one +// id at a time behind Reader.Get and behind commenter.AddComment: residence, +// not the row's Ephemeral/NoHistory flags, which `bd import` can leave pointing +// at the other plane (workapi.CommentPlanes says how, and what the listing +// answered before this resolved by table). GetWispsByIDs is the use-case call +// edgeReader.ReadEdges already makes to answer the same question, so this adds +// a caller rather than a mechanism, and one query serves the whole page. +// +// A MISSING WISPS TABLE MEANS NO WISPS, not a failed listing: the table is in +// the optional set every wisp query treats that way +// (sqlbuild.OptionalWispTable), the counts query that produced this page merged +// wisps under the same tolerance, and the store-backed seam's own router +// answers "durable" for it (DoltStore.wispExists). Erroring here would make +// `bd list --include-comments` the one read that cannot run on such a database. +func wispPlanesByResidence(ctx context.Context, uw UnitOfWork, ids []string) (map[string]bool, error) { + wisps, err := uw.IssueUseCase().GetWispsByIDs(ctx, ids) + if err != nil { + if name, ok := dberrors.MissingTableName(err); ok && sqlbuild.OptionalWispTable(name) { + return nil, nil + } + return nil, err + } + planes := make(map[string]bool, len(wisps)) + for _, wisp := range wisps { + if wisp != nil { + planes[wisp.ID] = true + } + } + return planes, nil +} + func (r *issueReader) Get(ctx context.Context, req publicops.GetRequest) (*publicops.IssueDetails, error) { return RunTxRead(ctx, r.provider, func(ctx context.Context, uw UnitOfWork) (*publicops.IssueDetails, error) { src := workapi.NewUOWDetailSource(uw) diff --git a/internal/storage/uow/list_comments_plane_test.go b/internal/storage/uow/list_comments_plane_test.go new file mode 100644 index 000000000..f05bb0d16 --- /dev/null +++ b/internal/storage/uow/list_comments_plane_test.go @@ -0,0 +1,251 @@ +package uow + +import ( + "context" + "errors" + "fmt" + "slices" + "testing" + + mysql "github.com/go-sql-driver/mysql" + + "github.com/steveyegge/beads/internal/storage" + "github.com/steveyegge/beads/internal/storage/domain" + "github.com/steveyegge/beads/internal/types" + publicops "github.com/steveyegge/beads/issueops" +) + +// The unit-of-work seam is the one whose comment source has to be TOLD which +// table to read — the store-backed sibling's source routes an id itself — so it +// is the one where a wrong answer is a silent wrong-table read. These tests +// drive the real Reader.List with --include-comments and assert the comment +// BODIES arrive, because the failure they cover produced an empty comments array +// beside a nonzero comment_count rather than an error or a visibly wrong row. +// +// The rows are the two shapes where a row's flags and its table disagree, and +// both are states the tree maintains on purpose: `bd import` pins a no_history +// record to the durable table while preserving the flag (clearing it would +// change the content hash and break export→import→export byte-identity), and +// pins a wisp_plane record to the wisps table without setting either flag. See +// workapi.CommentPlanes. + +// planeIssues serves one page and answers the residence question from the +// wisps-table membership the test declares, which is what +// IssueUseCase.GetWispsByIDs answers from a real database. +type planeIssues struct { + domain.IssueUseCase + rows []*types.IssueWithCounts + inWisps map[string]*types.Issue + wispErr error + asked [][]string +} + +func (f *planeIssues) SearchIssuesWithCounts(context.Context, string, types.IssueFilter) (domain.SearchCountsPage, error) { + return domain.SearchCountsPage{Items: f.rows}, nil +} + +func (f *planeIssues) GetWispsByIDs(_ context.Context, ids []string) ([]*types.Issue, error) { + f.asked = append(f.asked, ids) + if f.wispErr != nil { + return nil, f.wispErr + } + out := make([]*types.Issue, 0, len(ids)) + for _, id := range ids { + if wisp, ok := f.inWisps[id]; ok { + out = append(out, wisp) + } + } + return out, nil +} + +// planeComments keeps each plane's comments in its own map, the way the two +// comment tables do, so a read of the wrong one comes back empty here exactly as +// it does against a database. +type planeComments struct { + domain.CommentUseCase + issueComments map[string][]*types.Comment + wispComments map[string][]*types.Comment +} + +func (f planeComments) IterCommentsForIssue(_ context.Context, id string) (storage.Iter[types.Comment], error) { + return storage.NewSliceIter(f.issueComments[id]), nil +} + +func (f planeComments) IterCommentsForWisp(_ context.Context, id string) (storage.Iter[types.Comment], error) { + return storage.NewSliceIter(f.wispComments[id]), nil +} + +func planeReader(t *testing.T, issues *planeIssues, comments domain.CommentUseCase) publicops.Reader { + t.Helper() + uw := &mockUnitOfWork{issueUseCase: issues, configUseCase: readerConfig{}, commentUseCase: comments} + reader, err := NewIssueReader(&mockUnitOfWorkProvider{uows: []*mockUnitOfWork{uw}}) + if err != nil { + t.Fatalf("NewIssueReader: %v", err) + } + return reader +} + +func commentTexts(item *types.IssueWithCounts) []string { + out := make([]string, 0, len(item.Comments)) + for _, c := range item.Comments { + out = append(out, c.Text) + } + return out +} + +// TestListHydratesCommentsFromTheRowsTableNotItsFlags is the seam-level +// regression for the row class this reader used to answer with content-free +// rows: a durable bead that still carries no_history, listed with +// --include-comments, whose comments `bd comment` wrote to the ISSUES table and +// `bd show` reads from there. Routing by the flag sent the list read to +// wisp_comments, where the row has nothing, and the page came back asserting one +// comment, carrying none, and flagging nothing. +func TestListHydratesCommentsFromTheRowsTableNotItsFlags(t *testing.T) { + issues := &planeIssues{ + rows: []*types.IssueWithCounts{ + {Issue: &types.Issue{ID: "bd-1", Title: "import-pinned", NoHistory: true}, CommentCount: 1}, + }, + inWisps: map[string]*types.Issue{}, + } + comments := planeComments{ + issueComments: map[string][]*types.Comment{"bd-1": {{ID: "c1", Text: "zzzuniquephrase"}}}, + // Nothing on the wisp plane: the table the flag points at is empty for + // this id, which is why the defect was silent rather than wrong. + wispComments: map[string][]*types.Comment{}, + } + reader := planeReader(t, issues, comments) + + page, err := reader.List(context.Background(), publicops.ListRequest{IncludeComments: true}) + if err != nil { + t.Fatalf("List: %v", err) + } + + if len(page.Items) != 1 { + t.Fatalf("page has %d rows, want 1", len(page.Items)) + } + if got := commentTexts(page.Items[0]); !slices.Equal(got, []string{"zzzuniquephrase"}) { + t.Errorf("comments = %v, want [zzzuniquephrase]: the row lives in the issues table, whatever its no_history flag says", got) + } + if page.Items[0].CommentsOmitted != nil { + t.Errorf("CommentsOmitted = %v on a hydrated row, want unset", *page.Items[0].CommentsOmitted) + } + if len(issues.asked) != 1 || !slices.Equal(issues.asked[0], []string{"bd-1"}) { + t.Errorf("resolved residence with %v, want one lookup for [bd-1]: the plane is a query, not a guess", issues.asked) + } +} + +// TestListHydratesCommentsForAWispTableRowWithNoFlags is the mirror, and the one +// no flag-based rule can get right either: a row the import pinned to the WISPS +// table with neither plane flag set. Its comments are in wisp_comments and the +// flags point at the durable table. +func TestListHydratesCommentsForAWispTableRowWithNoFlags(t *testing.T) { + issues := &planeIssues{ + rows: []*types.IssueWithCounts{ + {Issue: &types.Issue{ID: "bd-2", Title: "plane-pinned"}, CommentCount: 1}, + }, + inWisps: map[string]*types.Issue{"bd-2": {ID: "bd-2"}}, + } + comments := planeComments{ + issueComments: map[string][]*types.Comment{}, + wispComments: map[string][]*types.Comment{"bd-2": {{ID: "c1", Text: "zzzuniquephrase"}}}, + } + reader := planeReader(t, issues, comments) + + page, err := reader.List(context.Background(), publicops.ListRequest{IncludeComments: true}) + if err != nil { + t.Fatalf("List: %v", err) + } + + if len(page.Items) != 1 { + t.Fatalf("page has %d rows, want 1", len(page.Items)) + } + if got := commentTexts(page.Items[0]); !slices.Equal(got, []string{"zzzuniquephrase"}) { + t.Errorf("comments = %v, want [zzzuniquephrase]: the row is in the wisps table, whatever its flags say", got) + } +} + +// TestListResolvesNoPlanesWithoutIncludeComments pins that the default listing — +// which is every `bd list` that does not pass the flag — pays nothing for the +// routing query. The marker path routes no read, so it asks no table where +// anything lives. +func TestListResolvesNoPlanesWithoutIncludeComments(t *testing.T) { + issues := &planeIssues{ + rows: []*types.IssueWithCounts{ + {Issue: &types.Issue{ID: "bd-1", NoHistory: true}, CommentCount: 1}, + }, + inWisps: map[string]*types.Issue{}, + } + reader := planeReader(t, issues, planeComments{}) + + page, err := reader.List(context.Background(), publicops.ListRequest{}) + if err != nil { + t.Fatalf("List: %v", err) + } + + if len(issues.asked) != 0 { + t.Errorf("resolved residence %d times on a listing that asked for no comments, want 0", len(issues.asked)) + } + if page.Items[0].CommentsOmitted == nil || !*page.Items[0].CommentsOmitted { + t.Errorf("CommentsOmitted = %v, want true: the default listing still says the text is missing", page.Items[0].CommentsOmitted) + } +} + +// TestListToleratesAMissingWispsTable keeps `bd list --include-comments` working +// on a database that has no wisps table at all. That table is in the optional set +// every wisp query treats as "no wisps" (sqlbuild.OptionalWispTable) — the counts +// query that produced the page merged wisps under the same tolerance, and the +// store-backed seam's router answers "durable" for it — so a listing must not be +// the one read that cannot run there. +// +// The fixture error is the one this seam receives: a missing table arrives from +// the server as MySQL 1146, and the table it names is what +// dberrors.MissingTableName reads. Classifying it through those two shared +// helpers rather than a local string check is what keeps this tolerance the SAME +// tolerance the counts query already applies. +func TestListToleratesAMissingWispsTable(t *testing.T) { + issues := &planeIssues{ + rows: []*types.IssueWithCounts{ + {Issue: &types.Issue{ID: "bd-1", NoHistory: true}, CommentCount: 1}, + }, + wispErr: fmt.Errorf("getByIDs: %w", &mysql.MySQLError{Number: 1146, Message: "table not found: wisps"}), + } + comments := planeComments{ + issueComments: map[string][]*types.Comment{"bd-1": {{ID: "c1", Text: "zzzuniquephrase"}}}, + } + reader := planeReader(t, issues, comments) + + page, err := reader.List(context.Background(), publicops.ListRequest{IncludeComments: true}) + if err != nil { + t.Fatalf("List over a database with no wisps table: %v", err) + } + if got := commentTexts(page.Items[0]); !slices.Equal(got, []string{"zzzuniquephrase"}) { + t.Errorf("comments = %v, want [zzzuniquephrase]: with no wisps table, every row is durable", got) + } +} + +// TestListFailsWhenResidenceCannotBeRead is the other half of that tolerance: +// any OTHER failure of the routing query fails the call. Hydration promises the +// bodies or an error, and a page that cannot find out where its rows live can +// only keep that promise by saying so — falling back to a plane would answer with +// the wrong table's contents, which is invisible in the response. +func TestListFailsWhenResidenceCannotBeRead(t *testing.T) { + sentinel := errors.New("connection reset") + issues := &planeIssues{ + rows: []*types.IssueWithCounts{ + {Issue: &types.Issue{ID: "bd-1"}, CommentCount: 1}, + }, + wispErr: sentinel, + } + comments := planeComments{ + issueComments: map[string][]*types.Comment{"bd-1": {{ID: "c1", Text: "zzzuniquephrase"}}}, + } + reader := planeReader(t, issues, comments) + + _, err := reader.List(context.Background(), publicops.ListRequest{IncludeComments: true}) + if err == nil { + t.Fatal("List returned nil when residence could not be read, want an error") + } + if !errors.Is(err, sentinel) { + t.Errorf("error = %v, want it to wrap %v", err, sentinel) + } +} diff --git a/internal/types/types.go b/internal/types/types.go index df0f85263..37dbf345b 100644 --- a/internal/types/types.go +++ b/internal/types/types.go @@ -1142,6 +1142,34 @@ type IssueWithCounts struct { DependentCount int `json:"dependent_count"` CommentCount int `json:"comment_count"` Parent *string `json:"parent,omitempty"` // Computed parent from parent-child dep (bd-ym8c) + + // CommentsOmitted is the list row's half of the ga-clgh contract + // IssueDetails.CommentsOmitted states for the detail view, and it is set + // under exactly the same rule: true only when CommentCount is nonzero AND + // the embedded Issue.Comments was left nil, never alongside a populated + // slice and never on a zero count. + // + // A LIST ROW NEEDS IT MORE THAN A DETAIL VIEW DOES (be-73x). A caller + // grepping a whole listing for a phrase that lives in a comment gets a + // plausible NON-ZERO answer with the matching rows missing — the shape + // that invites no suspicion at all, unlike an empty result. Without this + // marker nothing in the page says the text was never in scope. + // + // The comment BODIES ride on the embedded Issue.Comments, which already + // carries the `comments` key for export/import; this type adds only the + // marker, so a row that was hydrated and a row that was not are told + // apart by a field rather than by the caller remembering what it asked + // for. + // + // WHICH SURFACES SET IT, because this type is shared by more than the + // listing and an absent marker means different things on them. It is set + // by the page epilogue behind issueops.Reader.List — `bd list --json` on + // both routes, its --ready arm included, and GET /v0/beads/issues. It is + // NOT set by Reader.Ready (GET /v0/beads/ready) or by the claim response + // that returns this type, so on those an absent marker says nothing about + // whether a row's comments exist: read comment_count there. Extending the + // marker to them is be-ozp. + CommentsOmitted *bool `json:"comments_omitted,omitempty"` } // IssueDetails extends Issue with labels, dependencies, dependents, and comments. diff --git a/internal/workapi/detail.go b/internal/workapi/detail.go index e8b9480fd..648911fb9 100644 --- a/internal/workapi/detail.go +++ b/internal/workapi/detail.go @@ -218,7 +218,11 @@ func collectDependents(ctx context.Context, src DetailSource, id string, isWisp return out, nil } -func collectComments(ctx context.Context, src DetailSource, id string, isWisp bool) ([]*types.Comment, error) { +// collectComments takes the narrow CommentStreamer rather than the whole +// DetailSource because it reads exactly one method, and because the list-page +// hydration in list_comments.go calls the same body. DetailSource satisfies +// CommentStreamer, so BuildIssueDetails passes its source unchanged. +func collectComments(ctx context.Context, src CommentStreamer, id string, isWisp bool) ([]*types.Comment, error) { iter, err := src.IterComments(ctx, id, isWisp) if err != nil { return nil, fmt.Errorf("iter comments %s: %w", id, err) diff --git a/internal/workapi/list_comments.go b/internal/workapi/list_comments.go new file mode 100644 index 000000000..b5680f2e8 --- /dev/null +++ b/internal/workapi/list_comments.go @@ -0,0 +1,210 @@ +package workapi + +import ( + "context" + "fmt" + + "github.com/steveyegge/beads/internal/storage" + "github.com/steveyegge/beads/internal/types" +) + +// CommentStreamer is the one method list-comment hydration needs off a detail +// source. It is named separately, and taken as the narrower interface, so the +// hydration body cannot quietly grow a second read: DetailSource satisfies it, +// and both of the sources that exist (NewStoreDetailSource, NewUOWDetailSource) +// are therefore usable here without a new adapter. +type CommentStreamer interface { + IterComments(ctx context.Context, id string, isWisp bool) (storage.Iter[types.Comment], error) +} + +// CommentPlanes answers, for one page of ids, which of them keep their comments +// on the WISP plane: an id the map reports true for is read from wisp_comments, +// and an id it reports false for or omits from comments. +// +// IT IS A QUERY, NOT A PREDICATE ON THE ROW, because residence is the answer +// and only a query has it. An earlier version of this body derived the plane +// from the row's own Ephemeral/NoHistory flags — issueops.IsWisp's rule, which +// is the right rule for routing a record being WRITTEN — and that inference is +// wrong on a read for a row class the tree deliberately maintains. `bd import` +// pins a `no_history` record to the durable table while PRESERVING the flag on +// the row (cmd/bd/import_shared.go, applyImportWispPlane: clearing it would +// change the content hash and break export→import→export byte-identity, so +// "only the routing is pinned"), and every clone materializes its database by +// importing JSONL. A promoted no-history bead that has been through +// export→import is therefore a durable row whose flags say wisp, and reading +// its comments by those flags queries wisp_comments, finds nothing, and answers +// with a nonzero comment_count, an empty comments array, no marker and no error +// — be-73x's own failure mode, under the flag whose contract is "gets them or +// gets an error". +// +// Every other comment-touching role already resolves residence instead of +// inferring it: GetIssueOrWisp behind both Reader.Get implementations and behind +// uow.commenter.AddComment, DoltStore.GetIssueComments through isActiveWisp, +// issueops.GetCommentCountsInTx through PartitionWispIDsInTx. So `bd comment` +// writes such a row's comments where `bd show` reads them, and a listing that +// went by the flags was the one role that disagreed with the other three about +// the same row. A page is that same question asked about many ids, so it is +// answered the same way, once per page rather than once per row. +type CommentPlanes func(ctx context.Context, ids []string) (map[string]bool, error) + +// SourceRoutesCommentPlanes is the CommentPlanes to pass when the comment +// source needs no plane told to it because it resolves each id itself: the +// store-backed source is the one that does (DoltStore.GetIssueComments picks +// the table from isActiveWisp), and it ignores the argument entirely. +// +// It is a NAMED no-op rather than a nil default so that the seam with a routing +// question and the seam without one are told apart at the call site, and so a +// third seam added later has to answer the question rather than inherit +// "durable" by omission — which is exactly how the wrong-table read described +// on CommentPlanes got in. +func SourceRoutesCommentPlanes(context.Context, []string) (map[string]bool, error) { + return nil, nil +} + +// HydrateListComments fills in the comment half of one list page. +// +// It is the shared epilogue step FinishPageAt is, and for the identical +// reason: `bd list --json` reaches this through two Reader.List +// implementations — the store-backed one and the unit-of-work one — and a +// hydration written out longhand in each is how the two came apart before. +// One body, called from both, is what makes a CLI listing and an HTTP one +// answer the same request the same way. +// +// TWO OUTCOMES, AND NEITHER IS SILENT. +// +// include = true every row's Issue.Comments is populated, and any row that +// cannot be read fails the whole call. A caller that asked +// for the bodies gets them or gets an error; it never gets a +// short list it has no way to detect. +// include = false every row with a nonzero CommentCount is marked +// CommentsOmitted, so an absent `comments` key means "none" +// on one row and "not asked for" on the other, and the row +// says which. +// +// THE SOURCE IS A CONSTRUCTOR, NOT A SOURCE, AND THAT IS LOAD-BEARING RATHER +// THAN STYLE. Comment hydration is opt-in, so the DEPENDENCY on a comment +// reader must be opt-in with it: building one eagerly on every listing makes a +// capability that only the opt-in path uses into a requirement every caller +// has to satisfy. It is not hypothetical — the unit-of-work source is built +// from four use-case accessors, and constructing it unconditionally turned +// every `GET /v0/beads/issues` on a provider without a comment use case into a +// panic, on a request that had asked for no comments at all. A count-only +// listing now calls nothing. +// +// THE MARKER IS THE POINT, not the hydration (be-73x). A page that silently +// carries no comment text answers a content search with a plausible non-zero +// result whose matching rows are missing, and nothing in that answer invites a +// second look. The count alone does not fix it: comment_count sits on the row +// accurately reporting how much is not there, which reads as reassurance +// rather than as a warning. +// +// A ZERO COUNT IS NOT ALWAYS ZERO COMMENTS, AND countsKnown IS WHAT SEPARATES +// THE TWO. Under issueops.ListRequest.SkipCounts the cardinalities come back +// zero meaning UNKNOWN — the request type says so in as many words — so a body +// that reads CommentCount as authoritative would answer IncludeComments with +// an empty page and no error. countsKnown false therefore means: query every +// row, because there is no count to prove a row has nothing to fetch, and mark +// no row omitted, because the marker asserts a nonzero count this page cannot +// support. +// +// It is a PARAMETER rather than an assumption because issueops.ListRequest is +// PUBLIC and permits both fields at once. An earlier version of this body +// skipped every row on that combination and justified it in a comment reading +// "the JSON route never sets SkipCounts" — true of today's CLI callers, and +// not a property of the contract they were reading. The HTTP surface and any +// future caller may set both. +// +// THE PLANE COMES FROM THE PAGE'S SEAM, NOT FROM THE ROW. Which comment table +// an id's comments live in is a fact about where the row was found, so the +// caller resolves it (CommentPlanes) rather than this body inferring it from +// the row's flags — see CommentPlanes for the row class where the flags and the +// table disagree, and why that made a listing answer with content-free rows. +func HydrateListComments(ctx context.Context, newSrc func() CommentStreamer, planes CommentPlanes, items []*types.IssueWithCounts, include, countsKnown bool) error { + if len(items) == 0 { + return nil + } + if !include { + if countsKnown { + markCommentsOmitted(items) + } + return nil + } + if newSrc == nil { + return fmt.Errorf("hydrate list comments: comment source must not be nil") + } + if planes == nil { + return fmt.Errorf("hydrate list comments: comment plane resolution must not be nil (pass SourceRoutesCommentPlanes when the source routes ids itself)") + } + rows := rowsNeedingComments(items, countsKnown) + if len(rows) == 0 { + return nil + } + src := newSrc() + if src == nil { + return fmt.Errorf("hydrate list comments: comment source must not be nil") + } + // One plane query for the whole page, and only for the rows that are about + // to be read: the ids are the same set the loop below walks, so a page that + // needs no comment read pays for no plane lookup either. + wisp, err := planes(ctx, rowIDs(rows)) + if err != nil { + return fmt.Errorf("hydrate list comments: resolve comment planes: %w", err) + } + for _, item := range rows { + comments, err := collectComments(ctx, src, item.ID, wisp[item.ID]) + if err != nil { + return fmt.Errorf("hydrate list comments: %w", err) + } + item.Issue.Comments = comments + } + return nil +} + +// rowsNeedingComments is the page narrowed to the rows a comment read has to be +// issued for, and it is what bounds both that read and the plane lookup. +// +// A row the page can PROVE has no comments needs no query. Only a hydrated +// count proves it: under SkipCounts a zero means unknown, and treating it as +// none is how this body once dropped every comment a caller had asked for. +func rowsNeedingComments(items []*types.IssueWithCounts, countsKnown bool) []*types.IssueWithCounts { + out := make([]*types.IssueWithCounts, 0, len(items)) + for _, item := range items { + if item == nil || item.Issue == nil { + continue + } + if countsKnown && item.CommentCount == 0 { + continue + } + out = append(out, item) + } + return out +} + +func rowIDs(items []*types.IssueWithCounts) []string { + out := make([]string, 0, len(items)) + for _, item := range items { + out = append(out, item.ID) + } + return out +} + +// markCommentsOmitted flags the rows whose comment text was never fetched. +// Rows the caller already hydrated are left alone: CommentsOmitted never +// appears beside a populated slice, which is what lets a consumer read the two +// fields as one unambiguous answer. +// +// It is called only when the counts are real. The marker's meaning is "this +// row HAS comments and they are not here", so a page whose counts were skipped +// cannot honestly set it on any row — it does not know. That page is less +// informative, which is what its caller asked for by skipping the counts. +func markCommentsOmitted(items []*types.IssueWithCounts) { + for _, item := range items { + if item == nil || item.Issue == nil { + continue + } + if item.CommentCount > 0 && item.Issue.Comments == nil { + omitted := true + item.CommentsOmitted = &omitted + } + } +} diff --git a/internal/workapi/list_comments_test.go b/internal/workapi/list_comments_test.go new file mode 100644 index 000000000..6f666dab0 --- /dev/null +++ b/internal/workapi/list_comments_test.go @@ -0,0 +1,440 @@ +package workapi + +import ( + "context" + "errors" + "slices" + "testing" + + "github.com/steveyegge/beads/internal/storage" + "github.com/steveyegge/beads/internal/types" +) + +// fakeCommentStreamer records what was asked of it and answers from a map, so +// a test can assert on the CALLS as well as on the result. The recorded plane +// is the half no rendered output would show. +// +// It answers PER PLANE, like the storage it stands in for: comments put in byID +// are on the durable plane and comments put in wispByID on the wisp one, so a +// read of the wrong table comes back empty here exactly as it does against a +// database. That is what lets a test assert the comment TEXT rather than only +// the recorded plane flag — the defect this file's plane coverage exists for +// produced an empty array, not a wrong one. +type fakeCommentStreamer struct { + byID map[string][]*types.Comment + wispByID map[string][]*types.Comment + err error + calls []streamCall +} + +type streamCall struct { + id string + isWisp bool +} + +func (f *fakeCommentStreamer) IterComments(_ context.Context, id string, isWisp bool) (storage.Iter[types.Comment], error) { + f.calls = append(f.calls, streamCall{id: id, isWisp: isWisp}) + if f.err != nil { + return nil, f.err + } + if isWisp { + return storage.NewSliceIter(f.wispByID[id]), nil + } + return storage.NewSliceIter(f.byID[id]), nil +} + +// fakePlanes is the seam that knows where a row lives, which on the production +// unit-of-work path is a query against the wisps table. It records the ids it +// was asked about so a test can pin that the lookup is bounded to the rows a +// comment read is actually issued for — and that a page needing no read pays +// for no lookup. +type fakePlanes struct { + wisps map[string]bool + err error + asked [][]string +} + +// planesFor builds the answer for a page whose wisp-table residents are the +// given ids. Called with none, it is a page of durable rows. +func planesFor(wispIDs ...string) *fakePlanes { + wisps := make(map[string]bool, len(wispIDs)) + for _, id := range wispIDs { + wisps[id] = true + } + return &fakePlanes{wisps: wisps} +} + +func (f *fakePlanes) resolve(_ context.Context, ids []string) (map[string]bool, error) { + f.asked = append(f.asked, ids) + if f.err != nil { + return nil, f.err + } + return f.wisps, nil +} + +// noPlaneLookup fails the test if the plane is resolved at all, which is the +// same assertion the failing source constructor makes one layer up: the routing +// query is part of the READ, so a page that reads nothing must not pay for it. +func noPlaneLookup(t *testing.T) CommentPlanes { + t.Helper() + return func(_ context.Context, ids []string) (map[string]bool, error) { + t.Errorf("resolved comment planes for %v on a page that issues no comment read", ids) + return nil, nil + } +} + +// srcFunc adapts a fake to the lazy constructor HydrateListComments takes. +// The laziness is itself under test in TestHydrateListCommentsCountOnlyBuildsNoSource. +func srcFunc(src CommentStreamer) func() CommentStreamer { + return func() CommentStreamer { return src } +} + +func row(id string, commentCount int) *types.IssueWithCounts { + return &types.IssueWithCounts{ + Issue: &types.Issue{ID: id}, + CommentCount: commentCount, + } +} + +func comment(id, text string) *types.Comment { + return &types.Comment{ID: id, Text: text} +} + +// TestHydrateListCommentsMarksOmittedWithoutFetching pins the DEFAULT half of +// the contract, which is the half be-73x is actually about: a page nobody +// asked to hydrate must still say that its comment text is missing, and it +// must say so without paying for a single read. +func TestHydrateListCommentsMarksOmittedWithoutFetching(t *testing.T) { + src := &fakeCommentStreamer{byID: map[string][]*types.Comment{ + "a-1": {comment("c1", "root cause")}, + }} + items := []*types.IssueWithCounts{row("a-1", 1), row("a-2", 0)} + planes := planesFor() + + if err := HydrateListComments(context.Background(), srcFunc(src), planes.resolve, items, false, true); err != nil { + t.Fatalf("HydrateListComments: %v", err) + } + + if len(src.calls) != 0 { + t.Errorf("count-only mode issued %d comment reads, want 0: the marker is derived from the count already on the row", len(src.calls)) + } + // The plane lookup is part of the read, so a page that reads nothing must + // not pay for it either: the marker path routes no query and so asks no + // table where anything lives. + if len(planes.asked) != 0 { + t.Errorf("count-only mode resolved comment planes %d times, want 0: nothing is being read, so nothing needs routing", len(planes.asked)) + } + if items[0].CommentsOmitted == nil || !*items[0].CommentsOmitted { + t.Errorf("CommentsOmitted = %v on a row with comment_count 1, want true: without it an absent comments field reads as none", items[0].CommentsOmitted) + } + if items[0].Comments != nil { + t.Errorf("Comments = %v in count-only mode, want nil", items[0].Comments) + } + // The zero-count row is the control. A marker on it would make the flag + // meaningless: every row would carry it and none would be informative. + if items[1].CommentsOmitted != nil { + t.Errorf("CommentsOmitted = %v on a row with no comments, want unset: a true empty stays plain omission", *items[1].CommentsOmitted) + } +} + +// TestHydrateListCommentsPopulatesBodies pins the opt-in half, and asserts on +// the COMMENT TEXT rather than on a length: the defect this fixes is that the +// text is unreachable, and a count of rows cannot tell a populated slice from +// a slice of empty ones. +func TestHydrateListCommentsPopulatesBodies(t *testing.T) { + src := &fakeCommentStreamer{byID: map[string][]*types.Comment{ + "a-1": {comment("c1", "zzzuniquephrase"), comment("c2", "second")}, + }} + items := []*types.IssueWithCounts{row("a-1", 2), row("a-2", 0)} + planes := planesFor() + + if err := HydrateListComments(context.Background(), srcFunc(src), planes.resolve, items, true, true); err != nil { + t.Fatalf("HydrateListComments: %v", err) + } + + if got := len(items[0].Comments); got != 2 { + t.Fatalf("hydrated %d comments, want 2", got) + } + if got := items[0].Comments[0].Text; got != "zzzuniquephrase" { + t.Errorf("comment body = %q, want %q: the bodies are the whole point", got, "zzzuniquephrase") + } + if items[0].CommentsOmitted != nil { + t.Errorf("CommentsOmitted = %v beside a populated slice, want unset: the two fields must read as one unambiguous answer", *items[0].CommentsOmitted) + } + // A row with no comments is not queried at all, which is what keeps the + // per-row cost proportional to the rows that actually have text. + for _, call := range src.calls { + if call.id == "a-2" { + t.Errorf("issued a comment read for a row with comment_count 0") + } + } + // And the plane lookup covers that same narrowed set, not the whole page. + if len(planes.asked) != 1 || !slices.Equal(planes.asked[0], []string{"a-1"}) { + t.Errorf("resolved planes for %v, want one lookup for [a-1]: routing is asked about the rows being read", planes.asked) + } +} + +// TestHydrateListCommentsRoutesByResidenceNotFlags pins where the comment plane +// comes from, and the two rows in the middle of the table are the reason it is +// not the row's flags. +// +// Both of those rows are states the tree maintains on purpose. `bd import` pins +// a no_history record to the DURABLE table and preserves the flag on the row, +// because clearing it would change the content hash and break +// export→import→export byte-identity — so a promoted no-history bead that has +// been through a JSONL round-trip (which is how a clone materializes its +// database) is a durable row whose flags say wisp. The mirror case is an import +// record whose wisp_plane key pins it to the WISPS table with neither flag set. +// An earlier version of this body read Ephemeral || NoHistory, so it queried +// wisp_comments for the first and comments for the second, found nothing either +// way, and returned the row with its nonzero comment_count, no comments, no +// marker and no error — the silent hole be-73x exists to close, under the flag +// that promises the bodies or an error. +// +// The fixture puts each row's comments only on the plane it actually lives on, +// so a wrong-table read shows up as MISSING TEXT and not merely as a wrong flag +// in a recorded call. +func TestHydrateListCommentsRoutesByResidenceNotFlags(t *testing.T) { + cases := []struct { + name string + issue *types.Issue + inWisps bool + }{ + {"durable row, no flags", &types.Issue{ID: "a-1"}, false}, + // The flags say wisp and the table says durable: the import-pinned + // promoted bead. Residence wins. + {"durable row carrying no_history", &types.Issue{ID: "a-1", NoHistory: true}, false}, + // The mirror: the flags say durable and the row is in the wisps table. + {"wisp-table row carrying no flags", &types.Issue{ID: "a-1"}, true}, + {"wisp-table row carrying ephemeral", &types.Issue{ID: "a-1", Ephemeral: true}, true}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + src := &fakeCommentStreamer{} + planes := planesFor() + if tc.inWisps { + src.wispByID = map[string][]*types.Comment{"a-1": {comment("c1", "zzzuniquephrase")}} + planes = planesFor("a-1") + } else { + src.byID = map[string][]*types.Comment{"a-1": {comment("c1", "zzzuniquephrase")}} + } + items := []*types.IssueWithCounts{{Issue: tc.issue, CommentCount: 1}} + + if err := HydrateListComments(context.Background(), srcFunc(src), planes.resolve, items, true, true); err != nil { + t.Fatalf("HydrateListComments: %v", err) + } + + if len(src.calls) != 1 { + t.Fatalf("issued %d comment reads, want 1", len(src.calls)) + } + if src.calls[0].isWisp != tc.inWisps { + t.Errorf("read the %v plane for a row living on the %v plane", planeName(src.calls[0].isWisp), planeName(tc.inWisps)) + } + if got := len(items[0].Comments); got != 1 { + t.Fatalf("hydrated %d comments, want 1: a read of the other plane comes back empty, with a nonzero comment_count still on the row", got) + } + if got := items[0].Comments[0].Text; got != "zzzuniquephrase" { + t.Errorf("comment body = %q, want %q", got, "zzzuniquephrase") + } + if items[0].CommentsOmitted != nil { + t.Errorf("CommentsOmitted = %v on a hydrated row, want unset", *items[0].CommentsOmitted) + } + }) + } +} + +// TestHydrateListCommentsRequiresAPlaneAnswer pins that the routing question has +// to be ANSWERED rather than defaulted. +// +// A nil CommentPlanes would read every row on the durable plane, which is the +// wrong-table read of the test above wearing a default instead of an inference, +// and the seam that gets it wrong is the one whose source cannot detect it. A +// caller whose source routes ids itself says so by name +// (SourceRoutesCommentPlanes), so the two cases are distinguishable at the call +// site and a third seam has to make the choice rather than inherit it. +func TestHydrateListCommentsRequiresAPlaneAnswer(t *testing.T) { + src := &fakeCommentStreamer{byID: map[string][]*types.Comment{"a-1": {comment("c1", "x")}}} + items := []*types.IssueWithCounts{row("a-1", 1)} + + if err := HydrateListComments(context.Background(), srcFunc(src), nil, items, true, true); err == nil { + t.Error("hydrating with no plane resolution returned nil, want an error: an unanswered plane defaults to a wrong-table read no caller can see") + } + if len(src.calls) != 0 { + t.Errorf("issued %d comment reads without knowing the plane, want 0", len(src.calls)) + } + // The marker path routes nothing, so it needs no answer and must not + // demand one: a caller can pass the same arguments either way. + if err := HydrateListComments(context.Background(), srcFunc(src), nil, items, false, true); err != nil { + t.Errorf("count-only mode with no plane resolution: %v", err) + } + // SourceRoutesCommentPlanes is the explicit form of "durable for everyone, + // and the source is the one that knows better". + if err := HydrateListComments(context.Background(), srcFunc(src), SourceRoutesCommentPlanes, items, true, true); err != nil { + t.Fatalf("HydrateListComments with SourceRoutesCommentPlanes: %v", err) + } + if len(src.calls) != 1 || src.calls[0].isWisp { + t.Errorf("calls = %v, want one durable-plane read: the source is left to route the id", src.calls) + } +} + +// TestHydrateListCommentsFailsWhenThePlaneIsUnknown extends hydrate-or-error to +// the routing lookup. A page that cannot find out where its rows live must not +// fall back to a guess: guessing is what returned empty comment arrays beside +// nonzero counts, and it is worse here because the failure would be invisible in +// the answer rather than reported in it. +func TestHydrateListCommentsFailsWhenThePlaneIsUnknown(t *testing.T) { + sentinel := errors.New("wisps table unreachable") + src := &fakeCommentStreamer{byID: map[string][]*types.Comment{"a-1": {comment("c1", "x")}}} + planes := planesFor() + planes.err = sentinel + items := []*types.IssueWithCounts{row("a-1", 1)} + + err := HydrateListComments(context.Background(), srcFunc(src), planes.resolve, items, true, true) + if err == nil { + t.Fatal("HydrateListComments returned nil when the comment plane could not be resolved, want an error") + } + if !errors.Is(err, sentinel) { + t.Errorf("error = %v, want it to wrap %v", err, sentinel) + } + if len(src.calls) != 0 { + t.Errorf("issued %d comment reads after the plane lookup failed, want 0: a read on a guessed plane answers with the wrong table", len(src.calls)) + } +} + +func planeName(isWisp bool) string { + if isWisp { + return "wisp" + } + return "durable" +} + +// TestHydrateListCommentsFailsRatherThanShortening pins the promise that makes +// the opt-in half trustworthy. A caller that asked for the bodies and silently +// received fewer than exist is back in the failure this whole change removes, +// with no way to detect it. +func TestHydrateListCommentsFailsRatherThanShortening(t *testing.T) { + sentinel := errors.New("comment table unreachable") + src := &fakeCommentStreamer{err: sentinel} + items := []*types.IssueWithCounts{row("a-1", 1)} + + err := HydrateListComments(context.Background(), srcFunc(src), planesFor().resolve, items, true, true) + if err == nil { + t.Fatal("HydrateListComments returned nil on a failing read, want an error: a short list a caller cannot detect is the defect, not a degraded success") + } + if !errors.Is(err, sentinel) { + t.Errorf("error = %v, want it to wrap %v", err, sentinel) + } +} + +// TestHydrateListCommentsCountOnlyToleratesNoSource pins that the default path +// needs no comment source at all, which is what lets a caller pass one +// unconditionally without deciding whether it will be used. +func TestHydrateListCommentsCountOnlyToleratesNoSource(t *testing.T) { + items := []*types.IssueWithCounts{row("a-1", 3)} + if err := HydrateListComments(context.Background(), nil, planesFor().resolve, items, false, true); err != nil { + t.Fatalf("count-only mode with a nil source: %v", err) + } + if items[0].CommentsOmitted == nil || !*items[0].CommentsOmitted { + t.Error("count-only mode with a nil source did not mark the row omitted") + } + if err := HydrateListComments(context.Background(), nil, planesFor().resolve, items, true, true); err == nil { + t.Error("hydrating with a nil source returned nil, want an error") + } +} + +// TestHydrateListCommentsSkipsNilRows keeps the shared epilogue from panicking +// on a page shape a caller can legally hand it. +func TestHydrateListCommentsSkipsNilRows(t *testing.T) { + src := &fakeCommentStreamer{byID: map[string][]*types.Comment{}} + items := []*types.IssueWithCounts{nil, {Issue: nil, CommentCount: 2}, row("a-1", 0)} + for _, include := range []bool{false, true} { + if err := HydrateListComments(context.Background(), srcFunc(src), planesFor().resolve, items, include, true); err != nil { + t.Fatalf("include=%v: %v", include, err) + } + } +} + +// TestHydrateListCommentsCountOnlyBuildsNoSource pins the laziness as a +// behaviour rather than an implementation detail. +// +// It is here because the eager version shipped and broke something: building +// the unit-of-work comment source unconditionally panicked for a provider that +// has no comment use case, on list requests that had asked for no comments. +// A count-only listing must not so much as CONSTRUCT a comment reader, so the +// constructor here fails the test if it is ever called. +func TestHydrateListCommentsCountOnlyBuildsNoSource(t *testing.T) { + built := 0 + newSrc := func() CommentStreamer { + built++ + t.Error("count-only hydration constructed a comment source; the dependency must be as opt-in as the feature") + return &fakeCommentStreamer{} + } + items := []*types.IssueWithCounts{row("a-1", 4), row("a-2", 0)} + + if err := HydrateListComments(context.Background(), newSrc, noPlaneLookup(t), items, false, true); err != nil { + t.Fatalf("HydrateListComments: %v", err) + } + if built != 0 { + t.Errorf("constructed %d comment sources in count-only mode, want 0", built) + } + if items[0].CommentsOmitted == nil || !*items[0].CommentsOmitted { + t.Error("count-only mode did not mark the row omitted") + } +} + +// TestHydrateListCommentsHonorsIncludeWhenCountsAreSkipped is the regression +// for the combination that made the count-based skip unsound. +// +// issueops.ListRequest.SkipCounts zeroes CommentCount and says in its own doc +// that a zero then means UNKNOWN. A body that reads the count as authoritative +// therefore answers IncludeComments with an entirely empty page — no error, no +// short-list marker, nothing. That is the same silent-omission failure this +// whole change exists to remove, reintroduced one layer down and reachable by +// any caller of a PUBLIC request type. +func TestHydrateListCommentsHonorsIncludeWhenCountsAreSkipped(t *testing.T) { + src := &fakeCommentStreamer{byID: map[string][]*types.Comment{ + "a-1": {comment("c1", "zzzuniquephrase")}, + }} + // Counts skipped: every row reports zero whether or not it has comments. + items := []*types.IssueWithCounts{row("a-1", 0), row("a-2", 0)} + planes := planesFor() + + if err := HydrateListComments(context.Background(), srcFunc(src), planes.resolve, items, true, false); err != nil { + t.Fatalf("HydrateListComments: %v", err) + } + + if len(src.calls) != 2 { + t.Fatalf("issued %d comment reads, want 2: with no trustworthy count, every row must be queried", len(src.calls)) + } + // The plane lookup widens with them: a page whose counts prove nothing + // cannot narrow the set whose residence has to be resolved either. + if len(planes.asked) != 1 || !slices.Equal(planes.asked[0], []string{"a-1", "a-2"}) { + t.Errorf("resolved planes for %v, want one lookup for [a-1 a-2]", planes.asked) + } + if got := len(items[0].Comments); got != 1 { + t.Fatalf("hydrated %d comments for the row that has one, want 1", got) + } + if got := items[0].Comments[0].Text; got != "zzzuniquephrase" { + t.Errorf("comment body = %q, want %q", got, "zzzuniquephrase") + } + if items[1].Comments != nil { + t.Errorf("row with genuinely no comments got %v, want nil", items[1].Comments) + } +} + +// TestHydrateListCommentsMarksNothingWhenCountsAreSkipped is the other side of +// the same unknown. CommentsOmitted asserts "this row HAS comments and they are +// not here"; a page whose counts were skipped cannot support that claim about +// any row, so it must make it about none rather than deriving it from a zero +// that means nothing. +func TestHydrateListCommentsMarksNothingWhenCountsAreSkipped(t *testing.T) { + items := []*types.IssueWithCounts{row("a-1", 0), row("a-2", 0)} + if err := HydrateListComments(context.Background(), nil, nil, items, false, false); err != nil { + t.Fatalf("HydrateListComments: %v", err) + } + for _, item := range items { + if item.CommentsOmitted != nil { + t.Errorf("%s carries comments_omitted on a page with no trustworthy counts, want unset: the marker would be a claim the page cannot support", item.ID) + } + } +} diff --git a/internal/workapi/storereader/reader.go b/internal/workapi/storereader/reader.go index bada86661..8c0c2bae1 100644 --- a/internal/workapi/storereader/reader.go +++ b/internal/workapi/storereader/reader.go @@ -127,6 +127,17 @@ func (r *storeReader) List(ctx context.Context, req issueops.ListRequest) (issue // 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 } diff --git a/issueops/reader.go b/issueops/reader.go index a5b54cf78..0a0219f52 100644 --- a/issueops/reader.go +++ b/issueops/reader.go @@ -187,6 +187,34 @@ type ListRequest struct { // hydrated there either way, which costs time and not correctness. SkipCounts bool + // IncludeComments populates every row's Issue.Comments with that issue's + // full comment bodies, and is the LIST twin of GetRequest.IncludeComments. + // Like SkipLabels and SkipCounts it chooses what is HYDRATED, never which + // rows match: the rows, their order, Parent and the has-more verdict are + // what they would have been. + // + // IT IS OPT-IN BECAUSE IT COSTS A QUERY PER ROW, which is the same reason + // the detail view's twin is. A page of 50 is 50 comment reads; a listing + // asking for the whole store is that many. Nothing hydrates comments + // unless a caller asks. + // + // WHY THE KNOB EXISTS AT ALL (be-73x). comment_count has always been on + // the row and the bodies never were, so a caller searching a LISTING for + // text that lives in a comment gets a well-formed, non-empty, WRONG answer + // — the rows that match are simply absent, and no error, no zero and no + // short count marks them. That is the failure this knob exists to make + // answerable, which is why the unhydrated rows also carry + // types.IssueWithCounts.CommentsOmitted rather than staying silent. + // + // IT APPLIES TO BOTH ARMS, ReadyFlag included, and is neither carried nor + // refused by it: hydration runs in the shared page epilogue after the + // query, so it is not a filter the ready query has to be able to express. + // + // A row whose comments could not be read is an ERROR, not a short list. + // The detail view's IncludeComments makes the same promise for the same + // reason: a caller that asked for the rows gets them or gets told. + IncludeComments bool + // Brief suppresses the FREE-FORM TEXT the way SkipLabels suppresses labels // and SkipCounts the cardinalities: Description, Design, // AcceptanceCriteria, Notes, Payload and Waiters are not selected and come