@gtkx/codegen 0.21.0

package/src/gi-store.ts

@@ -0,0 +1,199 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type CodegenFingerprint, FINGERPRINT_FILENAME } from "./fingerprint.js";
+import { type StoreOptions, writeStore } from "./store-fs.js";
+import { transpileSource } from "./transpile.js";
+import { type StoreSourceFile, typecheckGiStore } from "./typecheck-store.js";
+
+/**
+ * Absolute path to the hand-written augment overlay shipped with `@gtkx/codegen`.
+ *
+ * Resolves the same way whether codegen runs from `src/` (tsx) or `dist/`,
+ * since `overlay/` sits at the package root next to both.
+ */
+const OVERLAY_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "overlay");
+
+/**
+ * Options for assembling the injected `@gtkx/gi` package.
+ */
+export type GiStoreOptions = StoreOptions & {
+    /** Real (symlink-resolved) directory of the installed `@gtkx/ffi`. */
+    readonly realFfiDir: string;
+    /** Real (symlink-resolved) directory of the installed `@gtkx/native`. */
+    readonly realNativeDir: string;
+};
+
+/** Per-namespace inputs the store assembler turns into gi modules. */
+export type GiNamespaceInput = {
+    /** Lowercased namespace directory name (e.g. `"gtk"`). */
+    readonly directory: string;
+    /** Transpilable raw module source, or `null` for augment-only namespaces (gl). */
+    readonly rawSource: string | null;
+};
+
+/** Returns the augment `.ts` files for a namespace, or `[]` when it is pure pass-through. */
+const overlayFiles = (directory: string): readonly string[] => {
+    const dir = join(OVERLAY_ROOT, directory);
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir).filter((name) => name.endsWith(".ts") && name !== "index.ts");
+};
+
+const isAugmented = (directory: string): boolean => existsSync(join(OVERLAY_ROOT, directory, "index.ts"));
+
+/**
+ * Whether an augmented namespace's barrel re-exports a generated module (and so
+ * may only be emitted when that namespace is generated), as opposed to a
+ * standalone overlay like `gl` that has no GIR backing.
+ */
+const barrelNeedsGenerated = (directory: string): boolean =>
+    readFileSync(join(OVERLAY_ROOT, directory, "index.ts"), "utf8").includes("../generated/");
+
+/**
+ * Retargets a barrel-template specifier from its source layout (under
+ * `overlay/<ns>/`) to its emitted layout (under `gi/<ns>/`): the namespace's
+ * own generated module becomes a sibling, augment files move under `augment/`,
+ * and relative runtime modules collapse to the `@gtkx/ffi` barrel. The
+ * `@gtkx/native` specifier passes through so low-level primitives resolve
+ * straight to the native package.
+ */
+const retargetBarrelSpecifier = (spec: string, directory: string): string => {
+    const generated = spec.match(/^\.\.\/generated\/[a-z0-9]+\/([a-z0-9]+)\.js$/);
+    if (generated) return `./${generated[1]}.js`;
+    if (spec.startsWith("../")) return "@gtkx/ffi";
+    const sibling = spec.match(/^\.\/([a-z0-9-]+)\.js$/);
+    if (sibling) {
+        return existsSync(join(OVERLAY_ROOT, directory, `${sibling[1]}.ts`))
+            ? `./augment/${sibling[1]}.js`
+            : "@gtkx/ffi";
+    }
+    return spec;
+};
+
+const barrelSource = (directory: string): string => {
+    if (!isAugmented(directory)) {
+        return `export * from "./${directory}.js";\n`;
+    }
+    const template = readFileSync(join(OVERLAY_ROOT, directory, "index.ts"), "utf8");
+    return template.replace(/"([^"]+)"/g, (_match, spec) => `"${retargetBarrelSpecifier(spec, directory)}"`);
+};
+
+type CollectedFile = {
+    readonly stem: string;
+    readonly fileName: string;
+    readonly source: string;
+    readonly overlay: boolean;
+};
+
+/**
+ * Gathers the per-namespace generated module, augment overlay, and barrel
+ * sources into a flat file list, building the package `exports` map alongside.
+ */
+const collectStoreSources = (
+    directories: ReadonlySet<string>,
+    standaloneSet: ReadonlySet<string>,
+    rawByDirectory: ReadonlyMap<string, string | null>,
+): { collected: CollectedFile[]; exportsMap: Record<string, unknown> } => {
+    const exportsMap: Record<string, unknown> = { "./package.json": "./package.json" };
+    const collected: CollectedFile[] = [];
+    for (const directory of directories) {
+        const rawSource = standaloneSet.has(directory) ? null : (rawByDirectory.get(directory) ?? null);
+        if (rawSource !== null) {
+            collected.push({
+                stem: `${directory}/${directory}`,
+                fileName: `${directory}/${directory}.ts`,
+                source: rawSource,
+                overlay: false,
+            });
+            exportsMap[`./${directory}/${directory}.js`] = {
+                types: `./${directory}/${directory}.d.ts`,
+                default: `./${directory}/${directory}.js`,
+            };
+        }
+        for (const file of overlayFiles(directory)) {
+            collected.push({
+                stem: `${directory}/augment/${file.slice(0, -".ts".length)}`,
+                fileName: `${directory}/augment/${file}`,
+                source: readFileSync(join(OVERLAY_ROOT, directory, file), "utf8"),
+                overlay: true,
+            });
+        }
+        collected.push({
+            stem: `${directory}/index`,
+            fileName: `${directory}/index.ts`,
+            source: barrelSource(directory),
+            overlay: false,
+        });
+        exportsMap[`./${directory}`] = {
+            types: `./${directory}/index.d.ts`,
+            default: `./${directory}/index.js`,
+        };
+    }
+    return { collected, exportsMap };
+};
+
+/**
+ * Assembles the self-contained injected `@gtkx/gi` package.
+ *
+ * Writes every namespace's raw generated module, its augment overlay, and its
+ * barrel into a temporary store, emits the `package.json` and gi's own
+ * `node_modules/@gtkx/{ffi,gi}` symlinks — the self-referential `@gtkx/gi` link
+ * lets augment modules resolve sibling namespaces without relying on the
+ * project's top-level alias — swaps it into place, and points the visible
+ * `node_modules/@gtkx/gi` alias at it.
+ *
+ * @param options - Resolved store/link/dependency paths
+ * @param namespaces - Per-namespace raw module inputs
+ * @param fingerprint - Staleness sentinel written into the store, when provided
+ */
+export const writeGiStore = (
+    options: GiStoreOptions,
+    namespaces: readonly GiNamespaceInput[],
+    fingerprint?: CodegenFingerprint,
+): void => {
+    const standaloneOverlays = readdirSync(OVERLAY_ROOT).filter(
+        (name) => isAugmented(name) && !barrelNeedsGenerated(name),
+    );
+    const standaloneSet = new Set(standaloneOverlays);
+    const directories = new Set<string>([...namespaces.map((n) => n.directory), ...standaloneOverlays]);
+    const rawByDirectory = new Map(namespaces.map((n) => [n.directory, n.rawSource]));
+
+    const { collected, exportsMap } = collectStoreSources(directories, standaloneSet, rawByDirectory);
+
+    writeStore({
+        storeDir: options.storeDir,
+        linkDir: options.linkDir,
+        files: collected.map((file) => ({ stem: file.stem, fileName: file.fileName, source: file.source })),
+        manifest: {
+            name: "@gtkx/gi",
+            type: "module",
+            version: options.version,
+            sideEffects: true,
+            exports: exportsMap,
+        },
+        rawFiles:
+            fingerprint === undefined
+                ? []
+                : [{ relativePath: FINGERPRINT_FILENAME, content: `${JSON.stringify(fingerprint, null, 2)}\n` }],
+        symlinks: [
+            { segments: ["node_modules", "@gtkx", "ffi"], target: options.realFfiDir },
+            { segments: ["node_modules", "@gtkx", "native"], target: options.realNativeDir },
+            { segments: ["node_modules", "@gtkx", "gi"], target: "self" },
+        ],
+        validate: (tmp) => {
+            const sources: StoreSourceFile[] = collected.map((file) =>
+                file.overlay
+                    ? { path: join(tmp, file.fileName), source: file.source, overlay: true }
+                    : {
+                          path: join(tmp, `${file.stem}.d.ts`),
+                          source: transpileSource(file.fileName, file.source).dts,
+                          overlay: false,
+                      },
+            );
+            typecheckGiStore(tmp, sources, {
+                ffiEntry: join(options.realFfiDir, "src", "index.ts"),
+                nativeEntry: join(options.realNativeDir, "dist", "index.d.ts"),
+            });
+        },
+    });
+};

package/src/gir/boxed.ts

@@ -0,0 +1,94 @@
+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";
+
+/**
+ * Discriminator for the different shapes a `<record>` (or `<glib:boxed>`)
+ * can take in GIR.
+ *
+ * - `boxed` — a record with a `glib:get-type`; registers as a GObject boxed.
+ * - `plain-struct` — a record without GType; passed by pointer using
+ *   `t.struct(ownership)`.
+ * - `vtable` — a record carrying `glib:is-gtype-struct-for`; its fields are
+ *   function pointers consumed by the class struct registration.
+ * - `glib-boxed` — a top-level `<glib:boxed>` element with no struct body.
+ */
+export type BoxedKind = "boxed" | "plain-struct" | "vtable" | "glib-boxed";
+
+/** A `<record>`, `<glib:boxed>`, or `<union>` declaration. */
+export type GirBoxed = {
+    readonly kind: BoxedKind;
+    /** Local name inside the namespace (no prefix). */
+    readonly name: string;
+    readonly cType: string | undefined;
+    /** GLib type name (e.g. `"GtkBorder"`); absent on plain structs. */
+    readonly glibTypeName: string | undefined;
+    /** GLib get-type C symbol; absent on plain structs. */
+    readonly glibGetType: string | undefined;
+    /** Class name this record is the vtable for (`glib:is-gtype-struct-for`). */
+    readonly glibIsGTypeStructFor: string | undefined;
+    /** GLib ref/unref/etc. function names on fundamentals. */
+    readonly glibRefFunc: string | undefined;
+    readonly glibUnrefFunc: string | undefined;
+    readonly glibSetValueFunc: string | undefined;
+    readonly glibGetValueFunc: string | undefined;
+    /** `copy-function`/`free-function` — the ref/unref pair for records that are reference-counted rather than g_boxed-copyable. */
+    readonly copyFunc: string | undefined;
+    readonly freeFunc: string | undefined;
+    /** `disguised="1"` — record has no introspectable fields. */
+    readonly disguised: boolean;
+    /** `opaque="1"` — record is opaque to callers. */
+    readonly opaque: boolean;
+    readonly introspectable: boolean;
+    readonly fields: readonly GirField[];
+    readonly methods: readonly GirFunction[];
+    readonly constructors: readonly GirFunction[];
+    readonly functions: readonly GirFunction[];
+    /** `true` when the source element was `<union>` rather than `<record>`. */
+    readonly isUnion: boolean;
+};
+
+/**
+ * Builds a {@link GirBoxed} from a `<record>`, `<union>`, or `<glib:boxed>` element.
+ *
+ * @param node - The XML element
+ * @param kind - The kind inferred from element name and attribute set
+ * @param isUnion - `true` when the source element was `<union>`
+ */
+export const boxedFromNode = (node: RawNode, kind: BoxedKind, isUnion: boolean): GirBoxed => ({
+    kind,
+    name: attr(node, "name") ?? attr(node, "glib:name") ?? "",
+    cType: attr(node, "c:type"),
+    glibTypeName: attr(node, "glib:type-name"),
+    glibGetType: attr(node, "glib:get-type"),
+    glibIsGTypeStructFor: attr(node, "glib:is-gtype-struct-for"),
+    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"),
+    copyFunc: attr(node, "copy-function"),
+    freeFunc: attr(node, "free-function"),
+    disguised: attrBool(node, "disguised"),
+    opaque: attrBool(node, "opaque"),
+    introspectable: attr(node, "introspectable") !== "0",
+    fields: childrenOf(node, "field").map(fieldFromNode),
+    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")),
+    isUnion,
+});
+
+/**
+ * Decides which {@link BoxedKind} applies to a `<record>` or `<union>` element.
+ *
+ * Vtable records (`glib:is-gtype-struct-for`) take precedence; otherwise a
+ * `glib:get-type` flips the record to a registered boxed; otherwise it's a
+ * plain struct.
+ *
+ * @param node - The `<record>` or `<union>` element
+ */
+export const boxedKind = (node: RawNode): BoxedKind => {
+    if (attr(node, "glib:is-gtype-struct-for") !== undefined) return "vtable";
+    if (attr(node, "glib:get-type") !== undefined) return "boxed";
+    return "plain-struct";
+};

package/src/gir/callback.ts

@@ -0,0 +1,26 @@
+import { type GirParameter, type GirReturnValue, parameterFromNode, returnValueFromNode } from "./parameter.js";
+import { attr, childOf, childrenOf, type RawNode } from "./parse.js";
+
+/** A `<callback>` declaration (top-level inside a namespace or nested in a field). */
+export type GirCallback = {
+    readonly name: string;
+    readonly cType: string | undefined;
+    readonly parameters: readonly GirParameter[];
+    readonly returnValue: GirReturnValue;
+    readonly introspectable: boolean;
+};
+
+/**
+ * Builds a {@link GirCallback} from a `<callback>` element.
+ */
+export const callbackFromNode = (node: RawNode): GirCallback => {
+    const parametersNode = childOf(node, "parameters");
+    const parameterNodes = childrenOf(parametersNode, "parameter");
+    return {
+        name: attr(node, "name") ?? "",
+        cType: attr(node, "c:type"),
+        parameters: parameterNodes.map((parameter) => parameterFromNode(parameter, false)),
+        returnValue: returnValueFromNode(childOf(node, "return-value")),
+        introspectable: attr(node, "introspectable") !== "0",
+    };
+};

package/src/gir/class.ts

@@ -0,0 +1,79 @@
+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 GirProperty, propertyFromNode } from "./property.js";
+import { type GirSignal, signalFromNode } from "./signal.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[];
+};
+
+/**
+ * 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") ?? "",
+    cType: attr(node, "c:type"),
+    parent: attr(node, "parent"),
+    glibTypeName: attr(node, "glib:type-name"),
+    glibGetType: attr(node, "glib:get-type"),
+    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",
+    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),
+});

package/src/gir/enum.ts

@@ -0,0 +1,55 @@
+import { functionFromNode, type GirFunction } from "./function.js";
+import { attr, childrenOf, 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;
+};
+
+/** Discriminator for enums vs bitfields. */
+export 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[];
+};
+
+/**
+ * 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"),
+    glibTypeName: attr(node, "glib:type-name"),
+    glibGetType: attr(node, "glib:get-type"),
+    errorDomain: attr(node, "glib:error-domain"),
+    introspectable: attr(node, "introspectable") !== "0",
+    members: childrenOf(node, "member").map((member) => ({
+        name: attr(member, "name") ?? "",
+        cIdentifier: attr(member, "c:identifier"),
+        value: attr(member, "value") ?? "0",
+    })),
+    functions: childrenOf(node, "function").map((function_) => functionFromNode(function_, "function")),
+});

package/src/gir/field.ts

@@ -0,0 +1,40 @@
+import { attr, attrBool, childOf, type RawNode } from "./parse.js";
+import { type GirTypeRef, typeRefFromSlot } 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;
+};
+
+/**
+ * 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),
+    };
+};

package/src/gir/function.ts

@@ -0,0 +1,67 @@
+import { type GirParameter, type GirReturnValue, parameterFromNode, returnValueFromNode } from "./parameter.js";
+import { attr, attrBool, childOf, childrenOf, type RawNode } from "./parse.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;
+};
+
+/**
+ * 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");
+    return {
+        kind,
+        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"),
+        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"),
+    };
+};