@gitkraken/core-gitlens 0.5.103 → 0.5.104

package/src/plus/git-github/api/issueSearchQuery.ts

@@ -0,0 +1,165 @@
+import type { IssueSearchCriteria, IssueSearchRelationship } from '../../../git/models/issue.js';
+
+/**
+ * Translation of the provider-neutral issue-search criteria into GitHub search qualifiers, and the sanitizing
+ * that keeps user input from becoming one.
+ *
+ * A module of its own because it is pure string building with no client, no token and no network — the part of the
+ * search that is worth reading, testing and reasoning about on its own, and the part where a mistake is a
+ * SECURITY mistake rather than a failed request: an unsanitized value that escapes its qualifier re-scopes
+ * someone's search. Keeping it out of the 4000-line API client is what makes that reviewable.
+ */
+
+/**
+ * Neutralizes everything in a user-supplied value that could break out of the qualifier it lands in: the double
+ * quote that would close its own `"…"`, and the control characters that cannot appear in a GitHub search query
+ * and exist here only as a smuggling vector.
+ *
+ * Not a general escape — GitHub search has no escape syntax — so the only safe transformation is removal. But a
+ * control character is REPLACED WITH A SPACE rather than deleted, because deleting it FUSES the words it separated:
+ * a pasted or multi-line `graph\nperformance` became the single token `graphperformance`, which matches nothing —
+ * turning a search that had results into a silent zero (measured: 2 results vs 0). Quotes are still deleted
+ * outright; they separate nothing, so a space there would only pad the value.
+ *
+ * Runs of whitespace are collapsed afterwards so the emitted qualifier stays canonical — a doubled space inside
+ * `label:"a  b"` would not match the label `a b`.
+ */
+export function sanitizeGitHubQualifierValue(value: string): string {
+	return (
+		value
+			.replace(/"/g, '')
+			// eslint-disable-next-line no-control-regex
+			.replace(/[\u0000-\u001f\u007f]/g, ' ')
+			.replace(/\s+/g, ' ')
+			.trim()
+	);
+}
+
+/**
+ * Sanitizes free text, which is a different problem from a qualifier value: bare words are the POINT here, so it
+ * can't just be quoted. What must not survive is anything that would read as a qualifier — GitHub parses any
+ * whitespace-delimited `key:value` token as one, so a user typing `foo org:someone-else` would otherwise re-scope
+ * the search to another org.
+ *
+ * Tokens containing `:` are dropped whole rather than having the colon removed: the remainder would silently
+ * change what the user searched for, and a dropped token at least matches nothing extra. The structured criteria
+ * are the qualifier channel.
+ */
+export function sanitizeGitHubSearchText(text: string): string {
+	return sanitizeGitHubQualifierValue(text)
+		.split(/\s+/)
+		.filter(token => token.length > 0 && !token.includes(':'))
+		.join(' ');
+}
+
+/**
+ * How each relationship is expressed: its GitHub search qualifier (`@me` binds to the token's own user), and the
+ * GraphQL alias its search runs under.
+ *
+ * The aliases are LITERALS rather than derived from the relationship name, for two reasons: `any-assignee` is not
+ * a valid GraphQL name, and an alias is also a persisted cursor key (see {@link GitHubApi.searchIssuesByAlias}),
+ * so it must be stable across releases — spelling them out makes that immovability visible instead of an
+ * emergent property of a transform. Being a `Record` over the union, the type fails the build if a relationship
+ * is added without both, rather than silently emitting an unconstrained search.
+ */
+export const gitHubIssueSearchRelationships: Record<IssueSearchRelationship, { qualifier: string; alias: string }> = {
+	authored: { qualifier: 'author:@me', alias: 'authored' },
+	assigned: { qualifier: 'assignee:@me', alias: 'assigned' },
+	mentioned: { qualifier: 'mentions:@me', alias: 'mentioned' },
+	'any-assignee': { qualifier: 'assignee:*', alias: 'anyAssignee' },
+	unassigned: { qualifier: 'no:assignee', alias: 'unassigned' },
+};
+
+/**
+ * The scope half of an issue search query: `org:` plus one `repo:` per repository.
+ *
+ * Shared by the search and the count probe rather than written twice, because the count is only meaningful if it
+ * applies EXACTLY the qualifiers the search would — a count under different constraints is a wrong number, not a
+ * missing one. A value emptied by sanitizing is dropped rather than emitted as a bare `org:`/`repo:`, which
+ * GitHub rejects; that is the same rule {@link toGitHubIssueSearchQualifiers} applies to its own values.
+ */
+export function toGitHubIssueSearchScopeQualifiers(
+	org: string | undefined,
+	repos: readonly string[] | undefined,
+): string[] {
+	const qualifiers: string[] = [];
+
+	if (org != null) {
+		const value = sanitizeGitHubQualifierValue(org);
+		if (value.length > 0) {
+			qualifiers.push(`org:${value}`);
+		}
+	}
+
+	for (const repo of repos ?? []) {
+		const value = sanitizeGitHubQualifierValue(repo);
+		if (value.length > 0) {
+			qualifiers.push(`repo:${value}`);
+		}
+	}
+
+	return qualifiers;
+}
+
+/**
+ * Translates the provider-neutral criteria into GitHub search qualifiers, EXCLUDING the relationship (which
+ * becomes its own aliased search, since GitHub AND-s qualifiers and relationships are OR-ed) and excluding the
+ * repository/org scope (which {@link toGitHubIssueSearchScopeQualifiers} owns).
+ *
+ * `sort:updated` is always emitted: the read's contract is most-recently-updated-first, so a consumer's "show the
+ * N most recent" policy at the result ceiling is correct. Free-form values go through the sanitizers above, and
+ * one emptied by sanitizing is dropped rather than emitted as an empty qualifier.
+ */
+export function toGitHubIssueSearchQualifiers(criteria: IssueSearchCriteria | undefined): string[] {
+	const qualifiers = ['type:issue'];
+
+	switch (criteria?.state) {
+		case 'closed':
+			qualifiers.push('is:closed');
+			break;
+		// Every state — no qualifier constrains it.
+		case 'all':
+			break;
+		default:
+			qualifiers.push('is:open');
+			break;
+	}
+
+	if (criteria?.includeArchived !== true) {
+		qualifiers.push('archived:false');
+	}
+
+	// One place to keep the "a value emptied by sanitizing is DROPPED, never emitted as an empty qualifier" rule,
+	// so a criterion added later can't skip it — a bare `milestone:""` is rejected by GitHub outright.
+	const pushSanitized = (value: string | undefined, toQualifier: (sanitized: string) => string): void => {
+		if (value == null) return;
+
+		const sanitized = sanitizeGitHubQualifierValue(value);
+		if (sanitized.length > 0) {
+			qualifiers.push(toQualifier(sanitized));
+		}
+	};
+
+	for (const label of criteria?.labels ?? []) {
+		pushSanitized(label, v => `label:"${v}"`);
+	}
+	pushSanitized(criteria?.milestone, v => `milestone:"${v}"`);
+	pushSanitized(criteria?.updatedAfter, v => `updated:>=${v}`);
+	pushSanitized(criteria?.createdAfter, v => `created:>=${v}`);
+
+	if (criteria?.withoutLinkedPullRequest === true) {
+		qualifiers.push('-linked:pr');
+	}
+
+	if (criteria?.text != null) {
+		const text = sanitizeGitHubSearchText(criteria.text);
+		if (text.length > 0) {
+			qualifiers.push(text);
+		}
+	}
+
+	// Contract, not an option: see `GitHubApi.searchIssuesPage`.
+	qualifiers.push('sort:updated');
+
+	return qualifiers;
+}

package/src/plus/integrations/index.ts

@@ -215,6 +215,11 @@ export type {
 } from './results.js';
 // Runtime enums — re-exported as values (not `export type`) so consumers can read their members.
 export { IssueFilter, PullRequestFilter } from './providerFilters.js';
+// The filtered issue search's criteria model and the capability table that says which of it a provider honors.
+// String unions and plain interfaces, so a consumer builds criteria without importing an internal subpath.
+export type { IssueSearchCapabilities, IssueSearchCriteria, IssueSearchRelationship } from './providerFilters.js';
+// The count-only issue probe's input and result shapes.
+export type { IssueCountResult, IssueCountScope } from './reads/counts.js';
 // Cross-provider PR/issue state filters (string unions in the git models).
 export type { PullRequestStateFilter } from '../../git/models/pullRequest.js';
 export type { IssueStateFilter } from '../../git/models/issue.js';

package/src/plus/integrations/integrationService.ts

@@ -1,5 +1,5 @@
 import type { Account } from '../../git/models/author.js';
-import type { IssueShape } from '../../git/models/issue.js';
+import type { IssueSearchCriteria, IssueShape } from '../../git/models/issue.js';
 import type { PullRequest, PullRequestShape, PullRequestStateFilter } from '../../git/models/pullRequest.js';
 import type { GitRemote } from '../../git/models/remote.js';
 import type { RemoteProviderId } from '../../git/models/remoteProvider.js';
@@ -62,6 +62,7 @@ import { createApiClients } from './providers/apiClients.js';
 import type { GitHubApi } from './providers/github/github.js';
 import type {
 	IssueFilter,
+	IssueSearchCapabilities,
 	ProviderOrganization,
 	ProviderReposInput,
 	ProviderRepositoryShape,
@@ -71,12 +72,15 @@ import { providersMetadata } from './providers/models.js';
 import type { ProvidersApi } from './providers/providersApi.js';
 import { broadenIssues } from './reads/broaden.js';
 import type { RepositoryResolutionContext } from './reads/context.js';
+import type { IssueCountResult, IssueCountScope } from './reads/counts.js';
+import { countIssues } from './reads/counts.js';
 import { getSupportedFilters } from './reads/filters.js';
 import { listOrgs, listProjects, listRepos } from './reads/hierarchy.js';
 import { listIssuesPage } from './reads/issues.js';
 import { listIssueTrackerIssuesPage } from './reads/issueTracker.js';
 import { listPullRequestsPage } from './reads/pullRequests.js';
 import { resolveRepository } from './reads/resolveRepository.js';
+import { searchIssuesPage } from './reads/searchIssues.js';
 import { sweepClosedPullRequests, sweepPullRequests } from './reads/sweeps.js';
 import { noConnectionWarning } from './reads/warnings.js';
 import type {
@@ -531,6 +535,7 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 		pullRequestsAccountWide: PullRequestFilter[];
 		issues: IssueFilter[];
 		issuesAccountWide: IssueFilter[];
+		issueSearch: IssueSearchCapabilities;
 	} {
 		return getSupportedFilters(providerId);
 	}
@@ -1077,6 +1082,47 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 		return listIssuesPage(this, options);
 	}
 
+	/**
+	 * Issues matching structured criteria over a repository/org scope, with no forced relationship to the current
+	 * user — see {@link IntegrationManager.searchIssuesPage} for the contract (mandatory scope, guaranteed
+	 * most-recently-updated-first ordering, and the result-ceiling omission that carries the total match count).
+	 */
+	async searchIssuesPage(options: {
+		providerId: IntegrationIds;
+		repos?: ProviderReposInput;
+		org?: string;
+		criteria?: IssueSearchCriteria;
+		page?: number;
+		cursor?: string;
+		itemsPerPage?: number;
+		forceSync?: boolean;
+		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<ProviderPagedResult<IssueShape>> {
+		return searchIssuesPage(this, options);
+	}
+
+	/**
+	 * How many issues match each scope, without fetching any — see {@link IntegrationManager.countIssues} for the
+	 * cost model, the per-scope isolation rules, and why `count: undefined` must not be rendered as zero.
+	 */
+	async countIssues(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>> {
+		return countIssues(this, options);
+	}
+
 	/**
 	 * Reads the user's issues from an issue-tracker provider (Jira/Linear/Trello), whose issues live under
 	 * resource → project (not repos), so they can't go through {@link listIssuesPage} (git-host, repo-scoped).

package/src/plus/integrations/manager.ts

@@ -1,10 +1,11 @@
-import type { IssueShape } from '../../git/models/issue.js';
+import type { IssueSearchCriteria, IssueShape } from '../../git/models/issue.js';
 import type { PullRequestShape, PullRequestStateFilter } from '../../git/models/pullRequest.js';
 import type { Event } from '../../utils/event.js';
 import type { ConfiguredIntegrationsChangeEvent } from './authentication/configuredIntegrationService.js';
 import type { ConfiguredIntegrationDescriptor } from './authentication/models.js';
 import type { IntegrationIds } from './constants.js';
-import type { IssueFilter, PullRequestFilter } from './providerFilters.js';
+import type { IssueFilter, IssueSearchCapabilities, PullRequestFilter } from './providerFilters.js';
+import type { IssueCountResult, IssueCountScope } from './reads/counts.js';
 import type {
 	ConnectionStateChangeEvent,
 	ProviderBroadenResult,
@@ -200,6 +201,12 @@ export interface IntegrationManager {
 		pullRequestsAccountWide?: PullRequestFilter[];
 		issues: IssueFilter[];
 		issuesAccountWide: IssueFilter[];
+		/**
+		 * What {@link searchIssuesPage} (and {@link countIssues}, over the same criteria) can express for this
+		 * provider. Always present: a provider with no filtered issue search reports an empty `relationships` and
+		 * all-false flags, which is the signal to hide that surface rather than to hide individual chips.
+		 */
+		issueSearch: IssueSearchCapabilities;
 	};
 	/** Forces an authoritative cloud connection refresh. Rejects if the backend connection list cannot be read. */
 	refreshConnections(): Promise<void>;
@@ -306,6 +313,85 @@ export interface IntegrationManager {
 		/** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
 		domain?: string;
 	}): Promise<ProviderPagedResult<IssueShape>>;
+	/**
+	 * Issues matching structured criteria over a repository/org scope, with NO forced relationship to the current
+	 * user — the issue counterpart of the PR search, and the read to use for "every issue in these repos matching
+	 * X" rather than "my issues".
+	 *
+	 * Why this and not {@link listIssuesPage}: that read is either bound to the user's own relationships
+	 * (account-wide) or routed through the SDK's repo-scoped read, whose over-limit recovery walk can spend up to
+	 * 128 sequential requests and still return an incomplete set. This one is a single request per page.
+	 *
+	 * Three parts of the contract worth reading before calling:
+	 *
+	 * - **Scope is mandatory.** Pass `repos`, `org`, or a user relationship (`authored`/`assigned`/`mentioned`).
+	 *   `any-assignee`/`unassigned` do NOT scope anything — either alone matches every such issue on the host —
+	 *   so a call carrying only those is refused (warning + `fetchFailed`).
+	 * - **Ordering is always most-recently-updated-first**, not an option. A "show the N most recent" policy at
+	 *   the provider's result ceiling is only correct under a guaranteed order.
+	 * - **At the result ceiling the read SUCCEEDS.** It reports an omission carrying `totalCount` (how many
+	 *   matched) and `limit` (how many are reachable) with `recovery: 'none'`, so a consumer can say "19.240
+	 *   matched, showing the 1.000 most recent" and know not to offer a "load more". It never falls back to a
+	 *   per-repository recovery walk.
+	 *
+	 * Check `getSupportedFilters().issueSearch` first: a provider with no filtered issue search reports empty
+	 * relationships (and this read refuses), and a criterion it can't express refuses the whole read rather than
+	 * serving a wider result than asked for.
+	 */
+	searchIssuesPage(options: {
+		providerId: IntegrationIds;
+		/** Repositories to search. Combines with `org`; both constrain the same query. */
+		repos?: ProviderRepositoriesInput;
+		/** Organization/account to search. Combines with `repos`. */
+		org?: string;
+		criteria?: IssueSearchCriteria;
+		/**
+		 * Requested 1-based page. This read is cursor-only, so without a `cursor` reaching page N costs O(N)
+		 * upstream requests; pass the previous page's cursor to make it exactly one.
+		 */
+		page?: number;
+		cursor?: string;
+		/**
+		 * Page size PER RELATIONSHIP, not per page. Each requested relationship is its own provider query, so a
+		 * page of a 2-relationship search returns up to `2 × itemsPerPage` items before deduplication — and fewer
+		 * than that when the two overlap. `page.itemsPerPage` reports what actually came back, so size the UI off
+		 * that rather than off this. A provider may also cap it below what is asked for.
+		 */
+		itemsPerPage?: number;
+		forceSync?: boolean;
+		connectionId?: string;
+		/** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+		domain?: string;
+	}): Promise<ProviderPagedResult<IssueShape>>;
+	/**
+	 * How many issues MATCH each scope, without fetching any of them — the probe behind a "this will fetch ~N
+	 * issues" preview, and behind a live count next to a filter the user hasn't applied yet.
+	 *
+	 * Cheap by design: every scope that can share a request does, and no issue data crosses the wire (measured
+	 * against GitHub, 30 counts are a single rate-limit point). Still a network request per batch, so debounce and
+	 * cache it if it's driven from UI state.
+	 *
+	 * A separate method rather than a flag on {@link searchIssuesPage} because transferring zero issues is the
+	 * whole point: a `countOnly` read would hand back a paged result whose `items`/`cursor`/`hasMore` are all
+	 * meaningless.
+	 *
+	 * Results are echoed under the caller's own `key`, so no positional matching is needed. Per-scope isolation is
+	 * the rule: a scope refused for its own reasons, or a batch that failed upstream, warns and drops only its own
+	 * scopes (with `fetchFailed` set) while every other count still comes back.
+	 *
+	 * `count: undefined` means the provider didn't report one — NOT zero, which is a real answer. Render the
+	 * difference: showing an unknown count as 0 tells the user a filter matches nothing when it may match
+	 * thousands. A provider that can't count at all (only GitHub/GHE can today) refuses the probe outright rather
+	 * than returning fabricated numbers.
+	 */
+	countIssues(options: {
+		providerId: IntegrationIds;
+		/** Each needs its own scope, and each requested relationship its own entry — see {@link IssueCountScope}. */
+		scopes: readonly IssueCountScope[];
+		connectionId?: string;
+		/** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+		domain?: string;
+	}): Promise<ProviderResult<IssueCountResult>>;
 	/** Issue trackers are cloud-only, so this read takes no `domain`. */
 	listIssueTrackerIssuesPage(options: {
 		providerId: IntegrationIds;

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;
+};