@gitkraken/core-gitlens 0.4.0 → 0.4.101

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();
+}

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

@@ -1,5 +1,4 @@
 import type { AnyEntityIdentifierInput, EntityIdentifier } from '@gitkraken/provider-apis';
-import { EntityIdentifierProviderType, EntityType, EntityVersion } from '@gitkraken/provider-apis';
 import type { Issue, IssueShape } from '../../../git/models/issue.js';
 import type { IssueOrPullRequest } from '../../../git/models/issueOrPullRequest.js';
 import type { PullRequest } from '../../../git/models/pullRequest.js';
@@ -21,6 +20,34 @@ import type { AzureProjectInputDescriptor } from './azure/models.js';
 import type { GitConfigEntityIdentifier } from './models.js';
 import { isGitHubDotCom, isGitLabDotCom } from './models.js';
 
+// Local runtime copies of the `@gitkraken/provider-apis` entity-identifier string enums, duplicated for
+// the same CJS-from-ESM reason as the enums in `models.ts`. Exported so the enum-parity test can guard
+// them against upstream drift. `EntityVersion` is an intentional subset: the package only ever writes
+// version 1, so the parity test asserts each local entry matches the SDK rather than a full mirror.
+export const EntityIdentifierProviderType = {
+	Azure: 'azure',
+	AzureDevOpsServer: 'azureDevOpsServer',
+	Github: 'github',
+	GithubEnterprise: 'githubEnterprise',
+	Gitlab: 'gitlab',
+	GitlabSelfHosted: 'gitlabSelfHosted',
+	Bitbucket: 'bitbucket',
+	BitbucketServer: 'bitbucketServer',
+	Jira: 'jira',
+	JiraServer: 'jiraServer',
+	Linear: 'linear',
+	Trello: 'trello',
+} as const;
+
+export const EntityType = {
+	PullRequest: 'pr',
+	Issue: 'issue',
+} as const;
+
+export const EntityVersion = {
+	One: '1',
+} as const;
+
 /**
  * Forward-compatible structural shape of the host's `LaunchpadItem`. The package
  * uses this for narrowing inside {@link getEntityIdentifierInput}; the host's
@@ -48,7 +75,7 @@ function isIssue(item: IssueOrPullRequest | LaunchpadItem): item is Issue {
 }
 
 export function getEntityIdentifierInput(entity: Issue | PullRequest | LaunchpadItem): AnyEntityIdentifierInput {
-	let entityType = EntityType.Issue;
+	let entityType: (typeof EntityType)[keyof typeof EntityType] = EntityType.Issue;
 	if (entity.type === 'pullrequest') {
 		entityType = EntityType.PullRequest;
 	}
@@ -69,6 +96,7 @@ export function getEntityIdentifierInput(entity: Issue | PullRequest | Launchpad
 
 	let projectId = null;
 	let resourceId = null;
+	let accountOrOrgId = null;
 	let organizationName = null;
 	let repoId = null;
 	if (provider === EntityIdentifierProviderType.Jira) {
@@ -93,6 +121,15 @@ export function getEntityIdentifierInput(entity: Issue | PullRequest | Launchpad
 		if (entityType === EntityType.PullRequest && repoId == null) {
 			throw new Error('Azure PRs must have a repository ID to be encoded');
 		}
+	} else if (provider === EntityIdentifierProviderType.Trello) {
+		if (!isIssue(entity) || entity.project == null) {
+			throw new Error('Trello issues must have a board project to be encoded');
+		}
+
+		projectId = entity.project.id;
+		// Trello currently exposes the board but not a separate workspace/org id here. Reuse the board id in
+		// both serialization slots so branch associations remain round-trippable until the upstream shape grows.
+		accountOrOrgId = entity.project.resourceId || entity.project.id;
 	} else if (
 		provider === EntityIdentifierProviderType.Bitbucket ||
 		provider === EntityIdentifierProviderType.BitbucketServer
@@ -115,9 +152,9 @@ export function getEntityIdentifierInput(entity: Issue | PullRequest | Launchpad
 	// structurally narrowed to any single variant. The 2-step cast through
 	// `unknown` is the documented escape for this discriminated-union pattern.
 	return {
-		accountOrOrgId: null, // needed for Trello issues, once supported
+		accountOrOrgId: accountOrOrgId,
 		organizationName: organizationName, // needed for Azure issues and PRs, once supported
-		projectId: projectId, // needed for Jira issues, Trello issues, and Azure issues and PRs, once supported
+		projectId: projectId,
 		repoId: repoId ?? null, // needed for Azure and BitBucket PRs, once supported
 		resourceId: resourceId, // needed for Jira issues
 		provider: provider,
@@ -144,6 +181,8 @@ export function getProviderIdFromEntityIdentifier(
 			return IssuesCloudHostIntegrationId.Jira;
 		case EntityIdentifierProviderType.Linear:
 			return IssuesCloudHostIntegrationId.Linear;
+		case EntityIdentifierProviderType.Trello:
+			return IssuesCloudHostIntegrationId.Trello;
 		case EntityIdentifierProviderType.Azure:
 			return GitCloudHostIntegrationId.AzureDevOps;
 		case EntityIdentifierProviderType.AzureDevOpsServer:
@@ -159,7 +198,9 @@ export function getProviderIdFromEntityIdentifier(
 	}
 }
 
-function fromStringToEntityIdentifierProviderType(str: string): EntityIdentifierProviderType {
+function fromStringToEntityIdentifierProviderType(
+	str: string,
+): (typeof EntityIdentifierProviderType)[keyof typeof EntityIdentifierProviderType] {
 	switch (str) {
 		case 'github':
 			return EntityIdentifierProviderType.Github;
@@ -173,6 +214,8 @@ function fromStringToEntityIdentifierProviderType(str: string): EntityIdentifier
 			return EntityIdentifierProviderType.Jira;
 		case 'linear':
 			return EntityIdentifierProviderType.Linear;
+		case 'trello':
+			return EntityIdentifierProviderType.Trello;
 		case 'azure':
 		case 'azureDevOps':
 		case 'azure-devops':
@@ -304,7 +347,8 @@ export async function getIssueFromGitConfigEntityIdentifier(
 		identifier.provider !== EntityIdentifierProviderType.Bitbucket &&
 		identifier.provider !== EntityIdentifierProviderType.BitbucketServer &&
 		identifier.provider !== EntityIdentifierProviderType.AzureDevOpsServer &&
-		identifier.provider !== EntityIdentifierProviderType.Azure
+		identifier.provider !== EntityIdentifierProviderType.Azure &&
+		identifier.provider !== EntityIdentifierProviderType.Trello
 	) {
 		return undefined;
 	}
@@ -322,20 +366,36 @@ export async function getIssueFromGitConfigEntityIdentifier(
 		owner: identifier.metadata.owner.owner,
 		name: identifier.metadata.owner.name,
 	};
+	const remoteLookupId =
+		identifier.provider === EntityIdentifierProviderType.Trello ? identifier.entityId : identifier.metadata.id;
 
 	// Cache-only read (no remote fetch). The package can't reach the host cache directly, so defer to the
 	// host-supplied reader; without one, honor the no-fetch contract by returning undefined. The cache key
 	// is resource+id (the integration only affects the etag), so peek even when the integration is
 	// unresolvable — a still-cached issue must survive an unconfigured/disconnected integration.
 	if (options?.cached) {
-		return options.peekCachedIssue?.(integration, resource, identifier.metadata.id);
+		const cachedIssue = options.peekCachedIssue?.(integration, resource, identifier.metadata.id);
+		if (
+			cachedIssue != null ||
+			(identifier.provider !== EntityIdentifierProviderType.Trello &&
+				identifier.provider !== EntityIdentifierProviderType.Linear)
+		) {
+			return cachedIssue;
+		}
+
+		// Two id generations coexist for these providers: Trello identifiers persisted before the stable-id
+		// switch carry the board-local `idShort` in `metadata.id` while the cache is keyed by the stable card
+		// id (`entityId`); Linear identifiers persisted before `Issue.id` became the human identifier carry
+		// the UUID in `metadata.id` while fresh cache entries key by the identifier — and vice versa, the
+		// UUID always survives in `entityId` (via `nodeId`). Peeking both keys resolves either generation.
+		return options.peekCachedIssue?.(integration, resource, identifier.entityId);
 	}
 
 	if (integration == null) {
 		return undefined;
 	}
 
-	return integration.getIssue(resource, identifier.metadata.id);
+	return integration.getIssue(resource, remoteLookupId);
 }
 
 export function getIssueOwner(