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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-for-gir/generator-json",
-  "version": "4.0.0-beta.44",
+  "version": "4.0.0-rc.2",
   "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",
+    "@ts-for-gir/tsconfig": "^4.0.0-rc.2",
+    "@types/node": "^24.12.2",
     "typescript": "^6.0.2"
   },
   "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",
+    "@gi.ts/parser": "^4.0.0-rc.2",
+    "@ts-for-gir/generator-base": "^4.0.0-rc.2",
+    "@ts-for-gir/generator-typescript": "^4.0.0-rc.2",
+    "@ts-for-gir/gir-module-metadata": "^4.0.0-rc.2",
+    "@ts-for-gir/lib": "^4.0.0-rc.2",
+    "@ts-for-gir/reporter": "^4.0.0-rc.2",
     "typedoc": "^0.28.18"
   }
 }

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

@@ -128,6 +128,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 +224,7 @@ export class TypeDocPipeline {
 			[new TSConfigReader()],
 		);
 		this.fixExportImportReferences(result.project);
+		this.enrichModuleReflections(result.project);
 		return result;
 	}
 
@@ -240,9 +250,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 });
@@ -635,7 +711,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,