@ts-for-gir/lib 4.0.0-beta.40 → 4.0.0-beta.42

package/src/gir-module.ts

@@ -1,4 +1,4 @@
-import type { GirType } from "@gi.ts/parser";
+import type { GirBoxedElement, GirInfoAttrs, GirType } from "@gi.ts/parser";
 import { ConsoleReporter, ReporterService } from "@ts-for-gir/reporter";
 import { DependencyManager } from "./dependency-manager.ts";
 import { IntrospectedAlias } from "./gir/alias.ts";
@@ -19,11 +19,13 @@ import { NullableType, ObjectType, TypeIdentifier } from "./gir.ts";
 import type { LibraryVersion } from "./library-version.ts";
 import type {
 	Dependency,
+	GirAliasElement,
 	GirBitfieldElement,
 	GirConstantElement,
 	GirEnumElement,
 	GirInterfaceElement,
 	IGirModule,
+	IntrospectedMetadata,
 	OptionsGeneration,
 	OptionsLoad,
 	TsDocTag,
@@ -244,6 +246,23 @@ export class GirModule implements IGirModule {
 		return tags;
 	}
 
+	getTsDocMetadataTags(metadata?: IntrospectedMetadata): TsDocTag[] {
+		const tags: TsDocTag[] = [];
+		if (metadata?.introducedVersion) {
+			tags.push({ tagName: "since", paramName: "", text: metadata.introducedVersion });
+		}
+		if (metadata?.deprecated) {
+			const text = [
+				metadata.deprecatedVersion ? `since ${metadata.deprecatedVersion}` : "",
+				metadata.deprecatedDoc ?? "",
+			]
+				.filter(Boolean)
+				.join(": ");
+			tags.push({ tagName: "deprecated", paramName: "", text });
+		}
+		return tags;
+	}
+
 	registerResolveName(resolveName: string, namespace: string, name: string) {
 		this._resolve_names.set(resolveName, new TypeIdentifier(name, namespace));
 	}
@@ -570,6 +589,90 @@ export class GirModule implements IGirModule {
 		return building;
 	}
 
+	/** Parse and store elements into this.members using a common pattern */
+	private parseAndStore<TXml, TResult extends GirNSMember>(
+		elements: TXml[] | undefined,
+		fromXML: (el: TXml) => TResult,
+		filter?: (el: TResult) => boolean,
+	): void {
+		if (!elements) return;
+		let items = (elements as Array<TXml & { $?: GirInfoAttrs }>).filter(isIntrospectable).map(fromXML);
+		if (filter) items = items.filter(filter);
+		for (const item of items) {
+			this.members.set(item.name, item);
+		}
+	}
+
+	/** Parse enumerations, which may be either enums or error domains */
+	private parseEnumerations(
+		enumerations: GirEnumElement[] | undefined,
+		options: OptionsLoad,
+		importConflicts: (el: { name: string }) => boolean,
+	): void {
+		this.parseAndStore(
+			enumerations,
+			(enumeration) => {
+				if (enumeration.$["glib:error-domain"]) {
+					return IntrospectedError.fromXML(enumeration, this, options);
+				}
+				return IntrospectedEnum.fromXML(enumeration, this, options);
+			},
+			importConflicts,
+		);
+	}
+
+	/** Parse glib:boxed elements into aliases */
+	private parseBoxed(boxed: GirBoxedElement[] | undefined): void {
+		if (!boxed) return;
+		const items = boxed.filter(isIntrospectable).map(
+			(b) =>
+				new IntrospectedAlias({
+					name: b.$["glib:name"],
+					namespace: this,
+					type: new NullableType(ObjectType),
+				}),
+		);
+		for (const item of items) {
+			this.members.set(item.name, item);
+		}
+	}
+
+	/** Parse aliases, filtering out non-introspectable symbol references */
+	private parseAliases(aliases: GirAliasElement[], options: OptionsLoad): void {
+		type NamedType = GirType & { $: { name: string } };
+
+		const parsed = aliases
+			.filter(isIntrospectable)
+			.map((b) => {
+				b.type = b.type
+					?.filter((t): t is NamedType => !!t?.$.name)
+					.map((t) => {
+						if (t.$.name && !this.hasSymbol(t.$.name) && !isPrimitiveType(t.$.name) && !t.$.name.includes(".")) {
+							return { $: { name: "unknown", "c:type": "unknown" } } as GirType;
+						}
+						return t;
+					});
+				return b;
+			})
+			.map((alias) => IntrospectedAlias.fromXML(alias, this, options))
+			.filter((alias): alias is IntrospectedAlias => alias != null);
+
+		for (const c of parsed) {
+			this.members.set(c.name, c);
+		}
+	}
+
+	/** Build the enum_constants map from parsed enum members */
+	private buildEnumConstantsMap(): void {
+		for (const m of this.members.values()) {
+			if (m instanceof IntrospectedEnum) {
+				for (const member of m.members.values()) {
+					this.enum_constants.set(member.c_identifier, [m.name, member.name] as const);
+				}
+			}
+		}
+	}
+
 	/** Start to parse all the data from the XML we need for the typescript generation */
 	public parse() {
 		this.log.debug(`Parsing ${this.dependency.packageName}...`);
@@ -590,170 +693,27 @@ export class GirModule implements IGirModule {
 			throw new Error(`Missing namespace in ${packageName}`);
 		}
 
-		const importConflicts = (
-			el: IntrospectedConstant | IntrospectedBaseClass | IntrospectedFunction | IntrospectedEnum | IntrospectedError,
-		) => {
-			return !this.hasImport(el.name);
-		};
-
-		if (ns.enumeration) {
-			// Get the requested enums
-			const enumerations = ns.enumeration
-				?.filter(isIntrospectable)
-				.map((enumeration) => {
-					if (enumeration.$["glib:error-domain"]) {
-						return IntrospectedError.fromXML(enumeration as GirEnumElement, this, options);
-					} else {
-						return IntrospectedEnum.fromXML(enumeration as GirEnumElement, this, options);
-					}
-				})
-				.filter(importConflicts);
-
-			for (const c of enumerations) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		// Constants
-		if (ns.constant) {
-			const constants = ns.constant
-				?.filter(isIntrospectable)
-				.map((constant) => IntrospectedConstant.fromXML(constant, this, options))
-				.filter(importConflicts);
-
-			for (const c of constants) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		// Get the requested functions
-		if (ns.function) {
-			const functions = ns.function
-				?.filter(isIntrospectable)
-				.map((func) => IntrospectedFunction.fromXML(func, this, options))
-				.filter(importConflicts);
-
-			for (const c of functions) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		if (ns.callback) {
-			const callbacks = ns.callback
-				?.filter(isIntrospectable)
-				.map((callback) => IntrospectedCallback.fromXML(callback, this, options))
-				.filter(importConflicts);
-
-			for (const c of callbacks) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		if (ns["glib:boxed"]) {
-			const boxed = ns["glib:boxed"]?.filter(isIntrospectable).map(
-				(boxed) =>
-					new IntrospectedAlias({
-						name: boxed.$["glib:name"],
-						namespace: this,
-						type: new NullableType(ObjectType),
-					}),
-			);
-
-			for (const c of boxed) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		// Bitfield is a type of enum
-		if (ns.bitfield) {
-			const bitfields = ns.bitfield
-				?.filter(isIntrospectable)
-				.map((field) => IntrospectedEnum.fromXML(field as GirBitfieldElement, this, options, true));
-
-			for (const c of bitfields) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		// The `enum_constants` map maps the C identifiers (GTK_BUTTON_TYPE_Y)
-		// to the name of the enum (Button) to resolve references (Gtk.Button.Y)
-		Array.from(this.members.values())
-			.filter((m): m is IntrospectedEnum => m instanceof IntrospectedEnum)
-			.forEach((m) => {
-				m.members.forEach((member) => {
-					this.enum_constants.set(member.c_identifier, [m.name, member.name] as const);
-				});
-			});
-
-		// Get the requested classes
-		if (ns.class) {
-			const classes = ns.class
-				?.filter(isIntrospectable)
-				.map((klass) => IntrospectedClass.fromXML(klass, this, options))
-				.filter(importConflicts);
-
-			for (const c of classes) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		if (ns.record) {
-			const records = ns.record
-				?.filter(isIntrospectable)
-				.map((record) => IntrospectedRecord.fromXML(record, this, options))
-				.filter(importConflicts);
+		const importConflicts = (el: { name: string }) => !this.hasImport(el.name);
 
-			for (const c of records) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		if (ns.union) {
-			const unions = ns.union
-				?.filter(isIntrospectable)
-				.map((union) => IntrospectedRecord.fromXML(union, this, options))
-				.filter(importConflicts);
-
-			for (const c of unions) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		if (ns.interface) {
-			const interfaces = ns.interface
-				?.map((inter) => IntrospectedInterface.fromXML(inter as GirInterfaceElement, this, options))
-				.filter(importConflicts);
-
-			for (const c of interfaces) {
-				this.members.set(c.name, c);
-			}
-		}
-
-		if (ns.alias) {
-			type NamedType = GirType & { $: { name: string } };
-
-			const aliases = ns.alias
-				?.filter(isIntrospectable)
-				// Avoid attempting to alias non-introspectable symbols.
-				.map((b) => {
-					b.type = b.type
-						?.filter((t): t is NamedType => !!t?.$.name)
-						.map((t) => {
-							if (t.$.name && !this.hasSymbol(t.$.name) && !isPrimitiveType(t.$.name) && !t.$.name.includes(".")) {
-								return { $: { name: "unknown", "c:type": "unknown" } } as GirType;
-							}
-
-							return t;
-						});
-
-					return b;
-				})
-				.map((alias) => IntrospectedAlias.fromXML(alias, this, options))
-				.filter((alias): alias is IntrospectedAlias => alias != null);
-
-			for (const c of aliases) {
-				this.members.set(c.name, c);
-			}
-		}
+		this.parseEnumerations(ns.enumeration as GirEnumElement[] | undefined, options, importConflicts);
+		this.parseAndStore(
+			ns.constant,
+			(c) => IntrospectedConstant.fromXML(c as GirConstantElement, this, options),
+			importConflicts,
+		);
+		this.parseAndStore(ns.function, (f) => IntrospectedFunction.fromXML(f, this, options), importConflicts);
+		this.parseAndStore(ns.callback, (cb) => IntrospectedCallback.fromXML(cb, this, options), importConflicts);
+		this.parseBoxed(ns["glib:boxed"]);
+		this.parseAndStore(ns.bitfield, (f) => IntrospectedEnum.fromXML(f as GirBitfieldElement, this, options, true));
+		this.buildEnumConstantsMap();
+		this.parseAndStore(ns.class, (k) => IntrospectedClass.fromXML(k, this, options), importConflicts);
+		this.parseAndStore(ns.record, (r) => IntrospectedRecord.fromXML(r, this, options), importConflicts);
+		this.parseAndStore(ns.union, (u) => IntrospectedRecord.fromXML(u, this, options), importConflicts);
+		this.parseAndStore(
+			ns.interface,
+			(i) => IntrospectedInterface.fromXML(i as GirInterfaceElement, this, options),
+			importConflicts,
+		);
+		if (ns.alias) this.parseAliases(ns.alias, options);
 	}
 }

package/src/gir.ts

@@ -21,7 +21,7 @@ export enum ConflictType {
 	VFUNC_SIGNATURE_CONFLICT,
 }
 
-import { ConsoleReporter, ReporterService } from "@ts-for-gir/reporter";
+import { type ConsoleReporter, LazyReporter } from "@ts-for-gir/reporter";
 import type { IntrospectedField, IntrospectedProperty } from "./gir/property.ts";
 import type { OptionsBase } from "./types/index.ts";
 import { isInvalid, sanitizeIdentifierName, sanitizeNamespace } from "./utils/naming.ts";
@@ -49,44 +49,14 @@ export class TypeIdentifier extends TypeExpression {
 	readonly name: string;
 	readonly namespace: string;
 
-	// Global reporter configuration and instance
-	private static reporterConfig: { enabled: boolean; output: string } = {
-		enabled: false,
-		output: "ts-for-gir-report.json",
-	};
-	private static globalReporter: ConsoleReporter | null = null;
+	private static readonly reporter = new LazyReporter("TypeIdentifier");
 
-	static configureReporter(enabled: boolean, output: string = "ts-for-gir-report.json") {
-		TypeIdentifier.reporterConfig = { enabled, output };
-
-		// Reset global reporter to force recreation with new config
-		if (TypeIdentifier.globalReporter) {
-			TypeIdentifier.globalReporter = null;
-		}
-
-		// Create and register the global reporter if enabled
-		if (enabled) {
-			TypeIdentifier.globalReporter = new ConsoleReporter(true, "TypeIdentifier", enabled, output);
-			const reporterService = ReporterService.getInstance();
-			reporterService.registerReporter("TypeIdentifier", TypeIdentifier.globalReporter);
-		}
-	}
-
-	private static getReporter(): ConsoleReporter {
-		if (!TypeIdentifier.globalReporter) {
-			const config = TypeIdentifier.reporterConfig;
-			TypeIdentifier.globalReporter = new ConsoleReporter(true, "TypeIdentifier", config.enabled, config.output);
-
-			if (config.enabled) {
-				const reporterService = ReporterService.getInstance();
-				reporterService.registerReporter("TypeIdentifier", TypeIdentifier.globalReporter);
-			}
-		}
-		return TypeIdentifier.globalReporter;
+	static configureReporter(enabled: boolean, output?: string) {
+		TypeIdentifier.reporter.configure(enabled, output);
 	}
 
 	get log(): ConsoleReporter {
-		return TypeIdentifier.getReporter();
+		return TypeIdentifier.reporter.get();
 	}
 
 	constructor(name: string, namespace: string) {
@@ -194,7 +164,7 @@ export class TypeIdentifier extends TypeExpression {
 
 			return new TypeIdentifier(c_resolved_name, ns.namespace);
 		} else if (namespace.namespace === ns.namespace) {
-			this.log.reportTypeResolutionError(
+			this.log.reportTypeResolutionWarning(
 				this.name,
 				ns.namespace,
 				`Unable to resolve type ${this.name} in same namespace ${ns.namespace}!`,
@@ -203,11 +173,12 @@ export class TypeIdentifier extends TypeExpression {
 			return null;
 		}
 
-		this.log.reportTypeResolutionError(
+		this.log.reportTypeResolutionWarning(
 			this.name,
 			this.namespace,
 			`Type ${this.name} could not be resolved in ${namespace.namespace} ${namespace.version}`,
-			`Failed to resolve type during namespace processing`,
+			`Referenced from ${namespace.namespace} ${namespace.version}`,
+			`${namespace.namespace} ${namespace.version}`,
 		);
 		return null;
 	}
@@ -876,7 +847,12 @@ export class ArrayType extends TypeExpression {
 	}
 }
 
-// Common native types as constants
+/**
+ * Common native types as constants.
+ * These represent TypeScript types in generated .d.ts output for GJS runtime,
+ * not internal tool types. Uses of `any` here are intentional — they produce
+ * correct type definitions for GLib/GIO/GObject APIs that accept dynamic values.
+ */
 export const ThisType = new NativeType("this");
 export const ObjectType = new NativeType("object");
 export const AnyType = new NativeType("any");

package/src/injections/gio.ts

@@ -1,3 +1,8 @@
+/**
+ * GIO type injection overrides.
+ * Uses of `any`/`AnyType` in this file are intentional — they produce
+ * generated .d.ts output matching GIO's dynamic runtime behavior.
+ */
 import { GirDirection } from "@gi.ts/parser";
 import { IntrospectedAlias } from "../gir/alias.ts";
 import { IntrospectedConstructor } from "../gir/constructor.ts";
@@ -28,6 +33,7 @@ import {
 	Uint8ArrayType,
 	VoidType,
 } from "../gir.ts";
+import { girParsingReporter } from "../utils/gir-parsing.ts";
 
 export default {
 	namespace: "Gio",
@@ -700,7 +706,14 @@ export default {
 		if (existingMethodIndex !== -1) {
 			ActionMap.members[existingMethodIndex] = newMethod;
 		} else {
-			console.warn("Could not find existing add_action_entries method to override");
+			girParsingReporter
+				.get()
+				.reportParsingFailure(
+					"add_action_entries",
+					"method",
+					"Gio",
+					"Could not find existing add_action_entries method to override in Gio.ActionMap",
+				);
 			ActionMap.members.push(newMethod);
 		}
 	},

package/src/injections/glib.ts

@@ -1,3 +1,8 @@
+/**
+ * GLib type injection overrides.
+ * Uses of `any`/`AnyType` in this file are intentional — they produce
+ * generated .d.ts output matching GLib's dynamic runtime behavior.
+ */
 import { GirDirection } from "@gi.ts/parser";
 import { IntrospectedConstructor } from "../gir/constructor.ts";
 import { IntrospectedDirectAllocationConstructor } from "../gir/direct-allocation-constructor.ts";

package/src/injections/gobject.ts

@@ -1,3 +1,8 @@
+/**
+ * GObject type injection overrides.
+ * Uses of `any`/`AnyType` in this file are intentional — they produce
+ * generated .d.ts output matching GObject's dynamic runtime behavior.
+ */
 import { GirDirection } from "@gi.ts/parser";
 import { IntrospectedAlias } from "../gir/alias.ts";
 import { IntrospectedFunction } from "../gir/function.ts";

package/src/types/options-generation.ts

@@ -50,4 +50,16 @@ export interface OptionsGeneration extends OptionsBase {
 	 * Output file path for the reporter
 	 */
 	reporterOutput: string;
+	/** Generate a single unified documentation for all modules instead of separate per-module docs */
+	combined?: boolean;
+	/** URL template for source links in generated documentation. Supports {path}, {line}, {gitRevision} placeholders */
+	sourceLinkTemplate?: string;
+	/** Theme for HTML documentation generation (default: "gi-docgen") */
+	theme?: string;
+	/** Path to a README file to use as the documentation index page (default: "none") */
+	readme?: string;
+	/** Use TypeDoc merge mode to generate HTML from pre-generated JSON files */
+	merge?: boolean;
+	/** Directory containing pre-generated TypeDoc JSON files for merge mode (from 'ts-for-gir json') */
+	jsonDir?: string;
 }

package/src/types/user-config.ts

@@ -55,4 +55,16 @@ export interface UserConfig {
 	 * Output file path for the reporter
 	 */
 	reporterOutput: string;
+	/** Generate a single unified documentation for all modules instead of separate per-module docs */
+	combined?: boolean;
+	/** URL template for source links in generated documentation. Supports {path}, {line}, {gitRevision} placeholders */
+	sourceLinkTemplate?: string;
+	/** Theme for HTML documentation generation (default: "gi-docgen") */
+	theme?: string;
+	/** Path to a README file to use as the documentation index page (default: "none") */
+	readme?: string;
+	/** Use TypeDoc merge mode to generate HTML from pre-generated JSON files */
+	merge?: boolean;
+	/** Directory containing pre-generated TypeDoc JSON files for merge mode (from 'ts-for-gir json') */
+	jsonDir?: string;
 }

package/src/utils/conflicts.ts

@@ -1,5 +1,5 @@
 import { GirDirection } from "@gi.ts/parser";
-import { ConsoleReporter, ReporterService } from "@ts-for-gir/reporter";
+import { LazyReporter } from "@ts-for-gir/reporter";
 import { IntrospectedConstructor } from "../gir/constructor.ts";
 import { FilterBehavior } from "../gir/data.ts";
 import type { IntrospectedFunction } from "../gir/function.ts";
@@ -20,48 +20,14 @@ import { AnyType, ArrayType, ConflictType, NeverType, TypeConflict } from "../gi
 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",
-};
+export const conflictsReporter = new LazyReporter("conflicts");
 
-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);
+// Use a function to always get the current reporter instance.
+// A module-level `const log = conflictsReporter.get()` would capture a stale
+// reference from before configure() is called, causing problems to be logged
+// to console but not stored in the report.
+function getLog() {
+	return conflictsReporter.get();
 }
 
 // Constants for GObject methods that always conflict
@@ -119,7 +85,7 @@ export function filterFunctionConflict<
 
 			if (conflictResult.shouldOmit) {
 				// Always omit methods that conflict with properties/fields
-				log.reportTypeConflict(
+				getLog().reportTypeConflict(
 					"field_property",
 					next.name,
 					next.parent?.namespace.namespace || "unknown",
@@ -127,7 +93,7 @@ export function filterFunctionConflict<
 				);
 			} else if (conflictResult.hasConflict) {
 				if (isInheritedMethods) {
-					log.reportTypeConflict(
+					getLog().reportTypeConflict(
 						"method",
 						next.name,
 						next.parent?.namespace.namespace || "unknown",
@@ -445,7 +411,7 @@ function checkPropertyConflicts<T extends IntrospectedClassMember | Introspected
 					element instanceof IntrospectedProperty &&
 					!isSubtypeOf(ns, thisType, resolved_parent.getType(), element.type, p.type)
 				) {
-					log.reportTypeConflict(
+					getLog().reportTypeConflict(
 						"general",
 						element.name,
 						element.parent?.namespace.namespace || "unknown",