@gitkraken/core-gitlens 0.3.1 → 0.4.0

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

@@ -0,0 +1,359 @@
+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';
+import type {
+	IssueResourceDescriptor,
+	RepositoryDescriptor,
+	ResourceDescriptor,
+} from '../../../git/models/resourceDescriptor.js';
+import { isIssueResourceDescriptor, isRepositoryDescriptor } from '../../../git/utils/resourceDescriptor.utils.js';
+import { Logger } from '../../../utils/logger.js';
+import type { IntegrationIds } from '../constants.js';
+import {
+	GitCloudHostIntegrationId,
+	GitSelfManagedHostIntegrationId,
+	IssuesCloudHostIntegrationId,
+} from '../constants.js';
+import { isCloudGitSelfManagedHostIntegrationId } from '../utils/integration.utils.js';
+import type { AzureProjectInputDescriptor } from './azure/models.js';
+import type { GitConfigEntityIdentifier } from './models.js';
+import { isGitHubDotCom, isGitLabDotCom } from './models.js';
+
+/**
+ * Forward-compatible structural shape of the host's `LaunchpadItem`. The package
+ * uses this for narrowing inside {@link getEntityIdentifierInput}; the host's
+ * actual `LaunchpadItem` (in `src/plus/launchpad/launchpadProvider.ts`) carries
+ * many more fields. The declared shape only includes fields integrations inspect.
+ */
+type LaunchpadItem = {
+	uuid: string;
+	type: 'issue' | 'pullrequest';
+	graphQLId?: string;
+	provider: { id: string; domain?: string };
+	underlyingPullRequest?: {
+		id: string;
+		project?: { id: string; resourceName?: string };
+		repository?: { id?: string };
+	};
+};
+
+function isLaunchpadItem(item: IssueOrPullRequest | LaunchpadItem): item is LaunchpadItem {
+	return (item as LaunchpadItem).uuid !== undefined;
+}
+
+function isIssue(item: IssueOrPullRequest | LaunchpadItem): item is Issue {
+	return item.type === 'issue';
+}
+
+export function getEntityIdentifierInput(entity: Issue | PullRequest | LaunchpadItem): AnyEntityIdentifierInput {
+	let entityType = EntityType.Issue;
+	if (entity.type === 'pullrequest') {
+		entityType = EntityType.PullRequest;
+	}
+
+	let provider = fromStringToEntityIdentifierProviderType(entity.provider.id);
+	let domain = null;
+	if (provider === EntityIdentifierProviderType.Github && !isGitHubDotCom(entity.provider.domain)) {
+		provider = EntityIdentifierProviderType.GithubEnterprise;
+		domain = entity.provider.domain ?? null;
+	}
+	if (provider === EntityIdentifierProviderType.Gitlab && !isGitLabDotCom(entity.provider.domain)) {
+		provider = EntityIdentifierProviderType.GitlabSelfHosted;
+		domain = entity.provider.domain ?? null;
+	}
+	if (provider === EntityIdentifierProviderType.AzureDevOpsServer) {
+		domain = entity.provider.domain ?? null;
+	}
+
+	let projectId = null;
+	let resourceId = null;
+	let organizationName = null;
+	let repoId = null;
+	if (provider === EntityIdentifierProviderType.Jira) {
+		if (!isIssue(entity) || entity.project == null) {
+			throw new Error('Jira issues must have a project');
+		}
+
+		projectId = entity.project.id;
+		resourceId = entity.project.resourceId;
+	} else if (
+		provider === EntityIdentifierProviderType.Azure ||
+		provider === EntityIdentifierProviderType.AzureDevOpsServer
+	) {
+		const project = isLaunchpadItem(entity) ? entity.underlyingPullRequest?.project : entity.project;
+		if (project == null) {
+			throw new Error('Azure issues and PRs must have a project to be encoded');
+		}
+
+		projectId = project.id;
+		organizationName = project.resourceName;
+		repoId = isLaunchpadItem(entity) ? entity.underlyingPullRequest?.repository?.id : entity.repository?.id;
+		if (entityType === EntityType.PullRequest && repoId == null) {
+			throw new Error('Azure PRs must have a repository ID to be encoded');
+		}
+	} else if (
+		provider === EntityIdentifierProviderType.Bitbucket ||
+		provider === EntityIdentifierProviderType.BitbucketServer
+	) {
+		repoId = isLaunchpadItem(entity) ? entity.underlyingPullRequest?.repository?.id : entity.repository?.id;
+	}
+
+	let entityId = isLaunchpadItem(entity) ? entity.graphQLId! : entity.nodeId!;
+	if (
+		provider === EntityIdentifierProviderType.Azure ||
+		provider === EntityIdentifierProviderType.AzureDevOpsServer
+	) {
+		entityId = (isLaunchpadItem(entity) ? entity.underlyingPullRequest?.id : entity.id) as string;
+	}
+
+	// `AnyEntityIdentifierInput` includes the catch-all `EntityIdentifier`
+	// variant which requires all fields, while each provider-specific variant
+	// requires a different subset. The function builds a polymorphic value
+	// that's correct at runtime per `provider` but the literal can't be
+	// 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
+		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
+		repoId: repoId ?? null, // needed for Azure and BitBucket PRs, once supported
+		resourceId: resourceId, // needed for Jira issues
+		provider: provider,
+		entityType: entityType,
+		version: EntityVersion.One,
+		domain: domain,
+		entityId: entityId,
+	} as unknown as AnyEntityIdentifierInput;
+}
+
+export function getProviderIdFromEntityIdentifier(
+	entityIdentifier: EntityIdentifier | AnyEntityIdentifierInput | GitConfigEntityIdentifier,
+): IntegrationIds | undefined {
+	switch (entityIdentifier.provider) {
+		case EntityIdentifierProviderType.Github:
+			return GitCloudHostIntegrationId.GitHub;
+		case EntityIdentifierProviderType.GithubEnterprise:
+			return GitSelfManagedHostIntegrationId.CloudGitHubEnterprise;
+		case EntityIdentifierProviderType.Gitlab:
+			return GitCloudHostIntegrationId.GitLab;
+		case EntityIdentifierProviderType.GitlabSelfHosted:
+			return GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted;
+		case EntityIdentifierProviderType.Jira:
+			return IssuesCloudHostIntegrationId.Jira;
+		case EntityIdentifierProviderType.Linear:
+			return IssuesCloudHostIntegrationId.Linear;
+		case EntityIdentifierProviderType.Azure:
+			return GitCloudHostIntegrationId.AzureDevOps;
+		case EntityIdentifierProviderType.AzureDevOpsServer:
+			return GitSelfManagedHostIntegrationId.AzureDevOpsServer;
+		case EntityIdentifierProviderType.Bitbucket:
+			return GitCloudHostIntegrationId.Bitbucket;
+		case EntityIdentifierProviderType.BitbucketServer:
+			return isGitConfigEntityIdentifier(entityIdentifier) && entityIdentifier.metadata.isCloudEnterprise
+				? GitSelfManagedHostIntegrationId.BitbucketServer
+				: undefined;
+		default:
+			return undefined;
+	}
+}
+
+function fromStringToEntityIdentifierProviderType(str: string): EntityIdentifierProviderType {
+	switch (str) {
+		case 'github':
+			return EntityIdentifierProviderType.Github;
+		case 'cloud-github-enterprise':
+			return EntityIdentifierProviderType.GithubEnterprise;
+		case 'cloud-gitlab-self-hosted':
+			return EntityIdentifierProviderType.GitlabSelfHosted;
+		case 'gitlab':
+			return EntityIdentifierProviderType.Gitlab;
+		case 'jira':
+			return EntityIdentifierProviderType.Jira;
+		case 'linear':
+			return EntityIdentifierProviderType.Linear;
+		case 'azure':
+		case 'azureDevOps':
+		case 'azure-devops':
+			return EntityIdentifierProviderType.Azure;
+		case GitSelfManagedHostIntegrationId.AzureDevOpsServer:
+			return EntityIdentifierProviderType.AzureDevOpsServer;
+		case 'bitbucket':
+			return EntityIdentifierProviderType.Bitbucket;
+		case 'bitbucket-server':
+			return EntityIdentifierProviderType.BitbucketServer;
+		default:
+			throw new Error(`Unknown provider type '${str}'`);
+	}
+}
+
+export function encodeIssueOrPullRequestForGitConfig(
+	entity: Issue | PullRequest,
+	owner: RepositoryDescriptor | IssueResourceDescriptor,
+): GitConfigEntityIdentifier {
+	const encodedOwner: GitConfigEntityIdentifier['metadata']['owner'] = {
+		key: owner.key,
+		name: owner.name,
+		id: undefined,
+		owner: undefined,
+	};
+	if (isRepositoryDescriptor(owner)) {
+		encodedOwner.owner = owner.owner;
+	} else if (isIssueResourceDescriptor(owner)) {
+		encodedOwner.id = owner.id;
+	} else {
+		throw new Error('Invalid owner');
+	}
+
+	return {
+		...getEntityIdentifierInput(entity),
+		metadata: {
+			id: entity.id,
+			owner: encodedOwner,
+			createdDate: new Date().toISOString(),
+			isCloudEnterprise: isCloudGitSelfManagedHostIntegrationId(entity.provider.id as IntegrationIds),
+		},
+	};
+}
+
+export function isGitConfigEntityIdentifier(entity: unknown): entity is GitConfigEntityIdentifier {
+	return (
+		entity != null &&
+		typeof entity === 'object' &&
+		'provider' in entity &&
+		entity.provider != null &&
+		'entityType' in entity &&
+		entity.entityType != null &&
+		'version' in entity &&
+		entity.version != null &&
+		'entityId' in entity &&
+		entity.entityId != null &&
+		'metadata' in entity &&
+		entity.metadata != null &&
+		typeof entity.metadata === 'object' &&
+		'id' in entity.metadata &&
+		entity.metadata.id != null &&
+		'owner' in entity.metadata &&
+		entity.metadata.owner != null &&
+		'createdDate' in entity.metadata &&
+		entity.metadata.createdDate != null
+	);
+}
+
+export function isGitConfigEntityIdentifiers(entities: unknown): entities is GitConfigEntityIdentifier[] {
+	return Array.isArray(entities) && entities.every(entity => isGitConfigEntityIdentifier(entity));
+}
+
+export function decodeEntityIdentifiersFromGitConfig(str: string): GitConfigEntityIdentifier[] {
+	const decoded = JSON.parse(str);
+
+	if (!isGitConfigEntityIdentifiers(decoded)) {
+		debugger;
+		Logger.error('Invalid entity identifiers in git config');
+		return [];
+	}
+
+	for (const decodedEntity of decoded) {
+		if (
+			decodedEntity.provider === EntityIdentifierProviderType.Jira &&
+			(decodedEntity.resourceId == null || decodedEntity.projectId == null)
+		) {
+			debugger;
+			Logger.error('Invalid Jira issue in git config');
+		}
+	}
+
+	return decoded;
+}
+
+interface IssueResolvableIntegration {
+	getIssue(owner: unknown, id: string): Promise<Issue | undefined>;
+}
+
+export async function getIssueFromGitConfigEntityIdentifier(
+	resolveIntegration: (id: IntegrationIds) => Promise<IssueResolvableIntegration | undefined>,
+	identifier: GitConfigEntityIdentifier,
+	options?: {
+		/** Only return a value already in the local cache. No remote fetch — returns undefined on cache miss. */
+		cached?: boolean;
+		/**
+		 * Host-supplied cache reader used when {@link cached} is set. The package is cache-agnostic, so the
+		 * host (which owns the cache) provides this to satisfy a cache-only read. When omitted, `cached`
+		 * yields undefined rather than falling through to a remote fetch.
+		 */
+		peekCachedIssue?: (
+			integration: IssueResolvableIntegration | undefined,
+			resource: ResourceDescriptor,
+			id: string,
+		) => Issue | undefined;
+	},
+): Promise<Issue | undefined> {
+	if (identifier.entityType !== EntityType.Issue) {
+		return undefined;
+	}
+
+	// TODO: Centralize where we represent all supported providers for issues
+	if (
+		identifier.provider !== EntityIdentifierProviderType.Jira &&
+		identifier.provider !== EntityIdentifierProviderType.Linear &&
+		identifier.provider !== EntityIdentifierProviderType.Github &&
+		identifier.provider !== EntityIdentifierProviderType.Gitlab &&
+		identifier.provider !== EntityIdentifierProviderType.GithubEnterprise &&
+		identifier.provider !== EntityIdentifierProviderType.GitlabSelfHosted &&
+		identifier.provider !== EntityIdentifierProviderType.Bitbucket &&
+		identifier.provider !== EntityIdentifierProviderType.BitbucketServer &&
+		identifier.provider !== EntityIdentifierProviderType.AzureDevOpsServer &&
+		identifier.provider !== EntityIdentifierProviderType.Azure
+	) {
+		return undefined;
+	}
+
+	const integrationId = getProviderIdFromEntityIdentifier(identifier);
+	if (integrationId == null) {
+		return undefined;
+	}
+
+	const integration = await resolveIntegration(integrationId);
+
+	const resource: ResourceDescriptor = {
+		id: identifier.metadata.owner.id,
+		key: identifier.metadata.owner.key,
+		owner: identifier.metadata.owner.owner,
+		name: identifier.metadata.owner.name,
+	};
+
+	// 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);
+	}
+
+	if (integration == null) {
+		return undefined;
+	}
+
+	return integration.getIssue(resource, identifier.metadata.id);
+}
+
+export function getIssueOwner(
+	issue: IssueShape,
+): RepositoryDescriptor | IssueResourceDescriptor | AzureProjectInputDescriptor | undefined {
+	const isAzure = ['azure', GitCloudHostIntegrationId.AzureDevOps, 'azure-devops'].includes(issue.provider.id);
+	return issue.repository
+		? {
+				key: `${issue.repository.owner}/${issue.repository.repo}`,
+				owner: issue.repository.owner,
+				name: issue.repository.repo,
+			}
+		: issue.project
+			? {
+					key: isAzure ? issue.project.id : issue.project.resourceId,
+					id: isAzure ? issue.project.id : issue.project.resourceId,
+					owner: isAzure ? issue.project.resourceName : undefined,
+					name: isAzure ? issue.project.name : issue.project.resourceName,
+				}
+			: undefined;
+}

package/src/plus/integrations/telemetry.ts

@@ -0,0 +1,29 @@
+/**
+ * Telemetry-source types used by the integrations package.
+ *
+ * Mirrors the shape of the host's `Source` / `Sources` types from
+ * `src/constants.telemetry.ts` but intentionally widens `source` to a plain
+ * `string` so the package doesn't depend on the host's enumerated union.
+ * The host passes its typed `Source` directly — TypeScript's structural
+ * subtyping accepts the narrower type here.
+ */
+export type Source = {
+	source: string;
+	correlationId?: string;
+
+	detail?: unknown;
+};
+
+export type Sources = string;
+
+/**
+ * Maps a telemetry `source`/`detail` to the `&context=` value the package appends when building
+ * cloud-connect URLs. Owned here in the package (the host no longer carries a duplicate copy).
+ */
+export const sourceToContext: { [source: string]: string | undefined } = {
+	launchpad: 'launchpad',
+};
+
+export const detailToContext: { [detail: string]: string | undefined } = {
+	mcp: 'mcp',
+};

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

@@ -0,0 +1,138 @@
+import type { RemoteProvider, RemoteProviderId } from '../../../git/models/remoteProvider.js';
+import type { CloudGitSelfManagedHostIntegrationIds, IntegrationIds } from '../constants.js';
+import {
+	GitCloudHostIntegrationId,
+	GitSelfManagedHostIntegrationId,
+	IssuesCloudHostIntegrationId,
+} from '../constants.js';
+import type { GitHostIntegration } from '../models/gitHostIntegration.js';
+import type { Integration, IntegrationConnectedKey } from '../models/integration.js';
+import { isGitHubDotCom, isGitLabDotCom } from '../providers/models.js';
+
+// These two domain checks live here (rather than in their provider modules) to
+// break a top-level circular import. The provider modules synchronously read
+// `providersMetadata[...]` at module init time, so importing from them while
+// `providers/models.ts` is still loading triggers a TDZ on `providersMetadata`.
+const azureCloudDomainRegex = /^dev\.azure\.com$|\bvisualstudio\.com$/i;
+const bitbucketCloudDomainRegex = /^bitbucket\.org$/i;
+function isAzureCloudDomain(domain: string | undefined): boolean {
+	return domain != null && azureCloudDomainRegex.test(domain);
+}
+function isBitbucketCloudDomain(domain: string | undefined): boolean {
+	return domain != null && bitbucketCloudDomainRegex.test(domain);
+}
+
+const selfHostedIntegrationIds: GitSelfManagedHostIntegrationId[] = [
+	GitSelfManagedHostIntegrationId.CloudGitHubEnterprise,
+	GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted,
+	GitSelfManagedHostIntegrationId.BitbucketServer,
+	GitSelfManagedHostIntegrationId.AzureDevOpsServer,
+] as const;
+
+export const supportedIntegrationIds: IntegrationIds[] = [
+	GitCloudHostIntegrationId.GitHub,
+	GitCloudHostIntegrationId.GitLab,
+	GitCloudHostIntegrationId.Bitbucket,
+	GitCloudHostIntegrationId.AzureDevOps,
+	IssuesCloudHostIntegrationId.Jira,
+	// Note: Trello is metadata-only (no auth provider), so it is intentionally absent — including it
+	// would make reset()'s ensureProvider() throw 'No authentication provider registered'.
+	...selfHostedIntegrationIds,
+] as const;
+
+export function convertRemoteProviderIdToIntegrationId(
+	remoteProviderId: RemoteProviderId,
+): GitCloudHostIntegrationId | GitSelfManagedHostIntegrationId | undefined {
+	switch (remoteProviderId) {
+		case 'azure-devops':
+			return GitCloudHostIntegrationId.AzureDevOps;
+		case 'bitbucket':
+			return GitCloudHostIntegrationId.Bitbucket;
+		case 'github':
+			return GitCloudHostIntegrationId.GitHub;
+		case 'gitlab':
+			return GitCloudHostIntegrationId.GitLab;
+		case 'bitbucket-server':
+			return GitSelfManagedHostIntegrationId.BitbucketServer;
+		default:
+			return undefined;
+	}
+}
+
+export function getIntegrationConnectedKey<T extends IntegrationIds>(
+	id: T,
+	domain?: string,
+): IntegrationConnectedKey<T> {
+	if (isGitSelfManagedHostIntegrationId(id)) {
+		if (!domain) {
+			throw new Error(`Domain is required for self-managed integration ID: ${id}`);
+		}
+		return `connected:${id}:${domain}` as IntegrationConnectedKey<T>;
+	}
+
+	return `connected:${id}` as IntegrationConnectedKey<T>;
+}
+
+export function getIntegrationIdForRemote(
+	provider: RemoteProvider | undefined,
+): GitCloudHostIntegrationId | GitSelfManagedHostIntegrationId | undefined {
+	switch (provider?.id) {
+		case 'azure-devops':
+			if (isAzureCloudDomain(provider.domain)) {
+				return GitCloudHostIntegrationId.AzureDevOps;
+			}
+			return provider.custom ? undefined : GitSelfManagedHostIntegrationId.AzureDevOpsServer;
+		case 'bitbucket':
+		case 'bitbucket-server':
+			if (isBitbucketCloudDomain(provider.domain)) {
+				return GitCloudHostIntegrationId.Bitbucket;
+			}
+			return GitSelfManagedHostIntegrationId.BitbucketServer;
+		case 'github':
+			if (provider.domain != null && !isGitHubDotCom(provider.domain)) {
+				return GitSelfManagedHostIntegrationId.CloudGitHubEnterprise;
+			}
+			return GitCloudHostIntegrationId.GitHub;
+		case 'gitlab':
+			if (provider.domain != null && !isGitLabDotCom(provider.domain)) {
+				return GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted;
+			}
+			return GitCloudHostIntegrationId.GitLab;
+		default:
+			return undefined;
+	}
+}
+
+export function isCloudGitSelfManagedHostIntegrationId(
+	id: IntegrationIds,
+): id is CloudGitSelfManagedHostIntegrationIds {
+	switch (id) {
+		case GitSelfManagedHostIntegrationId.CloudGitHubEnterprise:
+		case GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted:
+		case GitSelfManagedHostIntegrationId.BitbucketServer:
+		case GitSelfManagedHostIntegrationId.AzureDevOpsServer:
+			return true;
+		default:
+			return false;
+	}
+}
+
+export function isGitHostIntegration(integration: Integration): integration is GitHostIntegration {
+	return integration.type === 'git';
+}
+
+export function isGitCloudHostIntegrationId(id: IntegrationIds): id is GitCloudHostIntegrationId {
+	switch (id) {
+		case GitCloudHostIntegrationId.GitHub:
+		case GitCloudHostIntegrationId.GitLab:
+		case GitCloudHostIntegrationId.Bitbucket:
+		case GitCloudHostIntegrationId.AzureDevOps:
+			return true;
+		default:
+			return false;
+	}
+}
+
+export function isGitSelfManagedHostIntegrationId(id: IntegrationIds): id is GitSelfManagedHostIntegrationId {
+	return selfHostedIntegrationIds.includes(id as GitSelfManagedHostIntegrationId);
+}

package/src/utils/disposable.ts

@@ -1,6 +1,19 @@
 import { once } from './function.js';
 
-export type UnifiedDisposable = { dispose: () => void } & Disposable;
+/**
+ * Minimal disposable contract — a single `dispose(): void` method.
+ *
+ * Mirrors the shape of `vscode.Disposable` so vscode-free packages can name
+ * the contract without requiring lib.es2022's `[Symbol.dispose]`. Classes that
+ * already implement `dispose()` (the vscode-style) satisfy it without changes.
+ *
+ * Use {@link UnifiedDisposable} when you also need the `using`-statement
+ * (`Symbol.dispose`) protocol; everything else can stay on this looser type.
+ */
+
+export type Disposable = { dispose: () => void };
+
+export type UnifiedDisposable = { dispose: () => void } & globalThis.Disposable;
 export type UnifiedAsyncDisposable = { dispose: () => Promise<void> } & AsyncDisposable;
 
 export function createDisposable(dispose: () => void, options?: { once?: boolean }): UnifiedDisposable;
@@ -57,7 +70,7 @@ export function disposableInterval(fn: (...args: any[]) => void, ms: number): Un
 }
 
 export function fromDisposables(
-	...disposables: (UnifiedDisposable | Disposable | { dispose: () => void } | undefined)[]
+	...disposables: (UnifiedDisposable | globalThis.Disposable | { dispose: () => void } | undefined)[]
 ): UnifiedDisposable {
 	let disposed = false;
 	const dispose = () => {