@gitkraken/core-gitlens 0.5.114 → 0.5.115

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

@@ -0,0 +1,105 @@
+import type { IssueShape } from '../../../git/models/issue.js';
+import type { IntegrationIds } from '../constants.js';
+import { IssuesCloudHostIntegrationId } from '../constants.js';
+import { isIssuesIntegration } from '../models/issuesIntegration.js';
+import type { ProviderResult, ProviderWarning } from '../results.js';
+import { isIssuesHostIntegrationId } from '../utils/integration.utils.js';
+import type { ProviderReadContext } from './context.js';
+import { runCaptured } from './drains.js';
+import { issueTrackerOnlySurfaceWarning, otherWarning } from './warnings.js';
+
+export interface TrackerIssueResult {
+	key: string;
+	/**
+	 * The resolved issue, or `undefined` when it provably does not exist or is not visible to this connection.
+	 * A failed read returns no item and sets `fetchFailed`.
+	 */
+	issue?: IssueShape;
+}
+
+/** Issue trackers are cloud-only, so this read takes no `domain`. */
+export async function getTrackerIssue(
+	ctx: ProviderReadContext,
+	options: {
+		providerId: IntegrationIds;
+		resourceId: string;
+		resourceUrl?: string;
+		key: string;
+		connectionId?: string;
+	},
+): Promise<ProviderResult<TrackerIssueResult>> {
+	const refused = (warning: ProviderWarning): ProviderResult<TrackerIssueResult> => ({
+		items: [],
+		warnings: [warning],
+		fetchFailed: true,
+	});
+	const surface = 'Issue resolution by key';
+
+	if (!isIssuesHostIntegrationId(options.providerId)) {
+		return refused(issueTrackerOnlySurfaceWarning(options.providerId, options.connectionId, surface));
+	}
+
+	if (options.resourceId.trim().length === 0) {
+		return refused(
+			otherWarning(options.providerId, undefined, options.connectionId, `${surface} requires a resource id.`),
+		);
+	}
+
+	if (options.key.trim().length === 0) {
+		return refused(
+			otherWarning(options.providerId, undefined, options.connectionId, `${surface} requires an issue key.`),
+		);
+	}
+
+	const resourceUrl = options.resourceUrl?.trim() || undefined;
+	if (options.providerId === IssuesCloudHostIntegrationId.Jira && resourceUrl == null) {
+		return refused(
+			otherWarning(
+				options.providerId,
+				undefined,
+				options.connectionId,
+				`${surface} requires the Jira resource URL so the result contains a browser link without resource discovery.`,
+			),
+		);
+	}
+
+	const integration = await ctx.getIntegrationForRead(options.providerId, options.connectionId);
+	if (integration == null) {
+		const early = ctx.earlyReturnConnectionWarnings(options.providerId, options.connectionId);
+		return { items: [], warnings: early.warnings, fetchFailed: early.fetchFailed || undefined };
+	}
+	if (!isIssuesIntegration(integration)) {
+		return refused(issueTrackerOnlySurfaceWarning(options.providerId, options.connectionId, surface));
+	}
+	if (!integration.supportsIssueLookupByResourceId) {
+		return refused(
+			otherWarning(
+				options.providerId,
+				undefined,
+				options.connectionId,
+				`${surface} is not supported by '${options.providerId}'; its single-issue read cannot prove an absence, so a miss would not be safe to cache.`,
+			),
+		);
+	}
+
+	const domain = ctx.domainForRead(integration, options.providerId, options.connectionId);
+	const issue = await runCaptured(
+		options.providerId,
+		domain,
+		options.connectionId,
+		() =>
+			integration.getIssueByResourceIdResult(options.resourceId, options.key, {
+				connectionId: options.connectionId,
+				resourceUrl: resourceUrl,
+			}),
+		{ warnOnMissingSession: true },
+	);
+	if (issue.warning != null) {
+		return refused(issue.warning);
+	}
+
+	return {
+		items: [{ key: options.key, ...(issue.value != null ? { issue: issue.value } : {}) }],
+		warnings: [],
+	};
+}

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

@@ -8,7 +8,7 @@ import type {
 	PullRequestSorting,
 } from '../providerFilters.js';
 import { providersMetadata } from '../providers/models.js';
-import type { ProviderWarning } from '../results.js';
+import type { ProviderWarning, ProviderWarningOmissionRecovery } from '../results.js';
 import type { IssueSearchCriteriaRejection, PullRequestSearchCriteriaRejection } from './filters.js';
 import type { UnmergeableIssueSort, UnsupportedIssueSortRejection } from './ordering.js';
 
@@ -101,21 +101,23 @@ export function issueTrackerOnlySurfaceWarning(
 	);
 }
 
-/**
- * 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';
+/** Why a facade-driven read returned fewer results than requested. */
+export type IncompleteReadCause = 'interrupted' | 'page-budget' | 'exhausted' | 'scope-too-large';
+
+function recoveryForIncompleteReadCause(cause: IncompleteReadCause): ProviderWarningOmissionRecovery {
+	switch (cause) {
+		case 'page-budget':
+			return 'page-budget';
+		case 'scope-too-large':
+			return 'narrow-scope';
+		case 'interrupted':
+		case 'exhausted':
+			return 'none';
+		default:
+			cause satisfies never;
+			return 'none';
+	}
+}
 
 /**
  * Builds the warning for a read that returned less than everything, carrying the two facts a consumer cannot
@@ -143,7 +145,7 @@ export function incompleteReadWarning(
 		...warning,
 		omission: {
 			kind: 'pagination-incomplete',
-			recovery: cause === 'page-budget' ? 'page-budget' : 'none',
+			recovery: recoveryForIncompleteReadCause(cause),
 		},
 	};
 }
@@ -192,6 +194,10 @@ function truncationMessage(id: IntegrationIds, readKind: TruncatedReadKind, caus
 			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.`;
+		case 'scope-too-large':
+			// Says what is true — the scope is larger than a read of it — rather than blaming the provider for a
+			// ceiling that is ours, and names the remedy that exists, since no retry or budget has one.
+			return `${readKind} read for '${id}' covers more than one read can return; narrow the scope to read the rest.`;
 	}
 	// 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`

package/src/plus/integrations/results.ts

@@ -35,27 +35,11 @@ export type ProviderWarningKind = 'auth' | 'rate-limit' | 'not-found' | 'no-conn
 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.
+ * How a consumer can recover omitted results. `page-budget` reruns with a larger budget; `narrow-scope`
+ * requests a smaller server-side scope; `none` promises neither. Switch on the exact value because only
+ * `page-budget` is a fetch-more action.
  */
-export type ProviderWarningOmissionRecovery = 'none' | 'page-budget';
+export type ProviderWarningOmissionRecovery = 'none' | 'page-budget' | 'narrow-scope';
 
 /** Which repository / project / resource an omission is attributed to. All fields optional; a scope may name none. */
 export interface ProviderWarningOmissionScope {

package/src/utils/promise.ts

@@ -121,6 +121,21 @@ export async function mapBounded<T, R>(
 	return results;
 }
 
+/** Settles each task without stopping the sliding window when one of them rejects. */
+export function mapSettledBounded<T, R>(
+	items: readonly T[],
+	concurrency: number,
+	task: (item: T, index: number) => Promise<R>,
+): Promise<PromiseSettledResult<Awaited<R>>[]> {
+	return mapBounded(items, concurrency, async (item, index): Promise<PromiseSettledResult<Awaited<R>>> => {
+		try {
+			return { status: 'fulfilled', value: await task(item, index) };
+		} catch (reason) {
+			return { status: 'rejected', reason: reason };
+		}
+	});
+}
+
 export class PromiseCancelledError<T extends Promise<any> = Promise<any>> extends Error {
 	constructor(
 		public readonly promise: T,