@gtkx/gir 0.10.5 → 0.11.0

package/dist/index.d.ts

@@ -1,5 +1,27 @@
-export * from "./class-names.js";
-export * from "./doc-sanitizer.js";
-export * from "./naming.js";
-export * from "./parser.js";
-export * from "./types.js";
+/**
+ * @gtkx/gir - GObject Introspection Repository
+ *
+ * Pure GIR data layer with normalized types and a queryable API.
+ * All type references use fully qualified names (Namespace.TypeName).
+ *
+ * @example
+ * ```typescript
+ * import { GirRepository } from "@gtkx/gir";
+ *
+ * const repo = new GirRepository();
+ * await repo.loadFromDirectory("./girs");
+ * repo.resolve();
+ *
+ * const button = repo.resolveClass("Gtk.Button" as QualifiedName);
+ * button.isSubclassOf("Gtk.Widget" as QualifiedName); // true
+ * button.getInheritanceChain();
+ * // ["Gtk.Button", "Gtk.Widget", "GObject.InitiallyUnowned", "GObject.Object"]
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { INTRINSIC_TYPES, isIntrinsicType, isNumericType, isStringType, isVoidType, NUMERIC_TYPES, STRING_TYPES, VOID_TYPES, } from "./intrinsics.js";
+export { GirRepository } from "./repository.js";
+export type { ContainerType, QualifiedName, TypeKind, } from "./types.js";
+export { GirCallback, GirClass, GirConstant, GirConstructor, GirEnumeration, GirEnumerationMember, GirField, GirFunction, GirInterface, GirMethod, GirNamespace, GirParameter, GirProperty, GirRecord, GirSignal, GirType, parseQualifiedName, qualifiedName, } from "./types.js";
+export { toCamelCase, toPascalCase } from "./utils.js";

package/dist/index.js

@@ -1,5 +1,26 @@
-export * from "./class-names.js";
-export * from "./doc-sanitizer.js";
-export * from "./naming.js";
-export * from "./parser.js";
-export * from "./types.js";
+/**
+ * @gtkx/gir - GObject Introspection Repository
+ *
+ * Pure GIR data layer with normalized types and a queryable API.
+ * All type references use fully qualified names (Namespace.TypeName).
+ *
+ * @example
+ * ```typescript
+ * import { GirRepository } from "@gtkx/gir";
+ *
+ * const repo = new GirRepository();
+ * await repo.loadFromDirectory("./girs");
+ * repo.resolve();
+ *
+ * const button = repo.resolveClass("Gtk.Button" as QualifiedName);
+ * button.isSubclassOf("Gtk.Widget" as QualifiedName); // true
+ * button.getInheritanceChain();
+ * // ["Gtk.Button", "Gtk.Widget", "GObject.InitiallyUnowned", "GObject.Object"]
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { INTRINSIC_TYPES, isIntrinsicType, isNumericType, isStringType, isVoidType, NUMERIC_TYPES, STRING_TYPES, VOID_TYPES, } from "./intrinsics.js";
+export { GirRepository } from "./repository.js";
+export { GirCallback, GirClass, GirConstant, GirConstructor, GirEnumeration, GirEnumerationMember, GirField, GirFunction, GirInterface, GirMethod, GirNamespace, GirParameter, GirProperty, GirRecord, GirSignal, GirType, parseQualifiedName, qualifiedName, } from "./types.js";
+export { toCamelCase, toPascalCase } from "./utils.js";

package/dist/internal/normalizer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Normalizer that converts raw GIR types to normalized types.
+ *
+ * The key job is to qualify all type references with their namespace,
+ * except for intrinsic types which remain unqualified.
+ *
+ * @internal
+ */
+import { GirNamespace } from "../types.js";
+import type { RawNamespace } from "./raw-types.js";
+/**
+ * Context for normalization - provides access to all loaded namespaces
+ * for resolving cross-namespace references.
+ */
+export type NormalizerContext = {
+    /** All raw namespaces that have been loaded */
+    rawNamespaces: Map<string, RawNamespace>;
+};
+/**
+ * Normalizes a raw namespace into a normalized namespace.
+ */
+export declare const normalizeNamespace: (raw: RawNamespace, ctx: NormalizerContext) => GirNamespace;

package/dist/internal/normalizer.js

@@ -0,0 +1,398 @@
+/**
+ * Normalizer that converts raw GIR types to normalized types.
+ *
+ * The key job is to qualify all type references with their namespace,
+ * except for intrinsic types which remain unqualified.
+ *
+ * @internal
+ */
+import { isIntrinsicType } from "../intrinsics.js";
+import { GirCallback, GirClass, GirConstant, GirConstructor, GirEnumeration, GirEnumerationMember, GirField, GirFunction, GirInterface, GirMethod, GirNamespace, GirParameter, GirProperty, GirRecord, GirSignal, GirType, qualifiedName, } from "../types.js";
+/**
+ * Normalizes a raw namespace into a normalized namespace.
+ */
+export const normalizeNamespace = (raw, ctx) => {
+    const nsName = raw.name;
+    const classes = new Map();
+    const interfaces = new Map();
+    const records = new Map();
+    const enumerations = new Map();
+    const bitfields = new Map();
+    const callbacks = new Map();
+    const functions = new Map();
+    const constants = new Map();
+    for (const rawClass of raw.classes) {
+        const normalized = normalizeClass(rawClass, nsName, ctx);
+        classes.set(normalized.name, normalized);
+    }
+    for (const rawInterface of raw.interfaces) {
+        const normalized = normalizeInterface(rawInterface, nsName, ctx);
+        interfaces.set(normalized.name, normalized);
+    }
+    for (const rawRecord of raw.records) {
+        const normalized = normalizeRecord(rawRecord, nsName, ctx);
+        records.set(normalized.name, normalized);
+    }
+    for (const rawEnum of raw.enumerations) {
+        const normalized = normalizeEnumeration(rawEnum, nsName);
+        enumerations.set(normalized.name, normalized);
+    }
+    for (const rawBitfield of raw.bitfields) {
+        const normalized = normalizeEnumeration(rawBitfield, nsName);
+        bitfields.set(normalized.name, normalized);
+    }
+    for (const rawCallback of raw.callbacks) {
+        const normalized = normalizeCallback(rawCallback, nsName, ctx);
+        callbacks.set(normalized.name, normalized);
+    }
+    for (const rawFunction of raw.functions) {
+        const normalized = normalizeFunction(rawFunction, nsName, ctx);
+        functions.set(normalized.name, normalized);
+    }
+    for (const rawConstant of raw.constants) {
+        const normalized = normalizeConstant(rawConstant, nsName, ctx);
+        constants.set(normalized.name, normalized);
+    }
+    return new GirNamespace({
+        name: raw.name,
+        version: raw.version,
+        sharedLibrary: raw.sharedLibrary,
+        cPrefix: raw.cPrefix,
+        classes,
+        interfaces,
+        records,
+        enumerations,
+        bitfields,
+        callbacks,
+        functions,
+        constants,
+        doc: raw.doc,
+    });
+};
+/**
+ * Normalizes a type reference, qualifying it with its namespace if not intrinsic.
+ */
+const normalizeTypeName = (typeName, currentNamespace, ctx) => {
+    if (isIntrinsicType(typeName)) {
+        return typeName;
+    }
+    if (typeName.includes(".")) {
+        return typeName;
+    }
+    const currentNs = ctx.rawNamespaces.get(currentNamespace);
+    if (currentNs && typeExistsInNamespace(typeName, currentNs)) {
+        return qualifiedName(currentNamespace, typeName);
+    }
+    for (const [nsName, ns] of ctx.rawNamespaces) {
+        if (nsName !== currentNamespace && typeExistsInNamespace(typeName, ns)) {
+            return qualifiedName(nsName, typeName);
+        }
+    }
+    return qualifiedName(currentNamespace, typeName);
+};
+/**
+ * Checks if a type name exists in a namespace.
+ */
+const typeExistsInNamespace = (typeName, ns) => {
+    return (ns.classes.some((c) => c.name === typeName) ||
+        ns.interfaces.some((i) => i.name === typeName) ||
+        ns.records.some((r) => r.name === typeName) ||
+        ns.enumerations.some((e) => e.name === typeName) ||
+        ns.bitfields.some((b) => b.name === typeName) ||
+        ns.callbacks.some((c) => c.name === typeName));
+};
+const buildContainerTypeBase = (raw) => ({
+    cType: raw.cType,
+    containerType: raw.containerType,
+    transferOwnership: raw.transferOwnership,
+    nullable: raw.nullable ?? false,
+});
+/**
+ * Normalizes a raw type to a normalized type.
+ */
+const normalizeType = (raw, currentNamespace, ctx) => {
+    if (raw.containerType === "ghashtable") {
+        const typeParams = (raw.typeParameters ?? []).map((tp) => normalizeType(tp, currentNamespace, ctx));
+        return new GirType({
+            ...buildContainerTypeBase(raw),
+            name: qualifiedName("GLib", "HashTable"),
+            isArray: false,
+            elementType: typeParams[1] ?? null,
+            typeParameters: typeParams,
+        });
+    }
+    if (raw.containerType === "gptrarray" || raw.containerType === "garray") {
+        const typeParams = (raw.typeParameters ?? []).map((tp) => normalizeType(tp, currentNamespace, ctx));
+        const typeName = raw.containerType === "gptrarray" ? "PtrArray" : "Array";
+        return new GirType({
+            ...buildContainerTypeBase(raw),
+            name: qualifiedName("GLib", typeName),
+            isArray: true,
+            elementType: typeParams[0] ?? null,
+            typeParameters: typeParams,
+        });
+    }
+    if (raw.containerType === "glist" || raw.containerType === "gslist") {
+        const elementType = raw.elementType ? normalizeType(raw.elementType, currentNamespace, ctx) : null;
+        return new GirType({
+            ...buildContainerTypeBase(raw),
+            name: "array",
+            isArray: true,
+            elementType,
+            typeParameters: elementType ? [elementType] : [],
+        });
+    }
+    const isArray = raw.isArray === true || raw.name === "array";
+    if (isArray && raw.elementType) {
+        return new GirType({
+            name: "array",
+            cType: raw.cType,
+            isArray: true,
+            elementType: normalizeType(raw.elementType, currentNamespace, ctx),
+            transferOwnership: raw.transferOwnership,
+            nullable: raw.nullable ?? false,
+        });
+    }
+    if (isArray) {
+        return new GirType({
+            name: "array",
+            cType: raw.cType,
+            isArray: true,
+            elementType: null,
+            transferOwnership: raw.transferOwnership,
+            nullable: raw.nullable ?? false,
+        });
+    }
+    return new GirType({
+        name: normalizeTypeName(raw.name, currentNamespace, ctx),
+        cType: raw.cType,
+        isArray: false,
+        elementType: null,
+        transferOwnership: raw.transferOwnership,
+        nullable: raw.nullable ?? false,
+    });
+};
+/**
+ * Normalizes a raw class to a normalized class.
+ */
+const normalizeClass = (raw, currentNamespace, ctx) => {
+    const qn = qualifiedName(currentNamespace, raw.name);
+    let parent = null;
+    if (raw.parent) {
+        const normalizedParent = normalizeTypeName(raw.parent, currentNamespace, ctx);
+        if (typeof normalizedParent !== "string" || normalizedParent.includes(".")) {
+            parent = normalizedParent;
+        }
+    }
+    const implementsRefs = raw.implements.map((impl) => {
+        const normalized = normalizeTypeName(impl, currentNamespace, ctx);
+        return normalized;
+    });
+    return new GirClass({
+        name: raw.name,
+        qualifiedName: qn,
+        cType: raw.cType,
+        parent,
+        abstract: raw.abstract ?? false,
+        glibTypeName: raw.glibTypeName,
+        glibGetType: raw.glibGetType,
+        cSymbolPrefix: raw.cSymbolPrefix,
+        implements: implementsRefs,
+        methods: raw.methods.map((m) => normalizeMethod(m, currentNamespace, ctx)),
+        constructors: raw.constructors.map((c) => normalizeConstructor(c, currentNamespace, ctx)),
+        staticFunctions: raw.functions.map((f) => normalizeFunction(f, currentNamespace, ctx)),
+        properties: raw.properties.map((p) => normalizeProperty(p, currentNamespace, ctx)),
+        signals: raw.signals.map((s) => normalizeSignal(s, currentNamespace, ctx)),
+        doc: raw.doc,
+    });
+};
+/**
+ * Normalizes a raw interface to a normalized interface.
+ */
+const normalizeInterface = (raw, currentNamespace, ctx) => {
+    const qn = qualifiedName(currentNamespace, raw.name);
+    const prerequisites = raw.prerequisites.map((prereq) => {
+        const normalized = normalizeTypeName(prereq, currentNamespace, ctx);
+        return normalized;
+    });
+    return new GirInterface({
+        name: raw.name,
+        qualifiedName: qn,
+        cType: raw.cType,
+        glibTypeName: raw.glibTypeName,
+        prerequisites,
+        methods: raw.methods.map((m) => normalizeMethod(m, currentNamespace, ctx)),
+        properties: raw.properties.map((p) => normalizeProperty(p, currentNamespace, ctx)),
+        signals: raw.signals.map((s) => normalizeSignal(s, currentNamespace, ctx)),
+        doc: raw.doc,
+    });
+};
+/**
+ * Normalizes a raw record to a normalized record.
+ */
+const normalizeRecord = (raw, currentNamespace, ctx) => {
+    const qn = qualifiedName(currentNamespace, raw.name);
+    return new GirRecord({
+        name: raw.name,
+        qualifiedName: qn,
+        cType: raw.cType,
+        opaque: raw.opaque ?? false,
+        disguised: raw.disguised ?? false,
+        glibTypeName: raw.glibTypeName,
+        glibGetType: raw.glibGetType,
+        isGtypeStructFor: raw.isGtypeStructFor,
+        fields: raw.fields.map((f) => normalizeField(f, currentNamespace, ctx)),
+        methods: raw.methods.map((m) => normalizeMethod(m, currentNamespace, ctx)),
+        constructors: raw.constructors.map((c) => normalizeConstructor(c, currentNamespace, ctx)),
+        staticFunctions: raw.functions.map((f) => normalizeFunction(f, currentNamespace, ctx)),
+        doc: raw.doc,
+    });
+};
+/**
+ * Normalizes a raw enumeration to a normalized enumeration.
+ */
+const normalizeEnumeration = (raw, currentNamespace) => {
+    const qn = qualifiedName(currentNamespace, raw.name);
+    return new GirEnumeration({
+        name: raw.name,
+        qualifiedName: qn,
+        cType: raw.cType,
+        members: raw.members.map((m) => new GirEnumerationMember({
+            name: m.name,
+            value: m.value,
+            cIdentifier: m.cIdentifier,
+            doc: m.doc,
+        })),
+        doc: raw.doc,
+    });
+};
+/**
+ * Normalizes a raw callback to a normalized callback.
+ */
+const normalizeCallback = (raw, currentNamespace, ctx) => {
+    const qn = qualifiedName(currentNamespace, raw.name);
+    return new GirCallback({
+        name: raw.name,
+        qualifiedName: qn,
+        cType: raw.cType,
+        returnType: normalizeType(raw.returnType, currentNamespace, ctx),
+        parameters: raw.parameters.map((p) => normalizeParameter(p, currentNamespace, ctx)),
+        doc: raw.doc,
+    });
+};
+/**
+ * Normalizes a raw constant to a normalized constant.
+ */
+const normalizeConstant = (raw, currentNamespace, ctx) => {
+    const qn = qualifiedName(currentNamespace, raw.name);
+    return new GirConstant({
+        name: raw.name,
+        qualifiedName: qn,
+        cType: raw.cType,
+        value: raw.value,
+        type: normalizeType(raw.type, currentNamespace, ctx),
+        doc: raw.doc,
+    });
+};
+/**
+ * Normalizes a raw method to a normalized method.
+ */
+const normalizeMethod = (raw, currentNamespace, ctx) => {
+    return new GirMethod({
+        name: raw.name,
+        cIdentifier: raw.cIdentifier,
+        returnType: normalizeType(raw.returnType, currentNamespace, ctx),
+        parameters: raw.parameters.map((p) => normalizeParameter(p, currentNamespace, ctx)),
+        throws: raw.throws ?? false,
+        doc: raw.doc,
+        returnDoc: raw.returnDoc,
+        finishFunc: raw.finishFunc,
+    });
+};
+/**
+ * Normalizes a raw constructor to a normalized constructor.
+ */
+const normalizeConstructor = (raw, currentNamespace, ctx) => {
+    return new GirConstructor({
+        name: raw.name,
+        cIdentifier: raw.cIdentifier,
+        returnType: normalizeType(raw.returnType, currentNamespace, ctx),
+        parameters: raw.parameters.map((p) => normalizeParameter(p, currentNamespace, ctx)),
+        throws: raw.throws ?? false,
+        doc: raw.doc,
+        returnDoc: raw.returnDoc,
+    });
+};
+/**
+ * Normalizes a raw function to a normalized function.
+ */
+const normalizeFunction = (raw, currentNamespace, ctx) => {
+    return new GirFunction({
+        name: raw.name,
+        cIdentifier: raw.cIdentifier,
+        returnType: normalizeType(raw.returnType, currentNamespace, ctx),
+        parameters: raw.parameters.map((p) => normalizeParameter(p, currentNamespace, ctx)),
+        throws: raw.throws ?? false,
+        doc: raw.doc,
+        returnDoc: raw.returnDoc,
+    });
+};
+/**
+ * Normalizes a raw parameter to a normalized parameter.
+ */
+const normalizeParameter = (raw, currentNamespace, ctx) => {
+    return new GirParameter({
+        name: raw.name,
+        type: normalizeType(raw.type, currentNamespace, ctx),
+        direction: raw.direction ?? "in",
+        callerAllocates: raw.callerAllocates ?? false,
+        nullable: raw.nullable ?? false,
+        optional: raw.optional ?? false,
+        scope: raw.scope,
+        closure: raw.closure,
+        destroy: raw.destroy,
+        transferOwnership: raw.transferOwnership,
+        doc: raw.doc,
+    });
+};
+/**
+ * Normalizes a raw property to a normalized property.
+ */
+const normalizeProperty = (raw, currentNamespace, ctx) => {
+    return new GirProperty({
+        name: raw.name,
+        type: normalizeType(raw.type, currentNamespace, ctx),
+        readable: raw.readable ?? true,
+        writable: raw.writable ?? false,
+        constructOnly: raw.constructOnly ?? false,
+        hasDefault: raw.hasDefault ?? false,
+        getter: raw.getter,
+        setter: raw.setter,
+        doc: raw.doc,
+    });
+};
+/**
+ * Normalizes a raw signal to a normalized signal.
+ */
+const normalizeSignal = (raw, currentNamespace, ctx) => {
+    return new GirSignal({
+        name: raw.name,
+        when: raw.when ?? "last",
+        returnType: raw.returnType ? normalizeType(raw.returnType, currentNamespace, ctx) : null,
+        parameters: (raw.parameters ?? []).map((p) => normalizeParameter(p, currentNamespace, ctx)),
+        doc: raw.doc,
+    });
+};
+/**
+ * Normalizes a raw field to a normalized field.
+ */
+const normalizeField = (raw, currentNamespace, ctx) => {
+    return new GirField({
+        name: raw.name,
+        type: normalizeType(raw.type, currentNamespace, ctx),
+        writable: raw.writable ?? false,
+        readable: raw.readable ?? true,
+        private: raw.private ?? false,
+        doc: raw.doc,
+    });
+};

package/dist/internal/parser.d.ts

@@ -0,0 +1,42 @@
+/**
+ * GObject Introspection XML (GIR) parser.
+ *
+ * Parses GIR files to extract type information for GTK/GLib libraries.
+ * Outputs raw GIR types that are then normalized by the normalizer.
+ *
+ * @internal
+ */
+import type { RawNamespace } from "./raw-types.js";
+/**
+ * Parser for GObject Introspection XML (GIR) files.
+ *
+ * Converts GIR XML into raw TypeScript objects.
+ */
+export declare class RawGirParser {
+    private parser;
+    constructor();
+    /**
+     * Parses a GIR XML string into a raw namespace object.
+     */
+    parse(girXml: string): RawNamespace;
+    private parseCallbacks;
+    private parseClasses;
+    private parseImplements;
+    private parseInterfaces;
+    private parsePrerequisites;
+    private parseMethods;
+    private parseConstructors;
+    private parseFunctions;
+    private parseParameters;
+    private parseReturnType;
+    private parseType;
+    private extractTypeParameters;
+    private parseGLibContainerType;
+    private parseProperties;
+    private parseSignals;
+    private parseRecords;
+    private parseFields;
+    private parseEnumerations;
+    private parseEnumerationMembers;
+    private parseConstants;
+}