@gtkx/gir 0.20.0 → 0.21.0

package/src/repository.ts

@@ -1,259 +1,234 @@
+import { GirLoader } from "./internal/loader.js";
+import type { GirNamespaceIntermediate } from "./internal/normalizer.js";
+import { GirNormalizer } from "./internal/normalizer.js";
+import { GirParser } from "./internal/parser.js";
+import type { RawNamespace } from "./internal/raw-types.js";
+import { isIntrinsicType } from "./intrinsics.js";
+import type { GirAlias } from "./model/alias.js";
+import type { GirFunction } from "./model/callables.js";
+import type { GirCallback } from "./model/callback.js";
+import { GirClass } from "./model/class.js";
+import type { GirConstant } from "./model/constant.js";
+import type { GirEnumeration } from "./model/enumeration.js";
+import { GirInterface } from "./model/interface.js";
+import { GirNamespace } from "./model/namespace.js";
+import type { GirRecord } from "./model/record.js";
+import type { RepositoryLike, TypeKind } from "./model/repository-like.js";
+import type { GirType } from "./model/type.js";
+
 /**
- * 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.
+ * Options for loading a GIR repository.
  */
+export type RepositoryOptions = {
+    girPath: string[];
+};
 
-import { readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { type NormalizerContext, normalizeNamespace } from "./internal/normalizer.js";
-import { type ParserOptions, RawGirParser } from "./internal/parser.js";
-import type { RawNamespace } from "./internal/raw-types.js";
-import { isIntrinsicType } from "./intrinsics.js";
-import {
-    type GirAlias,
-    type GirCallback,
-    type GirClass,
-    type GirConstant,
-    type GirEnumeration,
-    type GirFunction,
-    type GirInterface,
-    type GirNamespace,
-    type GirRecord,
-    type GirType,
-    parseQualifiedName,
-    type QualifiedName,
-    type TypeKind,
-} from "./types.js";
+/**
+ * A dependency graph entry mapping namespace keys to their file paths
+ * and direct dependencies.
+ */
+export type DependencyGraph = Map<string, { filePath: string; dependencies: string[] }>;
 
 /**
- * Central repository for GIR data.
+ * Central registry for GIR data.
  *
- * Loads, normalizes, and provides query access to GIR namespaces.
- * All type references are normalized to fully qualified names.
+ * Loads, resolves, and provides query access to GIR namespaces.
+ * All type references use fully qualified names (`Namespace.TypeName`).
  *
  * @example
  * ```typescript
- * const repo = new GirRepository();
- * await repo.loadFromDirectory("./girs");
- * repo.resolve();
+ * const repo = await GirRepository.load(["Gtk-4.0", "Adw-1"], {
+ *     girPath: ["/usr/share/gir-1.0"]
+ * });
  *
- * const gtkNs = repo.getNamespace("Gtk");
- * const buttonClass = repo.resolveClass("Gtk.Button");
- * const chain = buttonClass.getInheritanceChain();
+ * const button = repo.resolveClass("Gtk.Button");
+ * button.isSubclassOf("Gtk.Widget"); // true
+ * button.getInheritanceChain();
  * // ["Gtk.Button", "Gtk.Widget", "GObject.InitiallyUnowned", "GObject.Object"]
  * ```
  */
-export type RepositoryOptions = ParserOptions;
-
-export class GirRepository {
-    private rawNamespaces = new Map<string, RawNamespace>();
-    private normalizedNamespaces = new Map<string, GirNamespace>();
-    private parser: RawGirParser;
-    private resolved = false;
+export class GirRepository implements RepositoryLike {
+    private readonly namespaces: Map<string, GirNamespace>;
 
-    constructor(options: RepositoryOptions = {}) {
-        this.parser = new RawGirParser(options);
+    private constructor(namespaces: Map<string, GirNamespace>) {
+        this.namespaces = namespaces;
     }
 
     /**
-     * Loads a single GIR file from XML content.
+     * Discovers all transitive dependencies for the given roots without
+     * performing a full parse. Returns namespace keys and their file paths.
+     *
+     * @param roots - Namespace keys to start from (e.g., `["Gtk-4.0", "Adw-1"]`)
+     * @param options - Search paths for GIR files
      */
-    loadFromXml(xml: string): void {
-        const raw = this.parser.parse(xml);
-        const existing = this.rawNamespaces.get(raw.name);
-        if (existing && this.compareVersions(existing.version, raw.version) >= 0) {
-            return;
-        }
-        this.rawNamespaces.set(raw.name, raw);
-        this.resolved = false;
+    static async discoverDependencies(roots: string[], options: RepositoryOptions): Promise<DependencyGraph> {
+        const loader = new GirLoader(options.girPath);
+        return loader.discoverDependencies(roots);
     }
 
     /**
-     * Loads a GIR file from disk.
+     * Loads GIR files for the given namespace roots and all their transitive
+     * dependencies, returning a fully resolved repository.
+     *
+     * @param roots - Namespace keys to load (e.g., `["Gtk-4.0", "Adw-1"]`)
+     * @param options - Search paths for GIR files
      */
-    async loadFromFile(path: string): Promise<void> {
-        const xml = await readFile(path, "utf-8");
-        this.loadFromXml(xml);
-    }
+    static async load(roots: string[], options: RepositoryOptions): Promise<GirRepository> {
+        const loader = new GirLoader(options.girPath);
+        const loaded = await loader.loadAll(roots);
 
-    /**
-     * Loads all .gir files from a directory.
-     */
-    async loadFromDirectory(dirPath: string): Promise<void> {
-        const files = await readdir(dirPath);
-        const girFiles = files.filter((f) => f.endsWith(".gir"));
+        const rawNamespaces = new Map<string, RawNamespace>();
+        for (const [name, { raw }] of loaded) {
+            rawNamespaces.set(name, raw);
+        }
 
-        await Promise.all(girFiles.map((file) => this.loadFromFile(join(dirPath, file))));
+        return GirRepository.buildFromRaw(rawNamespaces);
     }
 
     /**
-     * After loading all raw GIR files, normalize and resolve all references.
-     * This must be called after loading and before querying.
+     * Creates a repository from inline GIR XML strings.
+     * Useful for testing and scenarios where GIR data is already in memory.
      */
-    resolve(): void {
-        if (this.resolved) return;
-
-        const ctx: NormalizerContext = {
-            rawNamespaces: this.rawNamespaces,
-        };
+    static fromXml(xmlStrings: string[]): GirRepository {
+        const parser = new GirParser();
+        const rawNamespaces = new Map<string, RawNamespace>();
 
-        for (const [name, raw] of this.rawNamespaces) {
-            const normalized = normalizeNamespace(raw, ctx);
-            this.normalizedNamespaces.set(name, normalized);
+        for (const xml of xmlStrings) {
+            const raw = parser.parseNamespace(xml);
+            rawNamespaces.set(raw.name, raw);
         }
 
-        for (const ns of this.normalizedNamespaces.values()) {
-            for (const cls of ns.classes.values()) {
-                cls._setRepository(this);
+        return GirRepository.buildFromRaw(rawNamespaces);
+    }
+
+    private static buildFromRaw(rawNamespaces: Map<string, RawNamespace>): GirRepository {
+        const normalizer = new GirNormalizer();
+        const intermediates = normalizer.normalize(rawNamespaces);
+        return GirRepository.buildFromIntermediates(intermediates);
+    }
+
+    private static buildFromIntermediates(intermediates: Map<string, GirNamespaceIntermediate>): GirRepository {
+        const namespaceMap = new Map<string, GirNamespace>();
+        const repo = new GirRepository(namespaceMap);
+
+        for (const [nsName, data] of intermediates) {
+            const classes = new Map<string, GirClass>();
+            for (const [name, classData] of data.classes) {
+                classes.set(name, new GirClass(classData, repo));
             }
-            for (const iface of ns.interfaces.values()) {
-                iface._setRepository(this);
+
+            const interfaces = new Map<string, GirInterface>();
+            for (const [name, ifaceData] of data.interfaces) {
+                interfaces.set(name, new GirInterface(ifaceData, repo));
             }
+
+            namespaceMap.set(
+                nsName,
+                new GirNamespace({
+                    name: data.name,
+                    version: data.version,
+                    sharedLibrary: data.sharedLibrary,
+                    cPrefix: data.cPrefix,
+                    classes,
+                    interfaces,
+                    records: data.records,
+                    enumerations: data.enumerations,
+                    bitfields: data.bitfields,
+                    callbacks: data.callbacks,
+                    functions: data.functions,
+                    constants: data.constants,
+                    aliases: data.aliases,
+                    doc: data.doc,
+                }),
+            );
         }
 
-        this.resolved = true;
+        return repo;
     }
 
-    /**
-     * Gets all loaded namespace names.
-     */
+    /** Gets all loaded namespace names. */
     getNamespaceNames(): string[] {
-        this.ensureResolved();
-        return [...this.normalizedNamespaces.keys()];
+        return [...this.namespaces.keys()];
     }
 
-    /**
-     * Gets a normalized namespace by name.
-     */
+    /** Gets a namespace by name, or null if not loaded. */
     getNamespace(name: string): GirNamespace | null {
-        this.ensureResolved();
-        return this.normalizedNamespaces.get(name) ?? null;
+        return this.namespaces.get(name) ?? null;
     }
 
-    /**
-     * Gets all normalized namespaces.
-     */
+    /** Gets all loaded namespaces. */
     getAllNamespaces(): Map<string, GirNamespace> {
-        this.ensureResolved();
-        return this.normalizedNamespaces;
+        return this.namespaces;
     }
 
-    /**
-     * Resolves a class by qualified name.
-     * @example repo.resolveClass("Gtk.Button" as QualifiedName)
-     */
-    resolveClass(qualifiedName: QualifiedName): GirClass | null {
-        this.ensureResolved();
-        const { namespace, name } = parseQualifiedName(qualifiedName);
-        return this.normalizedNamespaces.get(namespace)?.classes.get(name) ?? null;
+    /** Resolves a class by qualified name (e.g., `"Gtk.Button"`). */
+    resolveClass(qualifiedName: string): GirClass | null {
+        const { namespace, name } = splitQualifiedName(qualifiedName);
+        return this.namespaces.get(namespace)?.classes.get(name) ?? null;
     }
 
-    /**
-     * Resolves an interface by qualified name.
-     * @example repo.resolveInterface("Gio.ListModel" as QualifiedName)
-     */
-    resolveInterface(qualifiedName: QualifiedName): GirInterface | null {
-        this.ensureResolved();
-        const { namespace, name } = parseQualifiedName(qualifiedName);
-        return this.normalizedNamespaces.get(namespace)?.interfaces.get(name) ?? null;
+    /** Resolves an interface by qualified name (e.g., `"Gio.ListModel"`). */
+    resolveInterface(qualifiedName: string): GirInterface | null {
+        const { namespace, name } = splitQualifiedName(qualifiedName);
+        return this.namespaces.get(namespace)?.interfaces.get(name) ?? null;
     }
 
-    /**
-     * Resolves a record (boxed type) by qualified name.
-     * @example repo.resolveRecord("Gdk.Rectangle" as QualifiedName)
-     */
-    resolveRecord(qualifiedName: QualifiedName): GirRecord | null {
-        this.ensureResolved();
-        const { namespace, name } = parseQualifiedName(qualifiedName);
-        return this.normalizedNamespaces.get(namespace)?.records.get(name) ?? null;
+    /** Resolves a record by qualified name (e.g., `"Gdk.Rectangle"`). */
+    resolveRecord(qualifiedName: string): GirRecord | null {
+        const { namespace, name } = splitQualifiedName(qualifiedName);
+        return this.namespaces.get(namespace)?.records.get(name) ?? null;
     }
 
-    /**
-     * Resolves an enumeration by qualified name.
-     * @example repo.resolveEnum("Gtk.Orientation" as QualifiedName)
-     */
-    resolveEnum(qualifiedName: QualifiedName): GirEnumeration | null {
-        this.ensureResolved();
-        const { namespace, name } = parseQualifiedName(qualifiedName);
-        return this.normalizedNamespaces.get(namespace)?.enumerations.get(name) ?? null;
+    /** Resolves an enumeration by qualified name (e.g., `"Gtk.Orientation"`). */
+    resolveEnum(qualifiedName: string): GirEnumeration | null {
+        const { namespace, name } = splitQualifiedName(qualifiedName);
+        return this.namespaces.get(namespace)?.enumerations.get(name) ?? null;
     }
 
-    /**
-     * Resolves a bitfield (flags) by qualified name.
-     * @example repo.resolveFlags("Gdk.ModifierType" as QualifiedName)
-     */
-    resolveFlags(qualifiedName: QualifiedName): GirEnumeration | null {
-        this.ensureResolved();
-        const { namespace, name } = parseQualifiedName(qualifiedName);
-        return this.normalizedNamespaces.get(namespace)?.bitfields.get(name) ?? null;
+    /** Resolves a bitfield by qualified name (e.g., `"Gdk.ModifierType"`). */
+    resolveFlags(qualifiedName: string): GirEnumeration | null {
+        const { namespace, name } = splitQualifiedName(qualifiedName);
+        return this.namespaces.get(namespace)?.bitfields.get(name) ?? null;
     }
 
-    /**
-     * Resolves a callback type by qualified name.
-     * @example repo.resolveCallback("Gio.AsyncReadyCallback" as QualifiedName)
-     */
-    resolveCallback(qualifiedName: QualifiedName): GirCallback | null {
-        this.ensureResolved();
-        const { namespace, name } = parseQualifiedName(qualifiedName);
-        return this.normalizedNamespaces.get(namespace)?.callbacks.get(name) ?? null;
+    /** Resolves a callback by qualified name (e.g., `"Gio.AsyncReadyCallback"`). */
+    resolveCallback(qualifiedName: string): GirCallback | null {
+        const { namespace, name } = splitQualifiedName(qualifiedName);
+        return this.namespaces.get(namespace)?.callbacks.get(name) ?? null;
     }
 
-    /**
-     * Resolves a constant by qualified name.
-     * @example repo.resolveConstant("Gtk.MAJOR_VERSION" as QualifiedName)
-     */
-    resolveConstant(qualifiedName: QualifiedName): GirConstant | null {
-        this.ensureResolved();
-        const { namespace, name } = parseQualifiedName(qualifiedName);
-        return this.normalizedNamespaces.get(namespace)?.constants.get(name) ?? null;
+    /** Resolves a constant by qualified name (e.g., `"Gtk.MAJOR_VERSION"`). */
+    resolveConstant(qualifiedName: string): GirConstant | null {
+        const { namespace, name } = splitQualifiedName(qualifiedName);
+        return this.namespaces.get(namespace)?.constants.get(name) ?? null;
     }
 
-    /**
-     * Resolves a standalone function by qualified name.
-     * @example repo.resolveFunction("Gtk.init" as QualifiedName)
-     */
-    resolveFunction(qualifiedName: QualifiedName): GirFunction | null {
-        this.ensureResolved();
-        const { namespace, name } = parseQualifiedName(qualifiedName);
-        return this.normalizedNamespaces.get(namespace)?.functions.get(name) ?? null;
+    /** Resolves a standalone function by qualified name (e.g., `"Gtk.init"`). */
+    resolveFunction(qualifiedName: string): GirFunction | null {
+        const { namespace, name } = splitQualifiedName(qualifiedName);
+        return this.namespaces.get(namespace)?.functions.get(name) ?? null;
     }
 
-    /**
-     * Resolves an alias by qualified name.
-     * @example repo.resolveAlias("Pango.LayoutRun" as QualifiedName)
-     */
-    resolveAlias(qualifiedName: QualifiedName): GirAlias | null {
-        this.ensureResolved();
-        const { namespace, name } = parseQualifiedName(qualifiedName);
-        return this.normalizedNamespaces.get(namespace)?.aliases.get(name) ?? null;
+    /** Resolves an alias by qualified name (e.g., `"Pango.LayoutRun"`). */
+    resolveAlias(qualifiedName: string): GirAlias | null {
+        const { namespace, name } = splitQualifiedName(qualifiedName);
+        return this.namespaces.get(namespace)?.aliases.get(name) ?? null;
     }
 
-    /**
-     * Resolves a type name through aliases to get the target type.
-     * If the type is an alias, returns the target type.
-     * If not an alias, returns null.
-     * @example repo.resolveTypeAlias("Pango.LayoutRun" as QualifiedName) // returns GirType pointing to Pango.GlyphItem
-     */
-    resolveTypeAlias(qualifiedName: QualifiedName): GirType | null {
-        const alias = this.resolveAlias(qualifiedName);
-        return alias?.targetType ?? null;
+    /** Resolves a type alias to its target type, or null if not an alias. */
+    resolveTypeAlias(qualifiedName: string): GirType | null {
+        return this.resolveAlias(qualifiedName)?.targetType ?? 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 {
-        this.ensureResolved();
-
-        if (isIntrinsicType(qualifiedName)) {
-            return null;
-        }
+    getTypeKind(qualifiedName: string): TypeKind | null {
+        if (isIntrinsicType(qualifiedName)) return null;
 
-        const { namespace, name } = parseQualifiedName(qualifiedName);
-        const ns = this.normalizedNamespaces.get(namespace);
+        const { namespace, name } = splitQualifiedName(qualifiedName);
+        const ns = this.namespaces.get(namespace);
         if (!ns) return null;
 
         if (ns.classes.has(name)) return "class";
@@ -266,156 +241,95 @@ export class GirRepository {
         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: QualifiedName): QualifiedName[] {
-        const cls = this.resolveClass(qualifiedName);
-        return cls?.getInheritanceChain() ?? [];
+    /** Gets the full inheritance chain for a class (most derived to base). */
+    getInheritanceChain(qualifiedName: string): string[] {
+        return this.resolveClass(qualifiedName)?.getInheritanceChain() ?? [];
     }
 
-    /**
-     * Gets all interfaces implemented by a class (including inherited).
-     */
-    getImplementedInterfaces(qualifiedName: QualifiedName): QualifiedName[] {
-        const cls = this.resolveClass(qualifiedName);
-        return cls?.getAllImplementedInterfaces() ?? [];
+    /** Gets all interfaces implemented by a class (including inherited). */
+    getImplementedInterfaces(qualifiedName: string): string[] {
+        return this.resolveClass(qualifiedName)?.getAllImplementedInterfaces() ?? [];
     }
 
-    /**
-     * Gets all classes that derive from a given class.
-     */
-    getDerivedClasses(qualifiedName: QualifiedName): QualifiedName[] {
-        this.ensureResolved();
-        const derived: QualifiedName[] = [];
-
-        for (const ns of this.normalizedNamespaces.values()) {
+    /** Gets all classes that derive from a given class. */
+    getDerivedClasses(qualifiedName: string): string[] {
+        const derived: string[] = [];
+        for (const ns of this.namespaces.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: QualifiedName): QualifiedName[] {
-        this.ensureResolved();
-        const implementors: QualifiedName[] = [];
-
-        for (const ns of this.normalizedNamespaces.values()) {
+    /** Gets all classes that implement a given interface. */
+    getImplementors(interfaceName: string): string[] {
+        const implementors: string[] = [];
+        for (const ns of this.namespaces.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: QualifiedName): boolean {
-        const cls = this.resolveClass(qualifiedName);
-        return cls?.hasGType() ?? false;
+    /** Checks if a type is a GObject (class with GType). */
+    isGObject(qualifiedName: string): boolean {
+        return this.resolveClass(qualifiedName)?.hasGType() ?? false;
     }
 
-    /**
-     * Checks if a type is a boxed type (record with GType).
-     */
-    isBoxed(qualifiedName: QualifiedName): boolean {
-        const record = this.resolveRecord(qualifiedName);
-        return record?.isBoxed() ?? false;
+    /** Checks if a type is a boxed type (record with GType). */
+    isBoxed(qualifiedName: string): boolean {
+        return this.resolveRecord(qualifiedName)?.isBoxed() ?? false;
     }
 
-    /**
-     * Checks if a type is a primitive (intrinsic).
-     */
+    /** Checks if a type is a primitive (intrinsic). */
     isPrimitive(typeName: string): boolean {
         return isIntrinsicType(typeName);
     }
 
-    /**
-     * Finds all classes matching a predicate across all namespaces.
-     */
+    /** Finds all classes matching a predicate across all namespaces. */
     findClasses(predicate: (cls: GirClass) => boolean): GirClass[] {
-        this.ensureResolved();
         const results: GirClass[] = [];
-
-        for (const ns of this.normalizedNamespaces.values()) {
+        for (const ns of this.namespaces.values()) {
             for (const cls of ns.classes.values()) {
-                if (predicate(cls)) {
-                    results.push(cls);
-                }
+                if (predicate(cls)) results.push(cls);
             }
         }
-
         return results;
     }
 
-    /**
-     * Finds all interfaces matching a predicate across all namespaces.
-     */
+    /** Finds all interfaces matching a predicate across all namespaces. */
     findInterfaces(predicate: (iface: GirInterface) => boolean): GirInterface[] {
-        this.ensureResolved();
         const results: GirInterface[] = [];
-
-        for (const ns of this.normalizedNamespaces.values()) {
+        for (const ns of this.namespaces.values()) {
             for (const iface of ns.interfaces.values()) {
-                if (predicate(iface)) {
-                    results.push(iface);
-                }
+                if (predicate(iface)) results.push(iface);
             }
         }
-
         return results;
     }
 
-    /**
-     * Finds all records matching a predicate across all namespaces.
-     */
+    /** Finds all records matching a predicate across all namespaces. */
     findRecords(predicate: (record: GirRecord) => boolean): GirRecord[] {
-        this.ensureResolved();
         const results: GirRecord[] = [];
-
-        for (const ns of this.normalizedNamespaces.values()) {
+        for (const ns of this.namespaces.values()) {
             for (const record of ns.records.values()) {
-                if (predicate(record)) {
-                    results.push(record);
-                }
+                if (predicate(record)) results.push(record);
             }
         }
-
         return results;
     }
+}
 
-    private compareVersions(a: string, b: string): number {
-        const partsA = a.split(".").map(Number);
-        const partsB = b.split(".").map(Number);
-        const len = Math.max(partsA.length, partsB.length);
-        for (let i = 0; i < len; i++) {
-            const diff = (partsA[i] ?? 0) - (partsB[i] ?? 0);
-            if (diff !== 0) return diff;
-        }
-        return 0;
-    }
-
-    private ensureResolved(): void {
-        if (!this.resolved) {
-            throw new Error(
-                "GirRepository.resolve() must be called before querying. Call resolve() after loading all GIR files.",
-            );
-        }
-    }
+function splitQualifiedName(qn: string): { namespace: string; name: string } {
+    const dot = qn.indexOf(".");
+    return {
+        namespace: qn.slice(0, dot),
+        name: qn.slice(dot + 1),
+    };
 }