@gtkx/codegen 0.21.0 → 1.0.0-rc.1

package/src/gir/class.ts

@@ -1,54 +1,34 @@
-import { fieldFromNode, type GirField } from "./field.js";
 import { functionFromNode, type GirFunction } from "./function.js";
-import { attr, attrBool, childrenOf, GIR_CONSTRUCTOR_TAG, type RawNode } from "./parse.js";
+import { type GirSignal, parseCallable } from "./parameter.js";
+import { attr, attrBool, childrenOf, docOf, GIR_CONSTRUCTOR_TAG, nameAttr, type RawNode } from "./parse.js";
 import { type GirProperty, propertyFromNode } from "./property.js";
-import { type GirSignal, signalFromNode } from "./signal.js";
+import type { ParseContext } from "./type-id.js";
 
-/** A `<class>` or `<interface>` declaration. */
 export type GirClass = {
-    /** Local name inside the namespace (no prefix). */
-    readonly name: string;
-    readonly cType: string | undefined;
-    /** GIR `parent`, possibly cross-namespace (e.g. `"GObject.InitiallyUnowned"`). */
-    readonly parent: string | undefined;
-    /** GLib type name (e.g. `"GtkWidget"`). */
-    readonly glibTypeName: string | undefined;
-    /** C symbol that returns the GType integer (e.g. `"gtk_widget_get_type"`). */
-    readonly glibGetType: string | undefined;
-    /** Local record name that holds this class's vtable (`glib:type-struct`). */
-    readonly glibTypeStruct: string | undefined;
-    /** Glib ref/unref/etc. function names on fundamentals; not used for GObject subclasses. */
-    readonly glibRefFunc: string | undefined;
-    readonly glibUnrefFunc: string | undefined;
-    readonly glibSetValueFunc: string | undefined;
-    readonly glibGetValueFunc: string | undefined;
-    /** `glib:fundamental="1"` — a non-GObject fundamental type (e.g. `GdkEvent`, `GskRenderNode`). */
-    readonly fundamental: boolean;
-    readonly abstract: boolean;
-    readonly final: boolean;
-    readonly isInterface: boolean;
-    readonly introspectable: boolean;
-    /** Names of interfaces this class implements (cross-namespace possible). */
-    readonly implements: readonly string[];
-    /** Names of interfaces a `<interface>` requires (`<prerequisite>` elements). */
-    readonly prerequisites: readonly string[];
-    readonly methods: readonly GirFunction[];
-    readonly constructors: readonly GirFunction[];
-    readonly functions: readonly GirFunction[];
-    readonly virtualMethods: readonly GirFunction[];
-    readonly properties: readonly GirProperty[];
-    readonly signals: readonly GirSignal[];
-    readonly fields: readonly GirField[];
+    name: string;
+    doc: string | undefined;
+    cType: string | undefined;
+    parent: string | undefined;
+    glibTypeName: string | undefined;
+    glibGetType: string | undefined;
+    glibTypeStruct: string | undefined;
+    glibRefFunc: string | undefined;
+    glibUnrefFunc: string | undefined;
+    fundamental: boolean;
+    isInterface: boolean;
+    introspectable: boolean;
+    implements: string[];
+    prerequisites: string[];
+    methods: GirFunction[];
+    constructors: GirFunction[];
+    functions: GirFunction[];
+    properties: GirProperty[];
+    signals: GirSignal[];
 };
 
-/**
- * Builds a {@link GirClass} from a `<class>` or `<interface>` element.
- *
- * @param node - The XML element
- * @param isInterface - `true` when the source element was `<interface>`
- */
-export const classFromNode = (node: RawNode, isInterface: boolean): GirClass => ({
-    name: attr(node, "name") ?? "",
+export const classFromNode = (node: RawNode, isInterface: boolean, context: ParseContext): GirClass => ({
+    name: nameAttr(node),
+    doc: docOf(node),
     cType: attr(node, "c:type"),
     parent: attr(node, "parent"),
     glibTypeName: attr(node, "glib:type-name"),
@@ -56,24 +36,18 @@ export const classFromNode = (node: RawNode, isInterface: boolean): GirClass =>
     glibTypeStruct: attr(node, "glib:type-struct"),
     glibRefFunc: attr(node, "glib:ref-func"),
     glibUnrefFunc: attr(node, "glib:unref-func"),
-    glibSetValueFunc: attr(node, "glib:set-value-func"),
-    glibGetValueFunc: attr(node, "glib:get-value-func"),
     fundamental: attrBool(node, "glib:fundamental"),
-    abstract: attrBool(node, "abstract"),
-    final: attrBool(node, "final"),
     isInterface,
-    introspectable: attr(node, "introspectable") !== "0",
+    introspectable: attrBool(node, "introspectable", true),
     implements: childrenOf(node, "implements")
         .map((implement) => attr(implement, "name"))
         .filter((name): name is string => name !== undefined),
     prerequisites: childrenOf(node, "prerequisite")
         .map((prerequisite) => attr(prerequisite, "name"))
         .filter((name): name is string => name !== undefined),
-    methods: childrenOf(node, "method").map((method) => functionFromNode(method, "method")),
-    constructors: childrenOf(node, GIR_CONSTRUCTOR_TAG).map((ctor) => functionFromNode(ctor, "constructor")),
-    functions: childrenOf(node, "function").map((function_) => functionFromNode(function_, "function")),
-    virtualMethods: childrenOf(node, "virtual-method").map((vmethod) => functionFromNode(vmethod, "virtual-method")),
-    properties: childrenOf(node, "property").map(propertyFromNode),
-    signals: childrenOf(node, "glib:signal").map(signalFromNode),
-    fields: childrenOf(node, "field").map(fieldFromNode),
+    methods: childrenOf(node, "method").map((method) => functionFromNode(method, context)),
+    constructors: childrenOf(node, GIR_CONSTRUCTOR_TAG).map((ctor) => functionFromNode(ctor, context)),
+    functions: childrenOf(node, "function").map((function_) => functionFromNode(function_, context)),
+    properties: childrenOf(node, "property").map((property) => propertyFromNode(property, context)),
+    signals: childrenOf(node, "glib:signal").map((signal) => parseCallable(signal, context)),
 });

package/src/gir/enum.ts

@@ -1,55 +1,37 @@
-import { functionFromNode, type GirFunction } from "./function.js";
-import { attr, childrenOf, type RawNode } from "./parse.js";
+import { attr, attrBool, childrenOf, docOf, nameAttr, type RawNode } from "./parse.js";
 
-/** A single `<member>` of an `<enumeration>` or `<bitfield>`. */
 type EnumMember = {
-    /** GIR `name`, snake_case lowercase (e.g. `"fill"`). */
-    readonly name: string;
-    /** GIR `c:identifier`, SCREAMING_SNAKE_CASE (e.g. `"GTK_ALIGN_FILL"`). */
-    readonly cIdentifier: string | undefined;
-    /** Numeric value as a string; preserved verbatim from GIR. */
-    readonly value: string;
+    name: string;
+    doc: string | undefined;
+    value: string;
+    cIdentifier: string | undefined;
 };
 
-/** Discriminator for enums vs bitfields. */
-export type EnumKind = "enumeration" | "bitfield";
+type EnumKind = "enumeration" | "bitfield";
 
-/** An `<enumeration>` or `<bitfield>` declaration. */
 export type GirEnum = {
-    readonly kind: EnumKind;
-    /** Local name within the namespace (no namespace prefix). */
-    readonly name: string;
-    readonly cType: string | undefined;
-    /** GLib type name (e.g. `"GtkAlign"`); absent for unregistered enums. */
-    readonly glibTypeName: string | undefined;
-    /** GLib get-type C symbol; absent for unregistered enums. */
-    readonly glibGetType: string | undefined;
-    /** Optional `glib:error-domain` marker; presence flips emission to `createErrorDomain`. */
-    readonly errorDomain: string | undefined;
-    readonly introspectable: boolean;
-    readonly members: readonly EnumMember[];
-    /** Free functions nested inside the enum (e.g. error quark accessors). */
-    readonly functions: readonly GirFunction[];
+    kind: EnumKind;
+    name: string;
+    doc: string | undefined;
+    glibTypeName: string | undefined;
+    glibGetType: string | undefined;
+    errorDomain: string | undefined;
+    introspectable: boolean;
+    members: EnumMember[];
 };
 
-/**
- * Builds a {@link GirEnum} from an `<enumeration>` or `<bitfield>` element.
- *
- * @param node - The XML element
- * @param kind - `"enumeration"` or `"bitfield"`, matching the element name
- */
 export const enumFromNode = (node: RawNode, kind: EnumKind): GirEnum => ({
     kind,
-    name: attr(node, "name") ?? "",
-    cType: attr(node, "c:type"),
+    name: nameAttr(node),
+    doc: docOf(node),
     glibTypeName: attr(node, "glib:type-name"),
     glibGetType: attr(node, "glib:get-type"),
     errorDomain: attr(node, "glib:error-domain"),
-    introspectable: attr(node, "introspectable") !== "0",
+    introspectable: attrBool(node, "introspectable", true),
     members: childrenOf(node, "member").map((member) => ({
-        name: attr(member, "name") ?? "",
-        cIdentifier: attr(member, "c:identifier"),
+        name: nameAttr(member),
+        doc: docOf(member),
         value: attr(member, "value") ?? "0",
+        cIdentifier: attr(member, "c:identifier"),
     })),
-    functions: childrenOf(node, "function").map((function_) => functionFromNode(function_, "function")),
 });

package/src/gir/field.ts

@@ -1,40 +1,25 @@
-import { attr, attrBool, childOf, type RawNode } from "./parse.js";
-import { type GirTypeRef, typeRefFromSlot } from "./type-ref.js";
+import { attr, attrBool, childOf, docOf, intAttr, nameAttr, type RawNode } from "./parse.js";
+import type { ParseContext, TypeId } from "./type-id.js";
+import { typeRefFromNode } from "./type-ref.js";
 
-/**
- * A `<field>` inside a class, interface, record, or union.
- *
- * Vtable slots (fields holding `<callback>` children inside a
- * `glib:is-gtype-struct-for` record) keep `callback` populated; ordinary
- * data fields keep `type`. The two are mutually exclusive.
- */
 export type GirField = {
-    /** GIR field name, snake_case. */
-    readonly name: string;
-    /** Field type, or `undefined` when the field is a vtable callback slot. */
-    readonly type: GirTypeRef | undefined;
-    /** Inline callback for vtable slots; `undefined` for data fields. */
-    readonly callback: RawNode | undefined;
-    readonly readable: boolean;
-    readonly writable: boolean;
-    readonly private: boolean;
-    /** GIR `bits` attribute width when the field is a bitfield member. */
-    readonly bits: number | undefined;
+    name: string;
+    doc: string | undefined;
+    type: TypeId | undefined;
+    cType: string | undefined;
+    readable: boolean;
+    writable: boolean;
+    private: boolean;
+    bits: number | undefined;
 };
 
-/**
- * Builds a {@link GirField} from a `<field>` element.
- */
-export const fieldFromNode = (node: RawNode): GirField => {
-    const callback = childOf(node, "callback");
-    const bitsAttr = attr(node, "bits");
-    return {
-        name: attr(node, "name") ?? "",
-        type: callback === undefined ? typeRefFromSlot(node) : undefined,
-        callback,
-        readable: attrBool(node, "readable", true),
-        writable: attrBool(node, "writable", false),
-        private: attrBool(node, "private", false),
-        bits: bitsAttr === undefined ? undefined : Number.parseInt(bitsAttr, 10),
-    };
-};
+export const fieldFromNode = (node: RawNode, context: ParseContext): GirField => ({
+    name: nameAttr(node),
+    doc: docOf(node),
+    type: typeRefFromNode(node, context),
+    cType: attr(childOf(node, "type"), "c:type"),
+    readable: attrBool(node, "readable", true),
+    writable: attrBool(node, "writable", false),
+    private: attrBool(node, "private", false),
+    bits: intAttr(node, "bits"),
+});

package/src/gir/function.ts

@@ -1,67 +1,28 @@
-import { type GirParameter, type GirReturnValue, parameterFromNode, returnValueFromNode } from "./parameter.js";
-import { attr, attrBool, childOf, childrenOf, type RawNode } from "./parse.js";
+import { type GirParameter, type GirReturnValue, parameterFromNode, parseCallable } from "./parameter.js";
+import { attr, attrBool, childOf, type RawNode } from "./parse.js";
+import type { ParseContext } from "./type-id.js";
 
-/**
- * Whether this callable is a free function, a static method on a type, an
- * instance method, a constructor, or a virtual method.
- *
- * The kind controls call-site shape in the writers: instance methods pass
- * `self` as the first FFI argument, constructors return a fresh native
- * handle, etc.
- */
-export type FunctionKind = "function" | "method" | "constructor" | "virtual-method";
-
-/**
- * A callable declaration: `<function>`, `<method>`, `<constructor>`, or
- * `<virtual-method>`.
- */
 export type GirFunction = {
-    readonly kind: FunctionKind;
-    /** GIR `name`, snake_case (e.g. `"set_label"`). */
-    readonly name: string;
-    /** C symbol identifier passed to `t.fn(library, symbol, …)`. */
-    readonly cIdentifier: string | undefined;
-    /** `throws="1"` — appends an implicit `GError**` out-parameter. */
-    readonly throws: boolean;
-    /** `introspectable="0"` — the function is skipped in JS output. */
-    readonly introspectable: boolean;
-    /** Indicates the function is the preferred binding for the named method. */
-    readonly shadows: string | undefined;
-    /** Indicates a different function is the preferred binding (the shadower). */
-    readonly shadowedBy: string | undefined;
-    /** Marker that re-homes a namespace function onto a type method. */
-    readonly movedTo: string | undefined;
-    /** The instance parameter for methods; `undefined` otherwise. */
-    readonly instance: GirParameter | undefined;
-    /** Regular parameters (no instance and no implicit GError). */
-    readonly parameters: readonly GirParameter[];
-    readonly returnValue: GirReturnValue;
-    /** Linked invoker method when this is a `<virtual-method>`. */
-    readonly invoker: string | undefined;
+    name: string;
+    doc: string | undefined;
+    cIdentifier: string | undefined;
+    throws: boolean;
+    introspectable: boolean;
+    shadowedBy: string | undefined;
+    instance: GirParameter | undefined;
+    parameters: GirParameter[];
+    returnValue: GirReturnValue;
 };
 
-/**
- * Builds a {@link GirFunction} from a callable element.
- *
- * @param node - The XML element
- * @param kind - The callable kind matching the element name
- */
-export const functionFromNode = (node: RawNode, kind: FunctionKind): GirFunction => {
-    const parametersNode = childOf(node, "parameters");
-    const instanceNode = childOf(parametersNode, "instance-parameter");
-    const parameterNodes = childrenOf(parametersNode, "parameter");
+export const functionFromNode = (node: RawNode, context: ParseContext): GirFunction => {
+    const instanceNode = childOf(childOf(node, "parameters"), "instance-parameter");
     return {
-        kind,
+        ...parseCallable(node, context),
         name: attr(node, "shadows") ?? attr(node, "name") ?? "",
         cIdentifier: attr(node, "c:identifier"),
         throws: attrBool(node, "throws"),
-        introspectable: attr(node, "introspectable") !== "0",
-        shadows: attr(node, "shadows"),
+        introspectable: attrBool(node, "introspectable", true),
         shadowedBy: attr(node, "shadowed-by"),
-        movedTo: attr(node, "moved-to"),
-        instance: instanceNode === undefined ? undefined : parameterFromNode(instanceNode, true),
-        parameters: parameterNodes.map((parameter) => parameterFromNode(parameter, false)),
-        returnValue: returnValueFromNode(childOf(node, "return-value")),
-        invoker: attr(node, "invoker"),
+        instance: instanceNode === undefined ? undefined : parameterFromNode(instanceNode, context),
     };
 };

package/src/gir/gir-path.ts

@@ -0,0 +1,49 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { formatChildProcessError } from "@gtkx/utils";
+
+const SYSTEM_GIR_PATH = "/usr/share/gir-1.0";
+
+export const resolveGirPath = (configGirPath: string[] | undefined): string[] => {
+    const paths: string[] = [];
+
+    if (configGirPath) {
+        paths.push(...configGirPath);
+    }
+
+    const envPath = process.env.GTKX_GIR_PATH;
+    if (envPath) {
+        paths.push(...envPath.split(":").filter((path) => path.length > 0));
+    }
+
+    if (existsSync(SYSTEM_GIR_PATH)) {
+        paths.push(SYSTEM_GIR_PATH);
+    }
+
+    const pkgConfigPath = queryPkgConfigGirDir();
+    if (pkgConfigPath !== undefined && existsSync(pkgConfigPath)) {
+        paths.push(pkgConfigPath);
+    }
+
+    return [...new Set(paths)];
+};
+
+const queryPkgConfigGirDir = (): string | undefined => {
+    try {
+        const output = execFileSync("pkg-config", ["--variable=girdir", "gobject-introspection-1.0"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const trimmed = output.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+        const details = formatChildProcessError(error);
+        throw new Error(
+            `pkg-config failed querying gobject-introspection-1.0 girdir${details ? `:\n${details}` : ""}`,
+            {
+                cause: error,
+            },
+        );
+    }
+};

package/src/gir/libraries.ts

@@ -0,0 +1,77 @@
+import { readdirSync } from "node:fs";
+import type { Config } from "@gtkx/config";
+import { GIR_LIBRARY_PATTERN, LIBRARIES_WILDCARD } from "@gtkx/config/internal";
+import { sortStrings } from "@gtkx/utils";
+
+const DEFAULT_LIBRARIES: string[] = ["Gtk-4.0"];
+
+const GIR_FILE_SUFFIX = ".gir";
+
+export const resolveLibraries = (libraries: Config["libraries"], girPath: string[]): string[] => {
+    if (libraries === undefined) {
+        return [...DEFAULT_LIBRARIES];
+    }
+
+    if (libraries === LIBRARIES_WILDCARD) {
+        const discovered = discoverGirNamespaces(girPath);
+        if (discovered.length === 0) {
+            throw new Error(
+                `gtkx.config.ts: \`libraries: "*"\` matched no .gir files in [${girPath.join(", ")}]. ` +
+                    "Install gobject-introspection data packages, or list the libraries explicitly.",
+            );
+        }
+        return discovered;
+    }
+
+    const hasGtk = libraries.some((library) => library.startsWith("Gtk-"));
+    return [...new Set([...(hasGtk ? [] : DEFAULT_LIBRARIES), ...libraries])];
+};
+
+export const discoverGirNamespaces = (girPath: string[]): string[] => {
+    const highestByName = new Map<string, { version: string; identifier: string }>();
+
+    for (const dir of girPath) {
+        let entries: string[];
+        try {
+            entries = readdirSync(dir);
+        } catch {
+            continue;
+        }
+
+        for (const entry of entries) {
+            if (!entry.endsWith(GIR_FILE_SUFFIX)) {
+                continue;
+            }
+
+            const identifier = entry.slice(0, -GIR_FILE_SUFFIX.length);
+            if (!GIR_LIBRARY_PATTERN.test(identifier)) {
+                continue;
+            }
+
+            const separator = identifier.indexOf("-");
+            const name = identifier.slice(0, separator);
+            const version = identifier.slice(separator + 1);
+            const existing = highestByName.get(name);
+            if (existing === undefined || compareVersions(version, existing.version) > 0) {
+                highestByName.set(name, { version, identifier });
+            }
+        }
+    }
+
+    return sortStrings([...highestByName.values()].map(({ identifier }) => identifier));
+};
+
+const compareVersions = (a: string, b: string): number => {
+    const aParts = a.split(".");
+    const bParts = b.split(".");
+    const length = Math.max(aParts.length, bParts.length);
+
+    for (let index = 0; index < length; index += 1) {
+        const difference = Number(aParts[index] ?? 0) - Number(bParts[index] ?? 0);
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+
+    return 0;
+};