@gitkraken/core-gitlens 0.1.0

package/src/utils/lazy.ts

@@ -0,0 +1,39 @@
+/** Provides lazy initialization support */
+export class Lazy<T> {
+	private _evaluated: boolean = false;
+	get evaluated(): boolean {
+		return this._evaluated;
+	}
+
+	private _exception: Error | undefined;
+	private _value?: T;
+
+	/**
+	 * Creates a new instance of Lazy<T> that uses the specified initialization function.
+	 * @param valueProvider The initialization function that is used to produce the value when it is needed.
+	 */
+	constructor(private readonly valueProvider: () => T) {}
+
+	/** Gets the lazily initialized value of the current Lazy<T> instance */
+	get value(): T {
+		if (!this._evaluated) {
+			try {
+				this._value = this.valueProvider();
+			} catch (ex) {
+				this._exception = ex;
+				throw ex;
+			} finally {
+				this._evaluated = true;
+			}
+		}
+
+		if (this._exception) throw this._exception;
+
+		return this._value!;
+	}
+}
+
+/** Creates a new lazy value with the specified initialization function */
+export function lazy<T>(valueProvider: () => T): Lazy<T> {
+	return new Lazy<T>(valueProvider);
+}

package/src/utils/loggable.ts

@@ -0,0 +1,7 @@
+export interface Loggable {
+	toLoggable(): string;
+}
+
+export function isLoggable(o: unknown): o is Loggable {
+	return o != null && typeof o === 'object' && 'toLoggable' in o && typeof (o as Loggable).toLoggable === 'function';
+}

package/src/utils/logger.scoped.ts

@@ -0,0 +1,237 @@
+import { enterScope, exitScope, getCurrentScope, runInScope } from '#env/logScope.js';
+import { getScopedCounter } from './counter.js';
+import { getDurationMilliseconds, hrtime } from './hrtime.js';
+import type { LogLevel } from './logger.js';
+import { Logger } from './logger.js';
+
+/** Runs a function within a log scope context. */
+export { runInScope };
+
+export const logScopeIdGenerator = getScopedCounter();
+
+export interface ScopedLogger {
+	readonly scopeId?: number;
+	readonly prevScopeId?: number;
+	readonly prefix: string;
+
+	enabled(level: Exclude<LogLevel, 'off'>): boolean;
+
+	trace(message: string, ...params: any[]): void;
+	debug(message: string, ...params: any[]): void;
+	info(message: string, ...params: any[]): void;
+	warn(message: string, ...params: any[]): void;
+	error(ex: Error | unknown, message?: string, ...params: any[]): void;
+
+	/** Adds exit details for this scope. Details are automatically prefixed with ' \u2022 ' and accumulate. */
+	addExitInfo(...details: string[]): void;
+	/** Sets the failure reason for this scope. Overwrites any previous failure. */
+	setFailed(reason: string): void;
+
+	/** @internal Returns exit info for logging - used internally by the @log decorator */
+	getExitInfo(): { details: string | undefined; failed: string | undefined };
+}
+
+export function createLogScope(scopeId: number, prevScopeId: number | undefined, prefix: string): ScopedLogger {
+	let exitDetails: string[] | undefined;
+	let exitFailed: string | undefined;
+
+	// eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+	const scope: ScopedLogger = {
+		scopeId: scopeId,
+		prevScopeId: prevScopeId,
+		prefix: prefix,
+		enabled: (level?: Exclude<LogLevel, 'off'>) => Logger.enabled(level),
+		addExitInfo: function (...details: string[]): void {
+			(exitDetails ??= []).push(...details);
+		},
+		setFailed: function (reason: string): void {
+			exitFailed = reason;
+		},
+
+		getExitInfo: function () {
+			return {
+				details: exitDetails?.length ? ` \u2022 ${exitDetails.join(', ')}` : undefined,
+				failed: exitFailed,
+			};
+		},
+	} as ScopedLogger;
+
+	// Lazy bind - getter replaces itself with bound function on first access
+	defineLazyBoundMethod(scope, 'trace', Logger.trace);
+	defineLazyBoundMethod(scope, 'debug', Logger.debug);
+	defineLazyBoundMethod(scope, 'info', Logger.info);
+	defineLazyBoundMethod(scope, 'warn', Logger.warn);
+	defineLazyBoundErrorMethod(scope);
+
+	return scope;
+}
+
+function defineLazyBoundMethod<K extends 'trace' | 'debug' | 'info' | 'warn'>(
+	scope: ScopedLogger,
+	name: K,
+	method: (typeof Logger)[K],
+): void {
+	Object.defineProperty(scope, name, {
+		configurable: true,
+		enumerable: true,
+		get: function () {
+			const bound = method.bind(Logger, scope);
+			Object.defineProperty(scope, name, { value: bound, writable: false, enumerable: true });
+			return bound;
+		},
+	});
+}
+
+function defineLazyBoundErrorMethod(scope: ScopedLogger): void {
+	Object.defineProperty(scope, 'error', {
+		configurable: true,
+		enumerable: true,
+		get: function () {
+			const bound = (ex: Error | unknown, message?: string, ...params: any[]) =>
+				Logger.error(ex, scope, message, ...params);
+			Object.defineProperty(scope, 'error', { value: bound, writable: false, enumerable: true });
+			return bound;
+		},
+	});
+}
+
+export function formatLoggableScopeBlock(prefix: string, suffix?: string): string {
+	if (suffix == null) return `[${prefix.padEnd(13)}]`;
+
+	return `[${prefix}${suffix.padStart(13 - prefix.length)}]`;
+}
+
+export function getLoggableScopeBlock(scopeId: number, prevScopeId?: number, label?: string): string {
+	if (label != null) {
+		const suffix =
+			prevScopeId == null ? scopeId.toString(16) : `${prevScopeId.toString(16)} \u2192 ${scopeId.toString(16)}`;
+		return formatLoggableScopeBlock(label, suffix);
+	}
+
+	return prevScopeId == null
+		? `[${scopeId.toString(16).padStart(13)}]`
+		: `[${prevScopeId.toString(16).padStart(5)} \u2192 ${scopeId.toString(16).padStart(5)}]`;
+}
+
+/** Gets the current log scope */
+export function getScopedLogger(): (ScopedLogger & Disposable) | undefined {
+	const scope = getCurrentScope();
+	if (scope == null) return undefined;
+
+	// Return a prototype wrapper with a no-op dispose so `using` won't exit a parent's scope
+	const wrapper = Object.create(scope) as ScopedLogger & Disposable;
+	wrapper[Symbol.dispose] = () => {};
+	return wrapper;
+}
+
+/**
+ * @internal only exported for use in other logging-related modules, not for general use
+ */
+export function getNewLogScope(
+	prefix: string,
+	scope: ScopedLogger | boolean | undefined,
+	label?: string,
+): ScopedLogger {
+	if (scope != null && typeof scope !== 'boolean') {
+		return createLogScope(scope.scopeId!, scope.prevScopeId, `${scope.prefix}${prefix}`);
+	}
+
+	const prevScopeId = scope ? getCurrentScope()?.scopeId : undefined;
+	const scopeId = logScopeIdGenerator.next();
+	return createLogScope(scopeId, prevScopeId, `${getLoggableScopeBlock(scopeId, prevScopeId, label)} ${prefix}`);
+}
+
+/** Starts a scoped logger for use with the `using` keyword */
+function startScopedLogger(
+	prefix: string,
+	scope: ScopedLogger | boolean | undefined,
+	label?: string,
+): ScopedLogger & Disposable {
+	const prevScope = getCurrentScope();
+	const newScope = getNewLogScope(prefix, scope, label) as ScopedLogger & Disposable;
+	enterScope(newScope);
+
+	// Add dispose method directly to preserve lazy-bound logger methods
+	newScope[Symbol.dispose] = () => {
+		exitScope(prevScope, newScope);
+	};
+
+	return newScope;
+}
+
+/**
+ * Creates a scoped logger for standalone functions and code blocks
+ * Returns `undefined` when all logging is disabled
+ *
+ * This is the non-decorator equivalent of `@log()` for standalone functions,
+ * callbacks, and code blocks. Supports the `using` keyword for automatic cleanup.
+ *
+ * @param prefix - The log prefix (typically `ClassName.methodName`)
+ * @param log - Controls automatic entry/exit logging with timing:
+ *   - omitted/falsy: scope tracking only (no auto-logging)
+ *   - `true`: auto entry + exit with timing at debug level
+ *   - `{ level?, message?, onlyExit? }`: fine-grained control
+ */
+export function maybeStartScopedLogger(
+	prefix: string,
+	log?: boolean | { level?: Exclude<LogLevel, 'off' | 'error' | 'warn'>; message?: string; onlyExit?: true },
+	options?: { scopeLabel?: string; scope?: ScopedLogger },
+): (ScopedLogger & Disposable) | undefined {
+	if (!Logger.enabled()) return undefined;
+
+	const scope = startScopedLogger(prefix, options?.scope ?? true, options?.scopeLabel);
+
+	if (!log) return scope;
+
+	let level: Exclude<LogLevel, 'off' | 'error' | 'warn'> = 'debug';
+	let message: string | undefined;
+	let onlyExit = false;
+	if (typeof log === 'object') {
+		level = log.level ?? level;
+		message = log.message;
+		onlyExit = log.onlyExit === true;
+	}
+
+	const start = hrtime();
+
+	if (!onlyExit) {
+		logAtLevel(scope, level, message ?? '');
+	}
+
+	const origDispose = scope[Symbol.dispose];
+	scope[Symbol.dispose] = () => {
+		const duration = getDurationMilliseconds(start);
+		const timing = ` [${duration}ms]`;
+		const exitInfo = scope.getExitInfo();
+		const exit = exitInfo.failed ?? 'completed';
+
+		if (exitInfo.failed != null) {
+			Logger.error(null, scope, `${exit}${exitInfo.details ?? ''}${timing}`);
+		} else {
+			logAtLevel(scope, level, `${exit}${exitInfo.details ?? ''}${timing}`);
+		}
+
+		origDispose();
+	};
+
+	return scope;
+}
+
+function logAtLevel(
+	scope: ScopedLogger,
+	level: Exclude<LogLevel, 'off' | 'error' | 'warn'>,
+	message: string,
+	...params: any[]
+): void {
+	switch (level) {
+		case 'trace':
+			Logger.trace(scope, message, ...params);
+			break;
+		case 'info':
+			Logger.info(scope, message, ...params);
+			break;
+		case 'debug':
+		default:
+			Logger.debug(scope, message, ...params);
+	}
+}

package/src/utils/logger.ts

@@ -0,0 +1,402 @@
+import type { ScopedLogger } from './logger.scoped.js';
+import { padOrTruncateEnd } from './string.js';
+import type { RequireSome } from './types.js';
+
+const isoTRegex = /T/;
+const stackCallerRegex = /.*\s*?at\s(.+?)\s/;
+const leadingUnderscoreRegex = /^_+/;
+
+export type LogLevel = 'off' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+
+export const OrderedLevel = {
+	Off: 0,
+	Trace: 1,
+	Debug: 2,
+	Info: 3,
+	Warn: 4,
+	Error: 5,
+} as const;
+export type OrderedLevel = (typeof OrderedLevel)[keyof typeof OrderedLevel];
+
+export interface LogChannelProvider {
+	readonly name: string;
+	createChannel(name: string): LogChannel;
+	toLoggable?(o: unknown): string | undefined;
+	hash?(data: string): string;
+
+	sanitizeKeys?: Set<string>;
+}
+
+export interface LogChannel {
+	readonly name: string;
+	readonly logLevel: OrderedLevel;
+	readonly onDidChangeLogLevel?: (listener: (level: OrderedLevel) => void) => { dispose(): void };
+
+	dispose?(): void;
+	show?(preserveFocus?: boolean): void;
+
+	trace(message: string, ...args: any[]): void;
+	debug(message: string, ...args: any[]): void;
+	info(message: string, ...args: any[]): void;
+	warn(message: string, ...args: any[]): void;
+	error(error: string | Error, ...args: any[]): void;
+}
+
+const defaultSanitizeKeys = ['accessToken', 'password', 'token'];
+
+class Logger {
+	#output: LogChannel | undefined;
+	#provider: RequireSome<LogChannelProvider, 'sanitizeKeys'> | undefined;
+
+	configure(provider: LogChannelProvider, debugging: boolean = false) {
+		this.#provider = {
+			...provider,
+			sanitizeKeys: new Set([...defaultSanitizeKeys, ...(provider.sanitizeKeys ?? [])]),
+		};
+
+		this.#isDebugging = debugging;
+
+		// Create output channel and sync with the host's log level
+		this.#output = provider.createChannel(provider.name);
+		this.#level = this.#output.logLevel;
+		this.#output.onDidChangeLogLevel?.(level => {
+			this.#level = level;
+		});
+	}
+
+	enabled(level?: Exclude<LogLevel, 'off'>): boolean {
+		if (this.isDebugging) return true;
+		if (this.#level === OrderedLevel.Off) return false;
+		if (level == null) return true;
+
+		return this.#level <= toOrderedLevel(level);
+	}
+
+	#isDebugging = false;
+	get isDebugging() {
+		return this.#isDebugging;
+	}
+
+	#level: OrderedLevel = OrderedLevel.Off;
+	get logLevel(): LogLevel {
+		return toFriendlyLogLevel(this.#level);
+	}
+
+	get timestamp(): string {
+		return `[${new Date().toISOString().replace(isoTRegex, ' ').slice(0, -1)}]`;
+	}
+
+	trace(message: string, ...params: any[]): void;
+	trace(scope: ScopedLogger | undefined, message: string, ...params: any[]): void;
+	trace(scopeOrMessage: ScopedLogger | string | undefined, ...params: any[]): void {
+		if ((this.#level === OrderedLevel.Off || this.#level > OrderedLevel.Trace) && !this.isDebugging) return;
+
+		let message;
+		if (typeof scopeOrMessage === 'string') {
+			message = scopeOrMessage;
+		} else {
+			message = params.shift();
+
+			if (scopeOrMessage != null) {
+				message = `${scopeOrMessage.prefix} ${message ?? ''}`;
+			}
+		}
+
+		if (this.isDebugging) {
+			console.debug(`[${padOrTruncateEnd(this.#provider!.name, 13)}]`, this.timestamp, message ?? '', ...params);
+		}
+		this.#output?.trace(`  ${message ?? ''}${this.#toLoggableParams(true, params)}`);
+	}
+
+	debug(message: string, ...params: any[]): void;
+	debug(scope: ScopedLogger | undefined, message: string, ...params: any[]): void;
+	debug(scopeOrMessage: ScopedLogger | string | undefined, ...params: any[]): void {
+		if ((this.#level === OrderedLevel.Off || this.#level > OrderedLevel.Debug) && !this.isDebugging) return;
+
+		let message;
+		if (typeof scopeOrMessage === 'string') {
+			message = scopeOrMessage;
+		} else {
+			message = params.shift();
+
+			if (scopeOrMessage != null) {
+				message = `${scopeOrMessage.prefix} ${message ?? ''}`;
+			}
+		}
+
+		if (this.isDebugging) {
+			console.debug(`[${padOrTruncateEnd(this.#provider!.name, 13)}]`, this.timestamp, message ?? '', ...params);
+		}
+		this.#output?.debug(`  ${message ?? ''}${this.#toLoggableParams(false, params)}`);
+	}
+
+	info(message: string, ...params: any[]): void;
+	info(scope: ScopedLogger | undefined, message: string, ...params: any[]): void;
+	info(scopeOrMessage: ScopedLogger | string | undefined, ...params: any[]): void {
+		if ((this.#level === OrderedLevel.Off || this.#level > OrderedLevel.Info) && !this.isDebugging) return;
+
+		let message;
+		if (typeof scopeOrMessage === 'string') {
+			message = scopeOrMessage;
+		} else {
+			message = params.shift();
+
+			if (scopeOrMessage != null) {
+				message = `${scopeOrMessage.prefix} ${message ?? ''}`;
+			}
+		}
+
+		if (this.isDebugging) {
+			console.info(`[${padOrTruncateEnd(this.#provider!.name, 13)}]`, this.timestamp, message ?? '', ...params);
+		}
+		this.#output?.info(`   ${message ?? ''}${this.#toLoggableParams(false, params)}`);
+	}
+
+	warn(message: string, ...params: any[]): void;
+	warn(scope: ScopedLogger | undefined, message: string, ...params: any[]): void;
+	warn(scopeOrMessage: ScopedLogger | string | undefined, ...params: any[]): void {
+		if ((this.#level === OrderedLevel.Off || this.#level > OrderedLevel.Warn) && !this.isDebugging) return;
+
+		let message;
+		if (typeof scopeOrMessage === 'string') {
+			message = scopeOrMessage;
+		} else {
+			message = params.shift();
+
+			if (scopeOrMessage != null) {
+				message = `${scopeOrMessage.prefix} ${message ?? ''}`;
+			}
+		}
+
+		if (this.isDebugging) {
+			console.warn(`[${padOrTruncateEnd(this.#provider!.name, 13)}]`, this.timestamp, message ?? '', ...params);
+		}
+		this.#output?.warn(`${message ?? ''}${this.#toLoggableParams(false, params)}`);
+	}
+
+	error(ex: Error | unknown, message?: string, ...params: any[]): void;
+	error(ex: Error | unknown, scope?: ScopedLogger, message?: string, ...params: any[]): void;
+	error(ex: Error | unknown, scopeOrMessage: ScopedLogger | string | undefined, ...params: any[]): void {
+		if ((this.#level === OrderedLevel.Off || this.#level > OrderedLevel.Error) && !this.isDebugging) return;
+
+		let message;
+		if (scopeOrMessage == null || typeof scopeOrMessage === 'string') {
+			message = scopeOrMessage;
+		} else {
+			message = `${scopeOrMessage.prefix} ${params.shift() ?? ''}`;
+		}
+
+		if (message == null) {
+			const stack = ex instanceof Error ? ex.stack : undefined;
+			if (stack) {
+				const match = stackCallerRegex.exec(stack);
+				if (match != null) {
+					message = match[1];
+				}
+			}
+		}
+
+		if (this.isDebugging) {
+			if (ex != null) {
+				console.error(
+					`[${padOrTruncateEnd(this.#provider!.name, 13)}]`,
+					this.timestamp,
+					message ?? '',
+					...params,
+					ex,
+				);
+			} else {
+				console.error(
+					`[${padOrTruncateEnd(this.#provider!.name, 13)}]`,
+					this.timestamp,
+					message ?? '',
+					...params,
+				);
+			}
+		}
+
+		const errorMessage = `  ${message ?? ''}${this.#toLoggableParams(false, params)}`;
+		if (ex != null) {
+			// eslint-disable-next-line @typescript-eslint/no-base-to-string
+			this.#output?.error(String(ex), errorMessage);
+		} else {
+			this.#output?.error(errorMessage);
+		}
+	}
+
+	showOutputChannel(preserveFocus?: boolean): void {
+		this.#output?.show?.(preserveFocus);
+	}
+
+	toLoggable(o: any, name?: string): string {
+		if (name != null) {
+			const sanitized = this.sanitize(name, o);
+			if (sanitized != null) return sanitized;
+		}
+
+		if (typeof o === 'function') return '<function>';
+		if (o == null || typeof o !== 'object') return String(o);
+
+		if (o instanceof Error) return String(o);
+
+		if (Array.isArray(o)) {
+			const maxItems = 10;
+			const items = o.length > maxItems ? o.slice(0, maxItems) : o;
+			const suffix = o.length > maxItems ? `, …+${o.length - maxItems}` : '';
+			return `[${items.map(i => this.toLoggable(i)).join(', ')}${suffix}]`;
+		}
+
+		const toLoggable = this.#provider?.toLoggable;
+
+		const loggable = toLoggable?.(o);
+		if (loggable != null) return loggable;
+
+		const sanitizeKeys = this.#provider?.sanitizeKeys;
+
+		try {
+			return JSON.stringify(o, (key: string, value: unknown): unknown => {
+				if (key.charCodeAt(0) === 95) return undefined; // skip '_'-prefixed keys
+				if (sanitizeKeys?.has(key)) return this.sanitize(key, value);
+
+				if (key !== '' && typeof value === 'object' && value != null && !Array.isArray(value)) {
+					if (value instanceof Error) return String(value);
+					return toLoggable?.(value) ?? value;
+				}
+
+				return value;
+			});
+		} catch {
+			debugger;
+			return '<error>';
+		}
+	}
+
+	sanitize(key: string, value: unknown): string | undefined {
+		// Nothing to redact if the value is null/undefined
+		if (value == null) return undefined;
+
+		// Strip leading underscores so `_token` matches `token` in sanitizeKeys
+		const sanitizeKey = key.replace(leadingUnderscoreRegex, '') || key;
+		if (!this.#provider?.sanitizeKeys?.has(sanitizeKey)) return undefined;
+
+		if (this.#provider.hash != null) {
+			return `<${sanitizeKey}:${this.#provider.hash(typeof value === 'string' ? value : JSON.stringify(value))}>`;
+		}
+		return `<${sanitizeKey}>`;
+	}
+
+	#toLoggableParams(debugOnly: boolean, params: any[]) {
+		if (
+			params.length === 0 ||
+			(debugOnly && (this.#level === OrderedLevel.Off || this.#level > OrderedLevel.Debug) && !this.isDebugging)
+		) {
+			return '';
+		}
+
+		const loggableParams = params.map(p => this.toLoggable(p)).join(', ');
+		return loggableParams.length !== 0 ? ` \u2014 ${loggableParams}` : '';
+	}
+}
+
+const _logger = new Logger();
+export { _logger as Logger };
+
+function toOrderedLevel(logLevel: LogLevel): OrderedLevel {
+	switch (logLevel) {
+		case 'off':
+			return OrderedLevel.Off;
+		case 'trace':
+			return OrderedLevel.Trace;
+		case 'debug':
+			return OrderedLevel.Debug;
+		case 'info':
+			return OrderedLevel.Info;
+		case 'warn':
+			return OrderedLevel.Warn;
+		case 'error':
+			return OrderedLevel.Error;
+		default:
+			return OrderedLevel.Off;
+	}
+}
+
+function toFriendlyLogLevel(level: OrderedLevel): LogLevel {
+	switch (level) {
+		case OrderedLevel.Off:
+			return 'off';
+		case OrderedLevel.Trace:
+			return 'trace';
+		case OrderedLevel.Debug:
+			return 'debug';
+		case OrderedLevel.Info:
+			return 'info';
+		case OrderedLevel.Warn:
+			return 'warn';
+		case OrderedLevel.Error:
+			return 'error';
+		default:
+			return 'off';
+	}
+}
+
+export const customLoggableNameFns = new WeakMap<object, (instance: any, name: string) => string>();
+
+export function getLoggableName(instance: object): string {
+	let ctor;
+	if (typeof instance === 'function') {
+		ctor = instance.prototype?.constructor;
+		if (ctor == null) return instance.name;
+	} else {
+		ctor = instance.constructor;
+	}
+
+	let name: string = ctor?.name ?? '';
+	// Strip webpack module name (since I never name classes with an _)
+	const index = name.indexOf('_');
+	if (index !== -1) {
+		name = name.substring(index + 1);
+	}
+
+	// Walk the prototype chain to find a custom name function (supports @logName on base classes)
+	let proto = ctor;
+	while (proto != null) {
+		const customNameFn = customLoggableNameFns.get(proto);
+		if (customNameFn != null) {
+			return customNameFn(instance, name);
+		}
+		proto = Object.getPrototypeOf(proto);
+	}
+
+	return name;
+}
+
+export interface LogProvider {
+	enabled(logLevel: Exclude<LogLevel, 'off'>): boolean;
+	log(logLevel: LogLevel, scope: ScopedLogger | undefined, message: string, ...params: any[]): void;
+}
+
+export const defaultLogProvider: LogProvider = {
+	enabled: (logLevel: Exclude<LogLevel, 'off'>) => _logger.enabled(logLevel),
+	log: (logLevel: LogLevel, scope: ScopedLogger | undefined, message: string, ...params: any[]) => {
+		switch (logLevel) {
+			case 'error':
+				_logger.error(undefined, scope, message, ...params);
+				break;
+			case 'warn':
+				scope?.warn(message, ...params);
+				break;
+			case 'info':
+				scope?.info(message, ...params);
+				break;
+			case 'debug':
+				scope?.debug(message, ...params);
+				break;
+			case 'trace':
+				scope?.trace(message, ...params);
+				break;
+			default:
+				scope?.debug(message, ...params);
+				break;
+		}
+	},
+};