@gitkraken/core-gitlens 0.4.0 → 0.4.100

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

@@ -0,0 +1,407 @@
+import type { IssueShape } from '../../../git/models/issue.js';
+import { mergeAssessmentInto } from '../collectionMetadata.js';
+import { GitCloudHostIntegrationId, GitSelfManagedHostIntegrationId, type IntegrationIds } from '../constants.js';
+import { IssueFilter, PagingMode, providersMetadata, type ProviderReposInput } from '../providers/models.js';
+import { mergeCollectionMetadata } from '../providers/utils/providerPaging.js';
+import type { ProviderPagedResult, 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 { resolveAccountWideIssueFilters } from './filters.js';
+import {
+	drainToRequestedPage,
+	isPageNumberAdvanceable,
+	pageToCursor,
+	refusedPage,
+	resolveContinuation,
+	resolveCurrentPage,
+	toProviderPageInfo,
+	usableCursor,
+} from './paging.js';
+import {
+	gitHostOnlySurfaceWarning,
+	issuesUnsupportedWarning,
+	otherWarning,
+	truncationWarning,
+	unsupportedAccountWideIssueFiltersWarning,
+} from './warnings.js';
+
+export async function listIssuesPage(
+	ctx: ProviderReadContext,
+	options: {
+		providerId: IntegrationIds;
+		repos?: ProviderReposInput;
+		/** Narrows the account-wide read to one org/account. Requires a host with a project layer (Azure). */
+		org?: string;
+		/** Narrows the account-wide read to one project. Requires a host with a project layer (Azure). */
+		project?: string;
+		/**
+		 * Narrows to the requested relationship(s). On the account-wide path this replaces the provider's own
+		 * definition of "my issues" (GitHub/GHE: authored ∪ assigned ∪ mentioned; Azure: assigned ∪ authored;
+		 * GitLab: assigned-to-me), so `[Assignee]` yields `assignee:@me` everywhere it's expressible. A set the
+		 * provider can't express server-side is refused whole (warning + `fetchFailed`), never widened — check
+		 * getSupportedFilters first to avoid that path.
+		 */
+		filters?: IssueFilter[];
+		/** Broadens the read to every assignee. Contradicts `filters`; passing both is refused. */
+		includeAllAssignees?: boolean;
+		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>> {
+	const page = Math.max(1, options.page ?? 1);
+	if (isIssuesHostIntegrationId(options.providerId)) {
+		return refusedPage(
+			page,
+			[gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'repository issue reads')],
+			true,
+		);
+	}
+
+	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 —
+		// surface a no-connection warning + fetchFailed rather than a silent empty page.
+		const early = ctx.earlyReturnConnectionWarnings(options.providerId, options.connectionId, options.domain);
+		return refusedPage(page, early.warnings, early.fetchFailed);
+	}
+	if (!isGitHostIntegration(integration)) {
+		return refusedPage(
+			page,
+			[gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'repository issue reads')],
+			true,
+		);
+	}
+
+	await ctx.forceRefreshIfRequested(integration, options.forceSync, options.connectionId);
+
+	const domain = ctx.domainForRead(integration, options.providerId, options.connectionId, options.domain);
+	const warnOnMissingSession = warnOnMissingSessionForDomain(options.providerId, options.domain);
+
+	// A git host whose issue tracker is deprecated (Bitbucket, superseded by dedicated issue integrations)
+	// reports issues as explicitly unsupported rather than serving a partial/legacy source or a silent empty.
+	if (!integration.supportsIssues) {
+		return refusedPage(page, [issuesUnsupportedWarning(options.providerId, domain, options.connectionId)], true);
+	}
+
+	const accountWide = (options.repos?.length ?? 0) === 0;
+
+	if (accountWide) {
+		// The account-wide read is cursor-only, so a refusal can't claim the requested position — it reports
+		// page 1, per ProviderPageInfo.currentPage.
+		const refused = (warning: ProviderWarning) => refusedPage<IssueShape>(1, [warning], true);
+
+		// Checked before the provider-specific guards below: a caller passing both has a contradictory request
+		// whatever the provider, and saying so is more useful than reporting one half of it as unsupported.
+		// `filters` narrows this read to a relationship (`[Assignee]` ⇒ just assigned-to-me); `includeAllAssignees`
+		// broadens it to every assignee. Honoring either silently would answer a question the caller didn't ask.
+		if (options.filters?.length && options.includeAllAssignees === true) {
+			return refused(
+				otherWarning(
+					options.providerId,
+					domain,
+					options.connectionId,
+					'`filters` and `includeAllAssignees` are contradictory for an account-wide issue read; pass only one.',
+				),
+			);
+		}
+
+		if (
+			options.includeAllAssignees === true &&
+			(options.providerId === GitCloudHostIntegrationId.GitHub ||
+				options.providerId === GitSelfManagedHostIntegrationId.CloudGitHubEnterprise)
+		) {
+			return refused(
+				otherWarning(
+					options.providerId,
+					domain,
+					options.connectionId,
+					'`includeAllAssignees` is not supported for account-wide GitHub issue reads; scope the read to repositories instead.',
+				),
+			);
+		}
+
+		// Only a host with a project layer can narrow server-side. Reject the request rather than serving an
+		// unscoped list as if it had been narrowed: the caller would otherwise have to filter client-side,
+		// which desynchronizes the filtered `items` from this read's `hasMore`/`currentPage` and shows
+		// "no issues" for a page that simply held none of the requested project's.
+		if ((options.org != null || options.project != null) && !integration.supportsProjectDiscovery) {
+			return refused(
+				otherWarning(
+					options.providerId,
+					domain,
+					options.connectionId,
+					`Project-scoped issue reads are not supported by '${options.providerId}'; scope the read to repositories instead.`,
+				),
+			);
+		}
+
+		// Narrowing the account-wide read is only honest when the provider can express it server-side: its
+		// per-relationship queries produced the page and the cursor together, so dropping items afterward would
+		// leave `items` describing a different result set than `hasMore`/`currentPage`.
+		const resolvedIssueFilters = resolveAccountWideIssueFilters(options.providerId, options.filters);
+		if (resolvedIssueFilters.unsupported) {
+			return refused(
+				unsupportedAccountWideIssueFiltersWarning(
+					options.providerId,
+					domain,
+					options.connectionId,
+					options.filters!,
+				),
+			);
+		}
+
+		// The repo-scoped core rejects empty repos (GitHub/Bitbucket/Azure); read the account-wide,
+		// already-user-scoped core instead. GitHub exposes a composite cursor across its authored,
+		// assigned, and mentioned searches. Walk it internally when the caller supplies only page N.
+		const readAccountWidePage = (cursor: string | undefined) =>
+			runCaptured(
+				options.providerId,
+				domain,
+				options.connectionId,
+				() =>
+					integration.searchMyIssuesWithTruncationResult(undefined, undefined, options.connectionId, {
+						includeAllAssignees: options.includeAllAssignees,
+						filters: resolvedIssueFilters.filters,
+						cursor: cursor,
+						org: options.org,
+						project: options.project,
+					}),
+				{ 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;
+		}
+
+		// 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`
+		// with no error. Surface that as an explicit unsupported warning + fetchFailed rather than a silent
+		// empty success — the caller must fall back (e.g. broadenIssues over repos).
+		if (value == null && warnings.length === 0) {
+			return refused(
+				otherWarning(
+					options.providerId,
+					domain,
+					options.connectionId,
+					`Account-wide issue search is not supported by '${options.providerId}'; scope the read to repositories instead.`,
+				),
+			);
+		}
+
+		const items = requestedPageMissing ? [] : (value?.values ?? []);
+		// Fold in structured per-scope failures from the account-wide fan-out (e.g. Azure across projects):
+		// scope-aware warnings + `fetchFailed` when a scope failed, without discarding the successful items.
+		const assessment = mergeAssessmentInto(warnings, options.providerId, domain, options.connectionId, allMetadata);
+		// An account-wide search that couldn't confirm completeness (a provider cap with no cursor, or a
+		// per-scope backstop/failure) is incomplete and can't be paged; report it as truncated (+ a
+		// provider-neutral warning, unless a structured failure already explains it) rather than a complete
+		// list. Don't hard-code GitHub's "100 per category" cap here — Azure reaches this via a per-project
+		// backstop, and other providers may cap differently.
+		// The account-wide read is cursor-only (its composite cursor spans several provider searches, so a
+		// page number can't address it): `hasMore` without a real cursor is a dead end, so report it as
+		// terminal-but-incomplete rather than inviting the caller to page forever.
+		const continuation = resolveContinuation(
+			{
+				hasMore: requestedPageMissing ? false : (value?.hasMore ?? false),
+				cursor: requestedPageMissing ? undefined : usableCursor(value?.cursor),
+				truncated: currentTruncated,
+			},
+			undefined,
+		);
+		const truncated = continuation.truncated || assessment.truncated;
+		if (truncated && warnings.length === 0) {
+			warnings.push(
+				otherWarning(
+					options.providerId,
+					domain,
+					options.connectionId,
+					`Account-wide issue search for '${options.providerId}' was truncated; results may be incomplete.`,
+				),
+			);
+		}
+		return {
+			items: items,
+			warnings: warnings,
+			page: {
+				// Positional, per ProviderPageInfo.currentPage. `currentPage` already carries what the provider
+				// reported or what the internal drain counted; a requested page past the terminal cursor is
+				// reported as that empty page N. The account-wide read is cursor-only, so a `page` the caller
+				// didn't pair with a cursor is never echoed.
+				currentPage: requestedPageMissing
+					? page
+					: resolveCurrentPage({
+							providerPage: currentPage,
+							requestedPage: page,
+							suppliedCursor: options.cursor,
+							pageAdvanceable: false,
+						}),
+				itemsPerPage: items.length,
+				truncated: truncated || undefined,
+			},
+			hasMore: continuation.hasMore,
+			cursor: continuation.cursor,
+			fetchFailed: assessment.fetchFailed || pageFetchFailed || undefined,
+		};
+	}
+
+	const cursor = options.cursor ?? pageToCursor(page);
+	const { value, warning } = await runCaptured(
+		options.providerId,
+		domain,
+		options.connectionId,
+		() =>
+			// The shapes seam returns normalized IssueShape, and is overridable by a provider whose only issue
+			// client already yields shapes (serving this path without a raw ProviderIssue round-trip).
+			integration.getMyIssuesForReposAsShapesResult(
+				options.repos ?? [],
+				// Forward `page`/`pageSize` alongside the cursor so PagingMode.Repo/Project hosts honor the
+				// requested page and page size rather than ignoring a synthesized page-number cursor.
+				{
+					filters: options.filters,
+					includeAllAssignees: options.includeAllAssignees,
+					cursor: cursor,
+					page: options.page,
+					pageSize: options.itemsPerPage,
+				},
+				options.connectionId,
+			),
+		{ warnOnMissingSession: warnOnMissingSession },
+	);
+
+	let items = value?.values ?? [];
+	const warnings = warning != null ? [warning] : [];
+	let pageFetchFailed = warning != null && value == null;
+	let paged = toProviderPageInfo(options.itemsPerPage ?? items.length, value?.paging);
+	let allMetadata = value?.metadata;
+
+	// Cursor-only repo-scoped hosts (e.g. GitHub) ignore a synthesized page-number cursor, so a page-only
+	// request is advanced through the provider's own continuations (see drainToRequestedPage).
+	if (
+		providersMetadata[options.providerId]?.issuesPagingMode === PagingMode.Repos &&
+		options.page != null &&
+		options.page > 1 &&
+		options.cursor == null &&
+		paged.page.currentPage === 1
+	) {
+		const drained = await drainToRequestedPage(
+			{ items: items, paged: paged, metadata: allMetadata, fetchFailed: pageFetchFailed },
+			{
+				requestedPage: options.page,
+				itemsPerPage: options.itemsPerPage,
+				warnings: warnings,
+				readPage: (cursor: string) =>
+					runCaptured(
+						options.providerId,
+						domain,
+						options.connectionId,
+						() =>
+							integration.getMyIssuesForReposAsShapesResult(
+								options.repos ?? [],
+								{
+									filters: options.filters,
+									includeAllAssignees: options.includeAllAssignees,
+									cursor: cursor,
+									pageSize: options.itemsPerPage,
+								},
+								options.connectionId,
+							),
+						{ warnOnMissingSession: warnOnMissingSession },
+					),
+			},
+		);
+		items = drained.items;
+		paged = drained.paged;
+		allMetadata = drained.metadata;
+		pageFetchFailed = drained.fetchFailed;
+	}
+
+	// Convert the SDK collection metadata into scope-aware warnings + failure/truncation flags, appending
+	// them to any captured thrown-error warning without discarding the partial result's items.
+	const assessment = mergeAssessmentInto(warnings, options.providerId, domain, options.connectionId, allMetadata);
+	// Never advertise `hasMore` without a continuation the caller can act on, and only synthesize a page
+	// number for a host that reads it as one (see `isPageNumberAdvanceable`).
+	const issuesPageAdvanceable = isPageNumberAdvanceable(providersMetadata[options.providerId]?.issuesPagingMode);
+	const continuation = resolveContinuation(paged, issuesPageAdvanceable ? paged.page.currentPage + 1 : undefined);
+	// A provider read that couldn't confirm completeness (e.g. Bitbucket's single-page repo issue read
+	// that dropped a repo) sets `paging.truncated`; surface it as a terminal `page.truncated` so a partial
+	// page isn't published as complete. Metadata incompleteness is an independent source of the same signal.
+	const truncated = continuation.truncated || assessment.truncated;
+	if (truncated && warnings.length === 0) {
+		warnings.push(truncationWarning(options.providerId, domain, options.connectionId, 'Issue'));
+	}
+	return {
+		items: items,
+		warnings: warnings,
+		page: {
+			...paged.page,
+			// Positional, per ProviderPageInfo.currentPage: the drain (above) already advanced `paged.page` for
+			// a cursor-only host, and a caller-threaded cursor advanced the provider without one.
+			currentPage: resolveCurrentPage({
+				providerPage: paged.page.currentPage,
+				requestedPage: page,
+				suppliedCursor: options.cursor,
+				pageAdvanceable: issuesPageAdvanceable,
+			}),
+			truncated: truncated || undefined,
+		},
+		hasMore: continuation.hasMore,
+		cursor: continuation.cursor,
+		fetchFailed: assessment.fetchFailed || pageFetchFailed || undefined,
+	};
+}

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

@@ -0,0 +1,277 @@
+import type { CollectionMetadata } from '@gitkraken/provider-apis';
+import type { PagedResult } from '../../../utils/paging.js';
+import { PagingMode } from '../providers/models.js';
+import { mergeCollectionMetadata, parsePageCursor, toPageCursor } from '../providers/utils/providerPaging.js';
+import type { ProviderPagedResult, ProviderPageInfo, ProviderWarning } from '../results.js';
+import { appendDedupedWarning } from '../results.js';
+
+/**
+ * The paging mechanics shared by every paged read on the provider facade: translating the SDK's `paging` into
+ * the page-oriented shape consumers get, deciding what position and what continuation a page may honestly
+ * claim, and walking a cursor-only read forward to a requested page number.
+ *
+ * Kept in one module because the value of these rules is that they are the SAME on every read — the contract
+ * they implement is documented once on {@link ProviderPageInfo} and on `IntegrationManager`'s paging section.
+ * Copies of them drifting apart is exactly the defect this consolidation removed.
+ */
+
+/**
+ * Whether a repo-scoped read for this provider ADVANCES on a page number, so the facade may synthesize a
+ * page-number cursor, `page.currentPage` may echo the request, and a next-page number is a usable continuation.
+ *
+ * Only `PagingMode.Repos` (GitHub/GHE) is excluded: its read is cursor-only, so it accepts a page number and
+ * ignores it, answering with page 1 — which is why {@link drainToRequestedPage} exists for that mode.
+ *
+ * Every other provider, including one with no declared mode (Bitbucket Data Center), reads `page` as a 1-based
+ * page number. That last part is only true as of `@gitkraken/provider-apis` 0.54.0: before it, Bitbucket Data
+ * Center consumed `page` as a raw `start` ITEM OFFSET, so a synthesized page 3 asked for `start=3` — a window
+ * overlapping page 1 — and this facade had to withhold the synthesized cursor from it. The SDK now converts
+ * (`start = (page - 1) * limit`) and reports `nextPage` as a page number, so the guard is gone and that host
+ * can be advanced by number like the rest.
+ */
+export function isPageNumberAdvanceable(mode: PagingMode | undefined): boolean {
+	return mode !== PagingMode.Repos;
+}
+
+/**
+ * Encodes a 1-based page number as the opaque cursor the provider paging layer understands, via the same
+ * {@link toPageCursor} the providers encode with (its `parsePageCursor` counterpart is what reads these back).
+ * Page 1 needs no cursor: it is the read's own starting position.
+ */
+export function pageToCursor(page: number | undefined): string | undefined {
+	return page == null || page <= 1 ? undefined : toPageCursor(page);
+}
+
+/**
+ * Filters out the provider paging layer's empty-cursor sentinel. `providersApi` seeds its next-cursor with
+ * `'{}'` and leaves it there when the SDK reports another page without an `endCursor`, so `'{}'` means "no
+ * usable continuation" and must never be threaded back as one.
+ */
+export function usableCursor(cursor: string | undefined): string | undefined {
+	return cursor == null || cursor === '{}' ? undefined : cursor;
+}
+
+/**
+ * The terminal page a paged read returns when it refuses the request outright — the surface doesn't apply (an
+ * issue tracker asked for a repo read), the target couldn't be resolved, a capability is missing, or a filter
+ * set isn't expressible server-side. Every one of those is "no page was served": empty `items`, no continuation,
+ * and the reason carried in `warnings`.
+ *
+ * `currentPage` stays a caller-supplied parameter rather than being derived here because the refusals differ on
+ * what position they can honestly claim: a read the provider advances by page number reports the requested page,
+ * while a cursor-only account-wide read has no addressable position and reports 1 (see
+ * {@link ProviderPageInfo.currentPage}).
+ */
+export function refusedPage<T>(
+	currentPage: number,
+	warnings: ProviderWarning[],
+	fetchFailed: boolean,
+): ProviderPagedResult<T> {
+	return {
+		items: [],
+		warnings: warnings,
+		page: { currentPage: currentPage, itemsPerPage: 0 },
+		hasMore: false,
+		fetchFailed: fetchFailed || undefined,
+	};
+}
+
+/** A provider page normalized off the SDK's `paging`, before continuation and position are reconciled. */
+export interface NormalizedPage {
+	page: ProviderPageInfo;
+	hasMore: boolean;
+	cursor?: string;
+	truncated: boolean;
+}
+
+/**
+ * Normalizes a `PagedResult.paging` into the page-oriented shape Kepler consumes: `page`, `hasMore`, and an
+ * opaque `cursor` retained only for cursor-only hosts (where jumping straight to page N isn't possible, so the
+ * caller threads the cursor back instead).
+ */
+export function toProviderPageInfo(
+	itemsPerPage: number,
+	paging: { more?: boolean; cursor?: string; page?: number; pageSize?: number; truncated?: boolean } | undefined,
+): NormalizedPage {
+	let cursor: string | undefined;
+	let cursorPage: number | undefined;
+	const raw = paging?.cursor;
+	if (raw != null && raw !== '{}') {
+		try {
+			const parsed = JSON.parse(raw) as { type?: string; cursors?: unknown; page?: number };
+			// Retain opaque cursor strings for cursor-only hosts, per-repo/project cursor bundles for
+			// PagingMode.Repo/Project reads, AND page/offset cursors. The latter matters for reads with no
+			// caller-visible page param to increment — e.g. Bitbucket Server's account-wide PR read threads
+			// its next `start` offset as a `type:'page'` cursor; dropping it left the caller with
+			// `hasMore:true` and nothing to continue with. A page cursor is a valid opaque continuation, so
+			// threading it back is always safe even where a page number is also reported.
+			if (parsed.type === 'cursor' || parsed.type === 'page' || Array.isArray(parsed.cursors)) {
+				cursor = raw;
+				// Per-repo/project cursor bundles also carry the current page number so the facade can report the
+				// real page when the consumer continues using only the cursor.
+				if (Array.isArray(parsed.cursors) && parsed.page != null) {
+					cursorPage = parsed.page;
+				}
+			}
+		} catch {}
+	}
+	// Only echo a page number the provider actually honored. Numbered-page hosts report their own
+	// `paging.page`; cursor-only hosts (e.g. GitHub PR search) report none and ignore a synthesized
+	// page-number cursor — returning their first page — so echoing the requested `page` would mislabel
+	// page 1 as page N. Report page 1 in that case rather than the unapplied request. Per-repo/project
+	// bundles may carry the page explicitly in the cursor.
+	const currentPage = paging?.page ?? cursorPage ?? 1;
+	return {
+		page: {
+			currentPage: Math.max(1, currentPage),
+			itemsPerPage: paging?.pageSize ?? itemsPerPage,
+		},
+		hasMore: paging?.more ?? false,
+		cursor: cursor,
+		// A single-page provider read that couldn't confirm completeness carries `paging.truncated`;
+		// surface it so callers can flag `page.truncated` instead of publishing a partial read as complete.
+		truncated: paging?.truncated ?? false,
+	};
+}
+
+/**
+ * Reconciles a provider's `hasMore` with the continuation it actually handed back. A provider can report
+ * `hasNextPage: true` while omitting the `endCursor` (the paging layer surfaces that as the sentinel `'{}'`,
+ * which {@link toProviderPageInfo} drops), leaving `hasMore: true` with no cursor — a consumer that pages while
+ * `hasMore` would then re-request the same page forever. Prefer the real provider cursor; else synthesize the
+ * next page number, but only for a read the provider actually advances by page number (`nextPage` omitted for
+ * cursor-only reads, which ignore it and answer with their first page again); else report the read as
+ * terminal-but-incomplete (`hasMore: false` + `truncated`).
+ */
+export function resolveContinuation(
+	paged: { hasMore: boolean; cursor?: string; truncated: boolean },
+	nextPage: number | undefined,
+): { hasMore: boolean; cursor?: string; truncated: boolean } {
+	if (!paged.hasMore) return { hasMore: false, cursor: undefined, truncated: paged.truncated };
+	if (paged.cursor != null) return { hasMore: true, cursor: paged.cursor, truncated: paged.truncated };
+
+	const synthesized = nextPage != null ? pageToCursor(nextPage) : undefined;
+	if (synthesized != null) return { hasMore: true, cursor: synthesized, truncated: paged.truncated };
+
+	return { hasMore: false, cursor: undefined, truncated: true };
+}
+
+/**
+ * Resolves the position a paged read reports as `page.currentPage`, per the single convention documented on
+ * {@link ProviderPageInfo.currentPage}. Every paged read routes through here so the field means the same thing
+ * on all of them: positional, never constant-1 for one read and positional for another.
+ *
+ * `providerPage` is what the provider (or the internal drain) established — 1 means "nothing reported".
+ * `pageAdvanceable` is whether the read honors a page number at all: false for a cursor-only read, which
+ * answers with its first page when handed a synthesized page-number cursor, so the requested `page` must NOT be
+ * echoed there.
+ */
+export function resolveCurrentPage(options: {
+	providerPage: number;
+	requestedPage: number;
+	suppliedCursor: string | undefined;
+	pageAdvanceable: boolean;
+}): number {
+	if (options.providerPage > 1) return options.providerPage;
+	// A caller-threaded cursor DID advance the provider, so the caller's own position is authoritative for a
+	// provider that reports none: prefer the page the cursor encodes, else the `page` supplied alongside it.
+	if (options.suppliedCursor != null) return parsePageCursor(options.suppliedCursor) ?? options.requestedPage;
+
+	return options.pageAdvanceable ? options.requestedPage : 1;
+}
+
+/** The mutable state {@link drainToRequestedPage} carries across the pages it walks. */
+export interface DrainState<T> {
+	items: T[];
+	paged: NormalizedPage;
+	metadata: CollectionMetadata | undefined;
+	fetchFailed: boolean;
+}
+
+/**
+ * Advances a cursor-only read to the requested page when the caller supplied only `page`.
+ *
+ * A cursor-only read accepts a synthesized page-number cursor and ignores it, answering with its first page, so
+ * the requested page has to be reached by walking the provider's own opaque continuations. Only the last
+ * successfully-read page's items are kept — returning pages 1..N as "page N" would duplicate items for a normal
+ * paged consumer — while warnings and metadata are merged across the whole drained prefix.
+ *
+ * Shared by the repo-scoped and account-wide PR reads and the repo-scoped issue read so the three cannot drift:
+ * a requested page past the provider's terminal cursor is an EMPTY page N on all of them, per
+ * {@link ProviderPageInfo.currentPage}, never the last available page relabeled.
+ */
+export async function drainToRequestedPage<T>(
+	state: DrainState<T>,
+	options: {
+		requestedPage: number;
+		itemsPerPage: number | undefined;
+		warnings: ProviderWarning[];
+		readPage: (cursor: string) => Promise<{
+			value?: (PagedResult<T> & { metadata?: CollectionMetadata }) | undefined;
+			warning?: ProviderWarning;
+		}>;
+	},
+): Promise<DrainState<T>> {
+	let { items, metadata, fetchFailed } = state;
+	let currentPage = 1;
+	let currentCursor = usableCursor(state.paged.hasMore ? state.paged.cursor : undefined);
+	let currentHasMore = state.paged.hasMore && currentCursor != null;
+	let currentTruncated = state.paged.truncated;
+	// A page requested past the terminal cursor is that empty page N. Distinguished from the first read
+	// having failed outright, which is already reported as page N with no items by the caller's own state.
+	const missRequestedPage = () => {
+		items = [];
+		currentPage = options.requestedPage;
+		currentCursor = undefined;
+		currentHasMore = false;
+	};
+
+	if (fetchFailed) {
+		missRequestedPage();
+	}
+
+	while (currentPage < options.requestedPage && currentHasMore && currentCursor != null) {
+		const { value, warning } = await options.readPage(currentCursor);
+		if (warning != null) {
+			appendDedupedWarning(options.warnings, warning);
+		}
+		if (value == null) {
+			fetchFailed = true;
+			missRequestedPage();
+			break;
+		}
+
+		items = value.values;
+		metadata = mergeCollectionMetadata(metadata, value.metadata);
+		const next = toProviderPageInfo(options.itemsPerPage ?? value.values.length, value.paging);
+		currentPage++;
+		currentTruncated ||= next.truncated;
+		const nextCursor = usableCursor(next.cursor);
+		// A provider that hands back the same cursor (or none) isn't advancing; stop rather than refetch
+		// the same page forever.
+		if (nextCursor == null || nextCursor === currentCursor) {
+			currentCursor = undefined;
+			currentHasMore = false;
+			break;
+		}
+
+		currentCursor = nextCursor;
+		currentHasMore = next.hasMore;
+	}
+
+	if (currentPage < options.requestedPage) {
+		missRequestedPage();
+	}
+
+	return {
+		items: items,
+		paged: {
+			page: { currentPage: currentPage, itemsPerPage: options.itemsPerPage ?? items.length },
+			hasMore: currentHasMore,
+			cursor: currentCursor,
+			truncated: currentTruncated,
+		},
+		metadata: metadata,
+		fetchFailed: fetchFailed,
+	};
+}