@gitkraken/core-gitlens 0.5.103 → 0.5.105

package/src/plus/integrations/models/gitHostIntegration.ts

@@ -1,7 +1,7 @@
 import type { CollectionMetadata, CollectionScopeFailure } from '@gitkraken/provider-apis';
 import type { Account, UnidentifiedAuthor } from '../../../git/models/author.js';
 import type { DefaultBranch } from '../../../git/models/defaultBranch.js';
-import type { IssueShape, IssueStateFilter } from '../../../git/models/issue.js';
+import type { IssueSearchCriteria, IssueShape, IssueStateFilter } from '../../../git/models/issue.js';
 import type { IssueOrPullRequestState as PullRequestState } from '../../../git/models/issueOrPullRequest.js';
 import type { PullRequest, PullRequestMergeMethod, PullRequestStateFilter } from '../../../git/models/pullRequest.js';
 import type { RepositoryMetadata } from '../../../git/models/repositoryMetadata.js';
@@ -44,7 +44,7 @@ import {
 } from '../providers/models.js';
 import type { ProvidersApi } from '../providers/providersApi.js';
 import { mergeCollectionMetadata } from '../providers/utils/providerPaging.js';
-import type { IntegrationResult, IntegrationType } from './integration.js';
+import type { IntegrationResult, IntegrationType, ProviderIssueSearchPage } from './integration.js';
 import { IntegrationBase } from './integration.js';
 
 function isAzureDevOpsProvider(
@@ -1614,6 +1614,106 @@ export abstract class GitHostIntegration<
 		options?: { include?: PullRequestState[] },
 	): Promise<PullRequest[] | undefined>;
 
+	/**
+	 * Result-returning wrapper for the FILTERED issue search — issues matching structured criteria over a
+	 * repository/org scope, with no forced relationship to the current user. Recovers thrown errors into
+	 * `{ error }` so the facade surfaces a warning instead of a silent empty page.
+	 *
+	 * Distinct from every other issue read on this class: {@link searchMyIssuesWithTruncationResult} is bound to
+	 * the current user by construction, and {@link getMyIssuesForReposAsShapesResult} goes through the SDK's
+	 * repo-scoped read (whose over-limit recovery walk can cost up to 128 requests). This one is one request per
+	 * page and carries no relationship it wasn't asked for.
+	 */
+	async searchIssuesPageResult(
+		options: {
+			/**
+			 * Repositories to search, as namespace/name descriptors. NOT repository ids: a search query names
+			 * repositories by path, so an id-based input can't be expressed and the facade rejects it before here.
+			 */
+			repos?: ProviderRepoInput[];
+			org?: string;
+			criteria?: IssueSearchCriteria;
+			cursor?: string;
+			pageSize?: number;
+		},
+		cancellation?: AbortSignal,
+		connectionId?: string,
+	): Promise<IntegrationResult<ProviderIssueSearchPage | undefined>> {
+		const scope = getScopedLogger();
+		// `connectionId` targets a specific account (multi-account); omitted reads the primary.
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return undefined;
+
+		const start = performance.now();
+		try {
+			const result = await this.searchProviderIssuesPage?.(session, options, cancellation);
+			this.resetRequestExceptionCount('searchIssuesPage');
+			return { value: result, duration: performance.now() - start };
+		} catch (ex) {
+			this.handleProviderException('searchIssuesPage', ex, { scope: scope, connectionId: connectionId });
+			return { error: toError(ex), duration: performance.now() - start };
+		}
+	}
+
+	/**
+	 * OPTIONAL, like {@link searchProviderPullRequests}: a provider that can't express the criteria server-side
+	 * doesn't implement it, and the facade refuses the read (warning + `fetchFailed`) rather than serving a list
+	 * that was never narrowed. Whether a provider implements this must agree with what
+	 * `ProviderMetadata.supportedIssueSearch` declares.
+	 */
+	protected searchProviderIssuesPage?(
+		session: ProviderAuthenticationSession,
+		options: {
+			repos?: ProviderRepoInput[];
+			org?: string;
+			criteria?: IssueSearchCriteria;
+			cursor?: string;
+			pageSize?: number;
+		},
+		cancellation?: AbortSignal,
+	): Promise<ProviderIssueSearchPage | undefined>;
+
+	/**
+	 * Result-returning wrapper for the count-only probe: how many issues MATCH each scope, transferring no issues
+	 * at all. Recovers thrown errors into `{ error }` like the reads around it.
+	 *
+	 * Counts come back POSITIONALLY — one per input scope, in order — because a caller's key must never reach the
+	 * provider query. `undefined` in a slot means the provider didn't report a count for it, never zero matches.
+	 */
+	async countIssuesResult(
+		scopes: readonly { repos?: ProviderRepoInput[]; org?: string; criteria?: IssueSearchCriteria }[],
+		cancellation?: AbortSignal,
+		connectionId?: string,
+	): Promise<IntegrationResult<(number | undefined)[] | undefined>> {
+		const scope = getScopedLogger();
+		// `connectionId` targets a specific account (multi-account); omitted reads the primary.
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return undefined;
+
+		const start = performance.now();
+		try {
+			const counts = await this.countProviderIssues?.(session, scopes, cancellation);
+			this.resetRequestExceptionCount('countIssues');
+			return { value: counts, duration: performance.now() - start };
+		} catch (ex) {
+			this.handleProviderException('countIssues', ex, { scope: scope, connectionId: connectionId });
+			return { error: toError(ex), duration: performance.now() - start };
+		}
+	}
+
+	/**
+	 * OPTIONAL: only a provider that can answer "how many match" WITHOUT fetching the matches implements this.
+	 * GitHub's search reports `issueCount` on a zero-node selection; GitLab's REST exposes a total on some
+	 * endpoints but not for a search-shaped query, and Azure has no equivalent. A provider that can't answer
+	 * doesn't implement it and the facade refuses the probe, so a consumer hides its count rather than being shown
+	 * a fabricated one.
+	 */
+	protected countProviderIssues?(
+		session: ProviderAuthenticationSession,
+		scopes: readonly { repos?: ProviderRepoInput[]; org?: string; criteria?: IssueSearchCriteria }[],
+		cancellation?: AbortSignal,
+	): Promise<(number | undefined)[] | undefined>;
+
 	getPullRequestIdentityFromMaybeUrl(search: string): PullRequestUrlIdentity | undefined {
 		return this.getProviderPullRequestIdentityFromMaybeUrl?.(search);
 	}

package/src/plus/integrations/models/integration.ts

@@ -1,4 +1,3 @@
-import type { CollectionMetadata } from '@gitkraken/provider-apis';
 import type { Account } from '../../../git/models/author.js';
 import type { AutolinkReference, DynamicAutolinkReference } from '../../../git/models/autolink.js';
 import type { Issue, IssueShape } from '../../../git/models/issue.js';
@@ -26,12 +25,12 @@ import { GitCloudHostIntegrationId } from '../constants.js';
 import type { IntegrationServiceContext } from '../context.js';
 import { AuthenticationError, RequestClientError, toError } from '../errors.js';
 import type { IntegrationConnectionChangeEvent } from '../integrationService.js';
-import type { IssueFilter } from '../providerFilters.js';
 import type { ProvidersApi } from '../providers/providersApi.js';
 import type { Sources } from '../telemetry.js';
 import { areDomainsOnSameHost } from '../utils/domain.utils.js';
 import { isGitSelfManagedHostIntegrationId } from '../utils/integration.utils.js';
 import type { GitHostIntegration } from './gitHostIntegration.js';
+import type { AccountWideIssuesResult, SearchMyIssuesOptions } from './issueReads.js';
 import type { IssuesIntegration } from './issuesIntegration.js';
 
 export type Integration = GitHostIntegration | IssuesIntegration;
@@ -40,6 +39,10 @@ export type IntegrationById<T extends IntegrationIds> = T extends IssuesCloudHos
 	: GitHostIntegration;
 export type IntegrationType = 'git' | 'issues';
 
+// The issue-read contracts live in their own module (pure data, and their relationship to each other is the
+// point of reading them together); re-exported here so the providers that implement these reads keep one import.
+export type { AccountWideIssuesResult, ProviderIssueSearchPage, SearchMyIssuesOptions } from './issueReads.js';
+
 export type IntegrationKey<T extends IntegrationIds = IntegrationIds> = T extends
 	| GitCloudHostIntegrationId
 	| IssuesCloudHostIntegrationId
@@ -53,50 +56,6 @@ export type IntegrationResult<T> =
 	| { error: Error; duration?: number; value?: never }
 	| undefined;
 
-/**
- * Account-wide issue read result. `truncated` is a provider-native incompleteness signal (GitHub's search
- * ceiling, an Azure per-project backstop); cursor-capable providers also expose `cursor`/`hasMore`/`page`.
- * `metadata` optionally carries structured per-scope failures from a fan-out (Azure across projects).
- */
-export type AccountWideIssuesResult = {
-	values: IssueShape[];
-	truncated: boolean;
-	metadata?: CollectionMetadata;
-	cursor?: string;
-	hasMore?: boolean;
-	page?: number;
-};
-
-/**
- * Options for the account-wide issue read. `includeAllAssignees` drops the "assigned to me" scoping so the
- * read broadens to issues assigned to anyone (the account-wide equivalent of the repo-scoped
- * {@link GitHostIntegration.getMyIssuesForReposResult}'s toggle). Authored/mentioned categories, where a
- * provider has them, stay user-relative — they're meaningless without a user.
- */
-export type SearchMyIssuesOptions = {
-	includeAllAssignees?: boolean;
-	/**
-	 * Narrows the account-wide read to the requested relationship(s) instead of the provider's own definition of
-	 * "my issues" (GitHub/GHE: authored ∪ assigned ∪ mentioned; Azure: assigned ∪ authored; GitLab:
-	 * assigned-to-me). Narrowing has to happen HERE, not on the returned page: the excluded items still counted
-	 * toward the provider's page/cursor, so a client-side filter desynchronizes `items` from `hasMore`.
-	 *
-	 * Only filters the provider can express server-side are accepted; the facade validates the set against
-	 * `ProviderMetadata.supportedAccountWideIssueFilters` (all-or-nothing) and refuses the read rather than
-	 * serving the unnarrowed union as if it had been filtered. Omitted keeps the provider's definition.
-	 */
-	filters?: IssueFilter[];
-	cursor?: string;
-	/**
-	 * Narrows the account-wide read to one org/account (Azure: the organization) and/or one project within it.
-	 * Only honored by a host with a project layer (Azure), whose account-wide read otherwise fans out over every
-	 * project of every org; the caller checks `supportsProjectDiscovery` before asking, so a host without a
-	 * project layer never silently returns an unscoped list as if it had been narrowed.
-	 */
-	org?: string;
-	project?: string;
-};
-
 type SyncReqUsecase = Exclude<
 	| 'getAccountForCommit'
 	| 'getAccountForEmail'
@@ -120,7 +79,9 @@ type SyncReqUsecase = Exclude<
 	| 'getRepositoryMetadata'
 	| 'getResourcesForUser'
 	| 'getSshSigningKeysForEmails'
+	| 'countIssues'
 	| 'mergePullRequest'
+	| 'searchIssuesPage'
 	| 'searchMyIssues'
 	| 'searchMyPullRequests'
 	| 'searchPullRequests',

package/src/plus/integrations/models/issueReads.ts

@@ -0,0 +1,73 @@
+import type { CollectionMetadata } from '@gitkraken/provider-apis';
+import type { IssueShape } from '../../../git/models/issue.js';
+import type { IssueFilter } from '../providerFilters.js';
+
+/**
+ * The result and option contracts of the integration layer's issue reads — the shapes a PROVIDER returns to the
+ * facade, before the facade turns them into the paged/warning results a consumer sees.
+ *
+ * They live together, and apart from `IntegrationBase`, because they are pure data with one job: pinning what
+ * each issue read promises. Reading them side by side is also the point — `ProviderIssueSearchPage` is
+ * deliberately `AccountWideIssuesResult` plus a count, and that relationship is invisible when they sit at
+ * opposite ends of a 1000-line class module.
+ */
+
+/**
+ * Account-wide issue read result. `truncated` is a provider-native incompleteness signal (GitHub's search
+ * ceiling, an Azure per-project backstop); cursor-capable providers also expose `cursor`/`hasMore`/`page`.
+ * `metadata` optionally carries structured per-scope failures from a fan-out (Azure across projects).
+ */
+export type AccountWideIssuesResult = {
+	values: IssueShape[];
+	truncated: boolean;
+	metadata?: CollectionMetadata;
+	cursor?: string;
+	hasMore?: boolean;
+	page?: number;
+};
+
+/**
+ * One page of the FILTERED issue search (`GitHostIntegration.searchIssuesPageResult`).
+ *
+ * Carries what {@link AccountWideIssuesResult} does, plus `totalCount`: the number of matches the provider
+ * reported, which is what makes the result ceiling reportable as a figure ("N matched, at most M can be read")
+ * rather than as a bare `truncated` flag. `undefined` means the provider reported no count, never zero matches.
+ */
+export type ProviderIssueSearchPage = {
+	values: IssueShape[];
+	truncated: boolean;
+	cursor?: string;
+	hasMore: boolean;
+	page: number;
+	totalCount?: number;
+};
+
+/**
+ * Options for the account-wide issue read. `includeAllAssignees` drops the "assigned to me" scoping so the
+ * read broadens to issues assigned to anyone (the account-wide equivalent of the repo-scoped
+ * `GitHostIntegration.getMyIssuesForReposResult`'s toggle). Authored/mentioned categories, where a
+ * provider has them, stay user-relative — they're meaningless without a user.
+ */
+export type SearchMyIssuesOptions = {
+	includeAllAssignees?: boolean;
+	/**
+	 * Narrows the account-wide read to the requested relationship(s) instead of the provider's own definition of
+	 * "my issues" (GitHub/GHE: authored ∪ assigned ∪ mentioned; Azure: assigned ∪ authored; GitLab:
+	 * assigned-to-me). Narrowing has to happen HERE, not on the returned page: the excluded items still counted
+	 * toward the provider's page/cursor, so a client-side filter desynchronizes `items` from `hasMore`.
+	 *
+	 * Only filters the provider can express server-side are accepted; the facade validates the set against
+	 * `ProviderMetadata.supportedAccountWideIssueFilters` (all-or-nothing) and refuses the read rather than
+	 * serving the unnarrowed union as if it had been filtered. Omitted keeps the provider's definition.
+	 */
+	filters?: IssueFilter[];
+	cursor?: string;
+	/**
+	 * Narrows the account-wide read to one org/account (Azure: the organization) and/or one project within it.
+	 * Only honored by a host with a project layer (Azure), whose account-wide read otherwise fans out over every
+	 * project of every org; the caller checks `supportsProjectDiscovery` before asking, so a host without a
+	 * project layer never silently returns an unscoped list as if it had been narrowed.
+	 */
+	org?: string;
+	project?: string;
+};

package/src/plus/integrations/providerFilters.ts

@@ -10,3 +10,18 @@ export enum IssueFilter {
 	Assignee = 'assignee',
 	Mention = 'mention',
 }
+
+/**
+ * The filtered issue search's criteria model, re-exported from the git models so it can be reached from here
+ * alongside the two filter enums above.
+ *
+ * It lives in `@gitkraken/core-gitlens/git` rather than in this package because the provider implementations that translate it
+ * to a query — the GitHub API client among them — sit BELOW this package in the dependency graph and can't import
+ * from it. {@link IssueSearchRelationship} is a superset of {@link IssueFilter}: it adds the two user-independent
+ * relationships (`any-assignee`, `unassigned`) that the user-relative "my issues" filters have no way to name.
+ */
+export type {
+	IssueSearchCapabilities,
+	IssueSearchCriteria,
+	IssueSearchRelationship,
+} from '../../git/models/issue.js';

package/src/plus/integrations/providers/github.ts

@@ -1,6 +1,6 @@
 import type { Account, UnidentifiedAuthor } from '../../../git/models/author.js';
 import type { DefaultBranch } from '../../../git/models/defaultBranch.js';
-import type { Issue, IssueShape } from '../../../git/models/issue.js';
+import type { Issue, IssueSearchCriteria, IssueShape } from '../../../git/models/issue.js';
 import type { IssueOrPullRequest } from '../../../git/models/issueOrPullRequest.js';
 import type {
 	PullRequest,
@@ -25,7 +25,7 @@ import { IntegrationReadUnavailableError } from '../errors.js';
 import type { IntegrationConnectionChangeEvent } from '../integrationService.js';
 import type { SearchMyPullRequestsOptions } from '../models/gitHostIntegration.js';
 import { GitHostIntegration } from '../models/gitHostIntegration.js';
-import type { SearchMyIssuesOptions } from '../models/integration.js';
+import type { ProviderIssueSearchPage, SearchMyIssuesOptions } from '../models/integration.js';
 import type { GitHubIntegrationIds } from './github/github.utils.js';
 import { getGitHubPullRequestIdentityFromMaybeUrl } from './github/github.utils.js';
 import type {
@@ -33,6 +33,7 @@ import type {
 	ProviderHierarchyResult,
 	ProviderOrganization,
 	ProviderPullRequest,
+	ProviderRepoInput,
 	ProviderRepository,
 } from './models.js';
 import {
@@ -592,6 +593,10 @@ abstract class GitHubIntegrationBase<ID extends GitHubIntegrationIds> extends Gi
 		cancellation?: AbortSignal,
 		options?: SearchMyIssuesOptions,
 	): Promise<{ values: IssueShape[]; truncated: boolean } | undefined> {
+		// `includeAllAssignees` becomes `assignee:*`, which needs a scope to mean anything — with none it matches
+		// millions of issues across all of GitHub rather than "assigned to anyone in the user's world". ANY scope
+		// works (one repo, several, or an org), so this refuses only the genuinely unscoped read; the scoped
+		// "assigned to anyone over these repos" request is served by `searchIssuesPage`.
 		if ((repos == null || repos.length === 0) && options?.includeAllAssignees) {
 			throw new IntegrationReadUnavailableError(
 				this.name,
@@ -620,6 +625,63 @@ abstract class GitHubIntegrationBase<ID extends GitHubIntegrationIds> extends Gi
 		);
 	}
 
+	/**
+	 * The filtered issue search: one GraphQL request per page, no forced relationship to the current user, and no
+	 * route through the SDK's repo-scoped read (whose over-limit recovery walk can spend up to 128 requests).
+	 *
+	 * The criteria → qualifier translation and the ordering guarantee live in the API client
+	 * (`GitHubApi.searchIssuesPage`), which is also where user input is sanitized so it can't inject a qualifier.
+	 */
+	protected override async searchProviderIssuesPage(
+		session: ProviderAuthenticationSession,
+		options: {
+			repos?: ProviderRepoInput[];
+			org?: string;
+			criteria?: IssueSearchCriteria;
+			cursor?: string;
+			pageSize?: number;
+		},
+		cancellation?: AbortSignal,
+	): Promise<ProviderIssueSearchPage | undefined> {
+		return (await this.authenticationService.apis.github)?.searchIssuesPage(
+			this,
+			toTokenWithInfo(this.id, session),
+			{
+				// `namespace` is the owner for GitHub, which is how a `repo:` qualifier names a repository.
+				repos: options.repos?.map(r => `${r.namespace}/${r.name}`),
+				org: options.org,
+				criteria: options.criteria,
+				baseUrl: this.apiBaseUrl,
+				includeBody: true,
+				cursor: options.cursor,
+				pageSize: options.pageSize,
+			},
+			cancellation,
+		);
+	}
+
+	/**
+	 * Counts several scopes in ONE request. GitHub's `search` reports `issueCount` on a zero-node selection, so a
+	 * count preview costs no issue transfer — measured, 30 aliased counts are a single rate-limit point.
+	 */
+	protected override async countProviderIssues(
+		session: ProviderAuthenticationSession,
+		scopes: readonly { repos?: ProviderRepoInput[]; org?: string; criteria?: IssueSearchCriteria }[],
+		cancellation?: AbortSignal,
+	): Promise<(number | undefined)[] | undefined> {
+		return (await this.authenticationService.apis.github)?.countIssues(
+			this,
+			toTokenWithInfo(this.id, session),
+			scopes.map(s => ({
+				repos: s.repos?.map(r => `${r.namespace}/${r.name}`),
+				org: s.org,
+				criteria: s.criteria,
+			})),
+			{ baseUrl: this.apiBaseUrl },
+			cancellation,
+		);
+	}
+
 	protected override async searchProviderPullRequests(
 		session: ProviderAuthenticationSession,
 		searchQuery: string,

package/src/plus/integrations/providers/models.ts

@@ -43,6 +43,7 @@ import type {
 } from '@gitkraken/provider-apis';
 import entityIdentifiersModule from '@gitkraken/provider-apis/entity-identifiers';
 import providerUtilsModule from '@gitkraken/provider-apis/provider-utils';
+import { githubSearchResultLimit } from '../../git-github/api/config.js';
 import type { Account as UserAccount } from '../../../git/models/author.js';
 import type { IssueMember, IssueProject, IssueShape, IssueStateFilter } from '../../../git/models/issue.js';
 import { Issue, RepositoryAccessLevel } from '../../../git/models/issue.js';
@@ -74,9 +75,11 @@ import {
 	IssuesCloudHostIntegrationId,
 } from '../constants.js';
 import type { Integration, IntegrationType } from '../models/integration.js';
+import type { IssueSearchCapabilities } from '../providerFilters.js';
 import { IssueFilter, PullRequestFilter } from '../providerFilters.js';
 
 export { IssueFilter, PullRequestFilter } from '../providerFilters.js';
+export type { IssueSearchCapabilities, IssueSearchCriteria, IssueSearchRelationship } from '../providerFilters.js';
 import type { ProviderRepositoryShape } from '../results.js';
 
 export type { ProviderOrganization, ProviderRepositoryShape } from '../results.js';
@@ -710,11 +713,53 @@ export interface ProviderMetadata {
 	 * axes; it omits `Mention` because that REST read has no first-class mention filter.
 	 */
 	supportedAccountWideIssueFilters?: IssueFilter[];
+	/**
+	 * What the provider's FILTERED issue search (`searchIssuesPage`, and the `countIssues` probe over the same
+	 * criteria) can express server-side. A third, wider surface than either filter set above: it is not bound to
+	 * the user at all, so it takes relationships those reads have no way to name (`any-assignee`, `unassigned`),
+	 * plus free text and issue attributes.
+	 *
+	 * Absent means the provider has NO filtered issue search and the read is refused. Present, it is a promise:
+	 * every field declared here reaches the provider query, so a consumer that intersects against it never has a
+	 * read refused, and a criterion is never silently ignored.
+	 */
+	supportedIssueSearch?: IssueSearchCapabilities;
+	/**
+	 * The maximum number of results the provider's filtered issue search will serve for ONE query, however it is
+	 * paged. Matches past it are UNREACHABLE, not merely unfetched, which is why a read that hits this reports an
+	 * omission with `recovery: 'none'` and the total match count rather than offering a "load more".
+	 *
+	 * Absent means the provider declares no ceiling, in which case a truncated read falls back to generic wording
+	 * instead of quoting a limit that was never published.
+	 */
+	issueSearchResultLimit?: number;
 }
 
 export type Providers = Record<IntegrationIds, ProviderInfo>;
 export type ProvidersMetadata = Record<IntegrationIds, ProviderMetadata>;
 
+/**
+ * GitHub and GitHub Enterprise express every criterion as a search qualifier on the same GraphQL `search` field,
+ * so the two share one declaration — a GHE instance running the same search syntax has the same capability, and
+ * two copies of this table would be free to drift.
+ *
+ * Every entry is a claim the implementation must keep: `searchIssuesPage` emits a qualifier for each of these,
+ * and a test asserts that (see the `issueSearch` capability tests) so the table can't quietly outrun the code.
+ */
+const githubIssueSearchCapabilities: IssueSearchCapabilities = {
+	// `author:@me` / `assignee:@me` / `mentions:@me` / `assignee:*` / `no:assignee`, each its own aliased search.
+	relationships: ['authored', 'assigned', 'mentioned', 'any-assignee', 'unassigned'],
+	text: true,
+	labels: true,
+	milestone: true,
+	updatedAfter: true,
+	createdAfter: true,
+	// `-linked:pr`.
+	withoutLinkedPullRequest: true,
+	// `is:open` / `is:closed`, or neither for all states.
+	states: true,
+};
+
 export const providersMetadata: ProvidersMetadata = {
 	[GitCloudHostIntegrationId.GitHub]: {
 		domain: 'github.com',
@@ -742,6 +787,8 @@ export const providersMetadata: ProvidersMetadata = {
 		// The account-wide read is three independent searches (`author:@me`, `assignee:@me`, `mentions:@me`) behind
 		// one composite cursor, so any subset of them is expressible.
 		supportedAccountWideIssueFilters: [IssueFilter.Author, IssueFilter.Assignee, IssueFilter.Mention],
+		supportedIssueSearch: githubIssueSearchCapabilities,
+		issueSearchResultLimit: githubSearchResultLimit,
 		scopes: ['repo', 'read:user', 'user:email'],
 	},
 	[GitSelfManagedHostIntegrationId.CloudGitHubEnterprise]: {
@@ -770,6 +817,8 @@ export const providersMetadata: ProvidersMetadata = {
 		// The account-wide read is three independent searches (`author:@me`, `assignee:@me`, `mentions:@me`) behind
 		// one composite cursor, so any subset of them is expressible.
 		supportedAccountWideIssueFilters: [IssueFilter.Author, IssueFilter.Assignee, IssueFilter.Mention],
+		supportedIssueSearch: githubIssueSearchCapabilities,
+		issueSearchResultLimit: githubSearchResultLimit,
 		scopes: ['repo', 'read:user', 'user:email'],
 	},
 	[GitCloudHostIntegrationId.GitLab]: {

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

@@ -23,6 +23,16 @@ import { gitHostOnlySurfaceWarning, issuesUnsupportedWarning, noConnectionWarnin
  * provider positions — one per org — so its continuation is a per-org cursor BUNDLE (see `cursors.ts`) and its
  * failure attribution is per provider across those orgs. Both are the reason a page number alone can't address a
  * later page, and why {@link broadenIssues} walks prior pages itself when given only `page`.
+ *
+ * SUPERSEDED for a caller that already knows its repositories: `searchIssuesPage({ repos, criteria })` answers
+ * the same question in one request per page, with no repository drain and no route through the SDK read whose
+ * over-limit recovery walk can spend up to 128 requests. This read stays for "fan out across these orgs,
+ * whatever repos they contain", whose per-provider attribution the single-provider search doesn't produce.
+ *
+ * If you migrate a caller, note the semantics carefully: broadening means ALL VISIBLE — it passes
+ * `includeAllAssignees: true`, which resolves to no assignee constraint at all, so unassigned issues ARE
+ * included. The equivalent is an OMITTED `relationships`, not `['any-assignee']`: `assignee:*` means "has some
+ * assignee" and would silently exclude every unassigned issue, which is the opposite of broadening.
  */
 
 export interface BroadenIssuesOptions {