@gitkraken/core-gitlens 0.1.0

package/src/utils/types.ts

@@ -0,0 +1,31 @@
+import type { Branded } from './brand.js';
+
+/** Makes all properties of T mutable (removes readonly) */
+export type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+
+/** Extracts all properties of T whose values extend U, mapping non-matching to never */
+export type ExtractAll<T, U> = { [K in keyof T]: T[K] extends U ? T[K] : never };
+
+/** Makes some properties of T required */
+export type RequireSome<T, K extends keyof T> = Omit<T, K> & { [P in K]-?: T[P] };
+
+/** Makes some sub-properties of a required property required */
+export type RequireSomeWithProps<T, K extends keyof T, Props extends keyof T[K]> = Omit<T, K> & {
+	[P in K]-?: RequireSome<T[P], Props>;
+};
+
+export type Shape<T> = T extends ((...args: any[]) => any) | RegExp
+	? never
+	: T extends Date | Promise<any>
+		? T
+		: T extends Map<infer K, infer V>
+			? [Shape<K>, Shape<V>][]
+			: T extends Set<infer U>
+				? Shape<U>[]
+				: T extends Branded<infer U, any>
+					? U
+					: T extends any[]
+						? Shape<T[number]>[]
+						: T extends object
+							? { [K in keyof T as T[K] extends (...args: any[]) => any ? never : K]: Shape<T[K]> }
+							: T;

package/src/utils/uri.ts

@@ -0,0 +1,117 @@
+import { URI, Utils } from 'vscode-uri';
+import { normalizePath } from './path.js';
+
+/**
+ * Structural URI interface satisfied by both `vscode.Uri` and `vscode-uri.URI`.
+ * Use in all function signatures so callers can pass either type without conversion.
+ *
+ * For construction, use the factory functions exported from this module
+ * (`parseUri`, `fileUri`, `fromUri`, etc.) or the concrete `vscode.Uri.*`
+ * statics when in extension code.
+ */
+export interface Uri {
+	readonly scheme: string;
+	readonly authority: string;
+	readonly path: string;
+	readonly query: string;
+	readonly fragment: string;
+	readonly fsPath: string;
+
+	with(change: {
+		scheme?: string;
+		authority?: string | null;
+		path?: string | null;
+		query?: string | null;
+		fragment?: string | null;
+	}): Uri;
+
+	toString(skipEncoding?: boolean): string;
+	toJSON(): UriComponents;
+}
+
+export interface UriComponents {
+	scheme: string;
+	authority: string;
+	path: string;
+	query: string;
+	fragment: string;
+}
+
+/** Compare two Uris for equality by their string representation. */
+export function areUrisEqual(a: Uri | undefined, b: Uri | undefined): boolean {
+	if (a === b) return true;
+	if (a == null || b == null) return false;
+
+	return a.toString() === b.toString();
+}
+
+/** Convert a string (file path or URI string) into a Uri. */
+export function coerceUri(pathOrUri: string): Uri {
+	return hasScheme(pathOrUri) ? URI.parse(pathOrUri) : URI.file(pathOrUri);
+}
+
+/** Create a file-scheme URI from a file-system path. */
+export function fileUri(path: string): Uri {
+	return URI.file(path);
+}
+
+/** Create a URI from component parts. */
+export function fromUri(components: {
+	scheme: string;
+	authority?: string;
+	path?: string;
+	query?: string;
+	fragment?: string;
+}): Uri {
+	return URI.from(components);
+}
+
+const hasSchemeRegex = /^([a-zA-Z][\w+.-]+):/;
+
+/** Check if a string has a URI scheme. */
+export function hasScheme(pathOrUri: string): boolean {
+	return hasSchemeRegex.test(pathOrUri);
+}
+
+/** Type guard: is the value a Uri-shaped object? */
+export function isUri(value: unknown): value is Uri {
+	return URI.isUri(value);
+}
+
+/** Join path segments onto a URI (like `vscode.Uri.joinPath` / `vscode-uri Utils.joinPath`). */
+export function joinUriPath(uri: Uri, ...paths: string[]): Uri {
+	return Utils.joinPath(uri satisfies URI, ...paths);
+}
+
+/** Parse a URI string (e.g. `file:///foo/bar`, `https://example.com`). */
+export function parseUri(value: string, strict?: boolean): Uri {
+	return URI.parse(value, strict);
+}
+
+/** Revive a serialized {@link UriComponents} back into a Uri. */
+export function reviveUri(data: UriComponents): Uri {
+	return URI.revive(data);
+}
+
+/**
+ * Canonical repository identity key.
+ *
+ * - file path string → `normalizePath(path)`
+ * - `file:` URI string → parse → `normalizePath(fsPath)`
+ * - non-file URI string → parse → canonicalized `toString()`
+ * - `file:` Uri object → `normalizePath(fsPath)`
+ * - non-file Uri object → `toString()`
+ */
+export function getRepositoryKey(pathOrUri: string | Uri): string {
+	if (typeof pathOrUri === 'string') {
+		if (!hasScheme(pathOrUri)) return normalizePath(pathOrUri);
+		// Parse URI strings so file: URIs get normalized to fsPath
+		pathOrUri = URI.parse(pathOrUri);
+	}
+	return pathOrUri.scheme === 'file' ? normalizePath(pathOrUri.fsPath) : pathOrUri.toString();
+}
+
+/** Extract the file-system path from a path-or-Uri value. */
+export function toFsPath(pathOrUri: string | Uri): string {
+	return typeof pathOrUri === 'string' ? pathOrUri : pathOrUri.fsPath;
+}

package/src/utils/validation.ts

@@ -0,0 +1,38 @@
+export type Validator<T> = (data: unknown) => data is T;
+
+export const Is = Object.freeze({
+	String: (data: unknown): data is string => typeof data === 'string',
+	Number: (data: unknown): data is number => typeof data === 'number',
+	Boolean: (data: unknown): data is boolean => typeof data === 'boolean',
+	Object: (data: unknown): data is object => data != null && typeof data === 'object',
+	Array:
+		<T>(elementValidator: Validator<T>): Validator<T[]> =>
+		(data: unknown): data is T[] =>
+			Array.isArray(data) && data.every(elementValidator),
+
+	Enum:
+		<T extends string | number>(...values: T[]): Validator<T> =>
+		(data: unknown): data is T =>
+			values.includes(data as T),
+	// Literal:
+	// 	<T extends string | number | boolean>(value: T): Validator<T> =>
+	// 	(data: unknown): data is T =>
+	// 		data === value,
+	Optional:
+		<T>(validator: Validator<T>): Validator<T | undefined> =>
+		(data: unknown): data is T | undefined =>
+			data === undefined || validator(data),
+	// Union:
+	// 	<T extends unknown[]>(...validators: { [K in keyof T]: Validator<T[K]> }): Validator<T[number]> =>
+	// 	(data: unknown): data is T[number] =>
+	// 		validators.some(v => v(data)),
+});
+
+export function createValidator<T extends object>(shape: { [K in keyof T]: Validator<T[K]> }): Validator<T> {
+	return (data: unknown): data is T => {
+		if (!Is.Object(data)) return false;
+
+		const entries = Object.entries(shape) as [keyof T, Validator<T[keyof T]>][];
+		return entries.every(([key, validator]) => validator((data as Record<keyof T, unknown>)[key]));
+	};
+}

package/src/utils/version.ts

@@ -0,0 +1,79 @@
+import { compareIgnoreCase } from './string.js';
+
+declare type VersionComparisonResult = -1 | 0 | 1;
+
+export interface Version {
+	major: number;
+	minor: number;
+	patch: number;
+	pre?: string;
+}
+
+export function compare(v1: string | Version, v2: string | Version): VersionComparisonResult {
+	if (typeof v1 === 'string') {
+		v1 = fromString(v1);
+	}
+	if (typeof v2 === 'string') {
+		v2 = fromString(v2);
+	}
+
+	if (v1.major > v2.major) return 1;
+	if (v1.major < v2.major) return -1;
+
+	if (v1.minor > v2.minor) return 1;
+	if (v1.minor < v2.minor) return -1;
+
+	if (v1.patch > v2.patch) return 1;
+	if (v1.patch < v2.patch) return -1;
+
+	if (v1.pre === undefined && v2.pre !== undefined) return 1;
+	if (v1.pre !== undefined && v2.pre === undefined) return -1;
+
+	if (v1.pre !== undefined && v2.pre !== undefined) return compareIgnoreCase(v1.pre, v2.pre);
+
+	return 0;
+}
+
+export function from(major: string | number, minor: string | number, patch?: string | number, pre?: string): Version {
+	return {
+		major: typeof major === 'string' ? parseInt(major, 10) : major,
+		minor: typeof minor === 'string' ? parseInt(minor, 10) : minor,
+		patch: patch == null ? 0 : typeof patch === 'string' ? parseInt(patch, 10) : patch,
+		pre: pre,
+	};
+}
+
+export function fromString(version: string): Version {
+	const [ver, pre] = version.split('-');
+	const [major, minor, patch] = ver.split('.');
+	return from(major, minor, patch, pre);
+}
+
+export function fromVersion(v: Version, includePre: false): `${number}.${number}.${number}`;
+export function fromVersion(v: Version, includePre?: boolean): `${number}.${number}.${number}${string | undefined}`;
+export function fromVersion(v: Version, includePre?: boolean): `${number}.${number}.${number}${string | undefined}` {
+	return `${v.major}.${v.minor}.${v.patch}${includePre && v.pre ? `-${v.pre}` : ''}`;
+}
+
+export function satisfies(
+	v: string | Version | null | undefined,
+	requirement: `${'=' | '>' | '>=' | '<' | '<='} ${string}`,
+): boolean {
+	if (v == null) return false;
+
+	const [op, version] = requirement.split(' ');
+
+	if (op === '=') {
+		return compare(v, version) === 0;
+	} else if (op === '>') {
+		return compare(v, version) > 0;
+	} else if (op === '>=') {
+		return compare(v, version) >= 0;
+	} else if (op === '<') {
+		return compare(v, version) < 0;
+	} else if (op === '<=') {
+		return compare(v, version) <= 0;
+	}
+
+	throw new Error(`Unknown operator: ${op}`);
+}