@gitkraken/core-gitlens 0.5.101 → 0.5.102

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

@@ -4,6 +4,7 @@ import type { IntegrationIds } from '../constants.js';
 import type { ProviderPullRequest, ProviderReposInput, PullRequestFilter } from '../providers/models.js';
 import { fromProviderPullRequest, PagingMode, providersMetadata } from '../providers/models.js';
 import type { ProviderPagedResult } from '../results.js';
+import { reconcileOmissionsWithFailure } from '../results.js';
 import {
 	isGitHostIntegration,
 	isIssuesHostIntegrationId,
@@ -226,8 +227,21 @@ export async function listPullRequestsPage(
 	// the page may be incomplete. 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, 'Pull request'));
+		// `exhausted`, never `page-budget`: a paged read has no budget the caller can raise. Ordinary
+		// continuation is already expressed by `hasMore`/`cursor`, so reaching here means this page itself
+		// couldn't be completed — raising anything would return the same page.
+		warnings.push(
+			truncationWarning(
+				options.providerId,
+				domain,
+				options.connectionId,
+				'Pull request',
+				assessment.fetchFailed || pageFetchFailed ? 'interrupted' : 'exhausted',
+			),
+		);
 	}
+	// A metadata omission from an earlier page asserts the read succeeded; a later page may since have failed.
+	reconcileOmissionsWithFailure(warnings, assessment.fetchFailed || pageFetchFailed);
 	const currentAccountId = items.some(pr => pr.author != null)
 		? await getCurrentAccountId(integration, options.connectionId)
 		: undefined;

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

@@ -93,22 +93,90 @@ export function issueTrackerOnlySurfaceWarning(
 }
 
 /**
- * Builds a warning for a drain that stopped short of completeness (hit a page backstop, or a single-page read
- * that couldn't confirm it drained everything). `truncated`/`allPages` already carry this on the result, but
- * consumers that only inspect `warnings` would otherwise see no signal the read is partial.
+ * Why a read the facade drove itself returned less than everything. The two questions a consumer cannot
+ * answer from `truncated` or from the message, kept together because they are decided together:
+ *
+ * - `interrupted`: the read did NOT succeed — the session went away, a later page failed. It leaves an unread
+ *   tail like the others, but it is a failure: it sets `fetchFailed`, and a retry is exactly the right move.
+ *   Gets no omission at all, since the omission asserts the opposite.
+ * - `page-budget`: the drain stopped at its own `maxPages`, with a usable cursor still in hand. The items ARE
+ *   reachable and were simply not fetched, so re-running with a higher budget returns them.
+ * - `exhausted`: everything else that succeeded and came back short — the provider capped the page it served,
+ *   advertised another page without a usable cursor (or with one it had already handed out), or a read could
+ *   not confirm it had drained everything. The default of the three: choose it whenever a raisable budget is
+ *   not demonstrably what stopped the read, so a consumer is never offered a fetch that cannot deliver.
+ */
+export type IncompleteReadCause = 'interrupted' | 'page-budget' | 'exhausted';
+
+/**
+ * Builds the warning for a read that returned less than everything, carrying the two facts a consumer cannot
+ * recover on its own: did the request succeed, and would anything fetch the rest?
+ *
+ * Every incompleteness warning the facade raises on its own terms goes through here, so no read can drift
+ * into claiming success on a failure or offering a "load more" that cannot deliver. The omission it attaches
+ * is the same shape `assessCollectionMetadata` derives from SDK metadata, so a consumer never has to care
+ * which layer noticed the gap.
+ *
+ * No `scope`: this applies to the whole read, not to one repository or project the way an SDK-attributed
+ * omission can, so a consumer acting on `recovery` re-runs the read itself.
+ */
+export function incompleteReadWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	message: string,
+	cause: IncompleteReadCause,
+): ProviderWarning {
+	const warning = otherWarning(id, domain, connectionId, message);
+	if (cause === 'interrupted') return warning;
+
+	return {
+		...warning,
+		omission: {
+			kind: 'pagination-incomplete',
+			recovery: cause === 'page-budget' ? 'page-budget' : 'none',
+		},
+	};
+}
+
+/**
+ * {@link incompleteReadWarning} for a paged or drained read, phrased per surface. `'Account-wide issue search'`
+ * names the composite read that spans several provider searches rather than one surface.
  */
 export function truncationWarning(
 	id: IntegrationIds,
 	domain: string | undefined,
 	connectionId: string | undefined,
-	readKind: 'Pull request' | 'Issue' | 'Repository',
+	readKind: 'Pull request' | 'Issue' | 'Repository' | 'Account-wide issue search',
+	/**
+	 * Deliberately REQUIRED and not defaulted: a default would make one of these the silent fallback at any
+	 * call site that forgot it, and both of the claims it carries — "the request succeeded" and "more can be
+	 * fetched" — are ones this warning must never make by accident.
+	 */
+	cause: IncompleteReadCause,
 ): ProviderWarning {
-	return otherWarning(
-		id,
-		domain,
-		connectionId,
-		`${readKind} read for '${id}' was truncated (a page backstop was reached); results may be incomplete.`,
-	);
+	return incompleteReadWarning(id, domain, connectionId, truncationMessage(id, readKind, cause), cause);
+}
+
+function truncationMessage(
+	id: IntegrationIds,
+	readKind: 'Pull request' | 'Issue' | 'Repository' | 'Account-wide issue search',
+	cause: IncompleteReadCause,
+): string {
+	switch (cause) {
+		case 'interrupted':
+			// Deliberately does not name a mechanism. This fires both when a page was lost mid-drain and when a
+			// drain that latched an earlier scope failure later stopped for its own reasons; "was interrupted"
+			// would be false in the second. What is true in both is that something failed and results are gone.
+			return `${readKind} read for '${id}' did not complete; some results are missing and the read reported a failure.`;
+		case 'page-budget':
+			return `${readKind} read for '${id}' stopped at its page budget; more results can be read by raising it.`;
+		case 'exhausted':
+			return `${readKind} read for '${id}' was truncated and cannot be continued; results may be incomplete.`;
+	}
+	// No `default`: `IncompleteReadCause` is declared in this file, so `noImplicitReturns` already fails the
+	// build here if a cause is added without its own wording. (`collectionOmissionMessage`'s `satisfies never`
+	// is not the same case — that union is the SDK's, and can widen under a dependency bump.)
 }
 
 /** Warning for an account-wide issue read whose requested filters the provider can't express server-side. */

package/src/plus/integrations/results.ts

@@ -15,6 +15,72 @@ export interface ConnectionStateChangeEvent {
  */
 export type ProviderWarningKind = 'auth' | 'rate-limit' | 'not-found' | 'no-connection' | 'other';
 
+/**
+ * Why a read that SUCCEEDED still withheld results:
+ * - `provider-limit`: the provider refuses to serve past a cap it enforces (GitHub search's 1,000-result
+ *   ceiling, Trello's `cards_limit`), so the excess is unreachable through that query.
+ * - `recovery-budget`: the internal partitioned recovery stopped spending upstream requests before it ran
+ *   out of partitions to visit.
+ * - `pagination-incomplete`: pages were left unread — a sub-scope of a multi-scope read that was not drained,
+ *   a drain that stopped at its own page backstop, or a provider that advertised another page and gave no way
+ *   to reach it. These have DIFFERENT remedies, so the kind alone does not say whether more can be fetched;
+ *   read {@link ProviderWarningOmission.recovery} for that.
+ *
+ * Mirrors the vocabulary the SDK reports. Declared here rather than imported so this module stays free of
+ * `@gitkraken/provider-apis` types (see the export block in `index.ts`); `collectionMetadata.ts` holds the
+ * compile-time link, so an SDK bump that adds a kind fails the build at that boundary.
+ */
+export type ProviderWarningOmissionKind = 'provider-limit' | 'recovery-budget' | 'pagination-incomplete';
+
+/**
+ * What, if anything, would fetch the withheld results — the question `kind` cannot answer.
+ *
+ * `kind` says WHY results are missing, and two omissions of the same kind can need opposite handling: a drain
+ * that stopped at a caller-settable page budget and a provider that advertised another page without a usable
+ * cursor are both `pagination-incomplete`, but only the first can be fetched. A consumer offering a "load
+ * more" affordance gates it on this, never on `kind`.
+ *
+ * - `none`: nothing the consumer can call returns the missing items — a provider-enforced cap, an internal
+ *   budget it does not control, or a continuation the provider refused to hand back. Say the results are
+ *   capped; do not offer to fetch more.
+ * - `page-budget`: re-run the SAME read with a higher page budget (`maxPages` on the sweep options). Note this
+ *   re-reads from the start rather than continuing — a sweep exposes no cursor — so it is a deliberate,
+ *   user-initiated action, not something to retry automatically.
+ *
+ * Required, not optional: an absent value would be indistinguishable from `none` while actually meaning "this
+ * producer didn't say", which is the ambiguity {@link ProviderWarning.omission} exists to remove. And a
+ * conservative union on purpose — it names only what a producer can PROVE. A value is added when some layer
+ * can vouch for it, never so that a plausible-looking case has something to map to; see
+ * `collectionMetadata.ts` for the SDK shape that looks recoverable and is not.
+ */
+export type ProviderWarningOmissionRecovery = 'none' | 'page-budget';
+
+/** Which repository / project / resource an omission is attributed to. All fields optional; a scope may name none. */
+export interface ProviderWarningOmissionScope {
+	providerId?: string;
+	resourceId?: string;
+	projectId?: string;
+	repositoryId?: string;
+}
+
+export interface ProviderWarningOmission {
+	kind: ProviderWarningOmissionKind;
+	/**
+	 * Whether anything would fetch the missing items, and what. Gate a "load more" affordance on this rather
+	 * than on `kind` — see {@link ProviderWarningOmissionRecovery}.
+	 */
+	recovery: ProviderWarningOmissionRecovery;
+	/**
+	 * The cap the provider enforces, when it reports one. NOT a result count for every kind: on
+	 * `recovery-budget` this is a REQUEST budget and must not be shown to a user as a number of results.
+	 */
+	limit?: number;
+	/** Total matches the provider reported, when it reports one. Only GitHub's search cap does today. */
+	totalCount?: number;
+	/** Which repository / project / resource was affected, when one is attributed. */
+	scope?: ProviderWarningOmissionScope;
+}
+
 export interface ProviderWarning {
 	providerId: IntegrationIds;
 	/** Disambiguates connections on self-managed hosts (where one provider id spans multiple domains). */
@@ -25,6 +91,29 @@ export interface ProviderWarning {
 	kind: ProviderWarningKind;
 	/** Convenience mirror of `kind === 'auth'`. */
 	isAuth: boolean;
+	/**
+	 * Present when this warning describes results the read could not return even though the request itself
+	 * SUCCEEDED — a provider-enforced cap, an exhausted recovery budget, a page budget, or a sub-scope the read
+	 * did not drain.
+	 *
+	 * Its presence is the signal: an omission is not a failure. Message it as incompleteness rather than as a
+	 * failed read, and do NOT derive that from `message`, which is English prose and subject to rewording.
+	 * `kind` stays `'other'` for these, so the failure discriminant keeps meaning exactly what it meant before
+	 * this field existed.
+	 *
+	 * Whether anything would fetch the rest is a SEPARATE question — read {@link ProviderWarningOmission.recovery},
+	 * not `kind`, and never assume a retry of the same request returns more.
+	 *
+	 * `limit` / `totalCount` / `scope` are forwarded only when they are reported; most omissions carry none of
+	 * the three, so render correctly without them — and see {@link ProviderWarningOmission.limit} before
+	 * showing that figure as a result count.
+	 *
+	 * Its ABSENCE proves nothing. It is never set on a warning derived from a caught exception (see
+	 * {@link toProviderWarning}) or from a structured scope failure — those are failures, and the field would
+	 * be a lie there. But it is also absent whenever incompleteness was reported without naming what was left
+	 * out, so treat a bare `kind: 'other'` warning as unclassified rather than as a proven failure.
+	 */
+	omission?: ProviderWarningOmission;
 }
 
 export interface ProviderPageInfo {
@@ -259,14 +348,94 @@ export function toProviderWarning(
 	};
 }
 
-/** A stable key for deduplicating warnings accumulated across drained pages / fan-out scopes. */
-function providerWarningKey(warning: ProviderWarning): string {
-	return [warning.providerId, warning.connectionId ?? '', warning.domain ?? '', warning.kind, warning.message].join(
+/**
+ * A scope's identity, as the stable string that keys it.
+ *
+ * The single definition of what "the same scope" means, shared by the failure and omission dedup keys in
+ * `providerPaging.ts` and by {@link providerWarningKey} below, so a scope gaining a field is one edit rather
+ * than three. `providerId` is included: the same repository ID under two providers is two scopes.
+ *
+ * The parameter is structural rather than the SDK's `CollectionScope` so this module keeps naming no
+ * `@gitkraken/provider-apis` types (see the export block in `index.ts`) while still serving its SDK-facing
+ * callers, which pass that type in unchanged.
+ */
+export function collectionScopeKey(scope: ProviderWarningOmissionScope | undefined): string {
+	return [scope?.providerId ?? '', scope?.resourceId ?? '', scope?.projectId ?? '', scope?.repositoryId ?? ''].join(
 		' ',
 	);
 }
 
-/** Appends `warning` to `into` only when an equal warning (by provider/connection/domain/kind/message) is absent. */
+/**
+ * The omission's contribution to a warning's identity — empty when there is none, so a warning without an
+ * omission keeps deduping exactly as it did before the field existed.
+ *
+ * Two omissions of different kinds do produce different `message` values today, so message alone would still
+ * separate them. That is incidental: the premise of `omission` is that consumers must not depend on prose
+ * carrying the distinguishing fact, and this key must not either.
+ */
+function providerWarningOmissionKey(omission: ProviderWarningOmission | undefined): string {
+	if (omission == null) return '';
+
+	return [
+		omission.kind,
+		omission.recovery,
+		omission.limit ?? '',
+		omission.totalCount ?? '',
+		collectionScopeKey(omission.scope),
+	].join(' ');
+}
+
+/**
+ * Strips the omission from every warning in `warnings` when the read as a whole failed.
+ *
+ * An omission asserts the request SUCCEEDED, and a drain only learns it failed AFTER it may have emitted one:
+ * an early page can report its own truncation and then a later page can die. Deciding per warning, at the
+ * moment each is built, cannot see that future — so the aggregate is reconciled once, here, where
+ * `fetchFailed` is final. Call it at the point a read returns its `fetchFailed`.
+ *
+ * Re-dedupes as it goes: the omission is part of a warning's identity, so two warnings that differed only
+ * there become identical once it is gone, and the array's contract is that no two entries are equal.
+ *
+ * Mutates in place: the warning array is the one being returned, and callers accumulate into it across pages.
+ */
+export function reconcileOmissionsWithFailure(warnings: ProviderWarning[], fetchFailed: boolean): void {
+	if (!fetchFailed || !warnings.some(w => w.omission != null)) return;
+
+	const reconciled: ProviderWarning[] = [];
+	for (const warning of warnings) {
+		if (warning.omission == null) {
+			appendDedupedWarning(reconciled, warning);
+			continue;
+		}
+
+		const { omission: _omission, ...rest } = warning;
+		appendDedupedWarning(reconciled, rest);
+	}
+
+	warnings.splice(0, warnings.length, ...reconciled);
+}
+
+/**
+ * A stable key for deduplicating warnings accumulated across drained pages / fan-out scopes.
+ *
+ * `message` stays LAST. It is the only free-form segment — provider prose, spaces and all — so anything
+ * appended after it could be impersonated by a message that happens to end in the same text.
+ */
+function providerWarningKey(warning: ProviderWarning): string {
+	return [
+		warning.providerId,
+		warning.connectionId ?? '',
+		warning.domain ?? '',
+		warning.kind,
+		providerWarningOmissionKey(warning.omission),
+		warning.message,
+	].join(' ');
+}
+
+/**
+ * Appends `warning` to `into` only when an equal warning (by provider/connection/domain/kind/message, plus the
+ * structured omission when one is present) is absent.
+ */
 export function appendDedupedWarning(into: ProviderWarning[], warning: ProviderWarning): void {
 	const key = providerWarningKey(warning);
 	if (into.some(existing => providerWarningKey(existing) === key)) return;