@gitkraken/core-gitlens 0.4.0 → 0.4.101

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

@@ -0,0 +1,224 @@
+import type { IntegrationIds } from '../constants.js';
+import { toPageCursor } from '../providers/utils/providerPaging.js';
+import { hostFromDomain } from '../utils/domain.utils.js';
+import { pageToCursor } from './paging.js';
+
+/**
+ * The COMPOSITE cursors, for the two reads a single provider cursor can't address.
+ *
+ * A plain paged read threads the provider's own opaque continuation. These two fan out instead — the
+ * issue-tracker read over a window of projects, the broaden read over a set of orgs — so one round produces
+ * several provider positions plus the bookkeeping needed to resume: which scopes failed and should be retried,
+ * and which are already drained and must NOT be re-read (a cursor-only provider handed a fresh page-1 request
+ * answers with its first page again, duplicating items).
+ *
+ * Both encodings are opaque to consumers and are parsed defensively: a cursor is caller-supplied data that may
+ * be stale, truncated, or from another read entirely, so anything unrecognized degrades to "no cursor" (which
+ * falls back to page paging) rather than throwing or being forwarded to a provider as a foreign string.
+ */
+
+// ---------------------------------------------------------------------------------------------------------
+// Issue-tracker page cursor (Jira/Linear/Trello: resource → project, paginated by a window of PROJECTS)
+// ---------------------------------------------------------------------------------------------------------
+
+export interface IssueTrackerPageCursor {
+	type: 'issue-tracker-page';
+	currentPage: number;
+	unpaged?: boolean;
+	nextPage?: number;
+	retryPages?: number[];
+	retryProjects?: string[];
+	completedProjects?: string[];
+}
+
+/** Positive safe integers only, deduped; `undefined` when nothing survives (so the field is omitted). */
+function positiveIntegers(values: unknown): number[] | undefined {
+	if (!Array.isArray(values)) return undefined;
+
+	const valid = values.filter(
+		(value): value is number => typeof value === 'number' && Number.isSafeInteger(value) && value > 0,
+	);
+	return valid.length > 0 ? [...new Set(valid)] : undefined;
+}
+
+/** Non-empty strings only, deduped; `undefined` when nothing survives (so the field is omitted). */
+function nonEmptyStrings(values: unknown): string[] | undefined {
+	if (!Array.isArray(values)) return undefined;
+
+	const valid = values.filter((value): value is string => typeof value === 'string' && value.length > 0);
+	return valid.length > 0 ? [...new Set(valid)] : undefined;
+}
+
+export function parseIssueTrackerPageCursor(cursor: string | undefined): IssueTrackerPageCursor | undefined {
+	if (cursor == null) return undefined;
+
+	try {
+		const parsed = JSON.parse(cursor) as Partial<IssueTrackerPageCursor>;
+		if (
+			parsed.type !== 'issue-tracker-page' ||
+			typeof parsed.currentPage !== 'number' ||
+			!Number.isSafeInteger(parsed.currentPage) ||
+			parsed.currentPage < 1
+		) {
+			return undefined;
+		}
+
+		const retryPages = positiveIntegers(parsed.retryPages);
+		const retryProjects = nonEmptyStrings(parsed.retryProjects);
+		const completedProjects = nonEmptyStrings(parsed.completedProjects);
+		return {
+			type: 'issue-tracker-page',
+			currentPage: parsed.currentPage,
+			...(parsed.unpaged === true ? { unpaged: true } : {}),
+			...(typeof parsed.nextPage === 'number' && Number.isSafeInteger(parsed.nextPage) && parsed.nextPage > 0
+				? { nextPage: parsed.nextPage }
+				: {}),
+			...(retryPages != null ? { retryPages: retryPages } : {}),
+			...(retryProjects != null ? { retryProjects: retryProjects } : {}),
+			...(completedProjects != null ? { completedProjects: completedProjects } : {}),
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+export function toIssueTrackerPageCursor(options: {
+	currentPage: number;
+	unpaged?: boolean;
+	nextPage?: number;
+	retryPages: readonly number[];
+	retryProjects: readonly string[];
+	completedProjects?: readonly string[];
+}): string | undefined {
+	const retryPages = [...new Set(options.retryPages)].sort((a, b) => a - b);
+	const retryProjects = [...new Set(options.retryProjects)].sort();
+	const completedProjects =
+		retryPages.length > 0 || retryProjects.length > 0 || options.nextPage != null
+			? [...new Set(options.completedProjects ?? [])].sort()
+			: [];
+	if (retryPages.length === 0 && retryProjects.length === 0 && options.nextPage == null) {
+		return undefined;
+	}
+	// Nothing to carry beyond the next window: emit the plain page cursor instead of a composite one, so an
+	// ordinary forward read round-trips through the same encoding every other paged read uses.
+	if (
+		retryPages.length === 0 &&
+		retryProjects.length === 0 &&
+		completedProjects.length === 0 &&
+		options.nextPage != null &&
+		options.unpaged !== true
+	) {
+		return toPageCursor(options.nextPage);
+	}
+	return JSON.stringify({
+		type: 'issue-tracker-page',
+		currentPage: options.currentPage,
+		...(options.unpaged === true ? { unpaged: true } : {}),
+		...(options.nextPage != null ? { nextPage: options.nextPage } : {}),
+		...(retryPages.length > 0 ? { retryPages: retryPages } : {}),
+		...(retryProjects.length > 0 ? { retryProjects: retryProjects } : {}),
+		...(completedProjects.length > 0 ? { completedProjects: completedProjects } : {}),
+	} satisfies IssueTrackerPageCursor);
+}
+
+// ---------------------------------------------------------------------------------------------------------
+// Broaden-issues cursor bundle (one provider position per org in the fan-out)
+// ---------------------------------------------------------------------------------------------------------
+
+/** Identifies one org slice of the fan-out. Connection and domain are part of the key: two accounts, or two
+ * self-managed hosts, can each have an org of the same name. */
+export interface BroadenIssuesOrgKey {
+	providerId: IntegrationIds;
+	name: string;
+	connectionId?: string;
+	domain?: string;
+}
+
+/** One org's position in the bundle: either the provider's own cursor, or a page to retry after a failure. */
+export interface BroadenIssuesOrgCursor {
+	providerId: IntegrationIds;
+	org: string;
+	connectionId?: string;
+	domain?: string;
+	cursor?: string;
+	retryPage?: number;
+}
+
+export type BroadenIssuesExhaustedOrg = Omit<BroadenIssuesOrgCursor, 'cursor' | 'retryPage'>;
+
+/** Whether a bundle entry addresses the same org slice as `org`, comparing domains by host. */
+function matchesOrg(
+	entry: { providerId?: IntegrationIds; org?: string; connectionId?: string; domain?: string },
+	org: BroadenIssuesOrgKey,
+): boolean {
+	return (
+		entry.providerId === org.providerId &&
+		entry.org === org.name &&
+		entry.connectionId === org.connectionId &&
+		(hostFromDomain(entry.domain) ?? entry.domain) === (hostFromDomain(org.domain) ?? org.domain)
+	);
+}
+
+/**
+ * The cursor to send for one org in this round: its entry in the bundle, or a synthesized page cursor.
+ *
+ * A single-org fan-out has no bundle to key into — its cursor IS the provider's, threaded straight through.
+ */
+export function getBroadenIssuesCursor(
+	cursor: string | undefined,
+	org: BroadenIssuesOrgKey,
+	page: number,
+	orgCount: number,
+): string | undefined {
+	if (orgCount === 1) return cursor ?? pageToCursor(page);
+
+	if (cursor != null) {
+		try {
+			const parsed = JSON.parse(cursor) as { cursors?: BroadenIssuesOrgCursor[] };
+			const match = parsed.cursors?.find(c => matchesOrg(c, org));
+			if (match?.cursor != null) return match.cursor;
+			if (typeof match?.retryPage === 'number' && Number.isSafeInteger(match.retryPage) && match.retryPage > 0) {
+				return toPageCursor(match.retryPage);
+			}
+		} catch {}
+	}
+
+	return pageToCursor(page);
+}
+
+/**
+ * Whether a prior round already drained this org (multi-org fan-out only). Once an org runs out of pages while
+ * another org keeps paging, the bundle records it as exhausted so the next round skips it instead of re-issuing
+ * a page-1 read — which cursor-only providers (having no page-number cursor to honor) would answer with their
+ * first page again, duplicating results.
+ */
+export function isBroadenIssuesOrgExhausted(
+	cursor: string | undefined,
+	org: BroadenIssuesOrgKey,
+	orgCount: number,
+): boolean {
+	if (orgCount === 1 || cursor == null) return false;
+
+	try {
+		const parsed = JSON.parse(cursor) as { exhausted?: BroadenIssuesExhaustedOrg[] };
+		return parsed.exhausted?.some(e => matchesOrg(e, org)) ?? false;
+	} catch {
+		return false;
+	}
+}
+
+/** Encodes the round's per-org positions. A single-org fan-out emits that org's cursor directly, unwrapped. */
+export function toBroadenIssuesCursor(
+	cursors: BroadenIssuesOrgCursor[],
+	exhausted: BroadenIssuesExhaustedOrg[],
+	orgCount: number,
+): string | undefined {
+	if (cursors.length === 0) return undefined;
+	if (orgCount === 1) {
+		return cursors[0].cursor ?? (cursors[0].retryPage != null ? toPageCursor(cursors[0].retryPage) : undefined);
+	}
+
+	// Carry the exhausted orgs alongside the still-active cursors so the next round can skip them (see
+	// isBroadenIssuesOrgExhausted). Only meaningful while at least one org still has more to read.
+	return JSON.stringify({ cursors: cursors, exhausted: exhausted });
+}

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

@@ -0,0 +1,343 @@
+import type { PullRequestStateFilter } from '../../../git/models/pullRequest.js';
+import { mergeAssessmentInto } from '../collectionMetadata.js';
+import type { IntegrationIds } from '../constants.js';
+import { supportedOrderedCloudIntegrationIds } from '../constants.js';
+import type { ProviderSweepTarget, PullRequestSweepOptions } from '../manager.js';
+import type { GitHostIntegration } from '../models/gitHostIntegration.js';
+import type { IntegrationResult } from '../models/integration.js';
+import type { PullRequestFilter } from '../providerFilters.js';
+import type { ProviderPullRequest, ProviderReposInput, ProviderRepository } from '../providers/models.js';
+import { getProviderPullRequestIdentity } from '../providers/models.js';
+import type { ProviderWarning } from '../results.js';
+import { appendDedupedWarning, toProviderWarning } from '../results.js';
+import { isIssuesHostIntegrationId } from '../utils/integration.utils.js';
+import { noConnectionWarning, truncationWarning } from './warnings.js';
+
+/**
+ * The all-pages reads: a provider read run repeatedly until it runs out of pages, as opposed to the single-page
+ * reads the facade's paged surface exposes. `sweepPullRequests` and `broadenIssues` are built on these.
+ *
+ * A drain's job is to keep going where a single page would stop, so what distinguishes it is its failure
+ * bookkeeping rather than its loop: it must return the prefix it did read plus enough signal for the caller to
+ * know the result is not authoritative — `truncated` when pages remain unread (a page backstop, or a provider
+ * claiming another page while handing back no usable cursor), `fetchFailed` when a page or scope failed
+ * outright. Discarding the prefix on a late failure, or returning it as if complete, are the two mistakes these
+ * exist to prevent.
+ */
+
+/**
+ * Runs a result-returning read and captures failure as a neutral {@link ProviderWarning} rather than
+ * letting it throw or silently vanish. Handles both a returned `{ error }` (the read cores' contract)
+ * and a hard throw; a soft warning (`{ value, error }`) yields the value *and* a warning.
+ */
+export async function runCaptured<T>(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	fn: () => Promise<IntegrationResult<T>>,
+	options?: { warnOnMissingSession?: boolean },
+): Promise<{ value?: T; warning?: ProviderWarning }> {
+	try {
+		const result = await fn();
+		if (result == null) {
+			// The read core returns undefined only when it couldn't resolve a session. For a per-connection
+			// or explicit-domain read that means the requested target is gone or its authentication is invalid,
+			// which must not be reported as an empty account. The untargeted primary path legitimately yields
+			// nothing when the provider isn't connected, so leave it as an empty result.
+			return connectionId != null || options?.warnOnMissingSession
+				? { warning: noConnectionWarning(id, domain, connectionId) }
+				: {};
+		}
+		if (result.error != null) {
+			return { value: result.value, warning: toProviderWarning(id, domain, connectionId, result.error) };
+		}
+		return { value: result.value };
+	} catch (ex) {
+		return { warning: toProviderWarning(id, domain, connectionId, ex) };
+	}
+}
+
+/**
+ * Drains every page of the user's pull requests for one git-host integration, threading the opaque
+ * next-cursor the provider returns (so it works for both page- and cursor-based hosts). Stops at
+ * `maxPages` (marking `truncated`) or on a hard read failure (marking `fetchFailed`), keeping the
+ * pages fetched so far. A soft warning (`{ value, error }`) is recorded but the drain continues.
+ */
+export async function drainPullRequests(
+	integration: GitHostIntegration,
+	id: IntegrationIds,
+	domain: string | undefined,
+	repos: ProviderReposInput,
+	state: PullRequestStateFilter[] | undefined,
+	filters: PullRequestFilter[] | undefined,
+	includeReviewRequested: boolean,
+	connectionId: string | undefined,
+	maxPages: number,
+	attributeUnavailableProvider: boolean,
+): Promise<{
+	items: ProviderPullRequest[];
+	warnings: ProviderWarning[];
+	fetchFailed: boolean;
+	truncated: boolean;
+	failedProvider: boolean;
+}> {
+	const items: ProviderPullRequest[] = [];
+	const itemIndexByIdentity = new Map<string, number>();
+	const warnings: ProviderWarning[] = [];
+	let cursor: string | undefined;
+	let page = 0;
+	// SDK metadata failures across pages mean the collection is incomplete even when no page threw; carry
+	// this through the terminal returns instead of resetting it to false at the last page.
+	let fetchFailed = false;
+	let truncated = false;
+
+	// With no repos this is an account-wide "my PRs" sweep. The repo-scoped core rejects an empty `repos`
+	// input, so read the provider-native account-wide core instead.
+	const accountWide = repos.length === 0;
+
+	for (;;) {
+		page++;
+		// Snapshot the mutable loop cursor so the read closure doesn't capture a later-reassigned value.
+		const pageCursor = cursor;
+		const { value, warning } = await runCaptured(id, domain, connectionId, () =>
+			accountWide
+				? integration.getMyPullRequestsForUserResult(
+						{
+							state: state,
+							cursor: pageCursor,
+							includeReviewRequested: includeReviewRequested,
+							filters: filters,
+							summary: true,
+						},
+						connectionId,
+					)
+				: integration.getMyPullRequestsForReposResult(
+						repos,
+						{ state: state, filters: filters, cursor: pageCursor },
+						connectionId,
+					),
+		);
+		if (warning != null) {
+			appendDedupedWarning(warnings, warning);
+		}
+		if (value == null) {
+			// An implicit sweep may silently skip a provider that has no session before it yields data.
+			// Once a page has been returned, however, losing that session leaves an unread tail and must
+			// be attributed even when the provider wasn't explicitly requested.
+			const sessionLostAfterProgress = warning == null && page > 1;
+			const unavailable = warning == null && (attributeUnavailableProvider || sessionLostAfterProgress);
+			if (unavailable) {
+				appendDedupedWarning(warnings, noConnectionWarning(id, domain, connectionId));
+			}
+			// `warning` set → a hard read failure (incomplete items); otherwise not connected / no session.
+			return {
+				items: items,
+				warnings: warnings,
+				fetchFailed: fetchFailed || warning != null || unavailable,
+				truncated: truncated || sessionLostAfterProgress,
+				// Only a top-level first-page rejection means the provider itself failed. A later-page or
+				// per-scope failure still yielded a usable provider slice and stays represented separately.
+				failedProvider: page === 1 && (warning != null || unavailable),
+			};
+		}
+
+		// Composite account-wide queries can surface the same PR on different relationship/state pages
+		// (for example authored + review-requested, or closed + merged). Keep the first stable position but
+		// replace its value with the latest representation so a later, richer merged state wins. A provider
+		// row without a canonical URL falls back to repository-scoped identity; a row with neither stays
+		// unkeyed and is retained so unrelated incomplete rows are never collapsed.
+		for (const pullRequest of value.values) {
+			const identity = getProviderPullRequestIdentity(pullRequest);
+			if (identity == null) {
+				items.push(pullRequest);
+				continue;
+			}
+
+			const existingIndex = itemIndexByIdentity.get(identity);
+			if (existingIndex == null) {
+				itemIndexByIdentity.set(identity, items.length);
+				items.push(pullRequest);
+			} else {
+				items[existingIndex] = pullRequest;
+			}
+		}
+
+		// Assess this page's SDK metadata: append scope-aware warnings (deduped across pages), and remember
+		// whether a structured failure or incompleteness occurred.
+		const assessment = mergeAssessmentInto(warnings, id, domain, connectionId, value.metadata);
+		fetchFailed = fetchFailed || assessment.fetchFailed;
+		const pageTruncated =
+			(value as { truncated?: boolean }).truncated === true ||
+			value.paging?.truncated === true ||
+			assessment.truncated;
+		truncated = truncated || pageTruncated;
+		if (pageTruncated && !assessment.truncated) {
+			appendDedupedWarning(warnings, truncationWarning(id, domain, connectionId, 'Pull request'));
+		}
+
+		if (!(value.paging?.more ?? false)) {
+			// A read that can't confirm completeness (single-page provider reads with no `hasNextPage`)
+			// sets `paging.truncated`; propagate it (and any top-level `truncated` and SDK incompleteness)
+			// so the sweep doesn't claim an all-pages result.
+			return {
+				items: items,
+				warnings: warnings,
+				fetchFailed: fetchFailed,
+				truncated: truncated,
+				failedProvider: false,
+			};
+		}
+		if (page >= maxPages) {
+			appendDedupedWarning(warnings, truncationWarning(id, domain, connectionId, 'Pull request'));
+			return {
+				items: items,
+				warnings: warnings,
+				fetchFailed: fetchFailed,
+				truncated: true,
+				failedProvider: false,
+			};
+		}
+
+		const nextCursor = value.paging?.cursor;
+		if (nextCursor == null || nextCursor === '{}') {
+			// Provider says there is more but didn't return a usable cursor; stop rather than refetch the same page.
+			appendDedupedWarning(warnings, truncationWarning(id, domain, connectionId, 'Pull request'));
+			return {
+				items: items,
+				warnings: warnings,
+				fetchFailed: fetchFailed,
+				truncated: true,
+				failedProvider: false,
+			};
+		}
+
+		cursor = nextCursor;
+	}
+}
+
+/**
+ * Drains every page of repositories under an org for one git-host integration, threading the opaque
+ * next-cursor the provider returns. Stops at `maxPages` (marking `truncated`) or on a hard read failure
+ * (marking `fetchFailed`), keeping the pages fetched so far.
+ */
+export async function drainRepositories(
+	integration: GitHostIntegration,
+	id: IntegrationIds,
+	domain: string | undefined,
+	org: string,
+	project: string | undefined,
+	connectionId: string | undefined,
+	maxPages: number,
+): Promise<{
+	repos: ProviderRepository[];
+	warnings: ProviderWarning[];
+	fetchFailed: boolean;
+	truncated: boolean;
+}> {
+	const repos: ProviderRepository[] = [];
+	const warnings: ProviderWarning[] = [];
+	let fetchFailed = false;
+	let truncated = false;
+	let cursor: string | undefined;
+	let page = 0;
+
+	for (;;) {
+		page++;
+		const pageCursor = cursor;
+		const { value, warning } = await runCaptured(
+			id,
+			domain,
+			connectionId,
+			() =>
+				integration.getRepositoriesForOrgResult(org, {
+					project: project,
+					cursor: pageCursor,
+					connectionId: connectionId,
+				}),
+			{ warnOnMissingSession: true },
+		);
+		if (warning != null) {
+			warnings.push(warning);
+		}
+		if (value == null) {
+			const interruptedAfterProgress = page > 1;
+			if (interruptedAfterProgress && warning == null) {
+				appendDedupedWarning(warnings, truncationWarning(id, domain, connectionId, 'Repository'));
+			}
+			return {
+				repos: repos,
+				warnings: warnings,
+				fetchFailed: fetchFailed || warning != null || interruptedAfterProgress,
+				truncated: truncated || interruptedAfterProgress,
+			};
+		}
+
+		repos.push(...value.values);
+		const assessment = mergeAssessmentInto(warnings, id, domain, connectionId, value.metadata);
+		fetchFailed = fetchFailed || assessment.fetchFailed;
+		truncated = truncated || value.truncated === true || value.paging?.truncated === true || assessment.truncated;
+		if (!(value.paging?.more ?? false)) {
+			return {
+				repos: repos,
+				warnings: warnings,
+				fetchFailed: fetchFailed,
+				truncated: truncated,
+			};
+		}
+		if (page >= maxPages) {
+			return { repos: repos, warnings: warnings, fetchFailed: fetchFailed, truncated: true };
+		}
+
+		const nextCursor = value.paging?.cursor;
+		if (nextCursor == null || nextCursor === '{}') {
+			// Provider says there is more but didn't return a usable cursor; stop rather than refetch the same page.
+			return { repos: repos, warnings: warnings, fetchFailed: fetchFailed, truncated: true };
+		}
+
+		cursor = nextCursor;
+	}
+}
+
+export function resolvePullRequestSweepTargets(options: PullRequestSweepOptions | undefined): {
+	targets: readonly ProviderSweepTarget[];
+	attributeUnavailableProviders: boolean;
+} {
+	if (options?.targets != null) {
+		if (options.providerIds != null || options.connectionId != null) {
+			throw new TypeError("Pull request sweep 'targets' cannot be combined with 'providerIds' or 'connectionId'");
+		}
+
+		const seenProviderIds = new Set<IntegrationIds>();
+		for (const target of options.targets) {
+			if (seenProviderIds.has(target.providerId)) {
+				throw new TypeError(
+					`Pull request sweep targets must contain at most one target per provider; duplicate '${target.providerId}'`,
+				);
+			}
+
+			seenProviderIds.add(target.providerId);
+		}
+
+		return { targets: options.targets, attributeUnavailableProviders: true };
+	}
+
+	const providerIds =
+		options?.providerIds ?? supportedOrderedCloudIntegrationIds.filter(id => !isIssuesHostIntegrationId(id));
+	const connectionId = providerIds.length === 1 ? options?.connectionId : undefined;
+	return {
+		targets: providerIds.map(providerId => ({ providerId: providerId, connectionId: connectionId })),
+		attributeUnavailableProviders: options?.providerIds != null,
+	};
+}
+
+export async function getCurrentAccountId(
+	integration: GitHostIntegration,
+	connectionId: string | undefined,
+): Promise<string | undefined> {
+	try {
+		return (await integration.getCurrentAccount({ connectionId: connectionId }))?.id;
+	} catch {
+		// Authorship is optional enrichment; don't turn a successful PR read into a failure if identity lookup fails.
+		return undefined;
+	}
+}

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

@@ -0,0 +1,124 @@
+import type { IntegrationIds } from '../constants.js';
+import type { IssueFilter, PullRequestFilter } from '../providerFilters.js';
+import { providersMetadata } from '../providers/models.js';
+
+/**
+ * Validation of a caller-supplied relationship filter set against what a provider can express server-side.
+ *
+ * Every one of these is ALL-OR-NOTHING, and deliberately so: dropping the members a provider can't express
+ * would silently widen the read past what was asked for (requesting Author+Mention on a host without Mention
+ * would return every authored item rather than the requested set), 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 instead of reading unfiltered.
+ *
+ * The three differ only in WHICH capability they check, because they govern three different provider queries —
+ * see `IntegrationManager.getSupportedFilters`, which exposes the same capability table so a consumer can
+ * intersect against it and never reach a refusal.
+ */
+export interface ResolvedFilters<T> {
+	filters?: T[];
+	unsupported: boolean;
+}
+
+/**
+ * Validates a repo-scoped PR filter set, so an unsupported filter never trips the read core's "Unsupported
+ * filters" guard. `unsupported: true` when the caller DID request filters and the provider can't express even
+ * ONE of them — the exact negation of the read core's `providerSupportsPullRequestFilters` (`every`), so this
+ * can only ever pre-empt that guard, never disagree with it.
+ *
+ * Returns `{ filters }` (possibly undefined when none were requested — an unfiltered read is intended). Genuine
+ * "my pull requests" self-scoping is delivered by the account-wide path
+ * (`GitHostIntegration.getMyPullRequestsForUserResult`); this only governs the optional repo-scoped narrowing.
+ */
+export function resolvePullRequestFilters(
+	id: IntegrationIds,
+	filters: PullRequestFilter[] | undefined,
+): ResolvedFilters<PullRequestFilter> {
+	if (filters == null || filters.length === 0) return { unsupported: false };
+
+	const supported = providersMetadata[id]?.supportedPullRequestFilters;
+	if (supported == null || filters.some(f => !supported.includes(f))) return { unsupported: true };
+
+	return { filters: filters, unsupported: false };
+}
+
+/**
+ * Validates an account-wide PR relationship union independently from the repo-scoped capability. Dropping an
+ * unsupported member would change the requested OR set, so validation is all-or-nothing.
+ */
+export function resolveAccountWidePullRequestFilters(
+	id: IntegrationIds,
+	filters: PullRequestFilter[] | undefined,
+): ResolvedFilters<PullRequestFilter> {
+	if (filters == null || filters.length === 0) return { unsupported: false };
+
+	const supported = providersMetadata[id]?.supportedAccountWidePullRequestFilters;
+	if (supported == null || filters.some(f => !supported.includes(f))) return { unsupported: true };
+
+	return { filters: [...new Set(filters)], unsupported: false };
+}
+
+/**
+ * Validates a caller-provided issue filter set against what the provider's ACCOUNT-WIDE issue read can express
+ * server-side (`ProviderMetadata.supportedAccountWideIssueFilters`), which is a different — usually narrower —
+ * set than the repo-scoped `ProviderMetadata.supportedIssueFilters`.
+ *
+ * Dropping the unexpressible members would silently widen the read back toward the provider's own union
+ * (authored ∪ assigned ∪ mentioned for GitHub), which is the opposite of what a caller narrowing to
+ * `[Assignee]` asked for.
+ */
+export function resolveAccountWideIssueFilters(
+	id: IntegrationIds,
+	filters: IssueFilter[] | undefined,
+): ResolvedFilters<IssueFilter> {
+	if (filters == null || filters.length === 0) return { unsupported: false };
+
+	const supported = providersMetadata[id]?.supportedAccountWideIssueFilters;
+	if (supported == null || filters.some(f => !supported.includes(f))) return { unsupported: true };
+
+	return { filters: filters, unsupported: false };
+}
+
+/**
+ * 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.
+ *
+ * This matters because the filter contract is all-or-nothing: a set containing even one unsupported filter is
+ * refused outright ({@link resolvePullRequestFilters}) rather than silently narrowed, since falling through to
+ * an unfiltered fetch would return every PR instead of the user's. Without this accessor a consumer had to
+ * hardcode its own copy of the table — reachable only by importing the internal `providers/models.js`
+ * subpath — and a copy that drifts turns a supported read into an empty page with `fetchFailed`.
+ *
+ * Empty means "no filter of that kind is expressible": either the provider has no such surface (issue trackers
+ * have no pull requests; Bitbucket exposes no issues) or its metadata declares none. Callers should treat it as
+ * "don't pass filters", not as an error. Returns copies, so mutating the result can't corrupt the metadata.
+ *
+ * `issues` and `issuesAccountWide` are separate because the repo-scoped and account-wide issue reads are
+ * different provider queries with different filter surfaces, and the same `filters` input is validated against
+ * whichever one the read uses (`repos` present or not). `issuesAccountWide` is generally the narrower of the
+ * two: GitLab, for instance, can express `Assignee` and `Author` account-wide, but not `Mention`.
+ *
+ * That split describes the GIT-HOST reads only. An issue tracker (Jira/Linear/Trello) has neither — its issues
+ * live under resource → project — so it reports its filters under `issues`, which is what
+ * {@link IntegrationService.listIssueTrackerIssuesPage} validates against, and leaves `issuesAccountWide`
+ * empty. Reading a tracker's capability off `issuesAccountWide` therefore under-reports it.
+ *
+ * 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
+ * filtered read from being refused; it isn't a directive to use every filter in it.
+ */
+export function getSupportedFilters(providerId: IntegrationIds): {
+	pullRequests: PullRequestFilter[];
+	pullRequestsAccountWide: PullRequestFilter[];
+	issues: IssueFilter[];
+	issuesAccountWide: IssueFilter[];
+} {
+	const metadata = providersMetadata[providerId];
+	return {
+		pullRequests: [...(metadata?.supportedPullRequestFilters ?? [])],
+		pullRequestsAccountWide: [...(metadata?.supportedAccountWidePullRequestFilters ?? [])],
+		issues: [...(metadata?.supportedIssueFilters ?? [])],
+		issuesAccountWide: [...(metadata?.supportedAccountWideIssueFilters ?? [])],
+	};
+}