@gitkraken/core-gitlens 0.5.103 → 0.5.105

package/src/plus/integrations/reads/counts.ts

@@ -0,0 +1,285 @@
+import type { IssueSearchCriteria } from '../../../git/models/issue.js';
+import { chunk } from '../../../utils/array.js';
+import { mapBounded } from '../../../utils/promise.js';
+import type { IntegrationIds } from '../constants.js';
+import { providerFanOutConcurrency } from '../constants.js';
+import type { ProviderRepoInput, ProviderReposInput } from '../providers/models.js';
+import { providersMetadata } from '../providers/models.js';
+import type { ProviderResult, ProviderWarning } from '../results.js';
+import { appendDedupedWarning } from '../results.js';
+import {
+	isGitHostIntegration,
+	isIssuesHostIntegrationId,
+	warnOnMissingSessionForDomain,
+} from '../utils/integration.utils.js';
+import type { ProviderReadContext } from './context.js';
+import { runCaptured } from './drains.js';
+import { resolveIssueSearchCriteria, resolveIssueSearchScope } from './filters.js';
+import {
+	gitHostOnlySurfaceWarning,
+	issuesUnsupportedWarning,
+	otherWarning,
+	unsupportedIssueSearchCriteriaWarning,
+} from './warnings.js';
+
+/**
+ * How many scopes go into one upstream request.
+ *
+ * Measured against the live GitHub API, 30 aliased counts cost a single rate-limit point and ~2s, and 60 cost the
+ * same point and roughly twice as long — so the constraint isn't rate limit, it's latency and the provider's
+ * (uncontracted, so not to be leaned on) query-complexity limits. 25 keeps a chunk comfortably inside both while
+ * still collapsing a realistic filter matrix into one or two requests.
+ */
+const issueCountChunkSize = 25;
+
+/**
+ * One scope to count.
+ *
+ * `key` is caller-owned and echoed back verbatim, so a batch result needs no positional matching by the consumer.
+ * It never reaches the provider query — the aliases in the upstream document are generated — so it can be any
+ * string the caller finds meaningful.
+ */
+export interface IssueCountScope {
+	key: string;
+	/** Repositories to count over. Combines with `org`, exactly as in `searchIssuesPage`. */
+	repos?: ProviderReposInput;
+	org?: string;
+	/** Same criteria model as `searchIssuesPage`, validated against the same capability table. */
+	criteria?: IssueSearchCriteria;
+}
+
+/** The count for one {@link IssueCountScope}, echoed back under the caller's own `key`. */
+export interface IssueCountResult {
+	key: string;
+	/**
+	 * Total matches the provider reports. `undefined` when the provider didn't report one for this scope — NEVER
+	 * zero, which is a real answer. Render the difference: an unreported count means "unknown", and showing it as
+	 * 0 would tell the user this filter matches nothing.
+	 */
+	count?: number;
+	/**
+	 * True when `count` exceeds the provider's own result ceiling, so a full read CANNOT return everything no
+	 * matter how it is paged. This is the signal to warn before starting an expensive fetch.
+	 */
+	exceedsProviderLimit: boolean;
+	/** The ceiling itself, when the provider declares one. */
+	providerLimit?: number;
+}
+
+/**
+ * Counts issues for many scopes without fetching any — the probe behind a "this will fetch ~N issues" preview.
+ *
+ * A distinct method rather than a `countOnly` flag on `searchIssuesPage`, because transferring ZERO issues is the
+ * entire value: a flag would return a paged result whose `items`, `cursor` and `hasMore` are all meaningless, and
+ * every consumer would have to know which fields to ignore. A separate method has a return type that only
+ * describes counts.
+ *
+ * Scopes are batched into as few upstream requests as possible ({@link issueCountChunkSize} each). A chunk that
+ * fails warns and drops only its own scopes, leaving the successful chunks' counts intact — so a partial answer is
+ * still useful — with `fetchFailed` set. A scope refused for its own reasons (unscoped, inexpressible criteria) is
+ * likewise isolated: its siblings are still counted.
+ *
+ * Cheap is not free: each chunk is a network request, so a caller driving this from UI state is expected to
+ * debounce and cache.
+ */
+export async function countIssues(
+	ctx: ProviderReadContext,
+	options: {
+		providerId: IntegrationIds;
+		scopes: readonly IssueCountScope[];
+		connectionId?: string;
+		/**
+		 * Explicit self-managed host domain. Used only when the requested connection has no configured domain;
+		 * it must come from the trusted authentication configuration, not repository or remote data.
+		 */
+		domain?: string;
+	},
+): Promise<ProviderResult<IssueCountResult>> {
+	const refused = (warning: ProviderWarning): ProviderResult<IssueCountResult> => ({
+		items: [],
+		warnings: [warning],
+		fetchFailed: true,
+	});
+
+	if (isIssuesHostIntegrationId(options.providerId)) {
+		return refused(gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'Issue counts'));
+	}
+
+	// Nothing was asked for, so nothing is missing: an empty success, not a refusal.
+	if (options.scopes.length === 0) return { items: [], warnings: [] };
+
+	const duplicateKey = findDuplicateKey(options.scopes);
+	if (duplicateKey != null) {
+		// Refuses the whole call rather than deduping: `key` exists so the caller can match results without
+		// positional bookkeeping, and two results under one key make that ambiguous for EVERY scope, not just the
+		// repeated one.
+		return refused(
+			otherWarning(
+				options.providerId,
+				undefined,
+				options.connectionId,
+				`Duplicate issue count scope key '${duplicateKey}'; keys identify results, so each must be unique.`,
+			),
+		);
+	}
+
+	const integration = await ctx.getIntegrationForRead(options.providerId, options.connectionId, options.domain);
+	if (integration == null) {
+		// A supplied connection or domain that no longer resolves is a broken target, not an empty account.
+		const early = ctx.earlyReturnConnectionWarnings(options.providerId, options.connectionId, options.domain);
+		return { items: [], warnings: early.warnings, fetchFailed: early.fetchFailed || undefined };
+	}
+	if (!isGitHostIntegration(integration)) {
+		return refused(gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'Issue counts'));
+	}
+
+	const domain = ctx.domainForRead(integration, options.providerId, options.connectionId, options.domain);
+	const warnOnMissingSession = warnOnMissingSessionForDomain(options.providerId, options.domain);
+
+	if (!integration.supportsIssues) {
+		return refused(issuesUnsupportedWarning(options.providerId, domain, options.connectionId));
+	}
+
+	const providerLimit = providersMetadata[options.providerId]?.issueSearchResultLimit;
+	const warnings: ProviderWarning[] = [];
+	let fetchFailed = false;
+
+	// Validate every scope first, so a refusal costs no request at all and the countable ones are still batched
+	// together.
+	const countable: IssueCountScope[] = [];
+	for (const scope of options.scopes) {
+		const warning = rejectScope(options.providerId, domain, options.connectionId, scope);
+		if (warning != null) {
+			// `push`, not `appendDedupedWarning`: every rejection message embeds the scope's own key, and duplicate
+			// keys were already refused above, so no two of these can ever collapse — deduping them would only pay
+			// the O(n²) key comparison to prove it.
+			warnings.push(warning);
+			fetchFailed = true;
+			continue;
+		}
+
+		countable.push(scope);
+	}
+
+	// Chunks are independent requests over their own slice of scopes — nothing in one reads what another produced,
+	// and `runCaptured` never throws — so they run concurrently, bounded like every other fan-out on the facade.
+	// Sequentially they would spend exactly the resource this probe is tuned to conserve: latency, ~2s per chunk.
+	// `mapBounded` returns in input order, so `items` and `warnings` stay in scope order.
+	const batches = await mapBounded(chunk(countable, issueCountChunkSize), providerFanOutConcurrency, batch =>
+		runCaptured(
+			options.providerId,
+			domain,
+			options.connectionId,
+			() =>
+				integration.countIssuesResult(
+					batch.map(s => ({
+						repos: s.repos as ProviderRepoInput[] | undefined,
+						org: s.org,
+						criteria: s.criteria,
+					})),
+					undefined,
+					options.connectionId,
+				),
+			{ warnOnMissingSession: warnOnMissingSession },
+		).then(result => ({ batch: batch, ...result })),
+	);
+
+	const items: IssueCountResult[] = [];
+	for (const { batch, value, warning } of batches) {
+		if (warning != null) {
+			appendDedupedWarning(warnings, warning);
+		}
+		if (value == null) {
+			// This batch contributes nothing, but the batches around it still do. Drop only these scopes.
+			fetchFailed = true;
+			continue;
+		}
+
+		for (let i = 0; i < batch.length; i++) {
+			const count = value[i];
+			items.push({
+				key: batch[i].key,
+				count: count,
+				// Only a reported count can exceed a declared ceiling; unknown-vs-limit is not a comparison.
+				exceedsProviderLimit: count != null && providerLimit != null && count > providerLimit,
+				providerLimit: providerLimit,
+			});
+		}
+	}
+
+	// A provider with no count support returns `undefined` with no error, which lands as an empty `items` and no
+	// warning. Say so explicitly rather than letting it read as "every scope matched nothing".
+	if (items.length === 0 && warnings.length === 0) {
+		return refused(
+			unsupportedIssueSearchCriteriaWarning(options.providerId, domain, options.connectionId, {
+				reason: 'unsupported-search',
+			}),
+		);
+	}
+
+	return { items: items, warnings: warnings, fetchFailed: fetchFailed || undefined };
+}
+
+/** The first key that appears twice, or `undefined` when every key is unique. */
+function findDuplicateKey(scopes: readonly IssueCountScope[]): string | undefined {
+	const seen = new Set<string>();
+	for (const scope of scopes) {
+		if (seen.has(scope.key)) return scope.key;
+
+		seen.add(scope.key);
+	}
+	return undefined;
+}
+
+/**
+ * Why one scope can't be counted, as the warning to report — or `undefined` when it can.
+ *
+ * The scope and criteria rules come from {@link resolveIssueSearchScope} / {@link resolveIssueSearchCriteria},
+ * the same validators `searchIssuesPage` uses, so a count always previews the constraints the read would apply.
+ * That is not cosmetic: a count computed under different constraints is a WRONG number rather than a missing
+ * one, which is worse. Only the wording is local, because these name the offending scope's key.
+ */
+function rejectScope(
+	providerId: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	scope: IssueCountScope,
+): ProviderWarning | undefined {
+	const scoping = resolveIssueSearchScope(scope.repos, scope.org, scope.criteria);
+	switch (scoping.rejection) {
+		case 'repo-ids':
+			return otherWarning(
+				providerId,
+				domain,
+				connectionId,
+				`Issue count scope '${scope.key}' cannot be scoped by repository id; pass repository descriptors (namespace + name) instead.`,
+			);
+		case 'unscoped':
+			return otherWarning(
+				providerId,
+				domain,
+				connectionId,
+				`Issue count scope '${scope.key}' is unscoped; pass \`repos\`, \`org\`, or a relationship to the current user. \`any-assignee\` and \`unassigned\` are not scopes.`,
+			);
+	}
+
+	const resolved = resolveIssueSearchCriteria(providerId, scope.criteria);
+	if (resolved.rejection != null) {
+		return unsupportedIssueSearchCriteriaWarning(providerId, domain, connectionId, resolved.rejection);
+	}
+
+	// Count-only, with no counterpart in the read: a relationship set is an OR across several searches, which one
+	// count can't express — summing them would double-count anything matching two, and taking the max would
+	// under-report. Rather than answer with a wrong number, ask the caller to count each relationship as its own
+	// scope, where the keys make the OR explicit.
+	if ((scope.criteria?.relationships?.length ?? 0) > 1) {
+		return otherWarning(
+			providerId,
+			domain,
+			connectionId,
+			`Issue count scope '${scope.key}' requests several relationships, which a single count can't express (they are OR-ed, so overlapping matches would be double-counted); pass one scope per relationship.`,
+		);
+	}
+
+	return undefined;
+}

package/src/plus/integrations/reads/filters.ts

@@ -1,5 +1,12 @@
 import type { IntegrationIds } from '../constants.js';
-import type { IssueFilter, PullRequestFilter } from '../providerFilters.js';
+import type {
+	IssueFilter,
+	IssueSearchCapabilities,
+	IssueSearchCriteria,
+	IssueSearchRelationship,
+	PullRequestFilter,
+} from '../providerFilters.js';
+import type { ProviderRepoInput, ProviderReposInput } from '../providers/models.js';
 import { providersMetadata } from '../providers/models.js';
 
 /**
@@ -79,6 +86,139 @@ export function resolveAccountWideIssueFilters(
 	return { filters: filters, unsupported: false };
 }
 
+/** Why {@link resolveIssueSearchCriteria} refused a criteria set, so the caller can word the refusal exactly. */
+export type IssueSearchCriteriaRejection =
+	/** The provider has no filtered issue search at all. */
+	| { reason: 'unsupported-search' }
+	/** The provider has one, but can't express these criteria server-side. */
+	| { reason: 'unsupported-criteria'; criteria: string[] }
+	/** `any-assignee` and `unassigned` partition the scope between them; asking for both asks for nothing. */
+	| { reason: 'contradictory-relationships' };
+
+/**
+ * Validates a filtered issue search's criteria against {@link ProviderMetadata.supportedIssueSearch}.
+ *
+ * All-or-nothing like its three siblings above, and for the same reason: a criterion dropped because the
+ * provider can't express it would serve a WIDER result than was asked for, and narrowing the returned page
+ * afterward would leave `items` describing a different result set than the `hasMore`/`cursor` the provider
+ * produced with it. So an inexpressible set is refused whole and the caller surfaces a warning.
+ *
+ * Unlike the sibling validators this also rejects a set that is internally contradictory, because this criteria
+ * model is the only one with two members that partition the scope between them (`any-assignee` ∪ `unassigned` =
+ * everything, ∩ = nothing). Silently keeping one would answer a question the caller didn't ask.
+ *
+ * `undefined` (or an empty relationship list plus no other criterion) is a valid UNNARROWED search of the given
+ * scope, not an error — the caller's `repos`/`org` is what bounds it.
+ */
+export function resolveIssueSearchCriteria(
+	id: IntegrationIds,
+	criteria: IssueSearchCriteria | undefined,
+): { rejection?: IssueSearchCriteriaRejection } {
+	const supported = providersMetadata[id]?.supportedIssueSearch;
+	if (supported == null) return { rejection: { reason: 'unsupported-search' } };
+	if (criteria == null) return {};
+
+	const relationships = criteria.relationships;
+	if (relationships?.includes('any-assignee') && relationships.includes('unassigned')) {
+		return { rejection: { reason: 'contradictory-relationships' } };
+	}
+
+	const unsupported: string[] = [];
+	for (const relationship of relationships ?? []) {
+		if (!supported.relationships.includes(relationship)) {
+			unsupported.push(`relationships:${relationship}`);
+		}
+	}
+	// Only a criterion the caller actually SET can be unsupported. `false`/empty means "don't narrow on this",
+	// which every provider can honor by doing nothing, so it must not be validated as a request.
+	if (criteria.text != null && criteria.text.trim().length > 0 && !supported.text) {
+		unsupported.push('text');
+	}
+	if (criteria.labels?.length && !supported.labels) {
+		unsupported.push('labels');
+	}
+	if (criteria.milestone != null && !supported.milestone) {
+		unsupported.push('milestone');
+	}
+	if (criteria.updatedAfter != null && !supported.updatedAfter) {
+		unsupported.push('updatedAfter');
+	}
+	if (criteria.createdAfter != null && !supported.createdAfter) {
+		unsupported.push('createdAfter');
+	}
+	if (criteria.withoutLinkedPullRequest === true && !supported.withoutLinkedPullRequest) {
+		unsupported.push('withoutLinkedPullRequest');
+	}
+	// `'open'` is every provider's own default, so asking for it needs no state capability.
+	if (criteria.state != null && criteria.state !== 'open' && !supported.states) {
+		unsupported.push('state');
+	}
+
+	if (unsupported.length > 0) return { rejection: { reason: 'unsupported-criteria', criteria: unsupported } };
+
+	return {};
+}
+
+/**
+ * The relationships that bound a filtered issue search to the CURRENT USER, and so can stand in for a
+ * repository/org scope.
+ *
+ * Derived from the union rather than spelled out per call site, because the distinction it encodes is the whole
+ * reason the scope rule exists: `any-assignee` and `unassigned` are deliberately absent — they describe the
+ * ISSUE, not the caller, so neither reduces the search to anyone's own world (measured: unscoped `no:assignee`
+ * matches ~45 million issues on GitHub).
+ */
+const userScopingIssueSearchRelationships: readonly IssueSearchRelationship[] = ['authored', 'assigned', 'mentioned'];
+
+/** What a provider with NO filtered issue search reports: nothing expressible, spelled out rather than absent. */
+const unsupportedIssueSearchCapabilities: IssueSearchCapabilities = {
+	relationships: [],
+	text: false,
+	labels: false,
+	milestone: false,
+	updatedAfter: false,
+	createdAfter: false,
+	withoutLinkedPullRequest: false,
+	states: false,
+};
+
+/** Why a filtered issue search's scope was refused, or `undefined` when it is usable. */
+export type IssueSearchScopeRejection =
+	/** No repositories, no org, and no user-relative relationship: a search of the whole host. */
+	| 'unscoped'
+	/** Repositories given as ids. A search names repositories by PATH, so ids can't express a scope. */
+	| 'repo-ids';
+
+/**
+ * Validates that a filtered issue search is scoped at all, and narrows `repos` to the descriptor form the
+ * provider query needs.
+ *
+ * Shared by `searchIssuesPage` and `countIssues` because a count computed under different constraints than the
+ * read it previews is a WRONG number rather than a missing one. The rejection is returned as a reason code, not a
+ * warning: the two callers word it differently (whole-read vs naming the offending scope's key), and wording is
+ * the warning layer's business.
+ *
+ * The two rejections are mutually exclusive — `repo-ids` requires repositories and `unscoped` requires none — so
+ * the order they're checked in cannot change the outcome.
+ */
+export function resolveIssueSearchScope(
+	repos: ProviderReposInput | undefined,
+	org: string | undefined,
+	criteria: IssueSearchCriteria | undefined,
+): { rejection?: IssueSearchScopeRejection; repos?: ProviderRepoInput[] } {
+	if (repos?.length) {
+		// `ProviderReposInput` is a union of descriptor and id arrays; only the descriptor form is usable here.
+		if (repos.some(r => typeof r === 'string' || typeof r === 'number')) return { rejection: 'repo-ids' };
+
+		return { repos: repos as ProviderRepoInput[] };
+	}
+
+	if (org != null && org.length > 0) return {};
+	if (criteria?.relationships?.some(r => userScopingIssueSearchRelationships.includes(r)) === true) return {};
+
+	return { rejection: 'unscoped' };
+}
+
 /**
  * The filters `listPullRequestsPage`/`listIssuesPage` (and the sweeps) accept for a provider, so a caller can
  * narrow to what the provider can express BEFORE issuing the read.
@@ -103,6 +243,11 @@ export function resolveAccountWideIssueFilters(
  * {@link IntegrationService.listIssueTrackerIssuesPage} validates against, and leaves `issuesAccountWide`
  * empty. Reading a tracker's capability off `issuesAccountWide` therefore under-reports it.
  *
+ * `issueSearch` is a third, wider surface: the FILTERED issue search (`searchIssuesPage`, and the `countIssues`
+ * probe over the same criteria), which is not bound to the user at all. It is a record of per-criterion flags
+ * rather than a list, because its criteria aren't a single kind. An empty `relationships` means the provider has
+ * no filtered issue search — hide the surface, not just its chips.
+ *
  * Note this is a CAPABILITY table — "what the provider can express" — not a recommendation. A consumer
  * matching another tool's behavior may deliberately pass fewer filters than are listed here (or none, where an
  * already-scoped read would only be narrowed by them). Intersecting against this table is what keeps a
@@ -113,12 +258,28 @@ export function getSupportedFilters(providerId: IntegrationIds): {
 	pullRequestsAccountWide: PullRequestFilter[];
 	issues: IssueFilter[];
 	issuesAccountWide: IssueFilter[];
+	issueSearch: IssueSearchCapabilities;
 } {
 	const metadata = providersMetadata[providerId];
+	const issueSearch = metadata?.supportedIssueSearch;
 	return {
 		pullRequests: [...(metadata?.supportedPullRequestFilters ?? [])],
 		pullRequestsAccountWide: [...(metadata?.supportedAccountWidePullRequestFilters ?? [])],
 		issues: [...(metadata?.supportedIssueFilters ?? [])],
 		issuesAccountWide: [...(metadata?.supportedAccountWideIssueFilters ?? [])],
+		// Always an object, never `undefined`: a provider WITHOUT a filtered issue search reports one whose
+		// `relationships` is empty and whose flags are all false, so a consumer reads capabilities the same way
+		// for every provider (and an empty `relationships` is the signal to hide the surface itself).
+		//
+		// Spread over the all-false baseline rather than defaulting each flag: a criterion added to
+		// `IssueSearchCapabilities` then can't be forgotten here and silently reported as `undefined` (which a
+		// consumer's `if (caps.x)` would read as unsupported — right answer, wrong reason, and untyped).
+		// `supportedIssueSearch` is typed as the complete shape, so no member can arrive as an explicit undefined.
+		issueSearch: {
+			...unsupportedIssueSearchCapabilities,
+			...issueSearch,
+			// Copied, so mutating the result can't corrupt the metadata table.
+			relationships: [...(issueSearch?.relationships ?? [])],
+		},
 	};
 }

package/src/plus/integrations/reads/issues.ts

@@ -6,7 +6,7 @@ import type { IssueFilter, ProviderReposInput } from '../providers/models.js';
 import { PagingMode, providersMetadata } from '../providers/models.js';
 import { mergeCollectionMetadata } from '../providers/utils/providerPaging.js';
 import type { ProviderPagedResult, ProviderWarning } from '../results.js';
-import { appendDedupedWarning, reconcileOmissionsWithFailure } from '../results.js';
+import { reconcileOmissionsWithFailure } from '../results.js';
 import {
 	isGitHostIntegration,
 	isIssuesHostIntegrationId,
@@ -16,6 +16,7 @@ import type { ProviderReadContext } from './context.js';
 import { runCaptured } from './drains.js';
 import { resolveAccountWideIssueFilters } from './filters.js';
 import {
+	drainFlatPagesToRequestedPage,
 	drainToRequestedPage,
 	isPageNumberAdvanceable,
 	pageToCursor,
@@ -121,6 +122,11 @@ export async function listIssuesPage(
 			);
 		}
 
+		// GitHub expresses "any assignee" as `assignee:*`, which is meaningless without a scope: unscoped it
+		// matches millions of issues across all of GitHub instead of the user's own world. ANY scope makes it
+		// meaningful (one repository, several, or an org) — it is specifically THIS branch, the account-wide read,
+		// that has none to offer. Scope the read to repositories (or use `searchIssuesPage`, whose criteria model
+		// takes `any-assignee` alongside a `repos`/`org` scope) rather than reading unscoped.
 		if (
 			options.includeAllAssignees === true &&
 			(options.providerId === GitCloudHostIntegrationId.GitHub ||
@@ -185,51 +191,22 @@ export async function listIssuesPage(
 				{ warnOnMissingSession: warnOnMissingSession },
 			);
 		const first = await readAccountWidePage(options.cursor);
-		let value = first.value;
 		const warnings = first.warning != null ? [first.warning] : [];
-		let allMetadata = value?.metadata;
-		let pageFetchFailed = first.warning != null && value == null;
-		let currentPage = value?.page ?? 1;
-		let currentTruncated = value?.truncated ?? false;
-		let requestedPageMissing = false;
-		if (options.cursor == null && page > 1 && value != null) {
-			// Guard against the empty-cursor sentinel: a provider that claims another page without handing
-			// back a usable cursor would otherwise be re-read with `'{}'` and answer with page 1 again.
-			for (
-				let nextCursor = usableCursor(value.cursor);
-				currentPage < page && value.hasMore && nextCursor != null;
-				nextCursor = usableCursor(value.cursor)
-			) {
-				const next = await readAccountWidePage(nextCursor);
-				if (next.warning != null) {
-					appendDedupedWarning(warnings, next.warning);
-				}
-				if (next.value == null) {
-					pageFetchFailed = pageFetchFailed || next.warning != null;
-					value = undefined;
-					requestedPageMissing = true;
-					break;
-				}
-
-				value = next.value;
-				allMetadata = mergeCollectionMetadata(allMetadata, value.metadata);
-				currentTruncated = currentTruncated || value.truncated;
-				currentPage = value.page ?? currentPage + 1;
-				// A provider that hands back the same cursor isn't advancing; stop rather than loop forever.
-				if (usableCursor(value.cursor) === nextCursor) {
-					currentTruncated = true;
-					break;
-				}
-			}
-
-			// A numbered page beyond the provider's terminal cursor is genuinely empty. Never return or
-			// relabel the last available page as the requested one.
-			if (currentPage < page) {
-				requestedPageMissing = true;
-			}
-		} else if (options.cursor == null && page > 1) {
-			requestedPageMissing = true;
-		}
+		// Merged across the walked pages, so a per-scope failure reported on an earlier page isn't lost by
+		// paging past it — the one thing this read accumulates that the filtered search doesn't.
+		let allMetadata = first.value?.metadata;
+		const drained = await drainFlatPagesToRequestedPage(first, {
+			requestedPage: page,
+			suppliedCursor: options.cursor,
+			warnings: warnings,
+			readPage: readAccountWidePage,
+			fold: p => {
+				allMetadata = mergeCollectionMetadata(allMetadata, p.metadata);
+			},
+		});
+		const { value, currentPage, requestedPageMissing } = drained;
+		const currentTruncated = drained.truncated;
+		const pageFetchFailed = drained.fetchFailed;
 
 		// GitHub, GitLab, and Azure implement an account-wide issue search; a provider that doesn't (Bitbucket
 		// exposes no issues at all, and `supportsIssues` already short-circuits it above) returns `undefined`

package/src/plus/integrations/reads/paging.ts

@@ -180,6 +180,108 @@ export function resolveCurrentPage(options: {
 	return options.pageAdvanceable ? options.requestedPage : 1;
 }
 
+/**
+ * One page of a FLAT cursor-paged provider read — the shape both issue reads' providers return directly.
+ *
+ * `hasMore` is optional because one of the two providers leaves it off on a terminal page; absent reads as "no
+ * more", which is what a provider that reported no continuation means.
+ */
+export interface FlatPage {
+	cursor?: string;
+	hasMore?: boolean;
+	page?: number;
+	truncated: boolean;
+}
+
+/** What {@link drainFlatPagesToRequestedPage} established by walking. */
+export interface FlatDrainResult<T extends FlatPage> {
+	/** The requested page, or `undefined` when a page failed mid-walk (which also sets `fetchFailed`). */
+	value: T | undefined;
+	/** The position actually reached — 1 when nothing advanced. */
+	currentPage: number;
+	truncated: boolean;
+	/** True when the requested page is past the provider's last one, so it is genuinely EMPTY. */
+	requestedPageMissing: boolean;
+	fetchFailed: boolean;
+}
+
+/**
+ * Walks a FLAT cursor-paged read forward to a requested page number, for a provider whose pages are
+ * `{cursor, hasMore, page, truncated}` rather than the SDK's `PagedResult` wrapper.
+ *
+ * The sibling of {@link drainToRequestedPage}, not a replacement for it: that one normalizes SDK `paging` through
+ * {@link toProviderPageInfo}, which retains only cursors whose JSON declares `type`/`cursors` — and the composite
+ * cursor of a GitHub aliased search declares neither, so it would be dropped and the walk would never advance.
+ * Two shapes genuinely need two entry points; what they must NOT have is two copies of the rules below, which is
+ * what this exists to prevent (see this module's own note on drift).
+ *
+ * The rules, all of them subtle enough to be worth stating once:
+ * - The empty-cursor sentinel is filtered, so a provider claiming another page without handing back a usable
+ *   continuation is not re-read with `'{}'` (which it would answer with page 1 again).
+ * - A provider that returns the SAME cursor isn't advancing: stop, and report the read as truncated rather than
+ *   looping forever or publishing a short page as complete.
+ * - A page requested past the provider's terminal cursor is that EMPTY page N — never the last available page
+ *   relabeled, per {@link ProviderPageInfo.currentPage}.
+ * - A page that fails mid-walk latches `fetchFailed` and leaves no value, so the caller can tell "the read broke"
+ *   from "the page was genuinely empty".
+ *
+ * `fold` is the one thing the callers differ on — one merges SDK collection metadata across the walked pages, the
+ * other keeps the largest reported match count — so it is a callback rather than a branch.
+ */
+export async function drainFlatPagesToRequestedPage<T extends FlatPage>(
+	first: { value?: T; warning?: ProviderWarning },
+	options: {
+		requestedPage: number;
+		suppliedCursor: string | undefined;
+		warnings: ProviderWarning[];
+		readPage: (cursor: string) => Promise<{ value?: T; warning?: ProviderWarning }>;
+		fold?: (page: T) => void;
+	},
+): Promise<FlatDrainResult<T>> {
+	let value = first.value;
+	let fetchFailed = first.warning != null && value == null;
+	let currentPage = value?.page ?? 1;
+	let truncated = value?.truncated ?? false;
+
+	const walkable = options.suppliedCursor == null && options.requestedPage > 1;
+	if (walkable && value != null) {
+		for (
+			let nextCursor = usableCursor(value.cursor);
+			currentPage < options.requestedPage && value.hasMore === true && nextCursor != null;
+			nextCursor = usableCursor(value.cursor)
+		) {
+			const next = await options.readPage(nextCursor);
+			if (next.warning != null) {
+				appendDedupedWarning(options.warnings, next.warning);
+			}
+			if (next.value == null) {
+				fetchFailed = next.warning != null;
+				value = undefined;
+				break;
+			}
+
+			value = next.value;
+			truncated = truncated || value.truncated;
+			options.fold?.(value);
+			currentPage = value.page ?? currentPage + 1;
+			if (usableCursor(value.cursor) === nextCursor) {
+				truncated = true;
+				break;
+			}
+		}
+	}
+
+	return {
+		value: value,
+		currentPage: currentPage,
+		truncated: truncated,
+		// Every case reduces to "a page was asked for by number and the walk fell short", including the one where
+		// no walk ran at all because the first page was already terminal.
+		requestedPageMissing: walkable && currentPage < options.requestedPage,
+		fetchFailed: fetchFailed,
+	};
+}
+
 /** The mutable state {@link drainToRequestedPage} carries across the pages it walks. */
 export interface DrainState<T> {
 	items: T[];