@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/gir/parse.ts

@@ -1,31 +1,10 @@
 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;
-};
+import { createXmlParser } from "../xml.js";
+
+type RawNode = Record<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 +12,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,124 +24,151 @@ 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]]);
-
-/**
- * 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,
+const GIR_CONSTRUCTOR_TAG = "gir-constructor";
+const RESERVED_TAG_RENAMES: Map<string, string> = new Map([["constructor", GIR_CONSTRUCTOR_TAG]]);
+const RENAMED_MULTI_TAGS: Set<string> = new Set([...MULTI_TAGS].map((tag) => renameReservedTag(tag)));
+
+const PARSER = createXmlParser({
     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");
+function renameReservedTag(tag: string): string {
+    return RESERVED_TAG_RENAMES.get(tag) ?? tag;
+}
+
+const parseGirFile = (path: string): RawNode => {
+    const xml = readFileSync(path, "utf8");
+
     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 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 isAttrTrue = (node: RawNode | undefined, name: string, isTrueByDefault = false): boolean => {
     const value = attr(node, name);
-    if (value === undefined) return fallback;
+
+    if (value === undefined) {
+        return isTrueByDefault;
+    }
+
     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 nameAttr = (node: RawNode): string => attr(node, "name") ?? "";
+
+const intAttr = (node: RawNode, name: string): number | undefined => {
+    const raw = attr(node, name);
+
+    return raw === undefined ? undefined : Number(raw);
+};
+
+const enumMember = <T extends string>(raw: string, members: Set<T>, label: string): T => {
+    for (const member of members) {
+        if (member === raw) {
+            return member;
+        }
+    }
+
+    throw new Error(`Unknown ${label} value "${raw}"`);
+};
+
+const parseEnumAttr = <T extends string, F extends T | undefined>(
+    raw: string | undefined,
+    members: Set<T>,
+    fallback: F,
+    label: string,
+): T | F => (raw === undefined ? fallback : enumMember(raw, members, label));
+
+const getChildren = (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 (value === undefined) {
+        return [];
+    }
+
+    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 getChild = (node: RawNode | undefined, tag: string): RawNode | undefined => {
+    if (node === undefined) {
+        return undefined;
+    }
+
     const value = node[tag];
-    if (value === undefined) return undefined;
+
+    if (value === undefined) {
+        return undefined;
+    }
+
     if (Array.isArray(value)) {
         return value.length === 0 ? undefined : (value[0] as RawNode);
     }
+
     return value as RawNode;
 };
+
+const normalizeDoc = (text: string): string | undefined => {
+    const trimmed = text.trim();
+
+    return trimmed.length === 0 ? undefined : trimmed;
+};
+
+const firstDocValue = (raw: unknown): unknown => (Array.isArray(raw) ? raw[0] : raw);
+
+const docTextFromObject = (value: object): string | undefined => {
+    const text = (value as RawNode)["#text"];
+
+    return typeof text === "string" ? normalizeDoc(text) : undefined;
+};
+
+const getDoc = (node: RawNode | undefined): string | undefined => {
+    if (node === undefined) {
+        return undefined;
+    }
+
+    const value = firstDocValue(node.doc);
+
+    if (typeof value === "string") {
+        return normalizeDoc(value);
+    }
+
+    if (value === null || typeof value !== "object") {
+        return undefined;
+    }
+
+    return docTextFromObject(value);
+};
+
+export {
+    GIR_CONSTRUCTOR_TAG,
+    parseGirFile,
+    attr,
+    isAttrTrue,
+    nameAttr,
+    intAttr,
+    parseEnumAttr,
+    getChildren,
+    getChild,
+    getDoc,
+    type RawNode,
+};

package/src/gir/primitives.ts

@@ -1,36 +1,24 @@
-/**
- * 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";
+type PrimitiveCategory =
+    | "void" |
+    "boolean" |
+    "int8" |
+    "uint8" |
+    "int16" |
+    "uint16" |
+    "int32" |
+    "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({
+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,7 @@ 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({
+const PRIMITIVE_TS_TYPE: Record<PrimitiveCategory, string> = {
     void: "void",
     boolean: "boolean",
     int8: "number",
@@ -129,9 +102,16 @@ 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",
-});
+};
+
+const primitiveCategory = (name: string): PrimitiveCategory | undefined => PRIMITIVE_BY_NAME.get(name);
+
+export { PRIMITIVE_SIZE, PRIMITIVE_TS_TYPE, primitiveCategory, type PrimitiveCategory };

package/src/gir/property.ts

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

package/src/gir/record.ts

@@ -0,0 +1,55 @@
+import type { ParseContext } from "./type-id.js";
+import { collectFields, type GirField } from "./field.js";
+import { functionFromNode, type GirFunction } from "./function.js";
+import { attr, getChildren, getDoc, GIR_CONSTRUCTOR_TAG, isAttrTrue, type RawNode } from "./parse.js";
+
+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;
+};
+
+const recordFromNode = (
+    node: RawNode,
+    isVtable: boolean,
+    isUnion: boolean,
+    context: ParseContext,
+): GirRecord => ({
+    isVtable,
+    name: attr(node, "name") ?? attr(node, "glib:name") ?? "",
+    doc: getDoc(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: isAttrTrue(node, "disguised"),
+    opaque: isAttrTrue(node, "opaque"),
+    introspectable: isAttrTrue(node, "introspectable", true),
+    fields: collectFields(node, context),
+    methods: getChildren(node, "method").map((method) => functionFromNode(method, context)),
+    constructors: getChildren(node, GIR_CONSTRUCTOR_TAG).map((ctor) => functionFromNode(ctor, context)),
+    functions: getChildren(node, "function").map((fn) => functionFromNode(fn, context)),
+    isUnion,
+});
+
+const isVtableRecord = (node: RawNode): boolean => attr(node, "glib:is-gtype-struct-for") !== undefined;
+
+export { recordFromNode, isVtableRecord, type GirRecord };