@gtkx/codegen 0.21.0 → 1.0.0-rc.1

package/src/gir/library.ts

@@ -0,0 +1,248 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { callbackFromNode } from "./callback.js";
+import {
+    createNamespaceShell,
+    type GirNamespace,
+    type NamespaceHeader,
+    parseNamespaceHeader,
+    populateNamespaceBody,
+} from "./namespace.js";
+import { parseGirFile, type RawNode } from "./parse.js";
+import type { PrimitiveCategory } from "./primitives.js";
+import type { GirType } from "./type.js";
+import type { CArrayType, HashTableType, ListType, ParseContext, TypeId } from "./type-id.js";
+import { splitOptionalNamespace } from "./type-ref.js";
+
+const INTERNAL_NS_ID = 0;
+
+type TypeTable = {
+    types: (GirType | undefined)[];
+    names: (string | undefined)[];
+    index: Map<string, number>;
+};
+
+export class Library {
+    private namespacesByName = new Map<string, GirNamespace>();
+    private namespaceById: (GirNamespace | undefined)[] = [];
+    private nsNameById: string[] = [];
+    private nsIdByName = new Map<string, number>();
+    private typeTables: TypeTable[] = [];
+    private girFilesValue: string[] = [];
+
+    public get namespaces(): Map<string, GirNamespace> {
+        return this.namespacesByName;
+    }
+
+    public get girFiles(): string[] {
+        return this.girFilesValue;
+    }
+
+    constructor() {
+        this.typeTables[INTERNAL_NS_ID] = { types: [], names: [], index: new Map() };
+        this.namespaceById[INTERNAL_NS_ID] = undefined;
+        this.nsNameById[INTERNAL_NS_ID] = "$internal";
+    }
+
+    private ensureNsId(name: string): number {
+        const existing = this.nsIdByName.get(name);
+        if (existing !== undefined) return existing;
+        const nsId = this.typeTables.length;
+        this.typeTables[nsId] = { types: [], names: [], index: new Map() };
+        this.namespaceById[nsId] = undefined;
+        this.nsNameById[nsId] = name;
+        this.nsIdByName.set(name, nsId);
+        return nsId;
+    }
+
+    private registerNamespace(header: NamespaceHeader): GirNamespace {
+        const nsId = this.ensureNsId(header.name);
+        const shell = createNamespaceShell(header, nsId);
+        this.namespaceById[nsId] = shell;
+        this.namespacesByName.set(header.name, shell);
+        return shell;
+    }
+
+    private namespaceOf(nsId: number): GirNamespace {
+        const namespace = this.namespaceById[nsId];
+        if (namespace === undefined) {
+            throw new Error(`No namespace registered for type table id ${nsId}`);
+        }
+        return namespace;
+    }
+
+    private typeTableOf(nsId: number): TypeTable {
+        const typeTable = this.typeTables[nsId];
+        if (typeTable === undefined) {
+            throw new Error(`No type table for namespace id ${nsId}`);
+        }
+        return typeTable;
+    }
+
+    private insertIntoTypeTable(
+        typeTable: TypeTable,
+        slot: { type: GirType | undefined; indexKey?: string; displayName?: string },
+    ): number {
+        const id = typeTable.types.length;
+        typeTable.types.push(slot.type);
+        typeTable.names.push(slot.displayName);
+        if (slot.indexKey !== undefined) typeTable.index.set(slot.indexKey, id);
+        return id;
+    }
+
+    private addType(nsId: number, name: string, type: GirType): void {
+        const typeTable = this.typeTableOf(nsId);
+        const existing = typeTable.index.get(name);
+        if (existing !== undefined) {
+            typeTable.types[existing] = type;
+            return;
+        }
+        this.insertIntoTypeTable(typeTable, { type, indexKey: name, displayName: name });
+    }
+
+    private findType(nsId: number, name: string): TypeId {
+        const typeTable = this.typeTableOf(nsId);
+        const existing = typeTable.index.get(name);
+        if (existing !== undefined) return { nsId, id: existing };
+        const id = this.insertIntoTypeTable(typeTable, { type: undefined, indexKey: name, displayName: name });
+        return { nsId, id };
+    }
+
+    private addAnonymousType(nsId: number, type: GirType): TypeId {
+        const typeTable = this.typeTableOf(nsId);
+        const id = this.insertIntoTypeTable(typeTable, { type });
+        return { nsId, id };
+    }
+
+    private findTypeByName(currentNsId: number, name: string): TypeId {
+        const [namespaceName, localName] = splitOptionalNamespace(name);
+        const targetNsId = namespaceName === undefined ? currentNsId : this.ensureNsId(namespaceName);
+        return this.findType(targetNsId, localName);
+    }
+
+    private parseContext(nsId: number): ParseContext {
+        const context: ParseContext = {
+            nsId,
+            findType: (name) => this.findTypeByName(nsId, name),
+            addPrimitive: (category) => this.addPrimitive(category),
+            addVarargs: () => this.addVarargs(),
+            addContainer: (type: CArrayType | ListType | HashTableType) => this.addAnonymousType(nsId, type),
+            addAnonymousCallback: (node) =>
+                this.addAnonymousType(nsId, {
+                    kind: "callback",
+                    namespace: this.namespaceOf(nsId),
+                    value: callbackFromNode(node, context),
+                }),
+        };
+        return context;
+    }
+
+    private addPrimitive(category: PrimitiveCategory): TypeId {
+        return this.findOrAddContainer(`primitive:${category}`, { kind: "primitive", category });
+    }
+
+    private addVarargs(): TypeId {
+        return this.findOrAddContainer("varargs", { kind: "varargs" });
+    }
+
+    private findOrAddContainer(key: string, type: GirType): TypeId {
+        const typeTable = this.typeTableOf(INTERNAL_NS_ID);
+        const existing = typeTable.index.get(key);
+        if (existing !== undefined) return { nsId: INTERNAL_NS_ID, id: existing };
+        const id = this.insertIntoTypeTable(typeTable, { type, indexKey: key });
+        return { nsId: INTERNAL_NS_ID, id };
+    }
+
+    private addDeclarations(shell: GirNamespace): void {
+        const nsId = shell.id;
+        for (const value of shell.classes) this.addType(nsId, value.name, { kind: "class", namespace: shell, value });
+        for (const value of shell.interfaces) {
+            this.addType(nsId, value.name, { kind: "interface", namespace: shell, value });
+        }
+        for (const value of shell.records) this.addType(nsId, value.name, { kind: "record", namespace: shell, value });
+        for (const value of shell.enums) this.addType(nsId, value.name, { kind: "enum", namespace: shell, value });
+        for (const value of shell.callbacks) {
+            this.addType(nsId, value.name, { kind: "callback", namespace: shell, value });
+        }
+        for (const alias of shell.aliases) {
+            this.addType(nsId, alias.name, { kind: "alias", namespace: shell, value: alias });
+        }
+    }
+
+    typeOf(tid: TypeId): GirType | undefined {
+        return this.typeTables[tid.nsId]?.types[tid.id];
+    }
+
+    nameOf(tid: TypeId): { namespaceName: string; typeName: string } | undefined {
+        const typeName = this.typeTables[tid.nsId]?.names[tid.id];
+        const namespaceName = this.nsNameById[tid.nsId];
+        if (typeName === undefined || namespaceName === undefined) return undefined;
+        return { namespaceName, typeName };
+    }
+
+    resolveType(currentNamespaceName: string, name: string): GirType | undefined {
+        const currentNsId = this.nsIdByName.get(currentNamespaceName);
+        if (currentNsId === undefined) return undefined;
+        const [namespaceName, localName] = splitOptionalNamespace(name);
+        const targetNsId = namespaceName === undefined ? currentNsId : this.nsIdByName.get(namespaceName);
+        if (targetNsId === undefined) return undefined;
+        const id = this.typeTableOf(targetNsId).index.get(localName);
+        if (id === undefined) return undefined;
+        return this.typeTableOf(targetNsId).types[id];
+    }
+
+    private static drive(library: Library, libraries: string[], girPath: string[]): void {
+        const queue: string[] = [...libraries];
+        const seen = new Set<string>();
+        const discovered: { header: NamespaceHeader; shell: GirNamespace }[] = [];
+        const girFiles: string[] = [];
+        while (queue.length > 0) {
+            const identifier = queue.shift();
+            if (identifier === undefined) continue;
+            const namespaceName = identifier.split("-")[0] ?? identifier;
+            if (seen.has(namespaceName)) continue;
+            seen.add(namespaceName);
+            const path = locateGirFile(identifier, girPath);
+            girFiles.push(path);
+            const repositoryNode = readRepositoryNode(path);
+            const header = parseNamespaceHeader(repositoryNode);
+            const shell = library.registerNamespace(header);
+            discovered.push({ header, shell });
+            for (const include of header.includes) {
+                queue.push(`${include.name}-${include.version}`);
+            }
+        }
+        for (const { header, shell } of discovered) {
+            populateNamespaceBody(shell, header.namespaceNode, library.parseContext(shell.id));
+        }
+        for (const { shell } of discovered) {
+            library.addDeclarations(shell);
+        }
+        library.girFilesValue = girFiles;
+    }
+
+    static load(libraries: string[], girPath: string[]): Library {
+        const library = new Library();
+        Library.drive(library, libraries, girPath);
+        return library;
+    }
+}
+
+const readRepositoryNode = (path: string): RawNode => {
+    const root = parseGirFile(path);
+    const repository = root.repository;
+    if (typeof repository !== "object" || repository === null) {
+        throw new Error(`GIR file at ${path} has no <repository> root`);
+    }
+    return repository as RawNode;
+};
+
+const locateGirFile = (identifier: string, girPath: string[]): string => {
+    const filename = `${identifier}.gir`;
+    for (const directory of girPath) {
+        const candidate = join(directory, filename);
+        if (existsSync(candidate)) return candidate;
+    }
+    const tried = girPath.map((directory) => join(directory, filename)).join(", ");
+    throw new Error(`GIR file ${filename} not found on girPath. Tried: ${tried}`);
+};

package/src/gir/namespace.ts

@@ -1,118 +1,123 @@
-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";
+import { attr, childOf, childrenOf, docOf, nameAttr, type RawNode } from "./parse.js";
+import { type GirRecord, isVtableRecord, recordFromNode } from "./record.js";
+import type { ParseContext, TypeId } from "./type-id.js";
+import { typeRefFromNode } 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;
+    name: string;
+    doc: string | undefined;
+    value: string;
+    type: TypeId | undefined;
 };
 
-/** A `<alias>` declaration at namespace level. */
 export type GirAlias = {
-    readonly name: string;
-    readonly target: GirTypeRef | undefined;
+    name: string;
+    doc: string | undefined;
+    cType: string | undefined;
+    target: TypeId | undefined;
+    targetCType: string | 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[];
+    id: number;
+    name: string;
+    sharedLibrary: string | undefined;
+    cSymbolPrefixes: string[];
+    classes: GirClass[];
+    interfaces: GirClass[];
+    records: GirRecord[];
+    enums: GirEnum[];
+    callbacks: GirCallback[];
+    functions: GirFunction[];
+    constants: GirConstant[];
+    aliases: GirAlias[];
 };
 
-/** A `<include>` entry pointing at another namespace identifier. */
+export const namespaceDirectory = (namespace: Pick<GirNamespace, "name">): string => namespace.name.toLowerCase();
+
 type NamespaceInclude = {
-    readonly name: string;
-    readonly version: string;
+    name: string;
+    version: string;
+};
+
+export type NamespaceHeader = {
+    name: string;
+    sharedLibrary: string | undefined;
+    cSymbolPrefixes: string[];
+    includes: NamespaceInclude[];
+    namespaceNode: RawNode;
 };
 
-/**
- * Builds a {@link GirNamespace} from a parsed `<repository>` root.
- *
- * @param repositoryNode - The raw `<repository>` element returned by `parseGirFile`
- */
-export const namespaceFromRepository = (repositoryNode: RawNode): GirNamespace => {
+export const parseNamespaceHeader = (repositoryNode: RawNode): NamespaceHeader => {
     const includes = childrenOf(repositoryNode, "include").map<NamespaceInclude>((include) => ({
-        name: attr(include, "name") ?? "",
+        name: nameAttr(include),
         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}`,
+        name: nameAttr(namespaceNode),
         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),
-        })),
+        namespaceNode,
     };
 };
 
-const splitPrefixes = (raw: string | undefined): readonly string[] =>
+export const createNamespaceShell = (header: NamespaceHeader, id: number): GirNamespace => ({
+    id,
+    name: header.name,
+    sharedLibrary: header.sharedLibrary,
+    cSymbolPrefixes: header.cSymbolPrefixes,
+    classes: [],
+    interfaces: [],
+    records: [],
+    enums: [],
+    callbacks: [],
+    functions: [],
+    constants: [],
+    aliases: [],
+});
+
+export const populateNamespaceBody = (shell: GirNamespace, namespaceNode: RawNode, context: ParseContext): void => {
+    shell.classes = childrenOf(namespaceNode, "class").map((klass) => classFromNode(klass, false, context));
+    shell.interfaces = childrenOf(namespaceNode, "interface").map((iface) => classFromNode(iface, true, context));
+    shell.records = collectRecords(namespaceNode, context);
+    shell.enums = collectEnums(namespaceNode);
+    shell.callbacks = childrenOf(namespaceNode, "callback").map((callback) => callbackFromNode(callback, context));
+    shell.functions = childrenOf(namespaceNode, "function").map((fn) => functionFromNode(fn, context));
+    shell.constants = childrenOf(namespaceNode, "constant").map((constant) => ({
+        name: nameAttr(constant),
+        doc: docOf(constant),
+        value: attr(constant, "value") ?? "",
+        type: typeRefFromNode(constant, context),
+    }));
+    shell.aliases = childrenOf(namespaceNode, "alias").map((alias) => ({
+        name: nameAttr(alias),
+        doc: docOf(alias),
+        cType: attr(alias, "c:type"),
+        target: typeRefFromNode(alias, context),
+        targetCType: attr(childOf(alias, "type"), "c:type"),
+    }));
+};
+
+const splitPrefixes = (raw: string | undefined): 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 collectRecords = (namespaceNode: RawNode, context: ParseContext): GirRecord[] => [
+    ...childrenOf(namespaceNode, "record").map((record) =>
+        recordFromNode(record, isVtableRecord(record), false, context),
+    ),
+    ...childrenOf(namespaceNode, "union").map((union) => recordFromNode(union, isVtableRecord(union), true, context)),
 ];
 
-const collectEnums = (namespaceNode: RawNode) => [
+const collectEnums = (namespaceNode: RawNode): GirEnum[] => [
     ...childrenOf(namespaceNode, "enumeration").map((enumeration) => enumFromNode(enumeration, "enumeration")),
     ...childrenOf(namespaceNode, "bitfield").map((bitfield) => enumFromNode(bitfield, "bitfield")),
 ];

package/src/gir/parameter.ts

@@ -1,120 +1,91 @@
-import { attr, attrBool, childOf, type RawNode } from "./parse.js";
-import { type GirTypeRef, typeRefFromSlot } from "./type-ref.js";
+import { attr, attrBool, childOf, childrenOf, docOf, intAttr, nameAttr, parseEnumAttr, type RawNode } from "./parse.js";
+import type { ParseContext, TypeId } from "./type-id.js";
+import { typeRefFromNode } 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.
- */
+const DIRECTIONS: Set<ParameterDirection> = new Set(["in", "out", "inout"]);
+const TRANSFERS: Set<ParameterTransfer> = new Set(["none", "full", "container"]);
+const SCOPES: Set<CallbackScope> = new Set(["call", "notified", "async", "forever"]);
+
+export const transferOwnership = (node: RawNode): ParameterTransfer =>
+    parseEnumAttr(attr(node, "transfer-ownership"), TRANSFERS, "none", "transfer-ownership");
+
+const nullableAttr = (node: RawNode): boolean => attrBool(node, "nullable") || attrBool(node, "allow-none");
+
 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;
+    name: string;
+    type: TypeId | undefined;
+    direction: ParameterDirection;
+    transferOwnership: ParameterTransfer;
+    nullable: boolean;
+    optional: boolean;
+    callerAllocates: boolean;
+    scope: CallbackScope | undefined;
+    closureIndex: number | undefined;
+    destroyIndex: number | undefined;
+    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,
-    };
-};
+export const parameterFromNode = (node: RawNode, context: ParseContext): GirParameter => ({
+    name: nameAttr(node),
+    type: typeRefFromNode(node, context),
+    direction: parseEnumAttr(attr(node, "direction"), DIRECTIONS, "in", "direction"),
+    transferOwnership: transferOwnership(node),
+    nullable: nullableAttr(node),
+    optional: attrBool(node, "optional"),
+    callerAllocates: attrBool(node, "caller-allocates"),
+    scope: parseEnumAttr(attr(node, "scope"), SCOPES, undefined, "scope"),
+    closureIndex: intAttr(node, "closure"),
+    destroyIndex: intAttr(node, "destroy"),
+    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;
+    type: TypeId | undefined;
+    transferOwnership: ParameterTransfer;
+    nullable: boolean;
+    skip: 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 => {
+const returnValueFromNode = (node: RawNode | undefined, context: ParseContext): GirReturnValue => {
     if (node === undefined) {
-        return { type: undefined, transferOwnership: "none", nullable: false };
+        return { type: undefined, transferOwnership: "none", nullable: false, skip: false };
     }
     return {
-        type: typeRefFromSlot(node),
-        transferOwnership: (attr(node, "transfer-ownership") ?? "none") as ParameterTransfer,
-        nullable: attrBool(node, "nullable") || attrBool(node, "allow-none"),
+        type: typeRefFromNode(node, context),
+        transferOwnership: transferOwnership(node),
+        nullable: nullableAttr(node),
+        skip: attrBool(node, "skip"),
+    };
+};
+
+export type GirSignal = {
+    name: string;
+    doc: string | undefined;
+    parameters: GirParameter[];
+    returnValue: GirReturnValue;
+};
+
+export const parseCallable = (node: RawNode, context: ParseContext): GirSignal => {
+    const parametersNode = childOf(node, "parameters");
+    const parameterNodes = childrenOf(parametersNode, "parameter");
+    return {
+        name: nameAttr(node),
+        doc: docOf(node),
+        parameters: parameterNodes.map((parameter) => parameterFromNode(parameter, context)),
+        returnValue: returnValueFromNode(childOf(node, "return-value"), context),
     };
 };