@gtkx/codegen 0.21.0

package/src/gir/namespace.ts

@@ -0,0 +1,118 @@
+import { boxedFromNode, boxedKind, type GirBoxed } from "./boxed.js";
+import { callbackFromNode, type GirCallback } from "./callback.js";
+import { classFromNode, type GirClass } from "./class.js";
+import { enumFromNode, type GirEnum } from "./enum.js";
+import { functionFromNode, type GirFunction } from "./function.js";
+import { attr, childrenOf, type RawNode } from "./parse.js";
+import { type GirTypeRef, typeRefFromSlot } from "./type-ref.js";
+
+/** A `<constant>` declaration at namespace level. */
+export type GirConstant = {
+    readonly name: string;
+    readonly cType: string | undefined;
+    readonly cIdentifier: string | undefined;
+    /** Constant value as the raw string from GIR. */
+    readonly value: string;
+    readonly type: GirTypeRef | undefined;
+};
+
+/** A `<alias>` declaration at namespace level. */
+export type GirAlias = {
+    readonly name: string;
+    readonly target: GirTypeRef | undefined;
+};
+
+/**
+ * A single namespace loaded from one `.gir` file.
+ *
+ * The class lives in `namespace.ts` (mutable holder) because populating it
+ * involves walking the raw XML tree once, materialising each construct.
+ * After construction the public surface is read-only by convention.
+ */
+export type GirNamespace = {
+    /** Namespace name (e.g. `"Gtk"`). */
+    readonly name: string;
+    /** Namespace version (e.g. `"4.0"`). */
+    readonly version: string;
+    /** `Name-Version` identifier (e.g. `"Gtk-4.0"`). */
+    readonly identifier: string;
+    /** Comma-separated `shared-library` value (passed verbatim to `t.fn(...)`). */
+    readonly sharedLibrary: string | undefined;
+    /** GIR `c:identifier-prefixes` (used to strip type prefixes). */
+    readonly cIdentifierPrefixes: readonly string[];
+    /** GIR `c:symbol-prefixes` (used to strip function prefixes). */
+    readonly cSymbolPrefixes: readonly string[];
+    /** Other namespaces referenced via `<include>`. */
+    readonly includes: readonly NamespaceInclude[];
+    readonly classes: readonly GirClass[];
+    readonly interfaces: readonly GirClass[];
+    readonly boxeds: readonly GirBoxed[];
+    readonly enums: readonly GirEnum[];
+    readonly callbacks: readonly GirCallback[];
+    readonly functions: readonly GirFunction[];
+    readonly constants: readonly GirConstant[];
+    readonly aliases: readonly GirAlias[];
+};
+
+/** A `<include>` entry pointing at another namespace identifier. */
+type NamespaceInclude = {
+    readonly name: string;
+    readonly version: string;
+};
+
+/**
+ * Builds a {@link GirNamespace} from a parsed `<repository>` root.
+ *
+ * @param repositoryNode - The raw `<repository>` element returned by `parseGirFile`
+ */
+export const namespaceFromRepository = (repositoryNode: RawNode): GirNamespace => {
+    const includes = childrenOf(repositoryNode, "include").map<NamespaceInclude>((include) => ({
+        name: attr(include, "name") ?? "",
+        version: attr(include, "version") ?? "",
+    }));
+    const namespaceNode = childrenOf(repositoryNode, "namespace")[0];
+    if (namespaceNode === undefined) {
+        throw new Error("GIR repository has no <namespace> child");
+    }
+    const name = attr(namespaceNode, "name") ?? "";
+    const version = attr(namespaceNode, "version") ?? "";
+    return {
+        name,
+        version,
+        identifier: `${name}-${version}`,
+        sharedLibrary: attr(namespaceNode, "shared-library"),
+        cIdentifierPrefixes: splitPrefixes(attr(namespaceNode, "c:identifier-prefixes")),
+        cSymbolPrefixes: splitPrefixes(attr(namespaceNode, "c:symbol-prefixes")),
+        includes,
+        classes: childrenOf(namespaceNode, "class").map((klass) => classFromNode(klass, false)),
+        interfaces: childrenOf(namespaceNode, "interface").map((iface) => classFromNode(iface, true)),
+        boxeds: collectBoxeds(namespaceNode),
+        enums: collectEnums(namespaceNode),
+        callbacks: childrenOf(namespaceNode, "callback").map(callbackFromNode),
+        functions: childrenOf(namespaceNode, "function").map((fn) => functionFromNode(fn, "function")),
+        constants: childrenOf(namespaceNode, "constant").map((constant) => ({
+            name: attr(constant, "name") ?? "",
+            cType: attr(constant, "c:type"),
+            cIdentifier: attr(constant, "c:identifier"),
+            value: attr(constant, "value") ?? "",
+            type: typeRefFromSlot(constant),
+        })),
+        aliases: childrenOf(namespaceNode, "alias").map((alias) => ({
+            name: attr(alias, "name") ?? "",
+            target: typeRefFromSlot(alias),
+        })),
+    };
+};
+
+const splitPrefixes = (raw: string | undefined): readonly string[] =>
+    (raw ?? "").split(",").filter((prefix) => prefix.length > 0);
+
+const collectBoxeds = (namespaceNode: RawNode): readonly GirBoxed[] => [
+    ...childrenOf(namespaceNode, "record").map((record) => boxedFromNode(record, boxedKind(record), false)),
+    ...childrenOf(namespaceNode, "union").map((union) => boxedFromNode(union, boxedKind(union), true)),
+];
+
+const collectEnums = (namespaceNode: RawNode) => [
+    ...childrenOf(namespaceNode, "enumeration").map((enumeration) => enumFromNode(enumeration, "enumeration")),
+    ...childrenOf(namespaceNode, "bitfield").map((bitfield) => enumFromNode(bitfield, "bitfield")),
+];

package/src/gir/parameter.ts

@@ -0,0 +1,120 @@
+import { attr, attrBool, childOf, type RawNode } from "./parse.js";
+import { type GirTypeRef, typeRefFromSlot } from "./type-ref.js";
+
+/** Direction of a `<parameter>` (`in`, `out`, `inout`). */
+type ParameterDirection = "in" | "out" | "inout";
+
+/**
+ * Lifetime conveyed by `transfer-ownership`. Mirrors the GIR vocabulary one
+ * for one; the marshal layer translates to the runtime's `Ownership` set.
+ */
+export type ParameterTransfer = "none" | "full" | "container";
+
+/** Lifetime of a callback parameter (`scope=…`). */
+type CallbackScope = "call" | "notified" | "async" | "forever";
+
+/**
+ * A `<parameter>` or `<instance-parameter>` of a callable.
+ *
+ * Only the bits the FFI writers actually look at are retained; the original
+ * raw node is dropped so the domain model is self-describing.
+ */
+export type GirParameter = {
+    /** Parameter name as authored in GIR (often snake_case). */
+    readonly name: string;
+    /** Typed slot of the parameter, or `undefined` for `<varargs/>`. */
+    readonly type: GirTypeRef | undefined;
+    readonly direction: ParameterDirection;
+    readonly transferOwnership: ParameterTransfer;
+    readonly nullable: boolean;
+    readonly optional: boolean;
+    /** `caller-allocates="1"` — used in out parameters that fill a caller buffer. */
+    readonly callerAllocates: boolean;
+    /** Lifetime of a callback parameter (defined only when the parameter is a callback). */
+    readonly scope: CallbackScope | undefined;
+    /** Index of the paired `gpointer user_data` parameter in the C signature. */
+    readonly closureIndex: number | undefined;
+    /** Index of the paired `GDestroyNotify` parameter in the C signature. */
+    readonly destroyIndex: number | undefined;
+    /** `true` for `<instance-parameter>` (the implicit `self` of a method). */
+    readonly isInstance: boolean;
+    /** `<varargs/>` parameter; not marshalable. */
+    readonly isVarargs: boolean;
+};
+
+/**
+ * Builds a {@link GirParameter} from a `<parameter>` or `<instance-parameter>`.
+ *
+ * @param node - The XML element
+ * @param isInstance - Whether the source element was `<instance-parameter>`
+ */
+export const parameterFromNode = (node: RawNode, isInstance: boolean): GirParameter => {
+    const direction = (attr(node, "direction") ?? "in") as ParameterDirection;
+    const transferOwnership = (attr(node, "transfer-ownership") ?? "none") as ParameterTransfer;
+    const closure = attr(node, "closure");
+    const destroy = attr(node, "destroy");
+    return {
+        name: attr(node, "name") ?? "",
+        type: typeRefFromSlot(node),
+        direction,
+        transferOwnership,
+        nullable: attrBool(node, "nullable") || attrBool(node, "allow-none"),
+        optional: attrBool(node, "optional"),
+        callerAllocates: attrBool(node, "caller-allocates"),
+        scope: attr(node, "scope") as CallbackScope | undefined,
+        closureIndex: closure === undefined ? undefined : Number.parseInt(closure, 10),
+        destroyIndex: destroy === undefined ? undefined : Number.parseInt(destroy, 10),
+        isInstance,
+        isVarargs: childOf(node, "varargs") !== undefined,
+    };
+};
+
+/**
+ * Whether a parameter is a pure out-parameter: `direction="out"` and not
+ * caller-allocated, so it marshals through a `{ value }` cell the callee writes into.
+ *
+ * @param parameter - The parameter to test
+ */
+export const isOutParameter = (parameter: GirParameter): boolean =>
+    parameter.direction === "out" && !parameter.callerAllocates;
+
+/**
+ * Whether a parameter is a caller-allocated out-parameter: `direction="out"`
+ * with `caller-allocates="1"`, passed as a pre-built handle the callee fills
+ * in place rather than through a `{ value }` cell.
+ *
+ * @param parameter - The parameter to test
+ */
+export const isCallerAllocatedOut = (parameter: GirParameter): boolean =>
+    parameter.direction === "out" && parameter.callerAllocates;
+
+/**
+ * Whether a parameter is an inout parameter (`direction="inout"`).
+ *
+ * @param parameter - The parameter to test
+ */
+export const isInoutParameter = (parameter: GirParameter): boolean => parameter.direction === "inout";
+
+/** A `<return-value>` plus its inferred type and transfer settings. */
+export type GirReturnValue = {
+    readonly type: GirTypeRef | undefined;
+    readonly transferOwnership: ParameterTransfer;
+    readonly nullable: boolean;
+};
+
+/**
+ * Builds a {@link GirReturnValue} from a `<return-value>` element, or returns a
+ * void return when the element is missing.
+ *
+ * @param node - The `<return-value>` element, or `undefined`
+ */
+export const returnValueFromNode = (node: RawNode | undefined): GirReturnValue => {
+    if (node === undefined) {
+        return { type: undefined, transferOwnership: "none", nullable: false };
+    }
+    return {
+        type: typeRefFromSlot(node),
+        transferOwnership: (attr(node, "transfer-ownership") ?? "none") as ParameterTransfer,
+        nullable: attrBool(node, "nullable") || attrBool(node, "allow-none"),
+    };
+};

package/src/gir/parse.ts

@@ -0,0 +1,171 @@
+import { readFileSync } from "node:fs";
+import { XMLParser } from "fast-xml-parser";
+
+/**
+ * Raw GIR XML element after parsing.
+ *
+ * Attributes are exposed under `@_<name>` keys (the default
+ * `fast-xml-parser` convention). Child elements appear under their tag name.
+ * Multi-occurrence tags (every container in {@link MULTI_TAGS}) are always
+ * arrays so callers do not need to disambiguate "single child" from "many
+ * children" at every access. Single-occurrence tags appear as bare objects.
+ */
+export type RawNode = {
+    readonly [attributeOrChild: string]: unknown;
+};
+
+/**
+ * Tag names that the GIR schema permits at multi-occurrence positions.
+ *
+ * `fast-xml-parser` is configured to always materialize these as arrays so
+ * downstream traversal never needs to branch on "is this an object or an
+ * array of objects". Tags missing from this set may appear as a single
+ * object (e.g. `<return-value>`, `<parameters>`, `<type>`, `<doc>`).
+ */
+const MULTI_TAGS: ReadonlySet<string> = new Set([
+    "include",
+    "c:include",
+    "package",
+    "class",
+    "interface",
+    "record",
+    "enumeration",
+    "bitfield",
+    "callback",
+    "function",
+    "function-macro",
+    "constant",
+    "alias",
+    "union",
+    "glib:boxed",
+    "method",
+    "constructor",
+    "virtual-method",
+    "property",
+    "field",
+    "glib:signal",
+    "implements",
+    "prerequisite",
+    "member",
+    "parameter",
+    "attribute",
+]);
+
+/**
+ * The tag name codegen reads GIR constructors under.
+ *
+ * GIR spells constructors `<constructor>`, but `fast-xml-parser` rejects the
+ * literal names `constructor`, `prototype`, and `__proto__` to guard against
+ * prototype pollution, with no opt-out. {@link parseGirFile} rewrites the tag
+ * to this token via `transformTagName` before that guard runs, so every
+ * downstream lookup of a constructor child must use this constant rather than
+ * the raw GIR name.
+ */
+export const GIR_CONSTRUCTOR_TAG = "gir-constructor";
+
+const RESERVED_TAG_RENAMES: ReadonlyMap<string, string> = new Map([["constructor", GIR_CONSTRUCTOR_TAG]]);
+
+/**
+ * Maps a GIR tag name to the token the parser exposes it under, rewriting the
+ * names {@link RESERVED_TAG_RENAMES} covers and passing every other tag
+ * through unchanged.
+ *
+ * @param tag - The raw GIR tag name
+ */
+const renameReservedTag = (tag: string): string => RESERVED_TAG_RENAMES.get(tag) ?? tag;
+
+const RENAMED_MULTI_TAGS: ReadonlySet<string> = new Set([...MULTI_TAGS].map(renameReservedTag));
+
+const PARSER = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    parseAttributeValue: false,
+    parseTagValue: false,
+    trimValues: true,
+    transformTagName: renameReservedTag,
+    isArray: (name) => RENAMED_MULTI_TAGS.has(name),
+});
+
+/**
+ * Parses a GIR XML file from disk and returns its raw tree.
+ *
+ * The returned object always has a single `repository` property containing
+ * the root `<repository>` element. Callers should not interpret the tree
+ * directly — pass it to {@link GirRepository.load} (in `./repository.ts`),
+ * which builds the typed domain model on top of it.
+ *
+ * @param path - Absolute path to a `.gir` file
+ * @returns The raw repository node
+ */
+export const parseGirFile = (path: string): RawNode => {
+    const xml = readFileSync(path, "utf-8");
+    return PARSER.parse(xml) as RawNode;
+};
+
+/**
+ * Reads an attribute from a raw GIR node as a string, returning `undefined`
+ * when the attribute is absent.
+ *
+ * The `@_` prefix is added by `fast-xml-parser`; this helper hides that
+ * convention from the call sites.
+ *
+ * @param node - The raw element
+ * @param name - The attribute name (without the `@_` prefix)
+ */
+export const attr = (node: RawNode | undefined, name: string): string | undefined => {
+    if (node === undefined) return undefined;
+    const value = node[`@_${name}`];
+    return typeof value === "string" ? value : undefined;
+};
+
+/**
+ * Reads an attribute as a boolean using GIR's `"1"` / `"0"` convention.
+ *
+ * Attributes that are missing return the supplied default (defaulting to
+ * `false`). Any non-`"1"` value is treated as `false`.
+ *
+ * @param node - The raw element
+ * @param name - The attribute name (without the `@_` prefix)
+ * @param fallback - Value returned when the attribute is missing
+ */
+export const attrBool = (node: RawNode | undefined, name: string, fallback = false): boolean => {
+    const value = attr(node, name);
+    if (value === undefined) return fallback;
+    return value === "1";
+};
+
+/**
+ * Returns the children of a raw node under a given tag name as an array.
+ *
+ * The parser configuration forces multi-occurrence tags to arrays already;
+ * this helper covers the residual case where a tag was registered as
+ * single-occurrence at the schema level but a particular file emits zero
+ * elements (returning `[]`) or where the caller wants a uniform array view.
+ *
+ * @param node - The parent element
+ * @param tag - The child tag name (with namespace prefix if any)
+ */
+export const childrenOf = (node: RawNode | undefined, tag: string): readonly RawNode[] => {
+    if (node === undefined) return [];
+    const value = node[tag];
+    if (value === undefined) return [];
+    if (Array.isArray(value)) return value as readonly RawNode[];
+    return [value as RawNode];
+};
+
+/**
+ * Returns the single child of a raw node under a given tag, or `undefined`
+ * if absent. If multiple are present the first is returned.
+ *
+ * @param node - The parent element
+ * @param tag - The child tag name (with namespace prefix if any)
+ */
+export const childOf = (node: RawNode | undefined, tag: string): RawNode | undefined => {
+    if (node === undefined) return undefined;
+    const value = node[tag];
+    if (value === undefined) return undefined;
+    if (Array.isArray(value)) {
+        return value.length === 0 ? undefined : (value[0] as RawNode);
+    }
+    return value as RawNode;
+};

package/src/gir/primitives.ts

@@ -0,0 +1,137 @@
+/**
+ * Mapping from GIR primitive type names to the FFI marshaling categories
+ * the writers emit.
+ *
+ * The categories mirror the `t.*` helpers exposed by `@gtkx/ffi`'s runtime
+ * (see `packages/ffi/src/helpers.ts`). Categories that are not directly
+ * marshaled (e.g. `void`, `string`, `unichar`) are still listed so callers
+ * can branch on them without falling through to a default.
+ */
+export type PrimitiveCategory =
+    | "void"
+    | "boolean"
+    | "int8"
+    | "uint8"
+    | "int16"
+    | "uint16"
+    | "int32"
+    | "uint32"
+    | "int64"
+    | "uint64"
+    | "float32"
+    | "float64"
+    | "string"
+    | "unichar"
+    | "pointer";
+
+/**
+ * Width in bytes of each primitive category on the x86-64 ABI (Linux LP64).
+ *
+ * The widths are also used as the natural alignment requirement of each
+ * category — every native integer/float aligns to its own size.
+ */
+export const PRIMITIVE_SIZE: Readonly<Record<PrimitiveCategory, number>> = Object.freeze({
+    void: 0,
+    boolean: 4,
+    int8: 1,
+    uint8: 1,
+    int16: 2,
+    uint16: 2,
+    int32: 4,
+    uint32: 4,
+    int64: 8,
+    uint64: 8,
+    float32: 4,
+    float64: 8,
+    string: 8,
+    unichar: 4,
+    pointer: 8,
+});
+
+const PRIMITIVE_BY_NAME: ReadonlyMap<string, PrimitiveCategory> = new Map([
+    ["none", "void"],
+    ["void", "void"],
+    ["gboolean", "boolean"],
+    ["gchar", "int8"],
+    ["gint8", "int8"],
+    ["guchar", "uint8"],
+    ["guint8", "uint8"],
+    ["gshort", "int16"],
+    ["gint16", "int16"],
+    ["gushort", "uint16"],
+    ["guint16", "uint16"],
+    ["gint", "int32"],
+    ["gint32", "int32"],
+    ["int", "int32"],
+    ["int8", "int8"],
+    ["uint8", "uint8"],
+    ["int16", "int16"],
+    ["uint16", "uint16"],
+    ["int32", "int32"],
+    ["uint32", "uint32"],
+    ["int64", "int64"],
+    ["uint64", "uint64"],
+    ["guint", "uint32"],
+    ["guint32", "uint32"],
+    ["glong", "int64"],
+    ["gint64", "int64"],
+    ["long", "int64"],
+    ["gssize", "int64"],
+    ["gintptr", "int64"],
+    ["gulong", "uint64"],
+    ["guint64", "uint64"],
+    ["gsize", "uint64"],
+    ["guintptr", "uint64"],
+    ["GType", "uint64"],
+    ["time_t", "int64"],
+    ["pid_t", "int32"],
+    ["uid_t", "uint32"],
+    ["gid_t", "uint32"],
+    ["gfloat", "float32"],
+    ["float", "float32"],
+    ["gdouble", "float64"],
+    ["double", "float64"],
+    ["long double", "float64"],
+    ["utf8", "string"],
+    ["filename", "string"],
+    ["gchararray", "string"],
+    ["gunichar", "unichar"],
+    ["gpointer", "pointer"],
+    ["gconstpointer", "pointer"],
+] as const);
+
+/**
+ * Returns the FFI category for a GIR primitive name (`"gint"`, `"utf8"`,
+ * `"gsize"`, …) or `undefined` when the name is not a primitive.
+ *
+ * Aliases that GIR uses inconsistently (`gint` / `int` / `gint32`, …) all
+ * map to the same canonical category.
+ *
+ * @param name - The GIR type name as it appears in `<type name="…">`
+ */
+export const primitiveCategory = (name: string): PrimitiveCategory | undefined => PRIMITIVE_BY_NAME.get(name);
+
+/**
+ * TypeScript surface type for each primitive category.
+ *
+ * Codegen surfaces both raw C primitives and string-marshalled categories
+ * (`string`, `unichar`) through this map so writers in the FFI and React
+ * pipelines agree on the same annotation per category.
+ */
+export const PRIMITIVE_TS_TYPE: Readonly<Record<PrimitiveCategory, string>> = Object.freeze({
+    void: "void",
+    boolean: "boolean",
+    int8: "number",
+    uint8: "number",
+    int16: "number",
+    uint16: "number",
+    int32: "number",
+    uint32: "number",
+    int64: "number",
+    uint64: "number",
+    float32: "number",
+    float64: "number",
+    string: "string",
+    unichar: "string",
+    pointer: "number",
+});

package/src/gir/property.ts

@@ -0,0 +1,39 @@
+import type { ParameterTransfer } from "./parameter.js";
+import { attr, attrBool, type RawNode } from "./parse.js";
+import { type GirTypeRef, typeRefFromSlot } from "./type-ref.js";
+
+/**
+ * A `<property>` of a class or interface.
+ *
+ * GIR property names are kebab-case; the writers convert them to camelCase
+ * for the JS surface and pass the original GIR name through to
+ * `registerConstructionMeta` for `g_object_newv` parameter building.
+ */
+export type GirProperty = {
+    /** GIR property name, kebab-case (e.g. `"css-name"`). */
+    readonly name: string;
+    /** Property value type. */
+    readonly type: GirTypeRef | undefined;
+    readonly writable: boolean;
+    readonly construct: boolean;
+    readonly constructOnly: boolean;
+    readonly transferOwnership: ParameterTransfer;
+    /** Optional method name that backs the property's getter (`getter="get_foo"`). */
+    readonly getter: string | undefined;
+    /** Optional method name that backs the property's setter (`setter="set_foo"`). */
+    readonly setter: string | undefined;
+};
+
+/**
+ * Builds a {@link GirProperty} from a `<property>` element.
+ */
+export const propertyFromNode = (node: RawNode): GirProperty => ({
+    name: attr(node, "name") ?? "",
+    type: typeRefFromSlot(node),
+    writable: attrBool(node, "writable"),
+    construct: attrBool(node, "construct"),
+    constructOnly: attrBool(node, "construct-only"),
+    transferOwnership: (attr(node, "transfer-ownership") ?? "none") as ParameterTransfer,
+    getter: attr(node, "getter"),
+    setter: attr(node, "setter"),
+});

package/src/gir/qualified-name.ts

@@ -0,0 +1,55 @@
+import type { GirClass } from "./class.js";
+import type { GirRepository } from "./repository.js";
+
+/**
+ * Splits a possibly cross-namespace GIR identifier (e.g. `"Gtk.Widget"`) into
+ * its namespace and local name.
+ *
+ * Identifiers without a dot are resolved against `defaultNamespace`. This
+ * mirrors the GIR convention where same-namespace references omit the
+ * namespace prefix.
+ *
+ * @param qualified - The GIR identifier as it appears in `<type>` / `parent`
+ * @param defaultNamespace - The namespace to assume when no prefix is present
+ */
+export const splitQualifiedName = (
+    qualified: string,
+    defaultNamespace: string,
+): { readonly namespaceName: string; readonly typeName: string } => {
+    const dot = qualified.indexOf(".");
+    if (dot === -1) {
+        return { namespaceName: defaultNamespace, typeName: qualified };
+    }
+    return { namespaceName: qualified.slice(0, dot), typeName: qualified.slice(dot + 1) };
+};
+
+/**
+ * A class or interface together with the namespace it was resolved through.
+ */
+export type ResolvedQualifiedClass = {
+    readonly klass: GirClass;
+    readonly namespaceName: string;
+};
+
+/**
+ * Resolves a possibly cross-namespace identifier to its `class` or `interface`
+ * entry plus the namespace that declares it.
+ *
+ * Returns `undefined` when the identifier resolves to a different kind of GIR
+ * entity (boxed, enum, …) or cannot be resolved at all.
+ *
+ * @param repository - The repository to query
+ * @param qualified - The GIR identifier (e.g. `"Gtk.Widget"`)
+ * @param defaultNamespace - Namespace to assume for unqualified identifiers
+ */
+export const resolveQualifiedClass = (
+    repository: GirRepository,
+    qualified: string,
+    defaultNamespace: string,
+): ResolvedQualifiedClass | undefined => {
+    const { namespaceName, typeName } = splitQualifiedName(qualified, defaultNamespace);
+    const resolved = repository.resolveNamed(namespaceName, typeName);
+    if (resolved === undefined) return undefined;
+    if (resolved.kind !== "class" && resolved.kind !== "interface") return undefined;
+    return { klass: resolved.value, namespaceName: resolved.namespace.name };
+};