@gitkraken/core-gitlens 0.6.0 → 0.7.0

package/src/utils/decorators/log.ts

@@ -1,320 +0,0 @@
-/* oxlint-disable typescript/no-unsafe-return */
-import { getParameters } from '../function.js';
-import { getDurationMilliseconds, hrtime } from '../hrtime.js';
-import type { LogLevel } from '../logger.js';
-import { customLoggableNameFns, getLoggableName, Logger } from '../logger.js';
-import {
-	createLogScope,
-	getLoggableScopeBlock,
-	getScopedLogger,
-	logScopeIdGenerator,
-	runInScope,
-} from '../logger.scoped.js';
-import { isPromise } from '../promise.js';
-
-export const defaultSlowCallWarningThreshold = 1500;
-
-export interface LogContext {
-	id: number;
-	instance: any;
-	instanceName: string;
-	name: string;
-	prefix: string;
-}
-
-interface LogOptions<T extends (...args: any[]) => any> {
-	/** Controls parameter formatting in log output. `false` suppresses all params. A function receives the method args and returns named fields to log (or `false` to suppress). When omitted, params are auto-formatted from parameter names. */
-	args?: false | ((...args: Parameters<T>) => Record<string, unknown> | false);
-	/** Conditionally skips logging entirely (scope, timing, everything). Must use a `function` expression (not arrow) — `this` is bound to the class instance via `.apply()`. Annotate `this` with the class type for type safety. */
-	when?(this: unknown, ...args: Parameters<T>): boolean;
-	/** Controls exit/result logging. `true` logs the return value. A function receives the result and returns a custom exit string. */
-	exit?: ((result: PromiseType<ReturnType<T>>) => string) | true;
-	/** Overrides the log line prefix. Receives a {@link LogContext} and the method args. */
-	prefix?(context: LogContext, ...args: Parameters<T>): string;
-	/** Suppresses the entry log line and only logs on exit. `{ after: N }` further suppresses exit unless duration exceeds N ms. */
-	onlyExit?: true | { after: number };
-	/** Controls duration timing. `false` disables timing. `{ warnAfter: N }` overrides the slow call warning threshold (default 500ms). */
-	timing?: boolean | { warnAfter: number };
-}
-
-// Using Function type to support classes with private/protected constructors
-// oxlint-disable-next-line typescript/no-unsafe-function-type
-export function logName<T>(fn: (c: T, name: string) => string): (target: Function & { prototype: T }) => void {
-	// oxlint-disable-next-line typescript/no-unsafe-function-type
-	return (target: (abstract new (...args: any[]) => T) | (Function & { prototype: T })): void =>
-		void customLoggableNameFns.set(target, fn);
-}
-
-/**
- * Class decorator that adds a `toLoggable()` method to the prototype at runtime,
- * making instances compatible with the `Loggable` interface without requiring the
- * method to appear in the class's structural type.
- *
- * @param fn Optional function returning the content inside the parentheses.
- * Defaults to `id` if the instance has one, otherwise just `ClassName`.
- */
-export function loggable<T extends object>(fn?: (instance: T) => string) {
-	// oxlint-disable-next-line typescript/no-unsafe-function-type
-	return (target: (abstract new (...args: any[]) => T) | (Function & { prototype: T })): void => {
-		target.prototype.toLoggable = function (this: T): string {
-			const name = getLoggableName(this);
-			if (fn != null) return `${name}(${fn(this)})`;
-			return name;
-		};
-	};
-}
-
-export function info<T extends (...arg: any[]) => any>(
-	options?: LogOptions<T>,
-): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void {
-	return log<T>('info', options);
-}
-
-export function debug<T extends (...arg: any[]) => any>(
-	options?: LogOptions<T>,
-): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void {
-	return log<T>('debug', options);
-}
-
-export function trace<T extends (...arg: any[]) => any>(
-	options?: LogOptions<T>,
-): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void {
-	return log<T>('trace', options);
-}
-
-type PromiseType<T> = T extends Promise<infer U> ? U : T;
-
-function log<T extends (...arg: any[]) => any>(
-	logLevel: Exclude<LogLevel, 'off' | 'error' | 'warn'>,
-	options?: LogOptions<T>,
-): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void {
-	let argsFn: LogOptions<T>['args'] | undefined;
-	let whenFn: LogOptions<T>['when'] | undefined;
-	let exitFn: LogOptions<T>['exit'] | undefined;
-	let prefixFn: LogOptions<T>['prefix'] | undefined;
-	let onlyExit: NonNullable<LogOptions<T>['onlyExit']> | false = false;
-	let timing: NonNullable<LogOptions<T>['timing']> = true;
-	if (options != null) {
-		({ args: argsFn, when: whenFn, exit: exitFn, prefix: prefixFn, onlyExit = false, timing = true } = options);
-	}
-
-	const slowThreshold = typeof timing === 'object' ? timing.warnAfter : defaultSlowCallWarningThreshold;
-	const timed = timing !== false || (typeof onlyExit === 'object' && onlyExit.after > 0);
-
-	const logFn: (message: string, ...params: any[]) => void =
-		logLevel === 'trace' ? Logger.trace : logLevel === 'debug' ? Logger.debug : Logger.info;
-
-	return (_target: any, key: string, descriptor: PropertyDescriptor & Record<string, any>) => {
-		// oxlint-disable-next-line typescript/no-unsafe-function-type
-		let fn: Function | undefined;
-		let fnKey: string | undefined;
-		if (typeof descriptor.value === 'function') {
-			fn = descriptor.value;
-			fnKey = 'value';
-		} else if (typeof descriptor.get === 'function') {
-			fn = descriptor.get;
-			fnKey = 'get';
-		}
-		if (fn == null || fnKey == null) throw new Error('Not supported');
-
-		// Only extract parameter names for default formatting (when no args option provided)
-		const parameters = argsFn == null ? getParameters(fn) : [];
-
-		descriptor[fnKey] = function (this: any, ...args: Parameters<T>) {
-			// Always create scope unless logging is completely off (or condition fails)
-			// This ensures scope is available for error logging even at lower log levels
-			if (!Logger.enabled() || (whenFn != null && !whenFn.apply(this, args))) {
-				return fn.apply(this, args);
-			}
-
-			const shouldLog = Logger.enabled(logLevel);
-
-			// Get parent scope
-			const parentScope = getScopedLogger();
-			const prevScopeId = parentScope?.scopeId;
-			const scopeId = logScopeIdGenerator.next();
-
-			const instanceName = this != null ? getLoggableName(this) : undefined;
-
-			let prefix = instanceName
-				? `${getLoggableScopeBlock(scopeId, prevScopeId)} ${instanceName}.${key}`
-				: `${getLoggableScopeBlock(scopeId, prevScopeId)} ${key}`;
-
-			if (prefixFn != null) {
-				prefix = prefixFn(
-					{
-						id: scopeId,
-						instance: this,
-						instanceName: instanceName ?? '',
-						name: key,
-						prefix: prefix,
-					},
-					...args,
-				);
-			}
-
-			const scope = createLogScope(scopeId, prevScopeId, prefix);
-
-			// Lazy parameter formatting — deferred until first use to avoid
-			// expensive Logger.toLoggable() calls when the log won't be emitted
-			let loggableParams: string | undefined;
-			let paramsResolved = false;
-			const resolveParams = (): string | undefined => {
-				if (!paramsResolved) {
-					paramsResolved = true;
-					loggableParams = formatParams(argsFn, args, parameters);
-				}
-				return loggableParams;
-			};
-
-			// For non-onlyExit mode, log entry immediately
-			if (!onlyExit && shouldLog) {
-				const params = resolveParams();
-				logFn.call(Logger, params ? `${prefix}(${params})` : prefix);
-			}
-
-			if (onlyExit || timed || exitFn != null) {
-				const start = timed ? hrtime() : undefined;
-
-				const logError = (ex: unknown) => {
-					const duration = start !== undefined ? ` [${getDurationMilliseconds(start)}ms]` : '';
-					const exitInfo = scope.getExitInfo();
-					if (onlyExit) {
-						const params = resolveParams();
-						Logger.error(
-							ex,
-							params ? `${prefix}(${params})` : prefix,
-							exitInfo?.details ? `failed${exitInfo.details}${duration}` : `failed${duration}`,
-						);
-					} else {
-						Logger.error(
-							ex,
-							prefix,
-							exitInfo?.details ? `failed${exitInfo.details}${duration}` : `failed${duration}`,
-						);
-					}
-				};
-
-				const logResult = (r: any) => {
-					let duration: number | undefined;
-					let exitLogFn: typeof logFn;
-					let durationSuffix;
-					if (start != null) {
-						duration = getDurationMilliseconds(start);
-						if (duration > slowThreshold) {
-							exitLogFn = Logger.warn;
-							durationSuffix = ` [*${duration}ms] (slow)`;
-						} else {
-							exitLogFn = logFn;
-							durationSuffix = ` [${duration}ms]`;
-						}
-					} else {
-						durationSuffix = '';
-						exitLogFn = logFn;
-					}
-
-					const exitInfo = scope.getExitInfo();
-					let exit;
-					if (exitFn != null) {
-						if (typeof exitFn === 'function') {
-							try {
-								exit = exitFn(r);
-							} catch (ex) {
-								exit = `@log.exit error: ${ex}`;
-							}
-						} else if (exitFn === true) {
-							exit = `returned ${Logger.toLoggable(r)}`;
-						}
-					} else if (exitInfo?.failed) {
-						exit = exitInfo.failed;
-						exitLogFn = (message: string, ...params: any[]) => Logger.error(null, message, ...params);
-					} else {
-						exit = 'completed';
-					}
-
-					// Only log if: logging at this level, or slow call warning, or error
-					if (shouldLog || exitLogFn !== logFn) {
-						const params = resolveParams();
-						if (onlyExit) {
-							if (onlyExit === true || onlyExit.after === 0 || duration! > onlyExit.after) {
-								exitLogFn.call(
-									Logger,
-									params
-										? `${prefix}(${params}) ${exit}${exitInfo?.details || ''}${durationSuffix}`
-										: `${prefix} ${exit}${exitInfo?.details || ''}${durationSuffix}`,
-								);
-							}
-						} else {
-							exitLogFn.call(
-								Logger,
-								params
-									? `${prefix}(${params}) ${exit}${exitInfo?.details || ''}${durationSuffix}`
-									: `${prefix} ${exit}${exitInfo?.details || ''}${durationSuffix}`,
-							);
-						}
-					}
-				};
-
-				const execute = () => {
-					let result;
-					try {
-						result = fn.apply(this, args);
-					} catch (ex) {
-						logError(ex);
-						throw ex;
-					}
-
-					if (result != null && isPromise(result)) {
-						void result.then(logResult, logError).catch(() => {});
-					} else {
-						logResult(result);
-					}
-
-					return result;
-				};
-
-				// Run within scope context
-				return runInScope(scope, execute);
-			}
-
-			return runInScope(scope, () => fn.apply(this, args));
-		};
-	};
-}
-
-function formatParams<T extends (...args: any[]) => any>(
-	argsFn: LogOptions<T>['args'] | undefined,
-	args: Parameters<T>,
-	parameters: string[],
-): string | undefined {
-	if (argsFn === false || !args.length) return undefined;
-
-	// Function form: call it and format the returned Record
-	if (typeof argsFn === 'function') {
-		const result = argsFn(...args);
-		if (result === false) return undefined;
-
-		let formatted = '';
-		for (const [name, value] of Object.entries(result)) {
-			if (formatted.length) {
-				formatted += ', ';
-			}
-			formatted += `${name}=${Logger.toLoggable(value, name)}`;
-		}
-		return formatted || undefined;
-	}
-
-	// Default: use parameter names from getParameters()
-	let formatted = '';
-	let paramIndex = -1;
-	for (const paramValue of args as unknown[]) {
-		const paramName = parameters[++paramIndex];
-		if (formatted.length) {
-			formatted += ', ';
-		}
-		formatted += paramName
-			? `${paramName}=${Logger.toLoggable(paramValue, paramName)}`
-			: Logger.toLoggable(paramValue);
-	}
-	return formatted || undefined;
-}

package/src/utils/decorators/memoize.ts

@@ -1,98 +0,0 @@
-/* oxlint-disable typescript/no-unsafe-return */
-import { resolveProp } from './resolver.js';
-
-/** Keys for memoize version invalidation */
-export type MemoizeVersionKey = 'providers';
-
-interface MemoizeVersionedEntry {
-	version: number;
-	value: unknown;
-}
-
-const versions = new Map<MemoizeVersionKey, number>();
-
-function getMemoizeVersion(key: MemoizeVersionKey): number {
-	return versions.get(key) ?? 0;
-}
-
-/** Invalidates all memoized values that depend on the given version key */
-export function invalidateMemoized(key: MemoizeVersionKey): void {
-	versions.set(key, (versions.get(key) ?? 0) + 1);
-}
-
-export interface MemoizeOptions<T extends (...arg: any) => any> {
-	/** Custom resolver for generating cache keys from arguments */
-	resolver?: (...args: Parameters<T>) => string;
-	/**
-	 * Version key for cache invalidation.
-	 * When invalidateMemoized(key) is called, all memoized values
-	 * with this version key will be invalidated (cache miss on next call).
-	 */
-	version?: MemoizeVersionKey;
-}
-
-export function memoize(
-	options?: Omit<MemoizeOptions<any>, 'resolver'>,
-): (_target: any, key: string, descriptor: PropertyDescriptor) => void;
-export function memoize<T extends (...args: any[]) => any>(
-	options?: MemoizeOptions<T>,
-): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void;
-export function memoize<T extends (...args: any[]) => any>(
-	options?: MemoizeOptions<T>,
-): (_target: any, key: string, descriptor: PropertyDescriptor) => void {
-	const opts = options ?? {};
-
-	return (_target: any, key: string, descriptor: PropertyDescriptor & Record<string, any>): void => {
-		// oxlint-disable-next-line typescript/no-unsafe-function-type
-		let fn: Function | undefined;
-		let fnKey: string | undefined;
-
-		if (typeof descriptor.value === 'function') {
-			fn = descriptor.value;
-			fnKey = 'value';
-		} else if (typeof descriptor.get === 'function') {
-			fn = descriptor.get;
-			fnKey = 'get';
-		} else {
-			throw new Error('Not supported');
-		}
-
-		if (fn == null) throw new Error('Not supported');
-
-		const memoizeKey = `$memoize$${key}`;
-
-		const resolver: MemoizeOptions<T>['resolver'] | undefined = 'resolver' in opts ? opts.resolver : undefined;
-		const versioned = opts.version != null;
-
-		let result;
-		descriptor[fnKey] = function (...args: any[]) {
-			const prop = resolveProp(memoizeKey, resolver, ...(args as Parameters<T>));
-			const version = versioned ? getMemoizeVersion(opts.version!) : undefined;
-
-			if (Object.hasOwn(this, prop)) {
-				const cached = this[prop];
-				if (versioned) {
-					const entry = cached as MemoizeVersionedEntry;
-					if (entry.version === version) {
-						return entry.value;
-					}
-				} else {
-					return cached;
-				}
-			}
-
-			result = fn.apply(this, args);
-			// Note: rejected promises are cached like any other result — this prevents
-			// hammering a failing source on every call. If auto-invalidation on rejection
-			// is needed, add a configurable option here.
-			Object.defineProperty(this, prop, {
-				configurable: true,
-				enumerable: false,
-				writable: versioned,
-				value: versioned ? { version: version, value: result } : result,
-			});
-
-			return result;
-		};
-	};
-}

package/src/utils/decorators/resolver.ts

@@ -1,95 +0,0 @@
-import { getScopedCounter } from '../counter.js';
-import { isLoggable } from '../loggable.js';
-
-export type Resolver<T extends (...args: any[]) => any> = (...args: Parameters<T>) => string;
-
-let _defaultResolverOverride: ((...args: unknown[]) => string) | undefined;
-
-/**
- * Sets a custom default resolver that will be used by `defaultResolver`, `resolveProp`,
- * and all decorators that depend on them (`@gate`, `@sequentialize`, `@memoize`).
- *
- * Call this early in your application startup to inject environment-specific argument resolution
- * (e.g., handling VS Code Uri, CancellationToken, or other platform-specific types).
- */
-export function setDefaultResolver(resolver: ((...args: unknown[]) => string) | undefined): void {
-	_defaultResolverOverride = resolver;
-}
-
-export function resolveProp<T extends (...args: any[]) => any>(
-	key: string,
-	resolver: Resolver<T> | undefined,
-	...args: Parameters<T>
-): string {
-	if (args.length === 0) return key;
-
-	let resolved;
-	if (resolver != null) {
-		try {
-			resolved = resolver(...args);
-		} catch {
-			debugger;
-			resolved = defaultResolver(...args);
-		}
-	} else {
-		resolved = defaultResolver(...args);
-	}
-
-	return `${key}$${resolved}`;
-}
-
-export function defaultResolver(...args: unknown[]): string {
-	if (_defaultResolverOverride != null) return _defaultResolverOverride(...args);
-
-	if (args.length === 0) return '';
-	if (args.length > 1) return safeStringify(args);
-
-	const [arg] = args;
-	if (arg == null) return '';
-
-	switch (typeof arg) {
-		case 'string':
-			return arg;
-
-		case 'number':
-		case 'boolean':
-		case 'undefined':
-		case 'symbol':
-		case 'bigint':
-			return String(arg);
-
-		default:
-			if (arg instanceof Error) return String(arg);
-
-			if (isLoggable(arg)) return arg.toLoggable();
-
-			return safeStringify(arg);
-	}
-}
-
-const _fallbackCounter = getScopedCounter();
-const _objectIds = new WeakMap<object, number>();
-
-/**
- * JSON.stringify with protection against RangeError from objects
- * that serialize beyond JavaScript's string length limit.
- * Returns a stable identity per object via WeakMap.
- */
-function safeStringify(value: unknown): string {
-	try {
-		return JSON.stringify(value);
-	} catch (ex) {
-		if (ex instanceof RangeError) {
-			if (value != null && typeof value === 'object') {
-				let id = _objectIds.get(value);
-				if (id == null) {
-					id = _fallbackCounter.next();
-					_objectIds.set(value, id);
-				}
-				return `#${id}`;
-			}
-			return `#${_fallbackCounter.next()}`;
-		}
-		throw ex;
-	}
-}

package/src/utils/decorators/sequentialize.ts

@@ -1,118 +0,0 @@
-import { defaultResolver } from './resolver.js';
-
-interface SequentializeState {
-	promise: Promise<any>;
-	waiting?: {
-		key: string;
-		promise: Promise<any>;
-	};
-}
-
-interface SequentializeOptions<T extends (...args: any[]) => any> {
-	/**
-	 * Optional function to resolve arguments into a deduplication key.
-	 * Consecutive duplicate calls (same deduplication key) that haven't started yet are deduplicated and share the same result.
-	 * If omitted, uses the default resolver which deduplicates based on argument values.
-	 */
-	getDedupingKey?: (...args: Parameters<T>) => string;
-
-	/**
-	 * Optional function to resolve arguments into a queue key.
-	 * Calls with the same queue key execute sequentially in that queue.
-	 * Calls with different queue keys execute in parallel (different queues).
-	 * If omitted, all calls share a single queue.
-	 */
-	getQueueKey?: (...args: Parameters<T>) => string;
-}
-
-/**
- * Method decorator that ensures all calls to the decorated async method are executed sequentially.
- * If the method is called multiple times before a previous invocation completes, subsequent calls are queued and executed one after another.
- *
- * Consecutive duplicate calls (same arguments) that haven't started yet are deduplicated and share the same result.
- *
- * @param options Optional options object:
- *   - getQueueKey: Groups calls into parallel queues
- *   - getDedupingKey: Deduplicates consecutive calls within each queue
- *   - If omitted: Uses default resolver for deduplication, single queue for all calls
- */
-export function sequentialize<T extends (...args: any[]) => any>(
-	options?: SequentializeOptions<T>,
-): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void {
-	const getQueueKey = options?.getQueueKey;
-	const getDedupingKey = options?.getDedupingKey;
-
-	return (_target: any, key: string, descriptor: PropertyDescriptor) => {
-		// oxlint-disable-next-line typescript/no-unsafe-function-type
-		let fn: Function | undefined;
-		if (typeof descriptor.value === 'function') {
-			fn = descriptor.value;
-		} else if (typeof descriptor.get === 'function') {
-			fn = descriptor.get;
-		}
-		if (fn === undefined) throw new Error('Not supported');
-
-		const serializeKey = `$sequentialize$${key}`;
-
-		descriptor.value = function (this: any, ...args: any[]) {
-			// Compute queue key (if getQueueKey provided, otherwise use default queue)
-			const queueKey = getQueueKey?.(...(args as Parameters<T>)) ?? '';
-			const prop = queueKey ? `${serializeKey}$${queueKey}` : serializeKey;
-
-			if (!Object.hasOwn(this, prop)) {
-				Object.defineProperty(this, prop, {
-					configurable: false,
-					enumerable: false,
-					writable: true,
-					value: undefined,
-				});
-			}
-
-			const state: SequentializeState | undefined = this[prop];
-			// oxlint-disable-next-line typescript/no-unsafe-return
-			const run = async () => await fn.apply(this, args);
-
-			// Compute the dedupe key once
-			const dedupeKey = getDedupingKey?.(...(args as Parameters<T>)) ?? defaultResolver(...args);
-
-			// If there's a waiting call, check if we can deduplicate with it and return the same promise as the waiting call
-			if (state?.waiting?.key === dedupeKey) return state.waiting.promise;
-
-			// Chain this call after the current promise (or start fresh if no state)
-			let promise: Promise<any>;
-			if (state == null) {
-				// No existing state, start fresh and don't set waiting (it starts immediately)
-				promise = run();
-				this[prop] = { promise: promise };
-			} else {
-				// Chain after existing promise with a single handler for both success and error
-				const clearWaitingAndRun = () => {
-					// Clear waiting status when this call starts running
-					const s = this[prop];
-					if (s?.waiting?.promise === promise) {
-						s.waiting = undefined;
-					}
-					return run();
-				};
-
-				promise = state.promise.then(clearWaitingAndRun, clearWaitingAndRun);
-
-				// Update state with this call as the new waiting call
-				state.promise = promise;
-				state.waiting = { key: dedupeKey, promise: promise };
-			}
-
-			// Cleanup when done
-			void promise
-				.finally(() => {
-					const s = this[prop];
-					if (s?.promise === promise && s.waiting == null) {
-						this[prop] = undefined;
-					}
-				})
-				.catch(() => {});
-
-			return promise;
-		};
-	};
-}

package/src/utils/decorators/serializable.ts

@@ -1,43 +0,0 @@
-/* oxlint-disable typescript/no-unsafe-function-type */
-
-/**
- * Class decorator that adds a `toJSON()` method materializing all prototype getters into the
- * serialized output. This ensures that computed properties survive `JSON.stringify` and
- * structured-clone boundaries (e.g. IPC between extension host and webviews).
- *
- * The prototype chain is walked **once at decoration time** — the resulting getter key list is
- * captured in a closure, so per-instance `toJSON()` is just a fast array loop with no reflection.
- *
- * If the class has no prototype getters the decorator returns immediately without modifying the
- * class — zero cost for pure-data models.
- */
-export function serializable(target: Function): void {
-	// Walk the prototype chain once at module-load time to find all getter keys
-	const getterKeys = new Set<string>();
-	let proto = target.prototype as object | null;
-	while (proto != null && proto !== Object.prototype) {
-		for (const key of Object.getOwnPropertyNames(proto)) {
-			if (key === 'constructor') continue;
-
-			const desc = Object.getOwnPropertyDescriptor(proto, key);
-			if (desc?.get != null) {
-				getterKeys.add(key);
-			}
-		}
-		proto = Object.getPrototypeOf(proto) as object | null;
-	}
-
-	// No getters — leave the class untouched
-	if (!getterKeys.size) return;
-
-	// Mutate the prototype directly (same pattern as @loggable)
-	(target.prototype as Record<string, unknown>).toJSON = function (this: object): Record<string, unknown> {
-		const result: Record<string, unknown> = { ...(this as Record<string, unknown>) };
-		for (const key of getterKeys) {
-			if (!Object.hasOwn(result, key)) {
-				result[key] = (this as Record<string, unknown>)[key];
-			}
-		}
-		return result;
-	};
-}