@ts-for-gir/generator-json 4.0.0-beta.39 → 4.0.0-beta.41

package/README.md

@@ -18,78 +18,100 @@
 
 # JSON Generator
 
-JSON output generator for `ts-for-gir`. This package provides an alternative output format that serializes the processed GIR data into structured JSON instead of TypeScript definitions.
+JSON output generator for `ts-for-gir`. This package uses [TypeDoc](https://typedoc.org/) to produce standardized **TypeDoc JSON Schema 2.0** output, enriched with GIR-specific metadata.
 
-## Purpose
+## How It Works
 
-The JSON generator serves as an alternative output format for the `ts-for-gir` toolchain, enabling:
+The generator uses a two-step process:
 
-- **Data Export**: Export processed GIR data in a structured, machine-readable format
-- **Analysis Tools**: Provide input for external analysis and processing tools
-- **Documentation**: Generate structured documentation data from GIR files
-- **Integration**: Enable integration with other tools and languages beyond TypeScript
+1. **Generate `.d.ts` files** into a temporary directory using the TypeScript type definition generator
+2. **Run TypeDoc programmatically** over those files to produce standardized JSON, enriched with GIR-specific metadata via a custom `SerializerComponent`
+
+This approach combines the best of both worlds: TypeDoc's standardized, well-documented JSON schema with GIR-specific introspection data that would otherwise be lost during TypeScript generation.
 
 ## Features
 
-- **Complete Type Serialization**: Converts all TypeScript type expressions to JSON format
-- **Structured Output**: Organizes data into logical categories (classes, interfaces, functions, etc.)
-- **Metadata Preservation**: Maintains documentation, deprecation info, and other metadata
-- **Type System Mapping**: Maps complex TypeScript types to JSON representations
+- **Standardized Output**: Produces [TypeDoc JSON Schema 2.0](https://typedoc.org/guides/documents/#json-output), compatible with the TypeDoc ecosystem
+- **GIR Metadata Enrichment**: Adds `girMetadata` fields to each reflection with GIR-specific data (C types, signal flags, property access, parameter directions, etc.)
+- **Namespace Metadata**: Includes `girNamespaceMetadata` at the project root with C prefixes, library version, and dependency information
+- **Complete Type Information**: Full TypeScript type information including generics, overloads, and JSDoc
 
 ## JSON Structure
 
-The generator produces JSON with the following structure:
+The output follows TypeDoc's JSON Schema 2.0 with additional GIR metadata:
 
 ```json
 {
-  "kind": "namespace",
-  "name": "ModuleName",
-  "version": "1.0",
-  "imports": {},
-  "classes": [...],
-  "interfaces": [...],
-  "functions": [...],
-  "enums": [...],
-  "constants": [...],
-  "records": [...],
-  "callbacks": [...],
-  "errors": [...]
+  "schemaVersion": "2.0",
+  "name": "Gtk-4.0",
+  "variant": "project",
+  "kind": 1,
+  "children": [
+    {
+      "name": "Gtk",
+      "variant": "declaration",
+      "kind": 4,
+      "children": [
+        {
+          "name": "Widget",
+          "kind": 128,
+          "girMetadata": {
+            "girKind": "class",
+            "resolveNames": ["GtkWidget"],
+            "classMetadata": {
+              "isAbstract": true,
+              "interfaces": ["Gtk.Accessible", "Gtk.Buildable"],
+              "signalNames": ["destroy", "show", "hide"]
+            }
+          }
+        }
+      ]
+    }
+  ],
+  "girNamespaceMetadata": {
+    "namespace": "Gtk",
+    "version": "4.0",
+    "packageName": "Gtk-4.0",
+    "cPrefixes": ["Gtk"],
+    "libraryVersion": "4.20.3",
+    "dependencies": [
+      { "namespace": "Gsk", "version": "4.0" },
+      { "namespace": "Gdk", "version": "4.0" }
+    ]
+  }
 }
 ```
 
-## Type Representations
-
-Types are serialized with a consistent structure:
+## GIR Metadata
 
-- **Identifiers**: `{ "kind": "identifier", "namespace": "...", "name": "..." }`
-- **Arrays**: `{ "kind": "array", "type": {...}, "depth": 1 }`
-- **Unions**: `{ "kind": "or", "types": [...] }`
-- **Tuples**: `{ "kind": "tuple", "types": [...] }`
-- **Nullable**: `{ "kind": "null", "type": {...} }`
-- **Native**: `{ "kind": "native", "type": "string" }`
+Each TypeDoc reflection can include a `girMetadata` field with GIR-specific data:
 
-## Node Types
+| GIR Kind | Metadata | Fields |
+|----------|----------|--------|
+| `class` | `classMetadata` | `isAbstract`, `interfaces`, `signalNames` |
+| `record` | `recordMetadata` | `isForeign`, `isSimple`, `structFor` |
+| `enum` / `bitfield` | `enumMetadata` | `isFlags` |
+| `method` / `virtual-method` / `static-method` | `functionMetadata` | `isVirtual`, `isStatic`, `parameterDirections`, `nullableParams`, `optionalParams` |
+| `property` | `propertyMetadata` | `readable`, `writable`, `constructOnly` |
+| `signal` | `signalMetadata` | `signalName`, `detailed` |
+| `constructor` | `functionMetadata` | `parameterDirections`, `nullableParams`, `optionalParams` |
+| `constant`, `alias`, `callback`, `field` | — | Common metadata only |
 
-Each element includes metadata:
-
-```json
-{
-  "kind": "class|interface|function|...",
-  "name": "ElementName",
-  "doc": "Documentation string",
-  "metadata": {...},
-  "private": false,
-  ...
-}
-```
+All GIR elements also include common metadata when available: `resolveNames` (C type names), `introducedVersion`, `deprecated`, `deprecatedVersion`, `deprecatedDoc`.
 
 ## Usage
 
-This package is used internally by the ts-for-gir CLI when JSON output is requested. It implements the standard Generator interface defined in `@ts-for-gir/generator-base`.
+```bash
+# Generate JSON for a specific module
+ts-for-gir json Gtk-4.0 --outdir ./json-output
+
+# Generate with verbose output (pretty-printed JSON)
+ts-for-gir json Gtk-4.0 --outdir ./json-output --verbose
+```
 
 The JSON output can be useful for:
 - Building documentation websites
-- Creating API analysis tools
+- Creating API analysis and exploration tools
 - Generating bindings for other languages
 - Data processing and transformation pipelines
 - IDE integration and tooling
@@ -98,6 +120,6 @@ The JSON output can be useful for:
 
 The JSON generator integrates with the ts-for-gir ecosystem through:
 - **Reporter System**: Comprehensive logging and error reporting
-- **Generator Interface**: Standard lifecycle methods (start, generate, finish)
-- **Type System**: Full compatibility with ts-for-gir type representations
+- **Generator Interface**: Standard lifecycle methods (`start`, `generate`, `finish`)
+- **TypeDoc**: Programmatic usage of TypeDoc for JSON serialization with custom `SerializerComponent`
 - **Configuration**: Respects all standard ts-for-gir options and settings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-for-gir/generator-json",
-  "version": "4.0.0-beta.39",
+  "version": "4.0.0-beta.41",
   "description": "JSON generator for ts-for-gir",
   "main": "src/index.ts",
   "module": "src/index.ts",
@@ -36,13 +36,17 @@
     "json"
   ],
   "devDependencies": {
-    "@types/node": "^24.11.0",
+    "@ts-for-gir/tsconfig": "^4.0.0-beta.41",
+    "@types/node": "^24.12.0",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@gi.ts/parser": "^4.0.0-beta.39",
-    "@ts-for-gir/generator-base": "^4.0.0-beta.39",
-    "@ts-for-gir/lib": "^4.0.0-beta.39",
-    "@ts-for-gir/reporter": "^4.0.0-beta.39"
+    "@gi.ts/parser": "^4.0.0-beta.41",
+    "@ts-for-gir/generator-base": "^4.0.0-beta.41",
+    "@ts-for-gir/generator-typescript": "^4.0.0-beta.41",
+    "@ts-for-gir/gir-module-metadata": "^4.0.0-beta.41",
+    "@ts-for-gir/lib": "^4.0.0-beta.41",
+    "@ts-for-gir/reporter": "^4.0.0-beta.41",
+    "typedoc": "^0.28.17"
   }
 }

package/src/gir-metadata-deserializer.ts

@@ -0,0 +1,34 @@
+import { DeclarationReflection, type DeserializerComponent } from "typedoc";
+
+import type { GirEnrichedReflection, GirNamespaceMetadata, GirReflectionMetadata } from "./gir-metadata-types.ts";
+
+/**
+ * TypeDoc deserializer component that restores GIR-specific metadata
+ * from JSON output back onto Reflection instances during merge mode.
+ *
+ * This is the counterpart to {@link GirMetadataSerializer} — it reads
+ * the `girMetadata` and `girNamespaceMetadata` fields from the JSON
+ * and attaches them as custom properties on the deserialized reflections.
+ */
+export class GirMetadataDeserializer implements DeserializerComponent {
+	readonly priority = -1;
+
+	supports(model: unknown, obj: unknown): boolean {
+		if (!(model instanceof DeclarationReflection)) return false;
+		if (typeof obj !== "object" || obj === null) return false;
+		return "girMetadata" in obj || "girNamespaceMetadata" in obj;
+	}
+
+	fromObject(model: unknown, obj: unknown): void {
+		if (!(model instanceof DeclarationReflection)) return;
+		const jsonObj = obj as Record<string, unknown>;
+		const enriched = model as DeclarationReflection & GirEnrichedReflection;
+
+		if (jsonObj.girMetadata) {
+			enriched.girMetadata = jsonObj.girMetadata as GirReflectionMetadata;
+		}
+		if (jsonObj.girNamespaceMetadata) {
+			enriched.girNamespaceMetadata = jsonObj.girNamespaceMetadata as GirNamespaceMetadata;
+		}
+	}
+}

package/src/gir-metadata-index.ts

@@ -0,0 +1,66 @@
+import { type GirModule, IntrospectedBaseClass, IntrospectedClass } from "@ts-for-gir/lib";
+
+/**
+ * A flat lookup index mapping TypeDoc reflection names to GIR introspected objects.
+ *
+ * Keys follow the pattern used by TypeDoc's `getFullName(".")` with the module prefix stripped:
+ * - Namespace members: `"Widget"`, `"init"`
+ * - Class members: `"Widget.show"`, `"Widget.visible"`
+ * - Signals: `"Widget.destroy"` (signal name)
+ */
+export type GirLookupIndex = Map<string, unknown>;
+
+/**
+ * Build a lookup index from a GirModule that maps TypeDoc reflection names
+ * to GIR introspected objects.
+ */
+export function buildGirLookupIndex(module: GirModule): GirLookupIndex {
+	const index: GirLookupIndex = new Map();
+
+	for (const [name, member] of module.members) {
+		const members = Array.isArray(member) ? member : [member];
+
+		for (const m of members) {
+			index.set(name, m);
+
+			if (m instanceof IntrospectedBaseClass) {
+				indexClassMembers(index, name, m);
+			}
+		}
+	}
+
+	return index;
+}
+
+function indexClassMembers(index: GirLookupIndex, className: string, cls: IntrospectedBaseClass): void {
+	for (const fn of cls.members) {
+		index.set(`${className}.${fn.name}`, fn);
+	}
+
+	for (const prop of cls.props) {
+		index.set(`${className}.${prop.name}`, prop);
+	}
+
+	for (const field of cls.fields) {
+		// Don't overwrite if a property with same name already exists
+		const key = `${className}.${field.name}`;
+		if (!index.has(key)) {
+			index.set(key, field);
+		}
+	}
+
+	for (const ctor of cls.constructors) {
+		index.set(`${className}.${ctor.name}`, ctor);
+	}
+
+	for (const cb of cls.callbacks) {
+		index.set(`${className}.${cb.name}`, cb);
+	}
+
+	if (cls instanceof IntrospectedClass) {
+		for (const signal of cls.signals) {
+			// Use a signal-specific prefix to avoid collisions with methods
+			index.set(`signal:${className}.${signal.name}`, signal);
+		}
+	}
+}

package/src/gir-metadata-serializer.ts

@@ -0,0 +1,237 @@
+import {
+	IntrospectedAlias,
+	IntrospectedBaseClass,
+	IntrospectedCallback,
+	IntrospectedClass,
+	IntrospectedClassFunction,
+	IntrospectedConstant,
+	IntrospectedConstructor,
+	IntrospectedEnum,
+	IntrospectedError,
+	IntrospectedField,
+	IntrospectedFunction,
+	type IntrospectedFunctionParameter,
+	IntrospectedProperty,
+	IntrospectedRecord,
+	IntrospectedSignal,
+	IntrospectedStaticClassFunction,
+	IntrospectedVirtualClassFunction,
+} from "@ts-for-gir/lib";
+import { DeclarationReflection, type SerializerComponent } from "typedoc";
+
+import type { GirLookupIndex } from "./gir-metadata-index.ts";
+import type {
+	GirClassMetadata,
+	GirElementKind,
+	GirEnumMetadata,
+	GirFunctionMetadata,
+	GirRecordMetadata,
+	GirReflectionMetadata,
+} from "./gir-metadata-types.ts";
+
+/**
+ * TypeDoc serializer component that enriches JSON output with GIR-specific metadata.
+ *
+ * For each `DeclarationReflection`, it looks up the corresponding GIR introspected
+ * object via the pre-built lookup index and adds a `girMetadata` field to the JSON.
+ */
+export class GirMetadataSerializer implements SerializerComponent<DeclarationReflection> {
+	readonly priority = -1;
+
+	constructor(private readonly index: GirLookupIndex) {}
+
+	supports(item: unknown): boolean {
+		return item instanceof DeclarationReflection;
+	}
+
+	toObject(item: DeclarationReflection, obj: Partial<Record<string, unknown>>): Partial<Record<string, unknown>> {
+		const key = this.getLookupKey(item);
+		const girObj = this.index.get(key);
+
+		if (!girObj) return obj;
+
+		const metadata = this.buildMetadata(girObj);
+		if (metadata) {
+			obj.girMetadata = metadata;
+		}
+
+		return obj;
+	}
+
+	private getLookupKey(reflection: DeclarationReflection): string {
+		const fullName = reflection.getFullName(".");
+		// Strip the namespace prefix (first segment, e.g. "freetype2" from "freetype2.Bitmap.$gtype")
+		const dotIndex = fullName.indexOf(".");
+		return dotIndex >= 0 ? fullName.substring(dotIndex + 1) : fullName;
+	}
+
+	/**
+	 * Dispatch table mapping GIR class constructors to their metadata builders.
+	 * Order matters: subclasses must appear before superclasses (e.g.
+	 * IntrospectedRecord before IntrospectedBaseClass, IntrospectedError before IntrospectedEnum).
+	 */
+	private static readonly METADATA_DISPATCH: Array<
+		// biome-ignore lint/suspicious/noExplicitAny: heterogeneous constructors and handlers require any
+		[abstract new (...args: any[]) => unknown, (self: GirMetadataSerializer, obj: any) => GirReflectionMetadata]
+	> = [
+		[IntrospectedRecord, (s, o) => s.buildRecordMetadata(o)],
+		[IntrospectedClass, (s, o) => s.buildClassMetadata(o)],
+		[IntrospectedBaseClass, (s, o) => s.buildBaseMetadata(o, "interface")],
+		[IntrospectedError, (s, o) => s.buildEnumMetadata(o, true)],
+		[IntrospectedEnum, (s, o) => s.buildEnumMetadata(o, false)],
+		[IntrospectedConstructor, (s, o) => s.buildFunctionLikeMetadata(o, "constructor")],
+		[IntrospectedVirtualClassFunction, (s, o) => s.buildFunctionLikeMetadata(o, "virtual-method", { isVirtual: true })],
+		[IntrospectedStaticClassFunction, (s, o) => s.buildFunctionLikeMetadata(o, "static-method", { isStatic: true })],
+		[IntrospectedClassFunction, (s, o) => s.buildFunctionLikeMetadata(o, "method")],
+		[IntrospectedCallback, (s, o) => s.buildFunctionLikeMetadata(o, "callback")],
+		[IntrospectedFunction, (s, o) => s.buildFunctionLikeMetadata(o, "function")],
+		[IntrospectedProperty, (s, o) => s.buildPropertyMetadata(o)],
+		[IntrospectedField, (s, o) => s.buildBaseMetadata(o, "field")],
+		[IntrospectedSignal, (s, o) => s.buildSignalMetadata(o)],
+		[IntrospectedConstant, (s, o) => s.buildBaseMetadata(o, "constant")],
+		[IntrospectedAlias, (s, o) => s.buildBaseMetadata(o, "alias")],
+	];
+
+	private buildMetadata(girObj: unknown): GirReflectionMetadata | null {
+		for (const [ctor, handler] of GirMetadataSerializer.METADATA_DISPATCH) {
+			if (girObj instanceof ctor) {
+				return handler(this, girObj);
+			}
+		}
+		return null;
+	}
+
+	private buildBaseMetadata(
+		girObj: {
+			resolve_names?: string[];
+			metadata?: {
+				introducedVersion?: string;
+				deprecated?: boolean;
+				deprecatedVersion?: string;
+				deprecatedDoc?: string;
+			};
+		},
+		girKind: GirElementKind,
+	): GirReflectionMetadata {
+		const metadata: GirReflectionMetadata = { girKind };
+
+		if (girObj.resolve_names && girObj.resolve_names.length > 0) {
+			metadata.resolveNames = girObj.resolve_names;
+		}
+
+		const m = girObj.metadata;
+		if (m) {
+			if (m.introducedVersion) metadata.introducedVersion = m.introducedVersion;
+			if (m.deprecated) metadata.deprecated = m.deprecated;
+			if (m.deprecatedVersion) metadata.deprecatedVersion = m.deprecatedVersion;
+			if (m.deprecatedDoc) metadata.deprecatedDoc = m.deprecatedDoc;
+		}
+
+		return metadata;
+	}
+
+	private buildClassMetadata(cls: IntrospectedClass): GirReflectionMetadata {
+		const metadata = this.buildBaseMetadata(cls, "class");
+
+		const classMetadata: GirClassMetadata = {};
+		if (cls.isAbstract) classMetadata.isAbstract = true;
+		if (cls.interfaces.length > 0) {
+			classMetadata.interfaces = cls.interfaces.map((i) => `${i.namespace}.${i.name}`);
+		}
+		if (cls.signals.length > 0) {
+			classMetadata.signalNames = cls.signals.map((s) => s.name);
+		}
+
+		if (Object.keys(classMetadata).length > 0) {
+			metadata.classMetadata = classMetadata;
+		}
+
+		return metadata;
+	}
+
+	private buildRecordMetadata(record: IntrospectedRecord): GirReflectionMetadata {
+		const metadata = this.buildBaseMetadata(record, "record");
+
+		const recordMetadata: GirRecordMetadata = {
+			isForeign: record.isForeign(),
+			isSimple: record.isSimple(),
+		};
+
+		if (record.structFor) {
+			recordMetadata.structFor = `${record.structFor.namespace}.${record.structFor.name}`;
+		}
+
+		metadata.recordMetadata = recordMetadata;
+
+		return metadata;
+	}
+
+	private buildEnumMetadata(enumObj: IntrospectedEnum, isFlags: boolean): GirReflectionMetadata {
+		const metadata = this.buildBaseMetadata(enumObj, isFlags ? "bitfield" : "enum");
+		const enumMetadata: GirEnumMetadata = { isFlags };
+		metadata.enumMetadata = enumMetadata;
+		return metadata;
+	}
+
+	private extractFunctionParams(params: IntrospectedFunctionParameter[]): Partial<GirFunctionMetadata> {
+		const result: Partial<GirFunctionMetadata> = {};
+
+		const directions: Record<string, string> = {};
+		const nullable: string[] = [];
+		const optional: string[] = [];
+
+		for (const p of params) {
+			directions[p.name] = p.direction.toString();
+			if (p.isNullable) nullable.push(p.name);
+			if (p.isOptional) optional.push(p.name);
+		}
+
+		if (Object.keys(directions).length > 0) result.parameterDirections = directions;
+		if (nullable.length > 0) result.nullableParams = nullable;
+		if (optional.length > 0) result.optionalParams = optional;
+
+		return result;
+	}
+
+	private buildFunctionLikeMetadata(
+		fn: IntrospectedFunction | IntrospectedClassFunction | IntrospectedConstructor,
+		girKind: GirElementKind,
+		extra?: Partial<GirFunctionMetadata>,
+	): GirReflectionMetadata {
+		const metadata = this.buildBaseMetadata(fn, girKind);
+
+		const fnMeta: GirFunctionMetadata = {
+			...this.extractFunctionParams(fn.parameters),
+			...extra,
+		};
+
+		if (Object.keys(fnMeta).length > 0) {
+			metadata.functionMetadata = fnMeta;
+		}
+
+		return metadata;
+	}
+
+	private buildPropertyMetadata(prop: IntrospectedProperty): GirReflectionMetadata {
+		const metadata = this.buildBaseMetadata(prop, "property");
+		metadata.propertyMetadata = {
+			readable: prop.readable,
+			writable: prop.writable,
+			constructOnly: prop.constructOnly,
+		};
+		return metadata;
+	}
+
+	private buildSignalMetadata(signal: IntrospectedSignal): GirReflectionMetadata {
+		const metadata = this.buildBaseMetadata(signal, "signal");
+		metadata.signalMetadata = {
+			signalName: signal.name,
+			detailed: signal.detailed,
+			...(signal.action ? { action: true } : {}),
+			...(signal.noRecurse ? { noRecurse: true } : {}),
+			...(signal.noHooks ? { noHooks: true } : {}),
+			...(signal.when ? { when: signal.when } : {}),
+		};
+		return metadata;
+	}
+}

package/src/gir-metadata-types.ts

@@ -0,0 +1,132 @@
+/**
+ * Type definitions for GIR-specific metadata added to TypeDoc JSON output.
+ *
+ * These types describe the `girMetadata` field added to each TypeDoc reflection
+ * and the `girNamespaceMetadata` field added to the project root.
+ */
+
+export type GirElementKind =
+	| "class"
+	| "interface"
+	| "record"
+	| "enum"
+	| "bitfield"
+	| "function"
+	| "method"
+	| "virtual-method"
+	| "static-method"
+	| "constructor"
+	| "property"
+	| "field"
+	| "signal"
+	| "constant"
+	| "alias"
+	| "callback";
+
+export interface GirReflectionMetadata {
+	/** The kind of GIR element this reflection corresponds to */
+	girKind: GirElementKind;
+	/** Registered type names (c:type, glib:type-name) */
+	resolveNames?: string[];
+	/** Version when this element was introduced */
+	introducedVersion?: string;
+	/** Whether this element is deprecated */
+	deprecated?: boolean;
+	/** Version when this element was deprecated */
+	deprecatedVersion?: string;
+	/** Deprecation message */
+	deprecatedDoc?: string;
+	/** Class/Interface-specific metadata */
+	classMetadata?: GirClassMetadata;
+	/** Function/Method-specific metadata */
+	functionMetadata?: GirFunctionMetadata;
+	/** Property-specific metadata */
+	propertyMetadata?: GirPropertyMetadata;
+	/** Signal-specific metadata */
+	signalMetadata?: GirSignalMetadata;
+	/** Record-specific metadata */
+	recordMetadata?: GirRecordMetadata;
+	/** Enum-specific metadata */
+	enumMetadata?: GirEnumMetadata;
+}
+
+export interface GirClassMetadata {
+	isAbstract?: boolean;
+	interfaces?: string[];
+	signalNames?: string[];
+}
+
+export interface GirFunctionMetadata {
+	isVirtual?: boolean;
+	isStatic?: boolean;
+	/** Parameter directions keyed by parameter name */
+	parameterDirections?: Record<string, string>;
+	/** Names of parameters that are nullable */
+	nullableParams?: string[];
+	/** Names of parameters that are optional */
+	optionalParams?: string[];
+}
+
+export interface GirPropertyMetadata {
+	readable: boolean;
+	writable: boolean;
+	constructOnly: boolean;
+}
+
+export interface GirSignalMetadata {
+	/** Original signal name (kebab-case) */
+	signalName: string;
+	/** Whether this is a detailed signal */
+	detailed: boolean;
+	/** Whether this signal can be emitted directly from user code */
+	action?: boolean;
+	/** Whether this signal prevents recursive emission */
+	noRecurse?: boolean;
+	/** Whether this signal disables emission hooks */
+	noHooks?: boolean;
+	/** Default handler timing relative to signal emission */
+	when?: "first" | "last" | "cleanup";
+}
+
+export interface GirRecordMetadata {
+	isForeign: boolean;
+	isSimple: boolean;
+	/** Class this record is a GType struct for */
+	structFor?: string;
+}
+
+export interface GirEnumMetadata {
+	/** Whether this enum represents flags (bitfield) */
+	isFlags: boolean;
+}
+
+export interface GirNamespaceMetadata {
+	namespace: string;
+	version: string;
+	packageName: string;
+	cPrefixes: string[];
+	libraryVersion: string;
+	dependencies: Array<{ namespace: string; version: string }>;
+	/** NPM package version (e.g. "4.20.3-4.0.0-beta.41") */
+	packageVersion?: string;
+	/** Human-readable display name, e.g. "GTK" */
+	displayName?: string;
+	/** Short description of the library */
+	description?: string;
+	/** Logo/icon URL */
+	logoUrl?: string;
+	/** Project website URL */
+	websiteUrl?: string;
+	/** URL to upstream C API documentation */
+	cDocsUrl?: string;
+	/** SPDX license identifier */
+	license?: string;
+	/** Category for grouping on documentation homepage */
+	category?: string;
+}
+
+/** A DeclarationReflection extended with optional GIR-specific metadata. */
+export interface GirEnrichedReflection {
+	girMetadata?: GirReflectionMetadata;
+	girNamespaceMetadata?: GirNamespaceMetadata;
+}

package/src/index.ts

@@ -1,2 +1,4 @@
+export * from "./gir-metadata-deserializer.ts";
+export * from "./gir-metadata-types.ts";
 export * from "./json-definition-generator.ts";
-export * from "./json-generator.ts";
+export * from "./typedoc-pipeline.ts";