@gtkx/codegen 0.21.0 → 1.0.0-rc.1

package/src/gir/parse.ts

@@ -1,31 +1,12 @@
 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;
+    [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([
+const MULTI_TAGS: Set<string> = new Set([
     "include",
-    "c:include",
-    "package",
     "class",
     "interface",
     "record",
@@ -33,14 +14,11 @@ const MULTI_TAGS: ReadonlySet<string> = new Set([
     "bitfield",
     "callback",
     "function",
-    "function-macro",
     "constant",
     "alias",
     "union",
-    "glib:boxed",
     "method",
     "constructor",
-    "virtual-method",
     "property",
     "field",
     "glib:signal",
@@ -48,33 +26,15 @@ const MULTI_TAGS: ReadonlySet<string> = new Set([
     "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]]);
+const RESERVED_TAG_RENAMES: Map<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 RENAMED_MULTI_TAGS: Set<string> = new Set([...MULTI_TAGS].map(renameReservedTag));
 
 const PARSER = new XMLParser({
     ignoreAttributes: false,
@@ -86,80 +46,51 @@ const PARSER = new XMLParser({
     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[] => {
+export const nameAttr = (node: RawNode): string => attr(node, "name") ?? "";
+
+export const intAttr = (node: RawNode, name: string): number | undefined => {
+    const raw = attr(node, name);
+    return raw === undefined ? undefined : Number.parseInt(raw, 10);
+};
+
+export const parseEnumAttr = <T extends string, F extends T | undefined>(
+    raw: string | undefined,
+    members: Set<T>,
+    fallback: F,
+    label: string,
+): T | F => {
+    if (raw === undefined) return fallback;
+    for (const member of members) {
+        if (member === raw) return member;
+    }
+    throw new Error(`Unknown ${label} value "${raw}"`);
+};
+
+export const childrenOf = (node: RawNode | undefined, tag: string): RawNode[] => {
     if (node === undefined) return [];
     const value = node[tag];
     if (value === undefined) return [];
-    if (Array.isArray(value)) return value as readonly RawNode[];
+    if (Array.isArray(value)) return value as 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];
@@ -169,3 +100,20 @@ export const childOf = (node: RawNode | undefined, tag: string): RawNode | undef
     }
     return value as RawNode;
 };
+
+const normalizeDoc = (text: string): string | undefined => {
+    const trimmed = text.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+};
+
+export const docOf = (node: RawNode | undefined): string | undefined => {
+    if (node === undefined) return undefined;
+    const raw = node.doc;
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof value === "string") return normalizeDoc(value);
+    if (value !== null && typeof value === "object") {
+        const text = (value as RawNode)["#text"];
+        if (typeof text === "string") return normalizeDoc(text);
+    }
+    return undefined;
+};

package/src/gir/primitives.ts

@@ -1,12 +1,3 @@
-/**
- * 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"
@@ -18,19 +9,16 @@ export type PrimitiveCategory =
     | "uint32"
     | "int64"
     | "uint64"
+    | "bigint64"
+    | "biguint64"
+    | "gtype"
     | "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({
+export const PRIMITIVE_SIZE: Record<PrimitiveCategory, number> = {
     void: 0,
     boolean: 4,
     int8: 1,
@@ -41,14 +29,17 @@ export const PRIMITIVE_SIZE: Readonly<Record<PrimitiveCategory, number>> = Objec
     uint32: 4,
     int64: 8,
     uint64: 8,
+    bigint64: 8,
+    biguint64: 8,
+    gtype: 8,
     float32: 4,
     float64: 8,
     string: 8,
     unichar: 4,
     pointer: 8,
-});
+};
 
-const PRIMITIVE_BY_NAME: ReadonlyMap<string, PrimitiveCategory> = new Map([
+const PRIMITIVE_BY_NAME: Map<string, PrimitiveCategory> = new Map([
     ["none", "void"],
     ["void", "void"],
     ["gboolean", "boolean"],
@@ -69,21 +60,21 @@ const PRIMITIVE_BY_NAME: ReadonlyMap<string, PrimitiveCategory> = new Map([
     ["uint16", "uint16"],
     ["int32", "int32"],
     ["uint32", "uint32"],
-    ["int64", "int64"],
-    ["uint64", "uint64"],
+    ["int64", "bigint64"],
+    ["uint64", "biguint64"],
     ["guint", "uint32"],
     ["guint32", "uint32"],
-    ["glong", "int64"],
-    ["gint64", "int64"],
-    ["long", "int64"],
+    ["glong", "bigint64"],
+    ["gint64", "bigint64"],
+    ["long", "bigint64"],
     ["gssize", "int64"],
     ["gintptr", "int64"],
-    ["gulong", "uint64"],
-    ["guint64", "uint64"],
+    ["gulong", "biguint64"],
+    ["guint64", "biguint64"],
     ["gsize", "uint64"],
     ["guintptr", "uint64"],
-    ["GType", "uint64"],
-    ["time_t", "int64"],
+    ["GType", "gtype"],
+    ["time_t", "bigint64"],
     ["pid_t", "int32"],
     ["uid_t", "uint32"],
     ["gid_t", "uint32"],
@@ -100,25 +91,9 @@ const PRIMITIVE_BY_NAME: ReadonlyMap<string, PrimitiveCategory> = new Map([
     ["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({
+export const PRIMITIVE_TS_TYPE: Record<PrimitiveCategory, string> = {
     void: "void",
     boolean: "boolean",
     int8: "number",
@@ -129,9 +104,12 @@ export const PRIMITIVE_TS_TYPE: Readonly<Record<PrimitiveCategory, string>> = Ob
     uint32: "number",
     int64: "number",
     uint64: "number",
+    bigint64: "bigint",
+    biguint64: "bigint",
+    gtype: "bigint",
     float32: "number",
     float64: "number",
     string: "string",
     unichar: "string",
     pointer: "number",
-});
+};

package/src/gir/property.ts

@@ -1,39 +1,37 @@
-import type { ParameterTransfer } from "./parameter.js";
-import { attr, attrBool, type RawNode } from "./parse.js";
-import { type GirTypeRef, typeRefFromSlot } from "./type-ref.js";
+import { type ParameterTransfer, transferOwnership } from "./parameter.js";
+import { attr, attrBool, docOf, nameAttr, type RawNode } from "./parse.js";
+import type { ParseContext, TypeId } from "./type-id.js";
+import { typeRefFromNode } 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;
+    name: string;
+    doc: string | undefined;
+    type: TypeId | undefined;
+    readable: boolean;
+    writable: boolean;
+    construct: boolean;
+    constructOnly: boolean;
+    introspectable: boolean;
+    transferOwnership: ParameterTransfer;
+    getter: string | undefined;
+    setter: string | undefined;
+    defaultValue: string | undefined;
 };
 
-/**
- * Builds a {@link GirProperty} from a `<property>` element.
- */
-export const propertyFromNode = (node: RawNode): GirProperty => ({
-    name: attr(node, "name") ?? "",
-    type: typeRefFromSlot(node),
+export const isConstructableProperty = (property: GirProperty): boolean =>
+    property.writable || property.construct || property.constructOnly;
+
+export const propertyFromNode = (node: RawNode, context: ParseContext): GirProperty => ({
+    name: nameAttr(node),
+    doc: docOf(node),
+    type: typeRefFromNode(node, context),
+    readable: attrBool(node, "readable", true),
     writable: attrBool(node, "writable"),
     construct: attrBool(node, "construct"),
     constructOnly: attrBool(node, "construct-only"),
-    transferOwnership: (attr(node, "transfer-ownership") ?? "none") as ParameterTransfer,
+    introspectable: attrBool(node, "introspectable", true),
+    transferOwnership: transferOwnership(node),
     getter: attr(node, "getter"),
     setter: attr(node, "setter"),
+    defaultValue: attr(node, "default-value"),
 });

package/src/gir/record.ts

@@ -0,0 +1,53 @@
+import { fieldFromNode, type GirField } from "./field.js";
+import { functionFromNode, type GirFunction } from "./function.js";
+import { attr, attrBool, childrenOf, docOf, GIR_CONSTRUCTOR_TAG, type RawNode } from "./parse.js";
+import type { ParseContext } from "./type-id.js";
+
+export type GirRecord = {
+    isVtable: boolean;
+    name: string;
+    doc: string | undefined;
+    cType: string | undefined;
+    glibTypeName: string | undefined;
+    glibGetType: string | undefined;
+    glibRefFunc: string | undefined;
+    glibUnrefFunc: string | undefined;
+    copyFunc: string | undefined;
+    freeFunc: string | undefined;
+    disguised: boolean;
+    opaque: boolean;
+    introspectable: boolean;
+    fields: GirField[];
+    methods: GirFunction[];
+    constructors: GirFunction[];
+    functions: GirFunction[];
+    isUnion: boolean;
+};
+
+export const recordFromNode = (
+    node: RawNode,
+    isVtable: boolean,
+    isUnion: boolean,
+    context: ParseContext,
+): GirRecord => ({
+    isVtable,
+    name: attr(node, "name") ?? attr(node, "glib:name") ?? "",
+    doc: docOf(node),
+    cType: attr(node, "c:type"),
+    glibTypeName: attr(node, "glib:type-name"),
+    glibGetType: attr(node, "glib:get-type"),
+    glibRefFunc: attr(node, "glib:ref-func"),
+    glibUnrefFunc: attr(node, "glib:unref-func"),
+    copyFunc: attr(node, "copy-function"),
+    freeFunc: attr(node, "free-function"),
+    disguised: attrBool(node, "disguised"),
+    opaque: attrBool(node, "opaque"),
+    introspectable: attrBool(node, "introspectable", true),
+    fields: childrenOf(node, "field").map((field) => fieldFromNode(field, context)),
+    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)),
+    isUnion,
+});
+
+export const isVtableRecord = (node: RawNode): boolean => attr(node, "glib:is-gtype-struct-for") !== undefined;

package/src/gir/size.ts

@@ -1,24 +1,10 @@
 import { PRIMITIVE_SIZE, type PrimitiveCategory } from "./primitives.js";
 
-/**
- * Size and alignment of a single field as it appears in a C struct laid out
- * according to the x86-64 ABI.
- */
 export type FieldLayout = {
-    /** Width of the field in bytes. */
-    readonly size: number;
-    /** Required alignment in bytes; storage offset rounds up to a multiple of this. */
-    readonly align: number;
+    size: number;
+    align: number;
 };
 
-/**
- * Returns the `{ size, align }` pair for a primitive category.
- *
- * Pointers and pointer-sized integers (the `pointer` and 64-bit categories)
- * report 8/8. Smaller integers and floats report their natural width.
- *
- * @param category - The primitive category
- */
 export const layoutOfPrimitive = (category: PrimitiveCategory): FieldLayout => {
     const size = PRIMITIVE_SIZE[category];
     return { size, align: size === 0 ? 1 : size };
@@ -30,54 +16,21 @@ const roundUp = (value: number, multiple: number): number => {
     return remainder === 0 ? value : value + (multiple - remainder);
 };
 
-/**
- * Layout slot for a single field that may participate in bitfield packing.
- *
- * `byteOffset` is always the offset of the underlying storage word; for
- * non-bitfield fields it is the field's offset directly, and for bitfield
- * members it is the start of the shared storage unit. `bitOffset` and
- * `bitWidth` are populated only for bitfield members.
- */
 export type FieldSlot = {
-    /** Byte offset of the storage word the field occupies. */
-    readonly byteOffset: number;
-    /** Bit position within the storage word, for bitfield members. */
-    readonly bitOffset: number | undefined;
-    /** Width in bits, for bitfield members. */
-    readonly bitWidth: number | undefined;
+    byteOffset: number;
+    bitOffset: number | undefined;
+    bitWidth: number | undefined;
 };
 
-/**
- * Describes a field for the purposes of layout computation.
- */
 export type FieldLayoutInput = {
-    /** Natural byte size and alignment of the field's value type. */
-    readonly layout: FieldLayout;
-    /** When set, the field is a bitfield member with this many bits. */
-    readonly bits: number | undefined;
+    layout: FieldLayout;
+    bits: number | undefined;
 };
 
-/**
- * Computes per-field byte offsets for a record, grouping consecutive
- * bitfield members of compatible storage widths into a shared storage
- * word.
- *
- * Mirrors the GCC/Itanium ABI rules for C bitfield packing in a
- * single-storage-word model: a new storage word is opened when the
- * underlying type's size changes, when the new field is not a bitfield,
- * or when adding the bits would exceed the word's bit count.
- *
- * A union (`isUnion`) overlays every member at byte offset 0; its size is the
- * largest member rounded up to the strongest member alignment.
- *
- * @param fields - Ordered field layouts and bit widths
- * @param isUnion - Whether the fields are union members (overlaid at offset 0)
- * @returns Parallel slot array and the total record size in bytes
- */
 export const computeFieldSlots = (
-    fields: readonly FieldLayoutInput[],
+    fields: FieldLayoutInput[],
     isUnion = false,
-): { readonly slots: readonly FieldSlot[]; readonly size: number } => {
+): { slots: FieldSlot[]; size: number } => {
     if (isUnion) {
         let maxSize = 0;
         let maxAlign = 1;

package/src/gir/type-id.ts

@@ -0,0 +1,49 @@
+import type { RawNode } from "./parse.js";
+import type { PrimitiveCategory } from "./primitives.js";
+
+export type TypeId = { nsId: number; id: number };
+
+export const LIST_FLAVOR_BY_NAME = {
+    "GLib.List": "glist",
+    "GLib.SList": "gslist",
+    "GLib.PtrArray": "gptrarray",
+    "GLib.Array": "garray",
+    "GLib.ByteArray": "gbytearray",
+} as const;
+
+export type ListFlavor = (typeof LIST_FLAVOR_BY_NAME)[keyof typeof LIST_FLAVOR_BY_NAME];
+
+type PrimitiveType = { kind: "primitive"; category: PrimitiveCategory };
+
+type VarargsType = { kind: "varargs" };
+
+export type CArrayType = {
+    kind: "carray";
+    element: TypeId;
+    elementCType: string | undefined;
+    lengthParameterIndex: number | undefined;
+    fixedSize: number | undefined;
+};
+
+export type ListType = {
+    kind: "list";
+    flavor: ListFlavor;
+    element: TypeId;
+};
+
+export type HashTableType = {
+    kind: "hashtable";
+    key: TypeId;
+    value: TypeId;
+};
+
+export type StructuralType = PrimitiveType | VarargsType | CArrayType | ListType | HashTableType;
+
+export type ParseContext = {
+    nsId: number;
+    findType(name: string): TypeId;
+    addPrimitive(category: PrimitiveCategory): TypeId;
+    addVarargs(): TypeId;
+    addContainer(type: CArrayType | ListType | HashTableType): TypeId;
+    addAnonymousCallback(node: RawNode): TypeId;
+};