@gitkraken/core-gitlens 0.3.1 → 0.4.100

package/src/plus/integrations/models/issuesIntegration.ts

@@ -0,0 +1,264 @@
+import type { CollectionMetadata } from '@gitkraken/provider-apis';
+import type { Account } from '../../../git/models/author.js';
+import type { IssueShape } from '../../../git/models/issue.js';
+import type { ResourceDescriptor } from '../../../git/models/resourceDescriptor.js';
+import { gate } from '../../../utils/decorators/gate.js';
+import { trace } from '../../../utils/decorators/log.js';
+import { getScopedLogger } from '../../../utils/logger.scoped.js';
+import type { ProviderAuthenticationSession } from '../authentication/models.js';
+import type { IntegrationIds } from '../constants.js';
+import { toError } from '../errors.js';
+import type { IssueFilter, ProviderApiCollectionResult } from '../providers/models.js';
+import type { Integration, IntegrationResult, IntegrationType } from './integration.js';
+import { IntegrationBase } from './integration.js';
+
+export function isIssuesIntegration(integration: Integration): integration is IssuesIntegration {
+	return integration.type === 'issues';
+}
+
+export abstract class IssuesIntegration<
+	ID extends IntegrationIds = IntegrationIds,
+	T extends ResourceDescriptor = ResourceDescriptor,
+> extends IntegrationBase<ID> {
+	readonly type: IntegrationType = 'issues';
+
+	@trace()
+	async getAccountForResource(resource: T, connectionId?: string): Promise<Account | undefined> {
+		return (await this.getAccountForResourceResult(resource, connectionId))?.value;
+	}
+
+	/**
+	 * Result-returning core of {@link getAccountForResource}. Recovers a thrown error into `{ error }` so
+	 * callers can preserve its classification (e.g. a 401/403 → an `auth` warning that drives re-auth)
+	 * instead of collapsing every failure into an untyped `undefined`. Gated here (not on the wrapper) so
+	 * direct callers such as the ProviderBackend facade share the same dedup as `getAccountForResource`.
+	 */
+	@gate()
+	async getAccountForResourceResult(
+		resource: T,
+		connectionId?: string,
+	): Promise<IntegrationResult<Account | undefined>> {
+		const scope = getScopedLogger();
+		// `connectionId` targets a specific account (multi-account); omitted reads the primary.
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return undefined;
+
+		try {
+			const account = await this.getProviderAccountForResource(session, resource);
+			this.resetRequestExceptionCount('getAccountForResource');
+			return { value: account };
+		} catch (ex) {
+			this.handleProviderException('getAccountForResource', ex);
+			return { error: toError(ex) };
+		}
+	}
+
+	protected abstract getProviderAccountForResource(
+		session: ProviderAuthenticationSession,
+		resource: T,
+	): Promise<Account | undefined>;
+
+	@trace()
+	async getResourcesForUser(connectionId?: string): Promise<T[] | undefined> {
+		return (await this.getResourcesForUserResult(connectionId))?.value;
+	}
+
+	/**
+	 * Result-returning core of {@link getResourcesForUser}. Recovers thrown errors into `{ error }` so callers
+	 * can surface them as warnings rather than silently swallowing them to `undefined`. Gated here (not on the
+	 * wrapper) so direct callers such as the ProviderBackend facade share the same dedup as `getResourcesForUser`.
+	 */
+	@gate()
+	async getResourcesForUserResult(connectionId?: string): Promise<IntegrationResult<T[] | undefined>> {
+		const scope = getScopedLogger();
+		// `connectionId` targets a specific account (multi-account); omitted reads the primary.
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return undefined;
+
+		try {
+			const resources = await this.getProviderResourcesForUser(session);
+			this.resetRequestExceptionCount('getResourcesForUser');
+			return { value: resources };
+		} catch (ex) {
+			this.handleProviderException('getResourcesForUser', ex);
+			return { error: toError(ex) };
+		}
+	}
+
+	protected abstract getProviderResourcesForUser(session: ProviderAuthenticationSession): Promise<T[] | undefined>;
+
+	@trace()
+	async getProjectsForResources(resources: T[], connectionId?: string): Promise<T[] | undefined> {
+		return (await this.getProjectsForResourcesResult(resources, connectionId))?.value;
+	}
+
+	/**
+	 * Result-returning core of {@link getProjectsForResources}. Recovers thrown errors into `{ error }` so callers
+	 * can surface them as warnings rather than silently swallowing them to `undefined`. Implemented by unwrapping
+	 * the metadata-aware path's `values` so the array-returning contract stays backward compatible.
+	 */
+	async getProjectsForResourcesResult(
+		resources: T[],
+		connectionId?: string,
+	): Promise<IntegrationResult<T[] | undefined>> {
+		const result = await this.getProjectsForResourcesWithMetadataResult(resources, connectionId);
+		if (result == null) return undefined;
+		if (result.error != null) return { value: result.value?.values, error: result.error };
+		return { value: result.value?.values };
+	}
+
+	/**
+	 * Metadata-aware counterpart of {@link getProjectsForResourcesResult} for ProviderBackend composition:
+	 * returns the SDK collection `{ values, metadata }` (completeness + per-resource failures) so callers can
+	 * warn on failed resources and set `fetchFailed` without discarding the resources that succeeded.
+	 */
+	async getProjectsForResourcesWithMetadataResult(
+		resources: T[],
+		connectionId?: string,
+	): Promise<IntegrationResult<ProviderApiCollectionResult<T> | undefined>> {
+		const scope = getScopedLogger();
+		// `connectionId` targets a specific account (multi-account); omitted reads the primary.
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return undefined;
+
+		try {
+			const projects = await this.getProviderProjectsForResourcesWithMetadata(session, resources);
+			this.resetRequestExceptionCount('getProjectsForResources');
+			return { value: projects };
+		} catch (ex) {
+			this.handleProviderException('getProjectsForResources', ex);
+			return { error: toError(ex) };
+		}
+	}
+
+	async getProjectsForUser(connectionId?: string): Promise<T[] | undefined> {
+		return (await this.getProjectsForUserResult(connectionId))?.value;
+	}
+
+	/**
+	 * Result-returning core of {@link getProjectsForUser}. Composes the resource and project result methods so
+	 * callers can surface per-step warnings. Unwraps the metadata-aware path for the array-returning contract.
+	 */
+	async getProjectsForUserResult(connectionId?: string): Promise<IntegrationResult<T[] | undefined>> {
+		const result = await this.getProjectsForUserWithMetadataResult(connectionId);
+		if (result == null) return undefined;
+		if (result.error != null) return { value: result.value?.values, error: result.error };
+		return { value: result.value?.values };
+	}
+
+	/**
+	 * Metadata-aware counterpart of {@link getProjectsForUserResult}: composes resource discovery with the
+	 * metadata-aware project read so ProviderBackend consumers get completeness/failures across resources.
+	 */
+	async getProjectsForUserWithMetadataResult(
+		connectionId?: string,
+	): Promise<IntegrationResult<ProviderApiCollectionResult<T> | undefined>> {
+		const resources = await this.getResourcesForUserResult(connectionId);
+		if (resources?.error != null) return { error: resources.error };
+		if (resources?.value == null) return undefined;
+
+		return this.getProjectsForResourcesWithMetadataResult(resources.value, connectionId);
+	}
+
+	/**
+	 * Metadata-aware provider project discovery. The default wraps the array-returning
+	 * {@link getProviderProjectsForResources} in `{ values }` with no metadata, so providers without a
+	 * fan-out completeness signal (Linear, Trello) need no change; Jira overrides it to preserve the SDK's
+	 * per-resource completeness/failures.
+	 */
+	protected async getProviderProjectsForResourcesWithMetadata(
+		session: ProviderAuthenticationSession,
+		resources: T[],
+	): Promise<ProviderApiCollectionResult<T>> {
+		const projects = await this.getProviderProjectsForResources(session, resources);
+		return { values: projects ?? [] };
+	}
+
+	protected abstract getProviderProjectsForResources(
+		session: ProviderAuthenticationSession,
+		resources: T[],
+	): Promise<T[] | undefined>;
+
+	@trace()
+	async getIssuesForProject(
+		project: T,
+		options?: { user?: string; filters?: IssueFilter[] },
+		connectionId?: string,
+	): Promise<IssueShape[] | undefined> {
+		return (await this.getIssuesForProjectResult(project, options, connectionId))?.value;
+	}
+
+	/**
+	 * Result-returning core of {@link getIssuesForProject}. Recovers thrown errors into `{ error }` so callers
+	 * (e.g. the ProviderBackend facade) can surface a per-provider warning instead of a silent empty read —
+	 * important for providers that throw on unsupported operations (e.g. Linear's not-implemented issue read).
+	 */
+	async getIssuesForProjectResult(
+		project: T,
+		options?: { user?: string; filters?: IssueFilter[] },
+		connectionId?: string,
+	): Promise<IntegrationResult<IssueShape[] | undefined>> {
+		const scope = getScopedLogger();
+		// `connectionId` targets a specific account (multi-account); omitted reads the primary.
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return undefined;
+
+		try {
+			const issues = await this.getProviderIssuesForProject(session, project, options);
+			this.resetRequestExceptionCount('getIssuesForProject');
+			return { value: issues };
+		} catch (ex) {
+			this.handleProviderException('getIssuesForProject', ex);
+			return { error: toError(ex) };
+		}
+	}
+
+	/**
+	 * Truncation-aware variant of {@link getIssuesForProjectResult}. A provider that drains a project's issues
+	 * with an internal page backstop (Jira/Linear) overrides {@link getProviderIssuesForProjectWithTruncation}
+	 * to report when that backstop was hit, so the facade can surface an incomplete project read instead of
+	 * publishing it as complete. The default reports `truncated: false`.
+	 */
+	async getIssuesForProjectWithTruncationResult(
+		project: T,
+		options?: { user?: string; filters?: IssueFilter[] },
+		connectionId?: string,
+	): Promise<
+		IntegrationResult<{ values: IssueShape[]; truncated: boolean; metadata?: CollectionMetadata } | undefined>
+	> {
+		const scope = getScopedLogger();
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return undefined;
+
+		try {
+			const result = await this.getProviderIssuesForProjectWithTruncation(session, project, options);
+			this.resetRequestExceptionCount('getIssuesForProject');
+			return { value: result };
+		} catch (ex) {
+			this.handleProviderException('getIssuesForProject', ex);
+			return { error: toError(ex) };
+		}
+	}
+
+	protected abstract getProviderIssuesForProject(
+		session: ProviderAuthenticationSession,
+		project: T,
+		options?: { user?: string; filters?: IssueFilter[] },
+	): Promise<IssueShape[] | undefined>;
+
+	/**
+	 * Truncation-aware core of {@link getProviderIssuesForProject}. The default wraps the plain read and
+	 * reports `truncated: false`; a provider whose per-project drain is capped by a page backstop overrides
+	 * this to report incompleteness. Optional metadata lets providers surface structured per-project failures
+	 * (e.g. a page-level auth rejection) without discarding the already-fetched prefix.
+	 */
+	protected async getProviderIssuesForProjectWithTruncation(
+		session: ProviderAuthenticationSession,
+		project: T,
+		options?: { user?: string; filters?: IssueFilter[] },
+	): Promise<{ values: IssueShape[]; truncated: boolean; metadata?: CollectionMetadata } | undefined> {
+		const values = await this.getProviderIssuesForProject(session, project, options);
+		if (values == null) return undefined;
+		return { values: values, truncated: false };
+	}
+}

package/src/plus/integrations/providerFilters.ts

@@ -0,0 +1,12 @@
+export enum PullRequestFilter {
+	Author = 'author',
+	Assignee = 'assignee',
+	ReviewRequested = 'review-requested',
+	Mention = 'mention',
+}
+
+export enum IssueFilter {
+	Author = 'author',
+	Assignee = 'assignee',
+	Mention = 'mention',
+}

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

@@ -0,0 +1,69 @@
+import type { Disposable } from '../../../utils/disposable.js';
+import { getScopedLogger } from '../../../utils/logger.scoped.js';
+import type { IntegrationServiceContext } from '../context.js';
+import type { AzureDevOpsApi } from './azure/azure.js';
+import type { BitbucketApi } from './bitbucket/bitbucket.js';
+import type { GitHubApi } from './github/github.js';
+import type { GitLabApi } from './gitlab/gitlab.js';
+
+/**
+ * The per-provider API clients, owned and built by the package. `GitLabApi`/`BitbucketApi`/`AzureDevOpsApi`
+ * live in the package; `GitHubApi` comes from `@gitkraken/core-gitlens/plus/git-github` (shared with the host's GitHub git
+ * provider, which reads the manager's memoized instance via `manager.github`). `undefined` is tolerated for
+ * offline/limited runtimes.
+ */
+export interface ApiClients {
+	readonly github: Promise<GitHubApi | undefined>;
+	readonly gitlab: Promise<GitLabApi | undefined>;
+	readonly bitbucket: Promise<BitbucketApi | undefined>;
+	readonly azure: Promise<AzureDevOpsApi | undefined>;
+}
+
+/**
+ * Lazily constructs + memoizes the API clients from the runtime context, pushing each to `disposables` for
+ * teardown. Mirrors the lazy-chunked construction the host's `Container` did before the package took
+ * ownership (the host used to build these and inject them back through the context — a pure round-trip).
+ */
+export function createApiClients(ctx: IntegrationServiceContext, disposables: Disposable[]): ApiClients {
+	let github: Promise<GitHubApi | undefined> | undefined;
+	let gitlab: Promise<GitLabApi | undefined> | undefined;
+	let bitbucket: Promise<BitbucketApi | undefined> | undefined;
+	let azure: Promise<AzureDevOpsApi | undefined> | undefined;
+
+	const build = async <T extends Disposable>(load: () => Promise<T>): Promise<T | undefined> => {
+		const scope = getScopedLogger();
+		try {
+			const api = await load();
+			disposables.push(api);
+			return api;
+		} catch (ex) {
+			scope?.error(ex, 'Failed to construct integration API client');
+			return undefined;
+		}
+	};
+
+	return {
+		get github() {
+			return (github ??= build(async () =>
+				(await import(/* webpackChunkName: "integrations" */ './github/github.js')).createGitHubApi(ctx),
+			));
+		},
+		get gitlab() {
+			return (gitlab ??= build(async () =>
+				(await import(/* webpackChunkName: "integrations" */ './gitlab/gitlab.js')).createGitLabApi(ctx),
+			));
+		},
+		get bitbucket() {
+			return (bitbucket ??= build(async () =>
+				(await import(/* webpackChunkName: "integrations" */ './bitbucket/bitbucket.js')).createBitbucketApi(
+					ctx,
+				),
+			));
+		},
+		get azure() {
+			return (azure ??= build(async () =>
+				(await import(/* webpackChunkName: "integrations" */ './azure/azure.js')).createAzureDevOpsApi(ctx),
+			));
+		},
+	};
+}

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

@@ -0,0 +1,71 @@
+import type { IntegrationServiceContext } from '../context.js';
+
+/**
+ * VS Code-free configuration for the package-owned provider API clients
+ * ({@link GitLabApi}, {@link BitbucketApi}, {@link AzureDevOpsApi}).
+ *
+ * Mirrors the role {@link import('../../git-github/api/config.js').GitHubApiConfig}
+ * plays for `GitHubApi`: instead of taking the full {@link IntegrationServiceContext},
+ * a client takes only the narrow HTTP + callback surface it actually uses. The
+ * `createIntegrationManager` path wires this from `ctx` (see the `create*Api`
+ * factories); a token-scoped consumer builds it from a `fetch` plus a
+ * `wrapForForcedInsecureSSL` (a pass-through is fine when not toggling SSL).
+ *
+ * Every field beyond `fetch`/`wrapForForcedInsecureSSL` is optional — a client omits
+ * the call when unset, so a minimal consumer only supplies the two required members.
+ */
+export interface ProviderApiConfig {
+	/** The `fetch` implementation to use for HTTP requests. */
+	fetch(input: string | URL, init?: RequestInit): Promise<Response>;
+
+	/**
+	 * Wraps an async operation so that TLS certificate validation is disabled when the
+	 * provider's `getIgnoreSSLErrors()` returns `'force'`. On the browser it's a no-op.
+	 */
+	wrapForForcedInsecureSSL<T>(ignoreSSLErrors: boolean | 'force', fn: () => Promise<T> | PromiseLike<T>): Promise<T>;
+
+	/**
+	 * Fires when the HTTP proxy configuration changes, so the client can reset its HTTP caches.
+	 * The factory filters the underlying config-change event down to the keys the client cares about.
+	 */
+	onConfigChanged?(listener: () => void): { dispose(): void };
+
+	/**
+	 * Ask the consumer to confirm reauthentication after an auth/permission failure (401/403). Resolves to
+	 * the user's choice; the client performs the actual `provider.reauthenticate()` when this is truthy.
+	 * Only GitLab wires this today.
+	 */
+	onReauthenticationRequired?(message: string): Promise<boolean | undefined>;
+
+	/** A non-fatal error to surface (debug display / notification). */
+	onError?(message: string): void;
+
+	/** The provider API returned a server-side (500-level) error. */
+	onRequestFailed?(message: string): void;
+
+	/** The provider API request timed out; `providerName` names the integration for the message. */
+	onRequestTimedOut?(providerName: string): void;
+
+	/** Bitbucket's "Pull Requests for Commit" app isn't installed; `revLink` opens the install page. */
+	onBitbucketCommitLinksAppMissing?(revLink: string): void;
+}
+
+/**
+ * The `ctx` → {@link ProviderApiConfig} mapping shared by every `create*Api` factory. Each provider
+ * spreads this and layers on its own deltas (GitLab also resets on `remotes` + wires reauth/timeout;
+ * Bitbucket adds the commit-links-app hook). Resets HTTP caches on HTTP proxy config changes.
+ */
+export function baseProviderApiConfig(ctx: IntegrationServiceContext): ProviderApiConfig {
+	return {
+		fetch: ctx.http.fetch.bind(ctx.http),
+		wrapForForcedInsecureSSL: ctx.http.wrapForForcedInsecureSSL.bind(ctx.http),
+		onConfigChanged: listener =>
+			ctx.config.onDidChange(e => {
+				if (e.httpProxy) {
+					listener();
+				}
+			}),
+		onError: message => ctx.hooks?.ui?.onError?.(message),
+		onRequestFailed: message => ctx.hooks?.ui?.onRequestFailed?.(message),
+	};
+}