Cap embedded closing pull requests and report the total

This enrichment runs on every issue_read get, so embedding up to 25
references costs more than the common case is worth. Embed at most 5,
keeping orderByState so open pull requests are the ones that survive.

Select totalCount alongside the nodes and return the summary as an
object of total_count plus references, so the rare issue with more than
five linked pull requests cannot be read as a complete list. The common
zero-to-two case stays compact and an empty result stays definitive.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a0b58914-0d94-47a9-8229-c0ef7e32e69f

Author: zwick

README.md

@@ -911,7 +911,7 @@ The following sets of tools are available:
   - `issue_number`: The number of the issue (number, required)
   - `method`: The read operation to perform on a single issue.
     Options are:
-    1. get - Get issue details. Also returns best-effort hierarchy flags (`has_parent`, `has_children`); `parent` and `sub_issues_summary` are optional relationship summaries, and `closed_by_pull_requests` lists the pull requests configured to close the issue.
+    1. get - Get issue details. Also returns best-effort hierarchy flags (`has_parent`, `has_children`); `parent` and `sub_issues_summary` are optional relationship summaries, and `closed_by_pull_requests` summarizes the pull requests configured to close the issue as `total_count` plus up to 5 `references`.
     2. get_comments - Get issue comments.
     3. get_sub_issues - Get sub-issues (children) of the issue.
     4. get_parent - Get the parent issue, if this issue is a sub-issue of another.

pkg/github/__toolsnaps__/issue_read.snap

@@ -12,7 +12,7 @@
         "type": "number"
       },
       "method": {
-        "description": "The read operation to perform on a single issue.\nOptions are:\n1. get - Get issue details. Also returns best-effort hierarchy flags (`has_parent`, `has_children`); `parent` and `sub_issues_summary` are optional relationship summaries, and `closed_by_pull_requests` lists the pull requests configured to close the issue.\n2. get_comments - Get issue comments.\n3. get_sub_issues - Get sub-issues (children) of the issue.\n4. get_parent - Get the parent issue, if this issue is a sub-issue of another.\n5. get_labels - Get labels assigned to the issue.\n",
+        "description": "The read operation to perform on a single issue.\nOptions are:\n1. get - Get issue details. Also returns best-effort hierarchy flags (`has_parent`, `has_children`); `parent` and `sub_issues_summary` are optional relationship summaries, and `closed_by_pull_requests` summarizes the pull requests configured to close the issue as `total_count` plus up to 5 `references`.\n2. get_comments - Get issue comments.\n3. get_sub_issues - Get sub-issues (children) of the issue.\n4. get_parent - Get the parent issue, if this issue is a sub-issue of another.\n5. get_labels - Get labels assigned to the issue.\n",
         "enum": [
           "get",
           "get_comments",

pkg/github/issues.go

@@ -615,7 +615,7 @@ func IssueRead(t translations.TranslationHelperFunc) inventory.ServerTool {
 				Type: "string",
 				Description: "The read operation to perform on a single issue.\n" +
 					"Options are:\n" +
-					"1. get - Get issue details. Also returns best-effort hierarchy flags (`has_parent`, `has_children`); `parent` and `sub_issues_summary` are optional relationship summaries, and `closed_by_pull_requests` lists the pull requests configured to close the issue.\n" +
+					"1. get - Get issue details. Also returns best-effort hierarchy flags (`has_parent`, `has_children`); `parent` and `sub_issues_summary` are optional relationship summaries, and `closed_by_pull_requests` summarizes the pull requests configured to close the issue as `total_count` plus up to 5 `references`.\n" +
 					"2. get_comments - Get issue comments.\n" +
 					"3. get_sub_issues - Get sub-issues (children) of the issue.\n" +
 					"4. get_parent - Get the parent issue, if this issue is a sub-issue of another.\n" +
@@ -791,14 +791,18 @@ func applyIssueReadEnrichment(ctx context.Context, minimalIssue *MinimalIssue, e
 		}
 	}
 
-	// An empty list is meaningful here: it tells an agent that nothing is currently set up to
-	// close the issue, so it does not need to fall back to scanning pull requests.
-	closing := make([]MinimalPullRequestRef, 0, len(enrichment.ClosedByPullRequests))
+	// A zero total is meaningful here: it tells an agent that nothing is currently set up to close
+	// the issue, so it does not need to fall back to scanning pull requests. Only a few references
+	// are embedded, so total_count is what distinguishes a complete list from a truncated one.
+	closing := MinimalClosingPullRequests{
+		TotalCount: enrichment.ClosedByPullRequestsTotal,
+		References: make([]MinimalPullRequestRef, 0, len(enrichment.ClosedByPullRequests)),
+	}
 	for _, pr := range enrichment.ClosedByPullRequests {
 		if lockdownMode && !isSafeRefContent(ctx, cache, pr.Ref.Repository, pr.AuthorLogin) {
 			continue
 		}
-		closing = append(closing, pr.Ref)
+		closing.References = append(closing.References, pr.Ref)
 	}
 	minimalIssue.ClosedByPullRequests = &closing
 
@@ -1852,8 +1856,9 @@ func fetchIssueFieldValuesByNodeID(ctx context.Context, gqlClient *githubv4.Clie
 // extra round-trips.
 //
 // closedByPullRequestsReferences needs includeClosedPrs so that a merged or closed pull request
-// still explains why an issue was closed, and orderByState so that open pull requests come first
-// and survive the node cap.
+// still explains why an issue was closed, and orderByState so that open pull requests come first.
+// Only a handful of references are embedded because this enrichment runs on every issue_read `get`;
+// totalCount is selected so that a truncated list is never mistaken for the complete set.
 type issueReadEnrichmentQuery struct {
 	Nodes []struct {
 		Issue struct {
@@ -1874,7 +1879,8 @@ type issueReadEnrichmentQuery struct {
 				}
 			}
 			ClosedByPullRequestsReferences struct {
-				Nodes []struct {
+				TotalCount githubv4.Int
+				Nodes      []struct {
 					Number githubv4.Int
 					Title  githubv4.String
 					State  githubv4.String
@@ -1886,7 +1892,7 @@ type issueReadEnrichmentQuery struct {
 						NameWithOwner githubv4.String
 					}
 				}
-			} `graphql:"closedByPullRequestsReferences(first: 25, includeClosedPrs: true, orderByState: true)"`
+			} `graphql:"closedByPullRequestsReferences(first: 5, includeClosedPrs: true, orderByState: true)"`
 			SubIssuesSummary struct {
 				Total            githubv4.Int
 				Completed        githubv4.Int
@@ -1912,10 +1918,11 @@ type issueReadClosingPullRequest struct {
 
 // issueReadEnrichment is the flattened result of the issue_read `get` enrichment query.
 type issueReadEnrichment struct {
-	FieldValues          []MinimalFieldValue
-	Parent               *issueReadParent
-	ClosedByPullRequests []issueReadClosingPullRequest
-	SubIssuesSummary     MinimalSubIssuesSummary
+	FieldValues               []MinimalFieldValue
+	Parent                    *issueReadParent
+	ClosedByPullRequests      []issueReadClosingPullRequest
+	ClosedByPullRequestsTotal int
+	SubIssuesSummary          MinimalSubIssuesSummary
 }
 
 // fetchIssueReadEnrichment runs one GraphQL nodes() query for the given issue node ID and returns
@@ -1969,6 +1976,7 @@ func fetchIssueReadEnrichment(ctx context.Context, gqlClient *githubv4.Client, n
 			})
 		}
 		enrichment.ClosedByPullRequests = closing
+		enrichment.ClosedByPullRequestsTotal = int(n.Issue.ClosedByPullRequestsReferences.TotalCount)
 
 		enrichment.SubIssuesSummary = MinimalSubIssuesSummary{
 			Total:            int(n.Issue.SubIssuesSummary.Total),

pkg/github/issues_test.go

@@ -49,7 +49,7 @@ func newRepoAccessHTTPClient() *http.Client {
 	return &http.Client{Transport: &repoAccessMockTransport{responses: responses}}
 }
 
-const issueReadEnrichmentQueryString = "query($ids:[ID!]!){nodes(ids: $ids){... on Issue{id,issueFieldValues(first: 25){nodes{__typename,... on IssueFieldDateValue{field{... on IssueFieldDate{name,fullDatabaseId},... on IssueFieldNumber{name,fullDatabaseId},... on IssueFieldSingleSelect{name,fullDatabaseId},... on IssueFieldText{name,fullDatabaseId}},value},... on IssueFieldNumberValue{field{... on IssueFieldDate{name,fullDatabaseId},... on IssueFieldNumber{name,fullDatabaseId},... on IssueFieldSingleSelect{name,fullDatabaseId},... on IssueFieldText{name,fullDatabaseId}},valueNumber: value},... on IssueFieldSingleSelectValue{field{... on IssueFieldDate{name,fullDatabaseId},... on IssueFieldNumber{name,fullDatabaseId},... on IssueFieldSingleSelect{name,fullDatabaseId},... on IssueFieldText{name,fullDatabaseId}},value},... on IssueFieldTextValue{field{... on IssueFieldDate{name,fullDatabaseId},... on IssueFieldNumber{name,fullDatabaseId},... on IssueFieldSingleSelect{name,fullDatabaseId},... on IssueFieldText{name,fullDatabaseId}},value}}},parent{number,title,state,url,author{login},repository{nameWithOwner}},closedByPullRequestsReferences(first: 25, includeClosedPrs: true, orderByState: true){nodes{number,title,state,url,author{login},repository{nameWithOwner}}},subIssuesSummary{total,completed,percentCompleted}}}}"
+const issueReadEnrichmentQueryString = "query($ids:[ID!]!){nodes(ids: $ids){... on Issue{id,issueFieldValues(first: 25){nodes{__typename,... on IssueFieldDateValue{field{... on IssueFieldDate{name,fullDatabaseId},... on IssueFieldNumber{name,fullDatabaseId},... on IssueFieldSingleSelect{name,fullDatabaseId},... on IssueFieldText{name,fullDatabaseId}},value},... on IssueFieldNumberValue{field{... on IssueFieldDate{name,fullDatabaseId},... on IssueFieldNumber{name,fullDatabaseId},... on IssueFieldSingleSelect{name,fullDatabaseId},... on IssueFieldText{name,fullDatabaseId}},valueNumber: value},... on IssueFieldSingleSelectValue{field{... on IssueFieldDate{name,fullDatabaseId},... on IssueFieldNumber{name,fullDatabaseId},... on IssueFieldSingleSelect{name,fullDatabaseId},... on IssueFieldText{name,fullDatabaseId}},value},... on IssueFieldTextValue{field{... on IssueFieldDate{name,fullDatabaseId},... on IssueFieldNumber{name,fullDatabaseId},... on IssueFieldSingleSelect{name,fullDatabaseId},... on IssueFieldText{name,fullDatabaseId}},value}}},parent{number,title,state,url,author{login},repository{nameWithOwner}},closedByPullRequestsReferences(first: 5, includeClosedPrs: true, orderByState: true){totalCount,nodes{number,title,state,url,author{login},repository{nameWithOwner}}},subIssuesSummary{total,completed,percentCompleted}}}}"
 
 // newIssueReadEnrichmentMatcher builds a matcher for the issue_read `get` enrichment query for a
 // single issue node ID.
@@ -822,7 +822,8 @@ func Test_GetIssue_ClosedByPullRequests(t *testing.T) {
 	tests := []struct {
 		name           string
 		closingPRs     []map[string]any
-		assertResponse func(t *testing.T, refs []MinimalPullRequestRef)
+		totalCount     int
+		assertResponse func(t *testing.T, closing MinimalClosingPullRequests)
 	}{
 		{
 			name: "closing pull requests are returned as compact references",
@@ -844,27 +845,40 @@ func Test_GetIssue_ClosedByPullRequests(t *testing.T) {
 					"repository": map[string]any{"nameWithOwner": "fork-owner/repo"},
 				},
 			},
-			assertResponse: func(t *testing.T, refs []MinimalPullRequestRef) {
-				require.Len(t, refs, 2)
+			totalCount: 2,
+			assertResponse: func(t *testing.T, closing MinimalClosingPullRequests) {
+				assert.Equal(t, 2, closing.TotalCount)
+				require.Len(t, closing.References, 2)
 				assert.Equal(t, MinimalPullRequestRef{
 					Number:     4242,
 					Title:      "Fix the broken thing",
 					State:      "OPEN",
 					URL:        "https://github.com/owner/repo/pull/4242",
 					Repository: "owner/repo",
-				}, refs[0])
+				}, closing.References[0])
 				// Closed and cross-repository pull requests are kept: they still explain what
 				// is (or was) set up to close the issue.
-				assert.Equal(t, 77, refs[1].Number)
-				assert.Equal(t, "CLOSED", refs[1].State)
-				assert.Equal(t, "fork-owner/repo", refs[1].Repository)
+				assert.Equal(t, 77, closing.References[1].Number)
+				assert.Equal(t, "CLOSED", closing.References[1].State)
+				assert.Equal(t, "fork-owner/repo", closing.References[1].Repository)
 			},
 		},
 		{
-			name:       "no closing pull requests yields an explicit empty list",
+			name:       "no closing pull requests yields an explicit zero total",
 			closingPRs: []map[string]any{},
-			assertResponse: func(t *testing.T, refs []MinimalPullRequestRef) {
-				assert.Empty(t, refs)
+			totalCount: 0,
+			assertResponse: func(t *testing.T, closing MinimalClosingPullRequests) {
+				assert.Equal(t, 0, closing.TotalCount)
+				assert.Empty(t, closing.References)
+			},
+		},
+		{
+			name:       "total count exceeding the embedded references marks the list as truncated",
+			closingPRs: closingPullRequestFixtures(5),
+			totalCount: 9,
+			assertResponse: func(t *testing.T, closing MinimalClosingPullRequests) {
+				require.Len(t, closing.References, 5, "at most five references are embedded")
+				assert.Equal(t, 9, closing.TotalCount, "total_count must report the full set so a truncated list is not read as complete")
 			},
 		},
 		{
@@ -879,9 +893,10 @@ func Test_GetIssue_ClosedByPullRequests(t *testing.T) {
 					"repository": map[string]any{"nameWithOwner": "owner/repo"},
 				},
 			},
-			assertResponse: func(t *testing.T, refs []MinimalPullRequestRef) {
-				require.Len(t, refs, 1)
-				assert.Equal(t, "Fix the thing", refs[0].Title)
+			totalCount: 1,
+			assertResponse: func(t *testing.T, closing MinimalClosingPullRequests) {
+				require.Len(t, closing.References, 1)
+				assert.Equal(t, "Fix the thing", closing.References[0].Title)
 			},
 		},
 	}
@@ -898,7 +913,7 @@ func Test_GetIssue_ClosedByPullRequests(t *testing.T) {
 						"id":                             "I_node_2990",
 						"issueFieldValues":               map[string]any{"nodes": []map[string]any{}},
 						"parent":                         nil,
-						"closedByPullRequestsReferences": map[string]any{"nodes": tc.closingPRs},
+						"closedByPullRequestsReferences": map[string]any{"totalCount": tc.totalCount, "nodes": tc.closingPRs},
 						"subIssuesSummary":               map[string]any{"total": 0, "completed": 0, "percentCompleted": 0},
 					},
 				},
@@ -928,7 +943,7 @@ func Test_GetIssue_ClosedByPullRequests(t *testing.T) {
 			require.False(t, result.IsError, "expected result to not be an error")
 
 			text := getTextResult(t, result).Text
-			assert.Contains(t, text, `"closed_by_pull_requests"`, "the key must always be present on an enriched issue so an empty list is a definitive answer")
+			assert.Contains(t, text, `"closed_by_pull_requests"`, "the key must always be present on an enriched issue so a zero total is a definitive answer")
 
 			var returnedIssue MinimalIssue
 			require.NoError(t, json.Unmarshal([]byte(text), &returnedIssue))
@@ -938,6 +953,23 @@ func Test_GetIssue_ClosedByPullRequests(t *testing.T) {
 	}
 }
 
+// closingPullRequestFixtures builds n distinct closing pull request nodes for the GraphQL mock.
+func closingPullRequestFixtures(n int) []map[string]any {
+	prs := make([]map[string]any, 0, n)
+	for i := range n {
+		number := 4242 + i
+		prs = append(prs, map[string]any{
+			"number":     number,
+			"title":      fmt.Sprintf("Candidate fix %d", number),
+			"state":      "OPEN",
+			"url":        fmt.Sprintf("https://github.com/owner/repo/pull/%d", number),
+			"author":     map[string]any{"login": "author"},
+			"repository": map[string]any{"nameWithOwner": "owner/repo"},
+		})
+	}
+	return prs
+}
+
 func Test_GetIssue_ClosedByPullRequests_Lockdown(t *testing.T) {
 	mockIssue := &github.Issue{
 		Number:  github.Ptr(2990),
@@ -962,6 +994,7 @@ func Test_GetIssue_ClosedByPullRequests_Lockdown(t *testing.T) {
 				"issueFieldValues": map[string]any{"nodes": []map[string]any{}},
 				"parent":           nil,
 				"closedByPullRequestsReferences": map[string]any{
+					"totalCount": 2,
 					"nodes": []map[string]any{
 						{
 							"number":     4242,
@@ -1013,8 +1046,9 @@ func Test_GetIssue_ClosedByPullRequests_Lockdown(t *testing.T) {
 	require.NoError(t, json.Unmarshal([]byte(getTextResult(t, result).Text), &returnedIssue))
 
 	require.NotNil(t, returnedIssue.ClosedByPullRequests)
-	require.Len(t, *returnedIssue.ClosedByPullRequests, 1, "unverified pull request references should be filtered out under lockdown")
-	assert.Equal(t, 4242, (*returnedIssue.ClosedByPullRequests)[0].Number)
+	require.Len(t, returnedIssue.ClosedByPullRequests.References, 1, "unverified pull request references should be filtered out under lockdown")
+	assert.Equal(t, 4242, returnedIssue.ClosedByPullRequests.References[0].Number)
+	assert.Equal(t, 2, returnedIssue.ClosedByPullRequests.TotalCount, "total_count reports what GitHub linked, so a filtered list is not read as complete")
 }
 
 func Test_SearchIssues(t *testing.T) {

pkg/github/minimal_types.go

@@ -485,11 +485,19 @@ type MinimalIssue struct {
 	Parent           *MinimalIssueRef         `json:"parent,omitempty"`
 	SubIssuesSummary *MinimalSubIssuesSummary `json:"sub_issues_summary,omitempty"`
 
-	// ClosedByPullRequests lists the pull requests configured to close this issue. It is a
-	// pointer so that an enriched issue with no such pull requests serializes as an explicit
-	// empty list, which is a definitive "nothing will close this issue" answer, while issues
-	// returned by paths that never run the enrichment omit the key entirely.
-	ClosedByPullRequests *[]MinimalPullRequestRef `json:"closed_by_pull_requests,omitempty"`
+	// ClosedByPullRequests summarizes the pull requests configured to close this issue. It is a
+	// pointer so that an enriched issue with no such pull requests still serializes a definitive
+	// "nothing will close this issue" answer, while issues returned by paths that never run the
+	// enrichment omit the key entirely.
+	ClosedByPullRequests *MinimalClosingPullRequests `json:"closed_by_pull_requests,omitempty"`
+}
+
+// MinimalClosingPullRequests summarizes the pull requests configured to close an issue.
+// References is capped, so TotalCount is authoritative: when it exceeds the number of
+// references the list is a truncated view rather than the complete set.
+type MinimalClosingPullRequests struct {
+	TotalCount int                     `json:"total_count"`
+	References []MinimalPullRequestRef `json:"references"`
 }
 
 // MinimalPullRequestRef is a compact reference to a related pull request.