@gitkraken/core-gitlens 0.1.0

package/src/git/models/contributor.ts

@@ -0,0 +1,84 @@
+import { formatDate, fromNow } from '../../utils/date.js';
+import { loggable } from '../../utils/decorators/log.js';
+import { serializable } from '../../utils/decorators/serializable.js';
+import type { Shape } from '../../utils/types.js';
+import type { GitCommitStats } from './commit.js';
+
+export type GitContributorShape = Shape<GitContributor>;
+
+@loggable(i => i.name)
+@serializable
+export class GitContributor {
+	constructor(
+		public readonly repoPath: string,
+		public readonly name: string,
+		public readonly email: string | undefined,
+		public readonly current: boolean,
+		public readonly contributionCount: number,
+		public readonly contributions?: GitContributorContribution[],
+		public readonly latestCommitDate?: Date,
+		public readonly firstCommitDate?: Date,
+		public readonly stats?: GitContributorStats,
+		public readonly username?: string | undefined,
+		public readonly avatarUrl?: string | undefined,
+		public readonly id?: string | undefined,
+	) {}
+
+	get coauthor(): string {
+		return `${this.name}${this.email ? ` <${this.email}>` : ''}`;
+	}
+
+	get label(): string {
+		return this.name ?? this.username!;
+	}
+
+	/** Creates a copy of this contributor with a different repoPath — ONLY used for worktree-aware caching */
+	withRepoPath(repoPath: string): GitContributor {
+		if (repoPath === this.repoPath) return this;
+		return new GitContributor(
+			repoPath,
+			this.name,
+			this.email,
+			this.current,
+			this.contributionCount,
+			this.contributions,
+			this.latestCommitDate,
+			this.firstCommitDate,
+			this.stats,
+			this.username,
+			this.avatarUrl,
+			this.id,
+		);
+	}
+
+	static is(contributor: unknown): contributor is GitContributor {
+		return contributor instanceof GitContributor;
+	}
+
+	static formatDate(contributor: GitContributorShape, format?: string | null): string {
+		return contributor.latestCommitDate != null
+			? formatDate(contributor.latestCommitDate, format ?? 'MMMM Do, YYYY h:mma')
+			: '';
+	}
+
+	static formatDateFromNow(contributor: GitContributorShape, short?: boolean): string {
+		return contributor.latestCommitDate != null ? fromNow(contributor.latestCommitDate, short) : '';
+	}
+}
+
+interface GitContributorContribution extends Partial<GitCommitStats<number>> {
+	readonly sha: string;
+	readonly date: Date;
+	readonly message: string;
+}
+
+export interface GitContributorStats extends GitCommitStats<number> {
+	readonly contributionScore: number;
+}
+
+export interface GitContributorsStats {
+	readonly count: number;
+	readonly contributions: number[];
+}
+
+export type GitContributionTiers = '[1]' | '[2-5]' | '[6-10]' | '[11-50]' | '[51-100]' | '[101+]';

package/src/git/models/defaultBranch.ts

@@ -0,0 +1,6 @@
+import type { ProviderReference } from './remoteProvider.js';
+
+export interface DefaultBranch {
+	provider: ProviderReference;
+	name: string;
+}

package/src/git/models/diff.ts

@@ -0,0 +1,74 @@
+import type { GitFileChange, GitFileChangeShape } from './fileChange.js';
+import type { GitRevisionRangeNotation } from './revision.js';
+
+export interface GitDiff {
+	readonly contents: string;
+	readonly from: string;
+	readonly to: string;
+	readonly notation: GitRevisionRangeNotation | undefined;
+}
+
+export interface GitDiffFiles {
+	readonly files: GitFileChange[];
+}
+
+export interface GitDiffFileStats {
+	readonly added: number;
+	readonly deleted: number;
+	readonly changed: number;
+}
+
+export type GitDiffFilter = 'A' | 'C' | 'D' | 'M' | 'R' | 'T' | 'U' | 'X' | 'B' | '*';
+
+export interface GitDiffShortStat {
+	readonly files: number;
+	readonly additions: number;
+	readonly deletions: number;
+}
+
+export interface GitLineDiff {
+	readonly hunk: ParsedGitDiffHunk;
+	readonly line: ParsedGitDiffHunkLine;
+}
+
+export interface ParsedGitDiff {
+	readonly files: ParsedGitDiffFile[];
+	readonly rawContent?: string;
+}
+
+export interface ParsedGitDiffFile extends Omit<GitFileChangeShape, 'repoPath'>, ParsedGitDiffHunks {
+	readonly header: string;
+	readonly metadata: ParsedGitDiffFileMetadata;
+}
+
+export interface ParsedGitDiffFileMetadata {
+	readonly binary: boolean;
+	readonly modeChanged: false | { oldMode: string; newMode: string };
+	readonly renamedOrCopied: false | { similarity: number | undefined };
+}
+
+export interface ParsedGitDiffHunks {
+	readonly hunks: ParsedGitDiffHunk[];
+	readonly rawContent?: string;
+}
+
+export interface ParsedGitDiffHunk {
+	readonly header: string;
+	readonly content: string;
+
+	readonly current: {
+		readonly count: number;
+		readonly position: { readonly start: number; readonly end: number };
+	};
+	readonly previous: {
+		readonly count: number;
+		readonly position: { readonly start: number; readonly end: number };
+	};
+	readonly lines: Map<number, ParsedGitDiffHunkLine>;
+}
+
+export interface ParsedGitDiffHunkLine {
+	current: string | undefined;
+	previous: string | undefined;
+	state: 'added' | 'changed' | 'removed' | 'unchanged';
+}

package/src/git/models/file.ts

@@ -0,0 +1,29 @@
+import type { GitCommit } from './commit.js';
+import type { GitFileChangeStats } from './fileChange.js';
+import type {
+	GitFileConflictStatus,
+	GitFileIndexStatus,
+	GitFileStatus,
+	GitFileWorkingTreeStatus,
+} from './fileStatus.js';
+
+export interface GitFile {
+	readonly path: string;
+	readonly originalPath?: string;
+	status: GitFileStatus;
+	readonly repoPath?: string;
+
+	readonly conflictStatus?: GitFileConflictStatus;
+	readonly indexStatus?: GitFileIndexStatus;
+	readonly workingTreeStatus?: GitFileWorkingTreeStatus;
+
+	/** Per-file diff stats (additions, deletions, changes). Available when provided by the source (e.g. GitHub API comparison). */
+	readonly stats?: GitFileChangeStats;
+
+	/** For submodule (gitlink) entries, contains the submodule's commit SHAs */
+	readonly submodule?: { readonly oid: string; readonly previousOid?: string } | undefined;
+}
+
+export interface GitFileWithCommit extends GitFile {
+	readonly commit: GitCommit;
+}

package/src/git/models/fileChange.ts

@@ -0,0 +1,82 @@
+import { loggable } from '../../utils/decorators/log.js';
+import type { Uri } from '../../utils/uri.js';
+import type { DiffRange } from '../providers/types.js';
+import type { GitFileStatus } from './fileStatus.js';
+import { GitFileConflictStatus } from './fileStatus.js';
+
+export interface GitFileChangeShape {
+	readonly repoPath: string;
+	readonly path: string;
+	readonly status: GitFileStatus;
+
+	readonly originalPath?: string | undefined;
+	readonly staged?: boolean;
+
+	/** Git file mode (e.g., 100644=regular, 100755=executable, 120000=symlink, 160000=submodule) */
+	readonly mode?: string | undefined;
+	/** For submodule (gitlink) entries, contains the submodule's commit SHAs */
+	readonly submodule?: { readonly oid: string; readonly previousOid?: string } | undefined;
+}
+
+@loggable(i => i.path)
+export class GitFileChange implements GitFileChangeShape {
+	private readonly _uri: Uri;
+	private readonly _originalUri: Uri | undefined;
+
+	constructor(
+		public readonly repoPath: string,
+		public readonly path: string,
+		public readonly status: GitFileStatus,
+		uri: Uri,
+		public readonly originalPath?: string | undefined,
+		originalUri?: Uri | undefined,
+		public readonly previousSha?: string | undefined,
+		public readonly stats?: GitFileChangeStats | undefined,
+		public readonly staged?: boolean,
+		public readonly range?: DiffRange | undefined,
+		public readonly mode?: string | undefined,
+		public readonly submodule?: { readonly oid: string; readonly previousOid?: string } | undefined,
+	) {
+		this._uri = uri;
+		this._originalUri = originalUri;
+	}
+
+	get hasConflicts(): boolean {
+		switch (this.status) {
+			case GitFileConflictStatus.AddedByThem:
+			case GitFileConflictStatus.AddedByUs:
+			case GitFileConflictStatus.AddedByBoth:
+			case GitFileConflictStatus.DeletedByThem:
+			case GitFileConflictStatus.DeletedByUs:
+			case GitFileConflictStatus.DeletedByBoth:
+			case GitFileConflictStatus.ModifiedByBoth:
+				return true;
+
+			default:
+				return false;
+		}
+	}
+
+	/** Indicates this is a submodule (gitlink) rather than a regular file */
+	get isSubmodule(): boolean {
+		return this.submodule != null;
+	}
+
+	get uri(): Uri {
+		return this._uri;
+	}
+
+	get originalUri(): Uri | undefined {
+		return this._originalUri;
+	}
+
+	static is(file: unknown): file is GitFileChange {
+		return file instanceof GitFileChange;
+	}
+}
+
+export interface GitFileChangeStats {
+	additions: number;
+	deletions: number;
+	changes: number;
+}

package/src/git/models/fileStatus.ts

@@ -0,0 +1,35 @@
+export declare type GitFileStatus = GitFileConflictStatus | GitFileIndexStatus | GitFileWorkingTreeStatus;
+
+export const GitFileConflictStatus = {
+	AddedByBoth: 'AA',
+	AddedByUs: 'AU',
+	AddedByThem: 'UA',
+	DeletedByBoth: 'DD',
+	DeletedByUs: 'DU',
+	DeletedByThem: 'UD',
+	ModifiedByBoth: 'UU',
+} as const satisfies Record<string, string>;
+export type GitFileConflictStatus = (typeof GitFileConflictStatus)[keyof typeof GitFileConflictStatus];
+
+export const GitFileIndexStatus = {
+	Modified: 'M',
+	TypeChanged: 'T',
+	Added: 'A',
+	Deleted: 'D',
+	Renamed: 'R',
+	Copied: 'C',
+	Unchanged: '.',
+	Untracked: '?',
+	Ignored: '!',
+	UpdatedButUnmerged: 'U',
+} as const satisfies Record<string, string>;
+export type GitFileIndexStatus = (typeof GitFileIndexStatus)[keyof typeof GitFileIndexStatus];
+
+export const GitFileWorkingTreeStatus = {
+	Modified: 'M',
+	Added: 'A',
+	Deleted: 'D',
+	Untracked: '?',
+	Ignored: '!',
+} as const satisfies Record<string, string>;
+export type GitFileWorkingTreeStatus = (typeof GitFileWorkingTreeStatus)[keyof typeof GitFileWorkingTreeStatus];

package/src/git/models/graph.ts

@@ -0,0 +1,184 @@
+import type { GitBranch } from './branch.js';
+import type { GitStashCommit } from './commit.js';
+import type { GitRemote } from './remote.js';
+import type { GkProviderId } from './repositoryIdentities.js';
+import type { GitWorktree } from './worktree.js';
+
+export type GitGraphRowType =
+	| 'commit-node'
+	| 'merge-node'
+	| 'stash-node'
+	| 'work-dir-changes'
+	| 'merge-conflict-node'
+	| 'unsupported-rebase-warning-node';
+
+export interface GitGraphRowHead {
+	id?: string;
+	name: string;
+	isCurrentHead: boolean;
+	context?: string | object;
+	upstream?: { name: string; id: string };
+	worktreeId?: string;
+}
+
+export interface GitGraphRowRemoteHead {
+	id?: string;
+	name: string;
+	url?: string;
+	owner: string;
+	avatarUrl?: string;
+	context?: string | object;
+	current?: boolean;
+	hostingServiceType?: GkProviderId;
+}
+
+export interface GitGraphRowTag {
+	id?: string;
+	name: string;
+	annotated: boolean;
+	context?: string | object;
+}
+
+/**
+ * Context data attached to graph row regions for command/menu handling.
+ * Structurally compatible with @gitkraken/gitkraken-components RowContexts.
+ */
+export interface GitGraphRowContexts {
+	row?: string | object;
+	ref?: string | object;
+	refGroups?: Record<string, string | object>;
+	graph?: string | object;
+	avatar?: string | object;
+	message?: string | object;
+	author?: string | object;
+	date?: string | object;
+	sha?: string | object;
+	stats?: string | object;
+}
+
+export interface GitGraphRowStats {
+	files: number;
+	additions: number;
+	deletions: number;
+}
+
+/** Library-owned graph row type. Structurally compatible with @gitkraken/gitkraken-components GraphRow. */
+export interface GitGraphRow {
+	sha: string;
+	parents: string[];
+	author: string;
+	email: string;
+	date: number;
+	commitDate?: number;
+	message: string;
+	type: GitGraphRowType;
+	heads?: GitGraphRowHead[];
+	remotes?: GitGraphRowRemoteHead[];
+	tags?: GitGraphRowTag[];
+	contexts?: GitGraphRowContexts;
+	stats?: GitGraphRowStats;
+	reachableFromBranches?: string[];
+	isCurrentUser?: boolean;
+}
+
+export interface GitGraph {
+	readonly repoPath: string;
+	/** A map of all avatar urls */
+	readonly avatars: Map<string, string>;
+	/** A set of all "seen" commit ids */
+	readonly ids: Set<string>;
+	readonly includes: { stats?: boolean } | undefined;
+	readonly branches: ReadonlyMap<string, GitBranch>;
+	readonly remotes: ReadonlyMap<string, GitRemote>;
+	readonly downstreams: ReadonlyMap<string, string[]>;
+	readonly stashes: ReadonlyMap<string, GitStashCommit> | undefined;
+	readonly worktrees: ReadonlyArray<GitWorktree> | undefined;
+	readonly worktreesByBranch: ReadonlyMap<string, GitWorktree> | undefined;
+
+	/** SHAs reachable from HEAD (for enrichment: marking commits on the current branch) */
+	readonly reachableFromHEAD?: ReadonlySet<string>;
+	/** Map of SHA → set of branch names reachable from that SHA (for enrichment: branch context) */
+	readonly reachableFromBranches?: ReadonlyMap<string, ReadonlySet<string>>;
+
+	/** The rows for the set of commits requested */
+	readonly rows: GitGraphRow[];
+	readonly id?: string;
+
+	readonly rowsStats?: GitGraphRowsStats;
+	readonly rowsStatsDeferred?: { isLoaded: () => boolean; promise: Promise<void> };
+
+	readonly paging?: {
+		readonly limit: number | undefined;
+		readonly startingCursor: string | undefined;
+		readonly hasMore: boolean;
+	};
+
+	/**
+	 * Loads more commits for the graph.
+	 *
+	 * @param limit - The number of commits to load (page size)
+	 * @param id - Optional SHA to find
+	 * @param cancellation - Cancellation token
+	 *
+	 * **Behavior based on parameters:**
+	 *
+	 * - **`id` provided + `limit > 0`**: Find the commit with the given SHA, then ensure at least `limit` commits are loaded.
+	 *   - If SHA is found early (e.g., at position 100), continues loading to reach `limit` total commits.
+	 *   - If SHA is found late (e.g., at position 2000 when limit is 1000), loads all commits up to and including the SHA.
+	 *   - This ensures the target commit is included AND provides a full page of context.
+	 *
+	 * - **`id` provided + `limit === 0`**: Find the commit with the given SHA and stop immediately.
+	 *   - Loads only as many commits as needed to reach the target SHA.
+	 *   - Used when you want to find a specific commit without loading extra commits.
+	 *
+	 * - **No `id` + `limit > 0`**: Load exactly `limit` commits (normal pagination).
+	 *   - Standard page-based loading without a specific target.
+	 *
+	 * - **No `id` + `limit === 0`**: Load all remaining commits.
+	 *   - Loads everything from the current position to the end of history.
+	 *   - Use with caution as this can load a large number of commits.
+	 *
+	 * @example
+	 * // Load next page of 1000 commits
+	 * await graph.more(1000);
+	 *
+	 * @example
+	 * // Find a specific commit and ensure a full page is loaded
+	 * await graph.more(1000, 'abc123');
+	 *
+	 * @example
+	 * // Find a specific commit and stop (minimal loading)
+	 * await graph.more(0, 'abc123');
+	 */
+	more?(limit: number, id?: string, cancellation?: AbortSignal): Promise<GitGraph | undefined>;
+}
+
+export type GitGraphRowsStats = Map<string, GitGraphRowStats>;
+
+/**
+ * Processes a single graph row — mutates the row in place.
+ *
+ * Sets `row.contexts`, `row.message` (e.g., emojified), `tag.context`,
+ * `head.context`, `remoteHead.context`, `remoteHead.avatarUrl`.
+ * Also populates `context.avatars` with email → URL mappings.
+ *
+ * Called inline during graph row iteration in the library's row-building
+ * loop, once per row. Because it runs inside the loop, `more()` pagination
+ * automatically gets processing for free — no wrapping needed.
+ */
+export interface GraphRowProcessor {
+	processRow(row: GitGraphRow, context: GraphContext): void;
+}
+
+export interface GraphContext {
+	readonly repoPath: string;
+	readonly useAvatars: boolean;
+	readonly branches: ReadonlyMap<string, GitBranch>;
+	readonly remotes: ReadonlyMap<string, GitRemote>;
+	readonly worktreesByBranch: ReadonlyMap<string, GitWorktree> | undefined;
+	readonly branchIdOfMainWorktree: string | undefined;
+	readonly stashes: ReadonlyMap<string, GitStashCommit> | undefined;
+	readonly reachableFromHEAD: ReadonlySet<string>;
+	readonly reachableFromBranches: ReadonlyMap<string, ReadonlySet<string>>;
+	readonly avatars: Map<string, string>;
+}

package/src/git/models/graphSearch.ts

@@ -0,0 +1,53 @@
+import type { SearchQuery, SearchQueryFilters } from './search.js';
+
+export interface GitGraphSearchResultData {
+	readonly date: number;
+	readonly i: number;
+	readonly files?: ReadonlyArray<Readonly<{ readonly path: string }>>;
+}
+export type GitGraphSearchResults = Map<string, GitGraphSearchResultData>;
+
+export interface GitGraphSearchProgress {
+	readonly repoPath: string;
+	readonly query: SearchQuery;
+	readonly queryFilters: SearchQueryFilters;
+	readonly comparisonKey: string;
+	/** Whether there are more results available beyond the current limit */
+	readonly hasMore: boolean;
+	/** New results since the last progress update */
+	readonly results: GitGraphSearchResults;
+	/** Total count of all results accumulated so far */
+	readonly runningTotal: number;
+}
+
+export interface CliGitGraphSearchCursorState {
+	readonly iterations: number;
+	readonly totalSeen: number;
+	readonly sha: string;
+	readonly skip: number;
+}
+
+export type GitGraphSearchCursorState = CliGitGraphSearchCursorState | string;
+
+export interface GitGraphSearchCursor {
+	readonly search: SearchQuery;
+	readonly state: GitGraphSearchCursorState;
+}
+
+export interface GitGraphSearch {
+	readonly repoPath: string;
+	readonly query: SearchQuery;
+	readonly queryFilters: SearchQueryFilters;
+	readonly comparisonKey: string;
+	/** Whether there are more results available beyond the current limit */
+	readonly hasMore: boolean;
+	/** Complete set of results up to the current limit */
+	readonly results: GitGraphSearchResults;
+
+	readonly paging?: {
+		readonly limit: number | undefined;
+		readonly cursor?: GitGraphSearchCursor;
+	};
+
+	more?(limit: number): Promise<GitGraphSearch>;
+}

package/src/git/models/issue.ts

@@ -0,0 +1,88 @@
+import { loggable } from '../../utils/decorators/log.js';
+import type { RequireSome, RequireSomeWithProps } from '../../utils/types.js';
+import type { IssueOrPullRequest, IssueOrPullRequestState } from './issueOrPullRequest.js';
+import type { ProviderReference } from './remoteProvider.js';
+import type { RepositoryIdentityDescriptor } from './repositoryIdentities.js';
+
+export interface IssueShape extends IssueOrPullRequest {
+	author: IssueMember;
+	assignees: IssueMember[];
+	repository?: IssueRepository;
+	labels?: IssueLabel[];
+	body?: string;
+	project?: IssueProject;
+}
+
+@loggable(i => i.id)
+export class Issue implements IssueShape {
+	readonly type = 'issue';
+
+	constructor(
+		public readonly provider: ProviderReference,
+		public readonly id: string,
+		public readonly nodeId: string | undefined,
+		public readonly title: string,
+		public readonly url: string,
+		public readonly createdDate: Date,
+		public readonly updatedDate: Date,
+		public readonly closed: boolean,
+		public readonly state: IssueOrPullRequestState,
+		public readonly author: IssueMember,
+		public readonly assignees: IssueMember[],
+		public readonly repository?: IssueRepository,
+		public readonly closedDate?: Date,
+		public readonly labels?: IssueLabel[],
+		public readonly commentsCount?: number,
+		public readonly thumbsUpCount?: number,
+		public readonly body?: string,
+		public readonly project?: IssueProject,
+		public readonly number?: string,
+	) {}
+
+	static is(issue: unknown): issue is Issue {
+		return issue instanceof Issue;
+	}
+}
+
+export const enum RepositoryAccessLevel {
+	Admin = 100,
+	Maintain = 40,
+	Write = 30,
+	Triage = 20,
+	Read = 10,
+	None = 0,
+}
+
+export interface IssueLabel {
+	color?: string;
+	name: string;
+}
+
+export interface IssueMember {
+	id: string;
+	name: string;
+	avatarUrl?: string;
+	url?: string;
+}
+
+export interface IssueProject {
+	id: string;
+	name: string;
+	resourceId: string;
+	resourceName: string;
+}
+
+export interface IssueRepository {
+	owner: string;
+	repo: string;
+	accessLevel?: RepositoryAccessLevel;
+	url?: string;
+	id?: string;
+}
+
+export type IssueRepositoryIdentityDescriptor = RequireSomeWithProps<
+	RequireSome<RepositoryIdentityDescriptor<string>, 'provider'>,
+	'provider',
+	'id' | 'domain' | 'repoDomain' | 'repoName'
+> &
+	RequireSomeWithProps<RequireSome<RepositoryIdentityDescriptor<string>, 'remote'>, 'remote', 'domain'>;

package/src/git/models/issueOrPullRequest.ts

@@ -0,0 +1,20 @@
+import type { ProviderReference } from './remoteProvider.js';
+
+export interface IssueOrPullRequest {
+	readonly type: IssueOrPullRequestType;
+	readonly provider: ProviderReference;
+	readonly id: string;
+	readonly nodeId: string | undefined;
+	readonly title: string;
+	readonly url: string;
+	readonly createdDate: Date;
+	readonly updatedDate: Date;
+	readonly closedDate?: Date;
+	readonly closed: boolean;
+	readonly state: IssueOrPullRequestState;
+	readonly commentsCount?: number;
+	readonly thumbsUpCount?: number;
+}
+
+export type IssueOrPullRequestType = 'issue' | 'pullrequest';
+export type IssueOrPullRequestState = 'opened' | 'closed' | 'merged';

package/src/git/models/lineRange.ts

@@ -0,0 +1,7 @@
+/** A 1-based line and character range, replacing VS Code's `Range` which depends on `Position` objects */
+export interface LineRange {
+	startLine: number;
+	startCharacter: number;
+	endLine: number;
+	endCharacter: number;
+}

package/src/git/models/log.ts

@@ -0,0 +1,21 @@
+import type { GitCommit } from './commit.js';
+import type { SearchQueryFilters } from './search.js';
+
+export interface GitLog {
+	readonly repoPath: string;
+	readonly commits: Map<string, GitCommit>;
+	readonly count: number;
+
+	readonly sha: string | undefined;
+	readonly searchFilters?: SearchQueryFilters;
+
+	readonly limit: number | undefined;
+	readonly startingCursor?: string;
+	readonly endingCursor?: string;
+	readonly hasMore: boolean;
+
+	readonly pagedCommits?: () => Map<string, GitCommit>;
+
+	query?(limit: number | undefined): Promise<GitLog | undefined>;
+	more?(limit: number | { until?: string } | undefined): Promise<GitLog | undefined>;
+}