@gtkx/gir 0.10.5 → 0.11.0

package/dist/repository.d.ts

@@ -0,0 +1,151 @@
+/**
+ * GIR Repository - Central entry point for GIR data.
+ *
+ * Loads, normalizes, and provides query access to GIR namespaces.
+ * All type references are normalized to fully qualified names.
+ */
+import { type GirCallback, type GirClass, type GirConstant, type GirEnumeration, type GirFunction, type GirInterface, type GirNamespace, type GirRecord, type QualifiedName, type TypeKind } from "./types.js";
+/**
+ * Central repository for GIR data.
+ *
+ * Loads, normalizes, and provides query access to GIR namespaces.
+ * All type references are normalized to fully qualified names.
+ *
+ * @example
+ * ```typescript
+ * const repo = new GirRepository();
+ * await repo.loadFromDirectory("./girs");
+ * repo.resolve();
+ *
+ * const gtkNs = repo.getNamespace("Gtk");
+ * const buttonClass = repo.resolveClass("Gtk.Button");
+ * const chain = buttonClass.getInheritanceChain();
+ * // ["Gtk.Button", "Gtk.Widget", "GObject.InitiallyUnowned", "GObject.Object"]
+ * ```
+ */
+export declare class GirRepository {
+    private rawNamespaces;
+    private normalizedNamespaces;
+    private parser;
+    private resolved;
+    /**
+     * Loads a single GIR file from XML content.
+     */
+    loadFromXml(xml: string): void;
+    /**
+     * Loads a GIR file from disk.
+     */
+    loadFromFile(path: string): Promise<void>;
+    /**
+     * Loads all .gir files from a directory.
+     */
+    loadFromDirectory(dirPath: string): Promise<void>;
+    /**
+     * After loading all raw GIR files, normalize and resolve all references.
+     * This must be called after loading and before querying.
+     */
+    resolve(): void;
+    /**
+     * Gets all loaded namespace names.
+     */
+    getNamespaceNames(): string[];
+    /**
+     * Gets a normalized namespace by name.
+     */
+    getNamespace(name: string): GirNamespace | null;
+    /**
+     * Gets all normalized namespaces.
+     */
+    getAllNamespaces(): Map<string, GirNamespace>;
+    /**
+     * Resolves a class by qualified name.
+     * @example repo.resolveClass("Gtk.Button" as QualifiedName)
+     */
+    resolveClass(qualifiedName: QualifiedName): GirClass | null;
+    /**
+     * Resolves an interface by qualified name.
+     * @example repo.resolveInterface("Gio.ListModel" as QualifiedName)
+     */
+    resolveInterface(qualifiedName: QualifiedName): GirInterface | null;
+    /**
+     * Resolves a record (boxed type) by qualified name.
+     * @example repo.resolveRecord("Gdk.Rectangle" as QualifiedName)
+     */
+    resolveRecord(qualifiedName: QualifiedName): GirRecord | null;
+    /**
+     * Resolves an enumeration by qualified name.
+     * @example repo.resolveEnum("Gtk.Orientation" as QualifiedName)
+     */
+    resolveEnum(qualifiedName: QualifiedName): GirEnumeration | null;
+    /**
+     * Resolves a bitfield (flags) by qualified name.
+     * @example repo.resolveFlags("Gdk.ModifierType" as QualifiedName)
+     */
+    resolveFlags(qualifiedName: QualifiedName): GirEnumeration | null;
+    /**
+     * Resolves a callback type by qualified name.
+     * @example repo.resolveCallback("Gio.AsyncReadyCallback" as QualifiedName)
+     */
+    resolveCallback(qualifiedName: QualifiedName): GirCallback | null;
+    /**
+     * Resolves a constant by qualified name.
+     * @example repo.resolveConstant("Gtk.MAJOR_VERSION" as QualifiedName)
+     */
+    resolveConstant(qualifiedName: QualifiedName): GirConstant | null;
+    /**
+     * Resolves a standalone function by qualified name.
+     * @example repo.resolveFunction("Gtk.init" as QualifiedName)
+     */
+    resolveFunction(qualifiedName: QualifiedName): GirFunction | null;
+    /**
+     * Gets the kind of a type (class, interface, record, enum, flags, callback).
+     * Returns null for intrinsic types or unknown types.
+     */
+    getTypeKind(qualifiedName: QualifiedName): TypeKind | null;
+    /**
+     * Gets the full inheritance chain for a class.
+     * Returns array from most derived to base.
+     *
+     * @example
+     * getInheritanceChain("Gtk.Button" as QualifiedName)
+     * // ["Gtk.Button", "Gtk.Widget", "GObject.InitiallyUnowned", "GObject.Object"]
+     */
+    getInheritanceChain(qualifiedName: QualifiedName): QualifiedName[];
+    /**
+     * Gets all interfaces implemented by a class (including inherited).
+     */
+    getImplementedInterfaces(qualifiedName: QualifiedName): QualifiedName[];
+    /**
+     * Gets all classes that derive from a given class.
+     */
+    getDerivedClasses(qualifiedName: QualifiedName): QualifiedName[];
+    /**
+     * Gets all classes that implement a given interface.
+     */
+    getImplementors(interfaceName: QualifiedName): QualifiedName[];
+    /**
+     * Checks if a type is a GObject (class with GType).
+     */
+    isGObject(qualifiedName: QualifiedName): boolean;
+    /**
+     * Checks if a type is a boxed type (record with GType).
+     */
+    isBoxed(qualifiedName: QualifiedName): boolean;
+    /**
+     * Checks if a type is a primitive (intrinsic).
+     */
+    isPrimitive(typeName: string): boolean;
+    /**
+     * Finds all classes matching a predicate across all namespaces.
+     */
+    findClasses(predicate: (cls: GirClass) => boolean): GirClass[];
+    /**
+     * Finds all interfaces matching a predicate across all namespaces.
+     */
+    findInterfaces(predicate: (iface: GirInterface) => boolean): GirInterface[];
+    /**
+     * Finds all records matching a predicate across all namespaces.
+     */
+    findRecords(predicate: (record: GirRecord) => boolean): GirRecord[];
+    private ensureResolved;
+}

package/dist/repository.js

@@ -0,0 +1,322 @@
+/**
+ * GIR Repository - Central entry point for GIR data.
+ *
+ * Loads, normalizes, and provides query access to GIR namespaces.
+ * All type references are normalized to fully qualified names.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { normalizeNamespace } from "./internal/normalizer.js";
+import { RawGirParser } from "./internal/parser.js";
+import { isIntrinsicType } from "./intrinsics.js";
+import { parseQualifiedName, } from "./types.js";
+/**
+ * Central repository for GIR data.
+ *
+ * Loads, normalizes, and provides query access to GIR namespaces.
+ * All type references are normalized to fully qualified names.
+ *
+ * @example
+ * ```typescript
+ * const repo = new GirRepository();
+ * await repo.loadFromDirectory("./girs");
+ * repo.resolve();
+ *
+ * const gtkNs = repo.getNamespace("Gtk");
+ * const buttonClass = repo.resolveClass("Gtk.Button");
+ * const chain = buttonClass.getInheritanceChain();
+ * // ["Gtk.Button", "Gtk.Widget", "GObject.InitiallyUnowned", "GObject.Object"]
+ * ```
+ */
+export class GirRepository {
+    rawNamespaces = new Map();
+    normalizedNamespaces = new Map();
+    parser = new RawGirParser();
+    resolved = false;
+    /**
+     * Loads a single GIR file from XML content.
+     */
+    loadFromXml(xml) {
+        const raw = this.parser.parse(xml);
+        this.rawNamespaces.set(raw.name, raw);
+        this.resolved = false;
+    }
+    /**
+     * Loads a GIR file from disk.
+     */
+    async loadFromFile(path) {
+        const xml = await readFile(path, "utf-8");
+        this.loadFromXml(xml);
+    }
+    /**
+     * Loads all .gir files from a directory.
+     */
+    async loadFromDirectory(dirPath) {
+        const files = await readdir(dirPath);
+        const girFiles = files.filter((f) => f.endsWith(".gir"));
+        await Promise.all(girFiles.map((file) => this.loadFromFile(join(dirPath, file))));
+    }
+    /**
+     * After loading all raw GIR files, normalize and resolve all references.
+     * This must be called after loading and before querying.
+     */
+    resolve() {
+        if (this.resolved)
+            return;
+        const ctx = {
+            rawNamespaces: this.rawNamespaces,
+        };
+        for (const [name, raw] of this.rawNamespaces) {
+            const normalized = normalizeNamespace(raw, ctx);
+            this.normalizedNamespaces.set(name, normalized);
+        }
+        for (const ns of this.normalizedNamespaces.values()) {
+            for (const cls of ns.classes.values()) {
+                cls._setRepository(this);
+            }
+            for (const iface of ns.interfaces.values()) {
+                iface._setRepository(this);
+            }
+        }
+        this.resolved = true;
+    }
+    /**
+     * Gets all loaded namespace names.
+     */
+    getNamespaceNames() {
+        this.ensureResolved();
+        return [...this.normalizedNamespaces.keys()];
+    }
+    /**
+     * Gets a normalized namespace by name.
+     */
+    getNamespace(name) {
+        this.ensureResolved();
+        return this.normalizedNamespaces.get(name) ?? null;
+    }
+    /**
+     * Gets all normalized namespaces.
+     */
+    getAllNamespaces() {
+        this.ensureResolved();
+        return this.normalizedNamespaces;
+    }
+    /**
+     * Resolves a class by qualified name.
+     * @example repo.resolveClass("Gtk.Button" as QualifiedName)
+     */
+    resolveClass(qualifiedName) {
+        this.ensureResolved();
+        const { namespace, name } = parseQualifiedName(qualifiedName);
+        return this.normalizedNamespaces.get(namespace)?.classes.get(name) ?? null;
+    }
+    /**
+     * Resolves an interface by qualified name.
+     * @example repo.resolveInterface("Gio.ListModel" as QualifiedName)
+     */
+    resolveInterface(qualifiedName) {
+        this.ensureResolved();
+        const { namespace, name } = parseQualifiedName(qualifiedName);
+        return this.normalizedNamespaces.get(namespace)?.interfaces.get(name) ?? null;
+    }
+    /**
+     * Resolves a record (boxed type) by qualified name.
+     * @example repo.resolveRecord("Gdk.Rectangle" as QualifiedName)
+     */
+    resolveRecord(qualifiedName) {
+        this.ensureResolved();
+        const { namespace, name } = parseQualifiedName(qualifiedName);
+        return this.normalizedNamespaces.get(namespace)?.records.get(name) ?? null;
+    }
+    /**
+     * Resolves an enumeration by qualified name.
+     * @example repo.resolveEnum("Gtk.Orientation" as QualifiedName)
+     */
+    resolveEnum(qualifiedName) {
+        this.ensureResolved();
+        const { namespace, name } = parseQualifiedName(qualifiedName);
+        return this.normalizedNamespaces.get(namespace)?.enumerations.get(name) ?? null;
+    }
+    /**
+     * Resolves a bitfield (flags) by qualified name.
+     * @example repo.resolveFlags("Gdk.ModifierType" as QualifiedName)
+     */
+    resolveFlags(qualifiedName) {
+        this.ensureResolved();
+        const { namespace, name } = parseQualifiedName(qualifiedName);
+        return this.normalizedNamespaces.get(namespace)?.bitfields.get(name) ?? null;
+    }
+    /**
+     * Resolves a callback type by qualified name.
+     * @example repo.resolveCallback("Gio.AsyncReadyCallback" as QualifiedName)
+     */
+    resolveCallback(qualifiedName) {
+        this.ensureResolved();
+        const { namespace, name } = parseQualifiedName(qualifiedName);
+        return this.normalizedNamespaces.get(namespace)?.callbacks.get(name) ?? null;
+    }
+    /**
+     * Resolves a constant by qualified name.
+     * @example repo.resolveConstant("Gtk.MAJOR_VERSION" as QualifiedName)
+     */
+    resolveConstant(qualifiedName) {
+        this.ensureResolved();
+        const { namespace, name } = parseQualifiedName(qualifiedName);
+        return this.normalizedNamespaces.get(namespace)?.constants.get(name) ?? null;
+    }
+    /**
+     * Resolves a standalone function by qualified name.
+     * @example repo.resolveFunction("Gtk.init" as QualifiedName)
+     */
+    resolveFunction(qualifiedName) {
+        this.ensureResolved();
+        const { namespace, name } = parseQualifiedName(qualifiedName);
+        return this.normalizedNamespaces.get(namespace)?.functions.get(name) ?? null;
+    }
+    /**
+     * Gets the kind of a type (class, interface, record, enum, flags, callback).
+     * Returns null for intrinsic types or unknown types.
+     */
+    getTypeKind(qualifiedName) {
+        this.ensureResolved();
+        if (isIntrinsicType(qualifiedName)) {
+            return null;
+        }
+        const { namespace, name } = parseQualifiedName(qualifiedName);
+        const ns = this.normalizedNamespaces.get(namespace);
+        if (!ns)
+            return null;
+        if (ns.classes.has(name))
+            return "class";
+        if (ns.interfaces.has(name))
+            return "interface";
+        if (ns.records.has(name))
+            return "record";
+        if (ns.enumerations.has(name))
+            return "enum";
+        if (ns.bitfields.has(name))
+            return "flags";
+        if (ns.callbacks.has(name))
+            return "callback";
+        return null;
+    }
+    /**
+     * Gets the full inheritance chain for a class.
+     * Returns array from most derived to base.
+     *
+     * @example
+     * getInheritanceChain("Gtk.Button" as QualifiedName)
+     * // ["Gtk.Button", "Gtk.Widget", "GObject.InitiallyUnowned", "GObject.Object"]
+     */
+    getInheritanceChain(qualifiedName) {
+        const cls = this.resolveClass(qualifiedName);
+        return cls?.getInheritanceChain() ?? [];
+    }
+    /**
+     * Gets all interfaces implemented by a class (including inherited).
+     */
+    getImplementedInterfaces(qualifiedName) {
+        const cls = this.resolveClass(qualifiedName);
+        return cls?.getAllImplementedInterfaces() ?? [];
+    }
+    /**
+     * Gets all classes that derive from a given class.
+     */
+    getDerivedClasses(qualifiedName) {
+        this.ensureResolved();
+        const derived = [];
+        for (const ns of this.normalizedNamespaces.values()) {
+            for (const cls of ns.classes.values()) {
+                if (cls.qualifiedName !== qualifiedName && cls.isSubclassOf(qualifiedName)) {
+                    derived.push(cls.qualifiedName);
+                }
+            }
+        }
+        return derived;
+    }
+    /**
+     * Gets all classes that implement a given interface.
+     */
+    getImplementors(interfaceName) {
+        this.ensureResolved();
+        const implementors = [];
+        for (const ns of this.normalizedNamespaces.values()) {
+            for (const cls of ns.classes.values()) {
+                if (cls.implementsInterface(interfaceName)) {
+                    implementors.push(cls.qualifiedName);
+                }
+            }
+        }
+        return implementors;
+    }
+    /**
+     * Checks if a type is a GObject (class with GType).
+     */
+    isGObject(qualifiedName) {
+        const cls = this.resolveClass(qualifiedName);
+        return cls?.hasGType() ?? false;
+    }
+    /**
+     * Checks if a type is a boxed type (record with GType).
+     */
+    isBoxed(qualifiedName) {
+        const record = this.resolveRecord(qualifiedName);
+        return record?.isBoxed() ?? false;
+    }
+    /**
+     * Checks if a type is a primitive (intrinsic).
+     */
+    isPrimitive(typeName) {
+        return isIntrinsicType(typeName);
+    }
+    /**
+     * Finds all classes matching a predicate across all namespaces.
+     */
+    findClasses(predicate) {
+        this.ensureResolved();
+        const results = [];
+        for (const ns of this.normalizedNamespaces.values()) {
+            for (const cls of ns.classes.values()) {
+                if (predicate(cls)) {
+                    results.push(cls);
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Finds all interfaces matching a predicate across all namespaces.
+     */
+    findInterfaces(predicate) {
+        this.ensureResolved();
+        const results = [];
+        for (const ns of this.normalizedNamespaces.values()) {
+            for (const iface of ns.interfaces.values()) {
+                if (predicate(iface)) {
+                    results.push(iface);
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Finds all records matching a predicate across all namespaces.
+     */
+    findRecords(predicate) {
+        this.ensureResolved();
+        const results = [];
+        for (const ns of this.normalizedNamespaces.values()) {
+            for (const record of ns.records.values()) {
+                if (predicate(record)) {
+                    results.push(record);
+                }
+            }
+        }
+        return results;
+    }
+    ensureResolved() {
+        if (!this.resolved) {
+            throw new Error("GirRepository.resolve() must be called before querying. Call resolve() after loading all GIR files.");
+        }
+    }
+}