@gitkraken/core-gitlens 0.1.0

package/src/git/exec.types.ts

@@ -0,0 +1,78 @@
+import type { CacheController } from '../utils/promiseCache.js';
+
+export type GitErrorHandling = 'throw' | 'ignore';
+
+export type GitResult<T extends string | Buffer | unknown = string> = {
+	readonly exitCode: number;
+	readonly stdout: T;
+	readonly stderr?: T;
+
+	readonly cancelled?: boolean;
+};
+
+/**
+ * Cache store interface for git command output caching.
+ * Stores full GitResult to preserve exitCode/stderr.
+ */
+export interface GitResultCache {
+	getOrCreate(
+		repoPath: string,
+		key: string,
+		factory: (cacheable: CacheController) => Promise<GitResult<unknown>>,
+		options?: { createTTL?: number; accessTTL?: number },
+	): Promise<GitResult<unknown>>;
+}
+
+/**
+ * Priority levels for git commands.
+ * - `interactive`: User-initiated operations (blame, hover) - highest priority
+ * - `normal`: Standard operations (status, config) - default priority
+ * - `background`: Expensive operations (log, graph) - can be throttled
+ */
+export type GitCommandPriority = 'interactive' | 'normal' | 'background';
+
+export interface GitExecOptions {
+	cancellation?: AbortSignal;
+	configs?: readonly string[];
+	readonly correlationKey?: string;
+	errors?: GitErrorHandling;
+	/** Priority level for queue ordering. If not specified, will be inferred from the command type. */
+	priority?: GitCommandPriority;
+	/** Specifies that this command should always be executed locally if possible (for live share sessions) */
+	runLocally?: boolean;
+
+	/**
+	 * If provided, cache the command's result (stdout, stderr, exitCode) in this store via an auto-generated cache key
+	 * Only use for commands with stable output (e.g., `git remote -v`)
+	 */
+	caching?: {
+		cache: GitResultCache;
+		/** The common repository path for worktree-shared caching. If not provided, defaults to cwd. */
+		commonPath?: string;
+		options?: { createTTL?: number; accessTTL?: number };
+	};
+
+	// Below options comes from RunOptions<BufferEncoding | 'buffer' | string>
+	cwd?: string;
+	readonly env?: Record<string, string | undefined>;
+	readonly encoding?: BufferEncoding | 'buffer' | string;
+	readonly maxBuffer?: number;
+	readonly stdin?: string | Buffer;
+	readonly stdinEncoding?: string;
+	// Set to 0 to disable
+	readonly timeout?: number;
+}
+
+export interface GitSpawnOptions {
+	cancellation?: AbortSignal;
+	configs?: readonly string[];
+
+	// Below options comes from SpawnOptions
+	cwd?: string;
+	readonly env?: Record<string, string | undefined>;
+	readonly encoding?: BufferEncoding | 'buffer' | string;
+	readonly stdin?: string | Buffer;
+	readonly stdinEncoding?: string;
+	// Set to 0 to disable
+	readonly timeout?: number;
+}

package/src/git/features.ts

@@ -0,0 +1,45 @@
+// GitFeature's must start with `git:` to be recognized in all usages
+export type GitFeatures =
+	| 'git:for-each-ref:worktreePath'
+	| 'git:ignoreRevsFile'
+	| 'git:merge-tree'
+	| 'git:merge-tree:write-tree'
+	| 'git:push:force-if-includes'
+	| 'git:rev-parse:end-of-options'
+	| 'git:signing:ssh'
+	| 'git:signing:x509'
+	| 'git:stash:push:pathspecs'
+	| 'git:stash:push:staged'
+	| 'git:stash:push:stdin'
+	| 'git:status:find-renames'
+	| 'git:status:porcelain-v2'
+	| 'git:worktrees';
+
+type ExtractPrefix<T> = T extends `${infer Prefix}:${infer Rest}`
+	? Rest extends `${infer SubPrefix}:${string}`
+		? T | `${Prefix}:${SubPrefix}` | Prefix
+		: T | Prefix
+	: never;
+
+export type GitFeatureOrPrefix = ExtractPrefix<GitFeatures>;
+export type FilteredGitFeatures<T extends GitFeatureOrPrefix> = T extends GitFeatures
+	? T
+	: Extract<GitFeatures, T | `${T}:${string}`>;
+
+export const gitMinimumVersion = '2.7.2';
+export const gitFeaturesByVersion = new Map<GitFeatures, string>([
+	['git:for-each-ref:worktreePath', '2.23'],
+	['git:ignoreRevsFile', '2.23'],
+	['git:merge-tree', '2.33'],
+	['git:merge-tree:write-tree', '2.38'],
+	['git:push:force-if-includes', '2.30.0'],
+	['git:rev-parse:end-of-options', '2.30'],
+	['git:signing:ssh', '2.34.0'],
+	['git:signing:x509', '2.19.0'],
+	['git:stash:push:pathspecs', '2.13.2'],
+	['git:stash:push:staged', '2.35.0'],
+	['git:stash:push:stdin', '2.30.0'],
+	['git:status:find-renames', '2.18'],
+	['git:status:porcelain-v2', '2.11'],
+	['git:worktrees', '2.17.0'],
+]);

package/src/git/models/author.ts

@@ -0,0 +1,19 @@
+import type { ProviderReference } from './remoteProvider.js';
+
+export interface CommitAuthor {
+	provider: ProviderReference;
+	readonly id: string | undefined;
+	readonly username: string | undefined;
+	name: string | undefined;
+	email: string | undefined;
+	avatarUrl: string | undefined;
+}
+
+export interface UnidentifiedAuthor extends CommitAuthor {
+	readonly id: undefined;
+	readonly username: undefined;
+}
+
+export interface Account extends CommitAuthor {
+	readonly id: string;
+}

package/src/git/models/autolink.ts

@@ -0,0 +1,59 @@
+import type { ProviderReference } from './remoteProvider.js';
+import type { ResourceDescriptor } from './resourceDescriptor.js';
+
+export type AutolinkType = 'issue' | 'pullrequest';
+export type AutolinkReferenceType = 'commit' | 'branch';
+
+export interface AutolinkReference {
+	/** Short prefix to match to generate autolinks for the external resource */
+	readonly prefix: string;
+	/** URL of the external resource to link to */
+	readonly url: string;
+	/** Whether alphanumeric characters should be allowed in `<num>` */
+	readonly alphanumeric: boolean;
+	/** Whether case should be ignored when matching the prefix */
+	readonly ignoreCase: boolean;
+	readonly title: string | undefined;
+
+	readonly type?: AutolinkType;
+	readonly referenceType?: AutolinkReferenceType;
+	readonly description?: string;
+	readonly descriptor?: ResourceDescriptor;
+}
+
+export interface Autolink extends Omit<CacheableAutolinkReference, 'id'> {
+	provider?: ProviderReference;
+	id: string;
+}
+
+export interface CacheableAutolinkReference extends AutolinkReference {
+	id?: never;
+
+	messageHtmlRegex?: RegExp;
+	messageMarkdownRegex?: RegExp;
+	messageRegex?: RegExp;
+	branchNameRegexes?: RegExp[];
+}
+
+/** Metadata for rendering a dynamic autolink pattern in text */
+export interface DynamicAutolinkDescriptor {
+	/** Regex with /g flag. Must capture groups: (fullMatch, repo, num) */
+	readonly regex: RegExp;
+	/** Builds URL from matched groups. Receives raw matched text — renderer handles escaping. */
+	readonly url: (repo: string, num: string) => string;
+	/** Hover title for the link */
+	readonly title: (repo: string, num: string) => string;
+	/** Label for footnotes */
+	readonly label: (repo: string, num: string) => string;
+}
+
+export interface DynamicAutolinkReference {
+	parse: (text: string, autolinks: Map<string, Autolink>) => void;
+	/** Descriptors for rendering dynamic autolinks in text. If absent, dynamic autolinks are parsed but not rendered as links. */
+	readonly descriptors?: readonly DynamicAutolinkDescriptor[];
+}
+
+export type RefSet = [
+	ProviderReference | undefined,
+	(AutolinkReference | DynamicAutolinkReference)[] | CacheableAutolinkReference[],
+];

package/src/git/models/blame.ts

@@ -0,0 +1,46 @@
+import type { Event } from '../../utils/event.js';
+import type { GitCommit, GitCommitLine } from './commit.js';
+
+export interface GitBlame {
+	readonly repoPath: string;
+	readonly authors: Map<string, GitBlameAuthor>;
+	readonly commits: Map<string, GitCommit>;
+	readonly lines: GitCommitLine[];
+}
+
+export interface GitBlameAuthor {
+	name: string;
+	lineCount: number;
+	current?: boolean;
+}
+
+export interface GitBlameLine {
+	readonly author?: GitBlameAuthor;
+	readonly commit: GitCommit;
+	readonly line: GitCommitLine;
+}
+
+export interface GitBlameProgressEvent {
+	readonly blame: GitBlame;
+	readonly complete: boolean;
+	/** Line indices (0-based) that were resolved since the last progress event */
+	readonly newLineIndices: number[];
+}
+
+/** Producer-side handle for writing to a progressive blame. Not exposed to consumers. */
+export interface ProgressiveGitBlameWriter {
+	update(blame: GitBlame, newLineIndices: number[]): void;
+	complete(blame: GitBlame): void;
+	fail(reason: unknown): void;
+}
+
+/**
+ * Read-only consumer view of an in-progress blame that grows as `git blame --incremental` streams entries.
+ * Exposes the current partial snapshot, a completion promise, and a progress event.
+ */
+export interface ProgressiveGitBlame {
+	readonly current: GitBlame;
+	readonly isComplete: boolean;
+	readonly completed: Promise<GitBlame>;
+	readonly onDidProgress: Event<GitBlameProgressEvent>;
+}

package/src/git/models/branch.ts

@@ -0,0 +1,236 @@
+import { formatDate, fromNow } from '../../utils/date.js';
+import { loggable } from '../../utils/decorators/log.js';
+import { memoize } from '../../utils/decorators/memoize.js';
+import { serializable } from '../../utils/decorators/serializable.js';
+import type { MaybePausedResult } from '../../utils/promise.js';
+import type { Shape } from '../../utils/types.js';
+import {
+	formatDetachedHeadName,
+	getBranchId,
+	getBranchTrackingWithoutRemote,
+	getRemoteNameFromBranchName,
+	getRemoteNameSlashIndex,
+	isDetachedHead,
+	parseRefName,
+} from '../utils/branch.utils.js';
+import { getUpstreamStatus } from '../utils/status.utils.js';
+import type { GitBranchReference } from './reference.js';
+
+export type BranchDisposition = 'starred' | 'archived';
+
+export interface BranchMetadata {
+	lastAccessedAt?: string;
+	lastModifiedAt?: string;
+	disposition?: BranchDisposition;
+}
+
+export type GitBranchShape = Shape<GitBranch>;
+
+@loggable(i => i.id)
+@serializable
+export class GitBranch implements GitBranchReference {
+	readonly refType = 'branch';
+	readonly detached: boolean;
+	readonly id: string;
+
+	private readonly _name: string;
+	get name(): string {
+		return this._name;
+	}
+
+	private readonly _remote: boolean;
+	get remote(): boolean {
+		return this._remote;
+	}
+
+	constructor(
+		public readonly repoPath: string,
+		public readonly refName: string,
+		public readonly current: boolean,
+		public readonly date: Date | undefined,
+		/** GK config metadata (dates, disposition) */
+		public readonly metadata: BranchMetadata | undefined,
+		public readonly sha?: string,
+		public readonly upstream?: GitTrackingUpstream,
+		public readonly worktree?: { path: string; isDefault: boolean } | false,
+		detached: boolean = false,
+		public readonly rebasing: boolean = false,
+	) {
+		({ name: this._name, remote: this._remote } = parseRefName(refName));
+
+		this.detached = detached || (this.current ? isDetachedHead(this._name) : false);
+		if (this.detached) {
+			this.id = getBranchId(repoPath, this._remote, this.sha!);
+			this._name = formatDetachedHeadName(this.sha!);
+		} else {
+			this.id = getBranchId(repoPath, this._remote, this._name);
+		}
+
+		this.upstream = upstream?.name ? upstream : undefined;
+	}
+
+	get archived(): boolean {
+		return this.metadata?.disposition === 'archived';
+	}
+
+	@memoize()
+	get basename(): string {
+		const name = this.nameWithoutRemote;
+		const index = name.lastIndexOf('/');
+		return index !== -1 ? name.substring(index + 1) : name;
+	}
+
+	get disposition(): BranchDisposition | undefined {
+		return this.metadata?.disposition;
+	}
+
+	/** @returns The most recent date among lastModifiedDate, lastAccessedDate, and branch.date */
+	get effectiveDate(): Date | undefined {
+		let maxTime: number | undefined;
+
+		const accessed = this.lastAccessedDate?.getTime();
+		if (accessed != null && (maxTime == null || accessed > maxTime)) {
+			maxTime = accessed;
+		}
+
+		const modified = this.lastModifiedDate?.getTime();
+		if (modified != null && (maxTime == null || modified > maxTime)) {
+			maxTime = modified;
+		}
+
+		const date = this.date?.getTime();
+		if (date != null && (maxTime == null || date > maxTime)) {
+			maxTime = date;
+		}
+
+		return maxTime != null ? new Date(maxTime) : undefined;
+	}
+
+	@memoize()
+	get lastAccessedDate(): Date | undefined {
+		return this.metadata?.lastAccessedAt ? new Date(this.metadata.lastAccessedAt) : undefined;
+	}
+
+	@memoize()
+	get lastModifiedDate(): Date | undefined {
+		return this.metadata?.lastModifiedAt ? new Date(this.metadata.lastModifiedAt) : undefined;
+	}
+
+	@memoize()
+	get nameWithoutRemote(): string {
+		return this.remote ? this.name.substring(getRemoteNameSlashIndex(this.name) + 1) : this.name;
+	}
+
+	get ref(): string {
+		return this.detached ? this.sha! : this._name;
+	}
+
+	@memoize()
+	get remoteName(): string | undefined {
+		if (this.remote) return getRemoteNameFromBranchName(this.name);
+		if (this.upstream != null) return getRemoteNameFromBranchName(this.upstream.name);
+
+		return undefined;
+	}
+
+	get starred(): boolean {
+		return this.metadata?.disposition === 'starred';
+	}
+
+	get status(): GitBranchStatus {
+		if (this.remote) return 'remote';
+		if (this.upstream == null) return this.detached ? 'detached' : 'local';
+
+		if (this.upstream.missing) return 'missingUpstream';
+		if (this.upstream.state.ahead && this.upstream.state.behind) return 'diverged';
+		if (this.upstream.state.ahead) return 'ahead';
+		if (this.upstream.state.behind) return 'behind';
+		return 'upToDate';
+	}
+
+	@memoize()
+	get trackingWithoutRemote(): string | undefined {
+		return getBranchTrackingWithoutRemote(this);
+	}
+
+	/** Creates a copy of this branch with a different repoPath and optionally a different current flag — ONLY used for worktree-aware caching */
+	withRepoPath(repoPath: string, current?: boolean): GitBranch {
+		const newCurrent = current ?? this.current;
+		if (repoPath === this.repoPath && newCurrent === this.current) return this;
+		return new GitBranch(
+			repoPath,
+			this.refName,
+			newCurrent,
+			this.date,
+			this.metadata,
+			this.sha,
+			this.upstream,
+			this.worktree,
+			this.detached,
+			this.rebasing,
+		);
+	}
+
+	static is(branch: unknown): branch is GitBranch {
+		return branch instanceof GitBranch;
+	}
+
+	static formatDate(branch: GitBranchShape, format?: string | null): string {
+		return branch.date != null ? formatDate(branch.date, format ?? 'MMMM Do, YYYY h:mma') : '';
+	}
+
+	static formatDateFromNow(branch: GitBranchShape): string {
+		return branch.date != null ? fromNow(branch.date) : '';
+	}
+
+	static formatDateWithStyle(
+		branch: GitBranchShape,
+		formatting: { dateStyle: string; dateFormat: string | null },
+	): string {
+		return formatting.dateStyle === 'absolute'
+			? GitBranch.formatDate(branch, formatting.dateFormat)
+			: GitBranch.formatDateFromNow(branch);
+	}
+
+	static getTrackingStatus(
+		branch: GitBranchShape,
+		options?: {
+			count?: boolean;
+			empty?: string;
+			expand?: boolean;
+			icons?: boolean;
+			prefix?: string;
+			separator?: string;
+			suffix?: string;
+		},
+	): string {
+		return getUpstreamStatus(branch.upstream, options);
+	}
+}
+
+export interface GitTrackingState {
+	readonly ahead: number;
+	readonly behind: number;
+}
+
+export interface GitTrackingUpstream {
+	readonly name: string;
+	readonly missing: boolean;
+	readonly state: GitTrackingState;
+}
+
+export type GitBranchStatus =
+	| 'local'
+	| 'detached'
+	| 'ahead'
+	| 'behind'
+	| 'diverged'
+	| 'upToDate'
+	| 'missingUpstream'
+	| 'remote';
+
+export interface BranchTargetInfo {
+	mergeTargetBranch: MaybePausedResult<string | undefined>;
+	baseBranch: string | undefined;
+	defaultBranch: string | undefined;
+}