@ts-for-gir/lib 4.0.0-beta.25 → 4.0.0-beta.26

package/src/utils/conflicts.ts

@@ -0,0 +1,490 @@
+import { GirDirection } from "@gi.ts/parser";
+import { ConsoleReporter, ReporterService } from "@ts-for-gir/reporter";
+import { IntrospectedConstructor } from "../gir/constructor.ts";
+import { FilterBehavior } from "../gir/data.ts";
+import type { IntrospectedFunction } from "../gir/function.ts";
+import type { IntrospectedClassMember } from "../gir/introspected-class-member.ts";
+import type { IntrospectedBaseClass } from "../gir/introspected-classes.ts";
+import {
+	IntrospectedClass,
+	IntrospectedClassFunction,
+	IntrospectedStaticClassFunction,
+	IntrospectedVirtualClassFunction,
+} from "../gir/introspected-classes.ts";
+import type { IntrospectedNamespace } from "../gir/namespace.ts";
+import { IntrospectedFunctionParameter } from "../gir/parameter.ts";
+import { IntrospectedField, IntrospectedProperty } from "../gir/property.ts";
+import type { TypeIdentifier } from "../gir.ts";
+import { AnyType, ArrayType, ConflictType, NeverType, TypeConflict } from "../gir.ts";
+import { findMap } from "../util.ts";
+import { isSubtypeOf } from "./type-resolution.ts";
+
+// Global reporter configuration for conflicts
+let conflictsReporterInstance: ConsoleReporter | null = null;
+let conflictsReporterConfig: { enabled: boolean; output: string } = {
+	enabled: false,
+	output: "ts-for-gir-report.json",
+};
+
+function configureConflictsReporterInternal(enabled: boolean, output: string = "ts-for-gir-report.json") {
+	conflictsReporterConfig = { enabled, output };
+
+	// Reset instance to force recreation with new config
+	if (conflictsReporterInstance) {
+		conflictsReporterInstance = null;
+	}
+
+	// Create and register the global reporter if enabled
+	if (enabled) {
+		conflictsReporterInstance = new ConsoleReporter(true, "conflicts", enabled, output);
+		const reporterService = ReporterService.getInstance();
+		reporterService.registerReporter("conflicts", conflictsReporterInstance);
+	}
+}
+
+function getConflictsReporterInstance(): ConsoleReporter {
+	if (!conflictsReporterInstance) {
+		const config = conflictsReporterConfig;
+		conflictsReporterInstance = new ConsoleReporter(true, "conflicts", config.enabled, config.output);
+
+		// Register with reporter service if reporting is enabled
+		if (config.enabled) {
+			const reporterService = ReporterService.getInstance();
+			reporterService.registerReporter("conflicts", conflictsReporterInstance);
+		}
+	}
+	return conflictsReporterInstance;
+}
+
+const log = getConflictsReporterInstance();
+
+// Export function to configure conflicts reporter
+export function configureConflictsReporter(enabled: boolean, output: string = "ts-for-gir-report.json") {
+	configureConflictsReporterInternal(enabled, output);
+}
+
+// Constants for GObject methods that always conflict
+const GOBJECT_RESERVED_METHODS = ["connect", "connect_after", "emit"] as const;
+
+export function isConflictingFunction(
+	namespace: IntrospectedNamespace,
+	childThis: TypeIdentifier,
+	child: IntrospectedFunction | IntrospectedClassFunction | IntrospectedConstructor,
+	parentThis: TypeIdentifier,
+	parent: IntrospectedClassFunction | IntrospectedFunction | IntrospectedConstructor,
+): boolean {
+	if (!parent.isIntrospectable || !child.isIntrospectable) {
+		return false;
+	}
+
+	// Handle constructor conflicts
+	if (isConstructorConflict(namespace, childThis, child, parentThis, parent)) {
+		return true;
+	}
+
+	// Handle mixed constructor/function conflicts
+	if (isMixedConstructorFunctionConflict(child, parent)) {
+		return true;
+	}
+
+	// Handle different function types (no conflict if different prototypes)
+	if (hasDifferentPrototypes(child, parent)) {
+		return false;
+	}
+
+	// Check parameter and return type conflicts
+	return hasParameterOrReturnTypeConflicts(namespace, childThis, child, parentThis, parent);
+}
+
+export function filterFunctionConflict<
+	T extends
+		| IntrospectedStaticClassFunction
+		| IntrospectedVirtualClassFunction
+		| IntrospectedClassFunction
+		| IntrospectedConstructor,
+>(
+	ns: IntrospectedNamespace,
+	base: IntrospectedBaseClass,
+	elements: T[],
+	conflict_ids: string[],
+	isInheritedMethods: boolean = false,
+): T[] {
+	const nextType = base.getType();
+
+	return elements
+		.filter((m) => m.name)
+		.reduce((prev, next) => {
+			const conflictResult = checkFunctionConflicts(ns, base, next, conflict_ids, nextType);
+
+			if (conflictResult.shouldOmit) {
+				// Always omit methods that conflict with properties/fields
+				log.reportTypeConflict(
+					"field_property",
+					next.name,
+					next.parent?.namespace.namespace || "unknown",
+					"Field/property name conflict",
+				);
+			} else if (conflictResult.hasConflict) {
+				if (isInheritedMethods) {
+					log.reportTypeConflict(
+						"method",
+						next.name,
+						next.parent?.namespace.namespace || "unknown",
+						"Parent method conflict",
+					);
+				} else {
+					const neverFunction = createNeverFunction(next, base, conflictResult.message);
+					prev.push(next, neverFunction as T);
+				}
+			} else {
+				prev.push(next);
+			}
+
+			return prev;
+		}, [] as T[]);
+}
+
+export function filterConflicts<T extends IntrospectedClassMember | IntrospectedClassFunction | IntrospectedProperty>(
+	ns: IntrospectedNamespace,
+	c: IntrospectedBaseClass,
+	elements: T[],
+	behavior = FilterBehavior.PRESERVE,
+): T[] {
+	const filtered = elements.filter((p) => p?.name);
+	const thisType = c.getType();
+	const result: T[] = [];
+
+	for (const element of filtered) {
+		const conflictType = detectConflictType(ns, c, element, thisType);
+
+		if (conflictType) {
+			if (behavior === FilterBehavior.PRESERVE) {
+				const conflictElement = createConflictElement(element, conflictType);
+				if (conflictElement) {
+					result.push(conflictElement);
+				} else {
+					result.push(element);
+				}
+			}
+		} else {
+			result.push(element);
+		}
+	}
+
+	return result;
+}
+
+// Helper Functions
+
+function isConstructorConflict(
+	namespace: IntrospectedNamespace,
+	childThis: TypeIdentifier,
+	child: IntrospectedFunction | IntrospectedClassFunction | IntrospectedConstructor,
+	parentThis: TypeIdentifier,
+	parent: IntrospectedClassFunction | IntrospectedFunction | IntrospectedConstructor,
+): boolean {
+	if (!(child instanceof IntrospectedConstructor && parent instanceof IntrospectedConstructor)) {
+		return false;
+	}
+
+	return (
+		child.parameters.length > parent.parameters.length ||
+		!isSubtypeOf(namespace, childThis, parentThis, child.return(), parent.return()) ||
+		child.parameters.some((p, i) => !isSubtypeOf(namespace, childThis, parentThis, p.type, parent.parameters[i].type))
+	);
+}
+
+function isMixedConstructorFunctionConflict(
+	child: IntrospectedFunction | IntrospectedClassFunction | IntrospectedConstructor,
+	parent: IntrospectedClassFunction | IntrospectedFunction | IntrospectedConstructor,
+): boolean {
+	return child instanceof IntrospectedConstructor !== parent instanceof IntrospectedConstructor;
+}
+
+function hasDifferentPrototypes(
+	child: IntrospectedFunction | IntrospectedClassFunction | IntrospectedConstructor,
+	parent: IntrospectedClassFunction | IntrospectedFunction | IntrospectedConstructor,
+): boolean {
+	// This occurs if two functions of the same name are passed but they
+	// are different types (e.g. GirStaticClassFunction vs GirClassFunction)
+	return Object.getPrototypeOf(child) !== Object.getPrototypeOf(parent);
+}
+
+function hasParameterOrReturnTypeConflicts(
+	namespace: IntrospectedNamespace,
+	childThis: TypeIdentifier,
+	child: IntrospectedFunction | IntrospectedClassFunction | IntrospectedConstructor,
+	parentThis: TypeIdentifier,
+	parent: IntrospectedClassFunction | IntrospectedFunction | IntrospectedConstructor,
+): boolean {
+	// Check basic parameter conflicts
+	if (child.parameters.length > parent.parameters.length) {
+		return true;
+	}
+
+	// Check return type conflicts
+	if (!isSubtypeOf(namespace, childThis, parentThis, child.return(), parent.return())) {
+		return true;
+	}
+
+	// Check parameter type conflicts
+	if (
+		child.parameters.some((np, i) => !isSubtypeOf(namespace, childThis, parentThis, np.type, parent.parameters[i].type))
+	) {
+		return true;
+	}
+
+	// Only check output parameters if both functions have them (constructors don't have output_parameters)
+	const childHasOutputParams = "output_parameters" in child;
+	const parentHasOutputParams = "output_parameters" in parent;
+
+	if (childHasOutputParams && parentHasOutputParams) {
+		// Length mismatch
+		if (child.output_parameters.length !== parent.output_parameters.length) {
+			return true;
+		}
+
+		// Type mismatch
+		if (
+			child.output_parameters.some(
+				(np, i) => !isSubtypeOf(namespace, childThis, parentThis, np.type, parent.output_parameters[i].type),
+			)
+		) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+interface ConflictResult {
+	hasConflict: boolean;
+	shouldOmit: boolean;
+	message: string | null;
+}
+
+function checkFunctionConflicts<T extends IntrospectedClassFunction | IntrospectedConstructor>(
+	ns: IntrospectedNamespace,
+	base: IntrospectedBaseClass,
+	functionElement: T,
+	conflict_ids: string[],
+	nextType: TypeIdentifier,
+): ConflictResult {
+	let message: string | null = null;
+
+	// Check explicit conflict IDs
+	if (conflict_ids.includes(functionElement.name)) {
+		return { hasConflict: true, shouldOmit: false, message };
+	}
+
+	// Check parent function conflicts
+	const hasParentConflict = base.someParent((resolved_parent) => {
+		const parentType = resolved_parent.getType();
+		return [...resolved_parent.constructors, ...resolved_parent.members].some((p) => {
+			if (p.name && p.name === functionElement.name) {
+				const conflicting = isConflictingFunction(ns, nextType, functionElement, parentType, p);
+
+				if (conflicting) {
+					message = `// Conflicted with ${resolved_parent.namespace.namespace}.${resolved_parent.name}.${p.name}`;
+					return true;
+				}
+				return false;
+			}
+			return false;
+		});
+	});
+
+	// Check field/property conflicts
+	const hasFieldConflicts = checkFieldPropertyConflicts(base, functionElement.name);
+
+	// Check GObject reserved methods
+	const hasGObjectConflicts = checkGObjectConflicts(base, functionElement.name);
+
+	const hasConflict = hasParentConflict || hasGObjectConflicts;
+
+	return {
+		hasConflict,
+		shouldOmit: hasFieldConflicts && !hasConflict,
+		message,
+	};
+}
+
+function checkFieldPropertyConflicts(base: IntrospectedBaseClass, name: string): boolean {
+	// Check if the method name conflicts with any props or fields either on
+	// the class or in the parent...
+	return (
+		[...base.props, ...base.fields].some((p) => p.name && p.name === name) ||
+		base.someParent((resolved_parent) =>
+			[...resolved_parent.props, ...resolved_parent.fields].some((p) => p.name && p.name === name),
+		)
+	);
+}
+
+function checkGObjectConflicts(base: IntrospectedBaseClass, name: string): boolean {
+	const isGObject = base.someParent((p) => p.namespace.namespace === "GObject" && p.name === "Object");
+	return isGObject && (GOBJECT_RESERVED_METHODS as readonly string[]).includes(name);
+}
+
+function createNeverFunction<T extends IntrospectedClassFunction | IntrospectedConstructor>(
+	original: T,
+	base: IntrospectedBaseClass,
+	message: string | null,
+):
+	| IntrospectedClassFunction
+	| IntrospectedConstructor
+	| IntrospectedStaticClassFunction
+	| IntrospectedVirtualClassFunction {
+	const neverParam = new IntrospectedFunctionParameter({
+		name: "args",
+		direction: GirDirection.In,
+		isVarArgs: true,
+		type: new ArrayType(NeverType),
+	});
+
+	const neverOptions = {
+		name: original.name,
+		parent: base,
+		parameters: [neverParam],
+		return_type: AnyType,
+	};
+
+	let neverFunction:
+		| IntrospectedClassFunction
+		| IntrospectedConstructor
+		| IntrospectedStaticClassFunction
+		| IntrospectedVirtualClassFunction;
+
+	if (original instanceof IntrospectedConstructor) {
+		neverFunction = new IntrospectedConstructor(neverOptions);
+	} else if (original instanceof IntrospectedStaticClassFunction) {
+		neverFunction = new IntrospectedStaticClassFunction({ ...neverOptions, parent: original.parent });
+	} else if (original instanceof IntrospectedVirtualClassFunction && original.parent instanceof IntrospectedClass) {
+		neverFunction = new IntrospectedVirtualClassFunction({ ...neverOptions, parent: original.parent });
+	} else if (original instanceof IntrospectedClassFunction) {
+		neverFunction = new IntrospectedClassFunction({ ...neverOptions, parent: original.parent });
+	} else {
+		const parent = Object.getPrototypeOf(original as (...args: unknown[]) => unknown) as
+			| ((...args: unknown[]) => unknown)
+			| null
+			| undefined;
+		throw new Error(`Unknown function type ${parent?.name} encountered.`);
+	}
+
+	if (message) {
+		neverFunction.setWarning(message);
+	}
+
+	return neverFunction;
+}
+
+function detectConflictType<T extends IntrospectedClassMember | IntrospectedClassFunction | IntrospectedProperty>(
+	ns: IntrospectedNamespace,
+	c: IntrospectedBaseClass,
+	element: T,
+	thisType: TypeIdentifier,
+): ConflictType | undefined {
+	// Check field conflicts first
+	const fieldConflict = checkFieldConflicts(c, element);
+	if (fieldConflict) return fieldConflict;
+
+	// Check property conflicts
+	const propertyConflict = checkPropertyConflicts(ns, c, element, thisType);
+	if (propertyConflict) return propertyConflict;
+
+	// Check function conflicts
+	return checkFunctionNameConflicts(ns, c, element, thisType);
+}
+
+function checkFieldConflicts<T extends IntrospectedClassMember | IntrospectedClassFunction | IntrospectedProperty>(
+	c: IntrospectedBaseClass,
+	element: T,
+): ConflictType | undefined {
+	return c.findParentMap((resolved_parent) => {
+		return findMap([...resolved_parent.fields], (p) => {
+			if (p.name && p.name === element.name) {
+				if (element instanceof IntrospectedProperty) {
+					return ConflictType.ACCESSOR_PROPERTY_CONFLICT;
+				}
+
+				if (
+					element instanceof IntrospectedField &&
+					!isSubtypeOf(c.namespace, c.getType(), resolved_parent.getType(), element.type, p.type)
+				) {
+					return ConflictType.FIELD_NAME_CONFLICT;
+				}
+			}
+
+			return undefined;
+		});
+	});
+}
+
+function checkPropertyConflicts<T extends IntrospectedClassMember | IntrospectedClassFunction | IntrospectedProperty>(
+	ns: IntrospectedNamespace,
+	c: IntrospectedBaseClass,
+	element: T,
+	thisType: TypeIdentifier,
+): ConflictType | undefined {
+	return c.findParentMap((resolved_parent) => {
+		return findMap([...resolved_parent.props], (p) => {
+			if (p.name && p.name === element.name) {
+				// Classes can override parent interface accessors with properties _but_
+				// classes cannot override parent class accessors with properties without an error occurring.
+				if (p.parent instanceof IntrospectedClass && element instanceof IntrospectedField) {
+					return ConflictType.PROPERTY_ACCESSOR_CONFLICT;
+				}
+
+				if (
+					element instanceof IntrospectedProperty &&
+					!isSubtypeOf(ns, thisType, resolved_parent.getType(), element.type, p.type)
+				) {
+					log.reportTypeConflict(
+						"general",
+						element.name,
+						element.parent?.namespace.namespace || "unknown",
+						`Conflict with ${p.parent?.name}.${p.name}`,
+					);
+					return ConflictType.PROPERTY_NAME_CONFLICT;
+				}
+			}
+
+			return undefined;
+		});
+	});
+}
+
+function checkFunctionNameConflicts<
+	T extends IntrospectedClassMember | IntrospectedClassFunction | IntrospectedProperty,
+>(ns: IntrospectedNamespace, c: IntrospectedBaseClass, element: T, thisType: TypeIdentifier): ConflictType | undefined {
+	return c.findParentMap((resolved_parent) =>
+		findMap([...resolved_parent.constructors, ...resolved_parent.members], (p) => {
+			if (p.name && p.name === element.name) {
+				if (element instanceof IntrospectedProperty) {
+					// Properties that conflict with parent functions should be treated as FUNCTION_NAME_CONFLICT
+					return ConflictType.FUNCTION_NAME_CONFLICT;
+				}
+				if (
+					!(element instanceof IntrospectedClassFunction) ||
+					isConflictingFunction(ns, thisType, element, resolved_parent.getType(), p)
+				) {
+					return ConflictType.FUNCTION_NAME_CONFLICT;
+				}
+			}
+
+			return undefined;
+		}),
+	);
+}
+
+function createConflictElement<T extends IntrospectedClassMember | IntrospectedClassFunction | IntrospectedProperty>(
+	element: T,
+	conflictType: ConflictType,
+): T | null {
+	if (element instanceof IntrospectedField || element instanceof IntrospectedProperty) {
+		return element.copy({
+			type: new TypeConflict(element.type, conflictType),
+		}) as T;
+	}
+
+	return null;
+}

package/{lib/utils/documentation.js → src/utils/documentation.ts}

@@ -1,37 +1,41 @@
-import { NEW_LINE_REG_EXP } from '../constants.js';
+import { NEW_LINE_REG_EXP } from "../constants.ts";
+
 /**
  * Transforms GIR documentation text to markdown format
  * @param text The documentation text to transform
  * @returns The transformed markdown text
  */
-export function transformGirDocText(text) {
-    text = transformGirDocHighlights(text);
-    text = transformGirDocCodeBlocks(text);
-    return text;
+export function transformGirDocText(text: string): string {
+	text = transformGirDocHighlights(text);
+	text = transformGirDocCodeBlocks(text);
+	return text;
 }
+
 /**
  * Transforms TSDoc tag text by removing newlines
  * Used for @param and @returns descriptions
  * @param text The tag text to transform
  * @returns The cleaned text
  */
-export function transformGirDocTagText(text) {
-    return text.replace(NEW_LINE_REG_EXP, ' ');
+export function transformGirDocTagText(text: string): string {
+	return text.replace(NEW_LINE_REG_EXP, " ");
 }
+
 /**
  * Replaces "@any_property" with "`any_property`"
  * @param description E.g. "Creates a binding between @source_property on @source and @target_property on @target."
  * @returns E.g. "Creates a binding between `source_property` on `source` and `target_property` on `target`."
  */
-function transformGirDocHighlights(description) {
-    const highlights = description.match(/@[A-Za-z_-]*[^\s.]/gm);
-    if (highlights) {
-        for (const highlight of highlights) {
-            description = description.replace(highlight, `\`${highlight.slice(1)}\``);
-        }
-    }
-    return description;
+function transformGirDocHighlights(description: string): string {
+	const highlights = description.match(/@[A-Za-z_-]*[^\s.]/gm);
+	if (highlights) {
+		for (const highlight of highlights) {
+			description = description.replace(highlight, `\`${highlight.slice(1)}\``);
+		}
+	}
+	return description;
 }
+
 /**
  * Replaces GIR code blocks with markdown code fences
  *
@@ -48,11 +52,10 @@ function transformGirDocHighlights(description) {
  * @param description The description containing code blocks
  * @returns The description with markdown code fences
  */
-function transformGirDocCodeBlocks(description) {
-    description = description
-        .replaceAll(/\|\[<!-- language="C" -->/gm, '\n```c') // C-Code
-        .replaceAll(/\|\[/gm, '\n```') // Other code
-        .replaceAll(/\]\|/gm, '```\n'); // End of code
-    return description;
+function transformGirDocCodeBlocks(description: string): string {
+	description = description
+		.replaceAll(/\|\[<!-- language="C" -->/gm, "\n```c") // C-Code
+		.replaceAll(/\|\[/gm, "\n```") // Other code
+		.replaceAll(/\]\|/gm, "```\n"); // End of code
+	return description;
 }
-//# sourceMappingURL=documentation.js.map

package/src/utils/files.ts

@@ -0,0 +1,71 @@
+import { constants } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { glob } from "glob";
+
+import type { FileInfo } from "../types/index.ts";
+
+export { inspect } from "node:util";
+
+/**
+ * Asynchronously checks if a file exists
+ * @param filePath The path to the file
+ * @returns A promise that resolves to true if the file exists, false otherwise
+ */
+export const fileExists = async (filePath: string): Promise<boolean> => {
+	try {
+		await access(filePath, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+};
+
+/**
+ * Find a file in a list of directories
+ * @param dirs The directories to search in
+ * @param filename The filename to search for
+ * @returns The file info
+ */
+export const findFilesInDirs = async (dirs: string[], filename: string): Promise<FileInfo[]> => {
+	const filesInfo: FileInfo[] = [];
+
+	const pattern = dirs.map((dir) => join(dir, filename));
+	const _files = await glob(pattern);
+
+	// Remove duplicates
+	const files = [...new Set(_files)];
+
+	for (const filePath of files) {
+		const fileInfo: FileInfo = {
+			path: null,
+			filename,
+			exists: false,
+		};
+		fileInfo.exists = await fileExists(filePath);
+		if (fileInfo.exists) {
+			fileInfo.path = filePath;
+			filesInfo.push(fileInfo);
+		}
+	}
+
+	if (filesInfo.length === 0) {
+		filesInfo.push({
+			path: null,
+			filename,
+			exists: false,
+		});
+	}
+
+	return filesInfo;
+};
+
+/**
+ * Read a JSON file
+ * @param filePath The path to the JSON file
+ * @returns The parsed JSON
+ */
+export const readJsonFile = async <T = unknown>(filePath: string): Promise<T> => {
+	const fileContent = await readFile(filePath, "utf8");
+	return JSON.parse(fileContent) as T;
+};

package/src/utils/function-type-guards.ts

@@ -0,0 +1,61 @@
+import type { IntrospectedClassFunction } from "../gir/introspected-classes.ts";
+import type { ClassFunctionLike, FunctionTypeKind } from "../types/class-function-types.ts";
+
+/**
+ * Type guard to check if an object is a class function-like
+ */
+export function isClassFunctionLike(obj: unknown): obj is ClassFunctionLike {
+	return obj != null && typeof obj === "object" && "__functionTypeKind" in obj;
+}
+
+/**
+ * Type guard to check if an object is a specific function type
+ */
+export function isFunctionOfType(obj: unknown, type: FunctionTypeKind): boolean {
+	return isClassFunctionLike(obj) && obj.__functionTypeKind === type;
+}
+
+/**
+ * Type guard specifically for class functions
+ */
+export function isClassFunction(obj: unknown): boolean {
+	return isFunctionOfType(obj, "CLASS_FUNCTION");
+}
+
+/**
+ * Type guard specifically for virtual class functions
+ */
+export function isVirtualClassFunction(obj: unknown): boolean {
+	return isFunctionOfType(obj, "VIRTUAL_CLASS_FUNCTION");
+}
+
+/**
+ * Type guard specifically for static class functions
+ */
+export function isStaticClassFunction(fn: IntrospectedClassFunction): boolean {
+	// Check if the function has the static class function characteristics
+	// IntrospectedStaticClassFunction extends IntrospectedClassFunction but doesn't add unique properties
+	// We can identify it by checking the constructor name or other characteristics
+	return fn.constructor.name === "IntrospectedStaticClassFunction";
+}
+
+/**
+ * Type guard specifically for constructors
+ */
+export function isConstructorFunction(obj: unknown): boolean {
+	return isFunctionOfType(obj, "CONSTRUCTOR");
+}
+
+/**
+ * Helper to get the function type kind from an object
+ */
+export function getFunctionTypeKind(obj: unknown): FunctionTypeKind | null {
+	return isClassFunctionLike(obj) ? obj.__functionTypeKind : null;
+}
+
+/**
+ * Helper to check if object has namespace property (common pattern in the codebase)
+ */
+export function hasNamespace(obj: unknown): obj is { namespace: unknown } {
+	return obj != null && typeof obj === "object" && "namespace" in obj;
+}