@ts-for-gir/generator-json 4.0.0-beta.44 → 4.0.0-rc.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-for-gir/generator-json",
-  "version": "4.0.0-beta.44",
+  "version": "4.0.0-rc.10",
   "description": "JSON generator for ts-for-gir",
   "main": "src/index.ts",
   "module": "src/index.ts",
@@ -36,17 +36,17 @@
     "json"
   ],
   "devDependencies": {
-    "@ts-for-gir/tsconfig": "^4.0.0-beta.44",
-    "@types/node": "^24.12.0",
-    "typescript": "^6.0.2"
+    "@ts-for-gir/tsconfig": "^4.0.0-rc.10",
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@gi.ts/parser": "^4.0.0-beta.44",
-    "@ts-for-gir/generator-base": "^4.0.0-beta.44",
-    "@ts-for-gir/generator-typescript": "^4.0.0-beta.44",
-    "@ts-for-gir/gir-module-metadata": "^4.0.0-beta.44",
-    "@ts-for-gir/lib": "^4.0.0-beta.44",
-    "@ts-for-gir/reporter": "^4.0.0-beta.44",
-    "typedoc": "^0.28.18"
+    "@gi.ts/parser": "^4.0.0-rc.10",
+    "@ts-for-gir/generator-base": "^4.0.0-rc.10",
+    "@ts-for-gir/generator-typescript": "^4.0.0-rc.10",
+    "@ts-for-gir/gir-module-metadata": "^4.0.0-rc.10",
+    "@ts-for-gir/lib": "^4.0.0-rc.10",
+    "@ts-for-gir/reporter": "^4.0.0-rc.10",
+    "typedoc": "^0.28.19"
   }
 }

package/src/gir-metadata-types.ts

@@ -115,6 +115,8 @@ export interface GirNamespaceMetadata {
 	description?: string;
 	/** Logo/icon URL */
 	logoUrl?: string;
+	/** Icon filename from refs/library-icons (e.g. "librsvg-r.svg") */
+	iconFile?: string;
 	/** Project website URL */
 	websiteUrl?: string;
 	/** URL to upstream C API documentation */

package/src/typedoc-pipeline.ts

@@ -16,9 +16,11 @@ import {
 	type ProjectReflection,
 	ReferenceReflection,
 	ReflectionCategory,
+	ReflectionKind,
 	Serializer,
 	TSConfigReader,
 	type TypeDocOptions,
+	type Reflection as TypeDocReflection,
 } from "typedoc";
 import { GirMetadataDeserializer } from "./gir-metadata-deserializer.ts";
 import { buildGirLookupIndex } from "./gir-metadata-index.ts";
@@ -128,6 +130,15 @@ export class TypeDocPipeline {
 		result.project.packageVersion = module.libraryVersion.toString();
 
 		this.registerGirMetadata(result.app, module);
+
+		// Attach metadata directly to module reflections for HTML rendering.
+		// registerGirMetadata only hooks into the serializer (for JSON export);
+		// the theme needs metadata on the reflections themselves.
+		const nsMeta = this.buildNamespaceMetadata(module);
+		for (const child of result.project.children ?? []) {
+			(child as unknown as { girNamespaceMetadata?: GirNamespaceMetadata }).girNamespaceMetadata ??= nsMeta;
+		}
+
 		return result;
 	}
 
@@ -215,6 +226,7 @@ export class TypeDocPipeline {
 			[new TSConfigReader()],
 		);
 		this.fixExportImportReferences(result.project);
+		this.enrichModuleReflections(result.project);
 		return result;
 	}
 
@@ -240,9 +252,75 @@ export class TypeDocPipeline {
 
 		const result = await this.convertApp(app, "merged documentation");
 		this.fixExportImportReferences(result.project);
+		this.enrichMergedModuleMetadata(result.project);
 		return result;
 	}
 
+	/**
+	 * Enrich module reflections with curated metadata after merge.
+	 *
+	 * In merge mode, girNamespaceMetadata lives at the project-root level of
+	 * each individual JSON file. When TypeDoc merges these files, the metadata
+	 * may not be transferred to the resulting module reflections. This method
+	 * fills in missing metadata from the curated registry so that the theme
+	 * can always categorise and describe every module.
+	 */
+	private enrichMergedModuleMetadata(project: ProjectReflection): void {
+		if (!project.children) return;
+		for (const child of project.children) {
+			const enriched = child as DeclarationReflection & { girNamespaceMetadata?: GirNamespaceMetadata };
+			// Skip modules that already have a category from the JSON deserializer
+			if (enriched.girNamespaceMetadata?.category) continue;
+
+			// Try to find curated metadata by matching the module name to a GIR ID.
+			// Module names in the merged project follow the pattern "Namespace-Version"
+			// (e.g. "Gtk-4.0") which matches the girId used in the metadata registry.
+			const meta = getModuleMetadata(child.name);
+			if (!meta) continue;
+
+			const existing = enriched.girNamespaceMetadata ?? ({} as GirNamespaceMetadata);
+			enriched.girNamespaceMetadata = {
+				...existing,
+				displayName: existing.displayName ?? meta.displayName,
+				description: existing.description ?? meta.description,
+				logoUrl:
+					existing.logoUrl ?? meta.logoUrl ?? (meta.iconFile ? `assets/library-icons/${meta.iconFile}` : undefined),
+				iconFile: existing.iconFile ?? meta.iconFile,
+				websiteUrl: existing.websiteUrl ?? meta.websiteUrl,
+				cDocsUrl: existing.cDocsUrl ?? meta.cDocsUrl,
+				license: existing.license ?? meta.license,
+				category: existing.category ?? meta.category,
+			};
+		}
+	}
+
+	/**
+	 * Attach metadata to module reflections by matching against known GIR modules.
+	 * Used in combined mode where modules are discovered via "packages" entry point strategy.
+	 */
+	private enrichModuleReflections(project: ProjectReflection): void {
+		if (!project.children) return;
+
+		// Build lookup maps: by importName (e.g. "rsvg-2.0") and by packageName (e.g. "Rsvg-2.0")
+		const metaByImportName = new Map<string, GirNamespaceMetadata>();
+		for (const module of this.modules) {
+			metaByImportName.set(module.importName, this.buildNamespaceMetadata(module));
+		}
+
+		for (const child of project.children) {
+			const enriched = child as DeclarationReflection & { girNamespaceMetadata?: GirNamespaceMetadata };
+			if (enriched.girNamespaceMetadata?.category) continue;
+
+			// Module name may be scoped (e.g. "@girs/rsvg-2.0") — extract the importName part
+			const scopeMatch = child.name.match(/^@[^/]+\/(.+)$/);
+			const importName = scopeMatch ? scopeMatch[1] : child.name.toLowerCase();
+			const nsMeta = metaByImportName.get(importName);
+			if (nsMeta) {
+				enriched.girNamespaceMetadata ??= nsMeta;
+			}
+		}
+	}
+
 	async cleanup(): Promise<void> {
 		if (this.tempDir) {
 			await rm(this.tempDir, { recursive: true, force: true });
@@ -472,25 +550,77 @@ export class TypeDocPipeline {
 
 	/**
 	 * Extract a human-readable source name from an inherited member's `inheritedFrom`.
-	 * e.g. `"Window.accessible_role"` → looks up parent to get `"Gtk.Window"`.
+	 *
+	 * Two TypeDoc quirks are handled:
+	 *
+	 * 1. Per-class phantom inheritance chain. For `Window extends Widget extends
+	 *    InitiallyUnowned extends Object`, Window's `bind_property.inheritedFrom`
+	 *    points to `Widget.bind_property` (itself inherited from
+	 *    `InitiallyUnowned.bind_property`), not directly to the original definer.
+	 *    Walking the chain transitively yields the most-original visible source,
+	 *    matching gi-docgen's upstream documentation convention. When the chain
+	 *    crosses a package boundary the reference can't be resolved at runtime
+	 *    (target=-1), but the reference's `name` field still records the
+	 *    qualified original definer.
+	 *
+	 * 2. Accessor signatures. For an inherited accessor like Widget.cursor,
+	 *    `inheritedFrom.reflection` may be the get/set signature whose `parent`
+	 *    is the Accessor reflection (`Gtk.Widget.cursor`), not the class. Using
+	 *    that name verbatim creates a per-property "Inherited from
+	 *    Widget.cursor" section instead of a single "Inherited from Gtk.Widget"
+	 *    section. Walking up to the nearest containing class/interface fixes it.
 	 */
 	private extractInheritedSourceName(child: DeclarationReflection): string | null {
 		if (!child.inheritedFrom) return null;
 
-		// Try to resolve via the referenced reflection's parent
-		const target = child.inheritedFrom.reflection;
-		if (target?.parent) {
-			const parent = target.parent;
-			// Get the full qualified name: "Gtk.Window" from the parent's path
-			const fullName = parent.getFullName();
-			// The full name format is "Module.Class" — keep as-is
+		// 1. Follow `inheritedFrom` transitively to the original definer.
+		// Capture the *unresolved* boundary name if we hit one — TypeDoc's
+		// per-package conversion can't follow `inheritedFrom` across package
+		// boundaries (target=-1), but the reference's `name` field still
+		// records the original definer's qualified name.
+		let target = child.inheritedFrom.reflection as DeclarationReflection | undefined;
+		let unresolvedBoundaryName: string | undefined = target ? undefined : child.inheritedFrom.name;
+		const seen = new Set<number>();
+		while (target?.isDeclaration() && target.inheritedFrom) {
+			if (!target.inheritedFrom.reflection) {
+				unresolvedBoundaryName = target.inheritedFrom.name;
+				break;
+			}
+			if (seen.has(target.id)) break;
+			seen.add(target.id);
+			target = target.inheritedFrom.reflection as DeclarationReflection;
+		}
+
+		// 2. If the chain ended at a cross-package boundary, parse the original
+		// definer from the unresolved reference's `name` (e.g. for the gtk-4.0
+		// project, `Widget.bind_property.inheritedFrom.name` is
+		// "GObject.InitiallyUnowned.bind_property"). Strip the trailing member
+		// name to get the qualified defining class.
+		if (unresolvedBoundaryName) {
+			const lastDot = unresolvedBoundaryName.lastIndexOf(".");
+			if (lastDot > 0) return unresolvedBoundaryName.slice(0, lastDot);
+		}
+
+		// 3. The chain resolved fully within this project. Walk the target's
+		// parent chain to the containing class/interface so accessor signatures
+		// don't yield "Class.property" as the source.
+		if (target) {
+			let owner: TypeDocReflection | undefined = target.parent;
+			while (owner && !owner.kindOf(ReflectionKind.ClassOrInterface)) {
+				owner = owner.parent;
+			}
+			const fullName = owner?.getFullName();
 			if (fullName) return fullName;
+			if (target.parent) {
+				const parentName = target.parent.getFullName();
+				if (parentName) return parentName;
+			}
 		}
 
-		// Fallback: extract from the name string (e.g. "Window.method" → "Window")
+		// Final fallback: parse the immediate `inheritedFrom.name`.
 		const name = child.inheritedFrom.name;
-		const dotIdx = name.indexOf(".");
-		return dotIdx > 0 ? name.slice(0, dotIdx) : name;
+		const lastDot = name.lastIndexOf(".");
+		return lastDot > 0 ? name.slice(0, lastDot) : name;
 	}
 
 	/**
@@ -635,7 +765,8 @@ export class TypeDocPipeline {
 			packageVersion: pkgJson?.version,
 			displayName: meta?.displayName,
 			description: meta?.description ?? pkgJson?.description,
-			logoUrl: meta?.logoUrl,
+			logoUrl: meta?.logoUrl ?? (meta?.iconFile ? `assets/library-icons/${meta.iconFile}` : undefined),
+			iconFile: meta?.iconFile,
 			websiteUrl: meta?.websiteUrl ?? pkgJson?.homepage,
 			cDocsUrl: meta?.cDocsUrl,
 			license: meta?.license ?? pkgJson?.license,