@gitkraken/core-gitlens 0.3.1 → 0.4.100

package/src/plus/integrations/providers/trello.ts

@@ -0,0 +1,205 @@
+import type { Account } from '../../../git/models/author.js';
+import type { Issue, IssueShape } from '../../../git/models/issue.js';
+import type { IssueOrPullRequest, IssueOrPullRequestType } from '../../../git/models/issueOrPullRequest.js';
+import type { IssueResourceDescriptor, ResourceDescriptor } from '../../../git/models/resourceDescriptor.js';
+import { isIssueResourceDescriptor } from '../../../git/utils/resourceDescriptor.utils.js';
+import type { IntegrationAuthenticationProviderDescriptor } from '../authentication/integrationAuthenticationProvider.js';
+import type { ProviderAuthenticationSession } from '../authentication/models.js';
+import { toTokenWithInfo } from '../authentication/models.js';
+import { IssuesCloudHostIntegrationId } from '../constants.js';
+import { IntegrationReadUnavailableError } from '../errors.js';
+import { IssuesIntegration } from '../models/issuesIntegration.js';
+import type { IssueFilter } from './models.js';
+import { fromProviderIssue, providersMetadata, toIssueShape } from './models.js';
+
+const metadata = providersMetadata[IssuesCloudHostIntegrationId.Trello];
+const authProvider = Object.freeze({ id: metadata.id, scopes: metadata.scopes });
+
+/** A Trello board, surfaced as both a "resource" (org analogue) and a "project" for issue reads. */
+export interface TrelloBoardDescriptor extends IssueResourceDescriptor {}
+
+export class TrelloIntegration extends IssuesIntegration<IssuesCloudHostIntegrationId.Trello> {
+	readonly authProvider: IntegrationAuthenticationProviderDescriptor = authProvider;
+
+	override get id(): IssuesCloudHostIntegrationId.Trello {
+		return IssuesCloudHostIntegrationId.Trello;
+	}
+	protected override get key(): 'trello' {
+		return 'trello';
+	}
+	override get name(): string {
+		return metadata.name;
+	}
+	override get domain(): string {
+		return metadata.domain;
+	}
+
+	/** The Trello client requires the app key paired with the token; a session without one can't read. */
+	private appKeyFor(session: ProviderAuthenticationSession): string | undefined {
+		return session.appKey;
+	}
+
+	/**
+	 * Resolves the app key or throws — a session that authenticated but carries no app key can't read Trello,
+	 * and must be surfaced as a broken read (warning + fetchFailed) rather than an empty account.
+	 */
+	private requireAppKey(session: ProviderAuthenticationSession): string {
+		const appKey = this.appKeyFor(session);
+		if (appKey == null) {
+			throw new IntegrationReadUnavailableError(metadata.name, 'missing app key (session has no appKey)');
+		}
+		return appKey;
+	}
+
+	protected override async getProviderAccountForResource(
+		session: ProviderAuthenticationSession,
+		_resource: ResourceDescriptor,
+	): Promise<Account | undefined> {
+		const appKey = this.requireAppKey(session);
+
+		const api = await this.getProvidersApi();
+		const user = await api.getTrelloCurrentUser(toTokenWithInfo(this.id, session), appKey);
+		if (user == null) return undefined;
+
+		return {
+			provider: this,
+			id: user.id,
+			name: user.name,
+			username: user.username,
+			email: user.email,
+			avatarUrl: user.avatarUrl ?? undefined,
+		};
+	}
+
+	protected override async getProviderResourcesForUser(
+		session: ProviderAuthenticationSession,
+	): Promise<TrelloBoardDescriptor[] | undefined> {
+		const appKey = this.requireAppKey(session);
+
+		const api = await this.getProvidersApi();
+		const boards = await api.getTrelloBoardsForCurrentUser(toTokenWithInfo(this.id, session), appKey);
+		return boards?.map(b => ({ key: b.id, id: b.id, name: b.name }));
+	}
+
+	protected override getProviderProjectsForResources(
+		_session: ProviderAuthenticationSession,
+		resources: ResourceDescriptor[],
+	): Promise<TrelloBoardDescriptor[] | undefined> {
+		// Trello boards are both the resource and the project scope, so projects are the boards themselves.
+		return Promise.resolve(
+			resources.filter(isIssueResourceDescriptor).map(r => ({ key: r.key, id: r.id, name: r.name })),
+		);
+	}
+
+	protected override async getProviderIssuesForProject(
+		session: ProviderAuthenticationSession,
+		project: ResourceDescriptor,
+		options?: { user?: string; filters?: IssueFilter[] },
+	): Promise<IssueShape[] | undefined> {
+		return (await this.getProviderIssuesForProjectWithTruncation(session, project, options))?.values;
+	}
+
+	protected override async getProviderIssuesForProjectWithTruncation(
+		session: ProviderAuthenticationSession,
+		project: ResourceDescriptor,
+		options?: { user?: string; filters?: IssueFilter[] },
+	): Promise<{ values: IssueShape[]; truncated: boolean } | undefined> {
+		// A non-issue descriptor genuinely has nothing to read (empty), but a missing app key is a broken read.
+		if (!isIssueResourceDescriptor(project)) return undefined;
+
+		const appKey = this.requireAppKey(session);
+
+		const api = await this.getProvidersApi();
+		const tokenWithInfo = toTokenWithInfo(this.id, session);
+
+		// Enrich issues with their board list names (card status), mirroring gitkraken.dev's Trello reads.
+		const lists = await api.getTrelloListsForBoard(tokenWithInfo, appKey, project.id);
+		const trelloBoardListsById = lists?.reduce<Record<string, { name: string }>>((acc, list) => {
+			acc[list.id] = { name: list.name };
+			return acc;
+		}, {});
+		const boardProject = {
+			id: project.id,
+			name: project.name,
+			resourceId: project.id,
+			resourceName: project.name,
+		};
+
+		const result = await api.getTrelloIssuesForBoard(tokenWithInfo, appKey, project.id, {
+			assigneeLogins: options?.user != null ? [options.user] : undefined,
+			trelloBoardListsById: trelloBoardListsById,
+		});
+
+		const values = result.values.flatMap(issue => {
+			const mapped = toIssueShape(issue, this);
+			return mapped == null ? [] : [{ ...mapped, project: boardProject } satisfies IssueShape];
+		});
+
+		// Trello's search caps results and reports the cap through `metadata.completeness` (partial/unknown),
+		// never a cursor. Surface that as terminal truncation; there is no next page to fetch, so retrying the
+		// same read cannot recover the omitted cards (D11).
+		const truncated = result.metadata != null && result.metadata.completeness !== 'complete';
+		return { values: values, truncated: truncated };
+	}
+
+	protected override searchProviderMyIssues(
+		_session: ProviderAuthenticationSession,
+		_resources?: ResourceDescriptor[],
+		_cancellation?: AbortSignal,
+	): Promise<IssueShape[] | undefined> {
+		// Trello has no cross-board "issues assigned to me" endpoint; issues are read per board via
+		// getIssuesForProject. Callers that need them enumerate boards first.
+		return Promise.resolve(undefined);
+	}
+
+	protected override getProviderLinkedIssueOrPullRequest(
+		_session: ProviderAuthenticationSession,
+		_resource: ResourceDescriptor,
+		_id: { id: string; key: string },
+		_type: undefined | IssueOrPullRequestType,
+	): Promise<IssueOrPullRequest | undefined> {
+		return Promise.resolve(undefined);
+	}
+
+	protected override async getProviderIssue(
+		session: ProviderAuthenticationSession,
+		resource: ResourceDescriptor,
+		id: string,
+	): Promise<Issue | undefined> {
+		if (!isIssueResourceDescriptor(resource)) return undefined;
+
+		const appKey = this.requireAppKey(session);
+		const api = await this.getProvidersApi();
+		const tokenWithInfo = toTokenWithInfo(this.id, session);
+		const lists = await api.getTrelloListsForBoard(tokenWithInfo, appKey, resource.id);
+		const trelloBoardListsById = lists?.reduce<Record<string, { name: string }>>((acc, list) => {
+			acc[list.id] = { name: list.name };
+			return acc;
+		}, {});
+
+		// Branch-association round-trips use the encoded entity identifier's stable Trello card id. Resolve that
+		// directly so large boards don't require a capped whole-board scan; keep a numeric idShort fallback so
+		// legacy/manual callers that still pass the board-local display number continue to resolve.
+		let issue = await api.getTrelloCard(tokenWithInfo, appKey, id, {
+			trelloBoardListsById: trelloBoardListsById,
+		});
+		if (issue == null && /^[0-9]+$/.test(id)) {
+			issue = (
+				await api.getTrelloIssuesForBoard(tokenWithInfo, appKey, resource.id, {
+					trelloBoardListsById: trelloBoardListsById,
+				})
+			).values.find(issue => issue.number === id);
+		}
+
+		return issue != null
+			? fromProviderIssue(issue, this, {
+					project: {
+						id: resource.id,
+						name: resource.name,
+						resourceId: resource.id,
+						resourceName: resource.name,
+					},
+				})
+			: undefined;
+	}
+}

package/src/plus/integrations/providers/utils/providerPaging.ts

@@ -0,0 +1,177 @@
+import type { CollectionCompleteness, CollectionMetadata, CollectionScopeFailure } from '@gitkraken/provider-apis';
+import { isCancellationError } from '../../../../utils/cancellation.js';
+import { toCollectionScopeFailure } from '../../collectionMetadata.js';
+import type { ProviderApiPagedResult, ProviderHierarchyResult } from '../models.js';
+
+/**
+ * Encodes an opaque numeric paging token as the `{ value, type: 'page' }` cursor the paging layer uses.
+ * The value is whatever the consumer round-trips unchanged: a 1-based page number for numbered-page reads,
+ * or a provider offset (e.g. Bitbucket Server's `nextPageStart`) that is never reinterpreted here.
+ */
+export function toPageCursor(page: number): string {
+	return JSON.stringify({ value: page, type: 'page' });
+}
+
+/** Extracts the numeric paging token from a `{ value, type: 'page' }` cursor; undefined when absent/malformed. */
+export function parsePageCursor(cursor: string | undefined): number | undefined {
+	if (cursor == null || cursor === '{}') return undefined;
+
+	try {
+		const parsed = JSON.parse(cursor) as { value?: unknown; type?: unknown };
+		if (parsed.type === 'page' && typeof parsed.value === 'number') return parsed.value;
+	} catch {}
+
+	return undefined;
+}
+
+/** Preserves successful sibling scopes, but doesn't turn an all-scope provider failure into an empty success. */
+export async function flatSettledOrThrow<T>(promises: Promise<T[]>[]): Promise<T[]> {
+	const results = await Promise.allSettled(promises);
+	const fulfilled = results.filter((result): result is PromiseFulfilledResult<T[]> => result.status === 'fulfilled');
+	if (fulfilled.length === 0) {
+		const rejected = results.find((result): result is PromiseRejectedResult => result.status === 'rejected');
+		if (rejected != null) throw rejected.reason;
+	}
+
+	return fulfilled.flatMap(result => result.value);
+}
+
+/** Precedence for merged completeness: any known omission (`partial`) wins, then inability to confirm
+ * (`unknown`), and only an all-`complete` set of pages stays `complete`. */
+const completenessRank: Record<CollectionCompleteness, number> = { partial: 2, unknown: 1, complete: 0 };
+
+/** A stable key for deduplicating structurally-identical scope failures accumulated across drained pages. */
+function collectionFailureKey(failure: CollectionScopeFailure): string {
+	const scope = failure.scope;
+	return [
+		failure.kind,
+		scope?.providerId ?? '',
+		scope?.resourceId ?? '',
+		scope?.projectId ?? '',
+		scope?.repositoryId ?? '',
+		failure.message ?? '',
+	].join(' ');
+}
+
+/**
+ * Merges SDK collection metadata across drained pages. Completeness follows {@link completenessRank};
+ * failures are concatenated and deduplicated by kind, scope IDs, and message. Returns `undefined` when no
+ * page supplied metadata, so metadata-free providers and test doubles keep behaving as before.
+ */
+export function mergeCollectionMetadata(
+	base: CollectionMetadata | undefined,
+	next: CollectionMetadata | undefined,
+): CollectionMetadata | undefined {
+	if (base == null) return next;
+	if (next == null) return base;
+
+	const completeness =
+		completenessRank[next.completeness] > completenessRank[base.completeness]
+			? next.completeness
+			: base.completeness;
+
+	const failures: CollectionScopeFailure[] = [];
+	const seen = new Set<string>();
+	for (const failure of [...(base.failures ?? []), ...(next.failures ?? [])]) {
+		const key = collectionFailureKey(failure);
+		if (seen.has(key)) continue;
+
+		seen.add(key);
+		failures.push(failure);
+	}
+
+	return { completeness: completeness, ...(failures.length ? { failures: failures } : {}) };
+}
+
+/**
+ * Drains a provider paged fetcher into a single result while preserving enough metadata to
+ * signal whether the defensive backstop interrupted the drain, and merging SDK collection metadata
+ * ({@link mergeCollectionMetadata}) across the fetched pages.
+ *
+ * The local `truncated` flag and SDK `metadata` are distinct facts: a page-drain backstop must remain visible
+ * even if every fetched page reported `complete`, and SDK incompleteness is preserved even when the drain
+ * finished within its page budget.
+ */
+export async function collectProviderPagedResult<T>(
+	fetch: (cursor: string | undefined) => Promise<ProviderApiPagedResult<T> | undefined>,
+	maxPages = 20,
+	scope?: CollectionScopeFailure['scope'],
+): Promise<ProviderHierarchyResult<T>> {
+	const values: NonNullable<T>[] = [];
+	let cursor: string | undefined;
+	let metadata: CollectionMetadata | undefined;
+	let truncated = false;
+
+	// Omit `metadata` entirely when no page supplied it, so a metadata-free drain stays deep-equal to its
+	// pre-metadata shape (and consumers never see an explicit `undefined`).
+	const build = (extra?: Partial<ProviderHierarchyResult<T>>): ProviderHierarchyResult<T> => {
+		const mergedMetadata = extra?.metadata ?? metadata;
+		return {
+			values: values,
+			...extra,
+			...(truncated || extra?.truncated === true ? { truncated: true } : {}),
+			...(mergedMetadata != null ? { metadata: mergedMetadata } : {}),
+		};
+	};
+
+	for (let page = 0; page < maxPages; page++) {
+		let result: ProviderApiPagedResult<T> | undefined;
+		try {
+			result = await fetch(cursor);
+		} catch (ex) {
+			if (isCancellationError(ex)) throw ex;
+
+			// When the caller supplied a scope, preserve the items already fetched from that scope and record the
+			// failure in collection metadata rather than re-throwing and discarding the prefix. Callers without a
+			// scope keep the legacy throw behavior.
+			if (scope == null) throw ex;
+			return build({
+				truncated: true,
+				metadata: mergeCollectionMetadata(metadata, {
+					completeness: 'partial',
+					failures: [toCollectionScopeFailure(scope, ex)],
+				}),
+			});
+		}
+		if (result == null) {
+			if (page === 0) return build();
+
+			return build({
+				truncated: true,
+				...(scope != null
+					? {
+							metadata: mergeCollectionMetadata(metadata, {
+								completeness: 'partial',
+								failures: [
+									toCollectionScopeFailure(
+										scope,
+										new Error('Provider returned no page after advertising a continuation'),
+									),
+								],
+							}),
+						}
+					: undefined),
+			});
+		}
+
+		values.push(...result.values);
+		metadata = mergeCollectionMetadata(metadata, result.metadata);
+		truncated ||= result.paging?.truncated === true;
+
+		if (!result.paging?.more) return build();
+
+		if (result.paging.cursor === cursor) {
+			return build({ truncated: true });
+		}
+
+		cursor = result.paging.cursor;
+		if (cursor == null || cursor === '{}') {
+			return build({ truncated: true });
+		}
+		if (page === maxPages - 1) {
+			return build({ paging: result.paging, truncated: true });
+		}
+	}
+
+	return build();
+}