@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/gir/size.ts

@@ -1,129 +1,115 @@
 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;
+type FieldLayout = {
+    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 => {
+type FieldSlot = {
+    byteOffset: number;
+    bitOffset: number | undefined;
+    bitWidth: number | undefined;
+};
+
+type FieldLayoutInput = {
+    layout: FieldLayout;
+    bits: number | undefined;
+};
+
+type StructLayoutState = {
+    bitCursor: number;
+    maxAlign: number;
+};
+
+const floorDown = (value: number, multiple: number): number => value - (value % multiple);
+
+const layoutOfPrimitive = (category: PrimitiveCategory): FieldLayout => {
     const size = PRIMITIVE_SIZE[category];
+
     return { size, align: size === 0 ? 1 : size };
 };
 
 const roundUp = (value: number, multiple: number): number => {
-    if (multiple <= 1) return value;
+    if (multiple <= 1) {
+        return value;
+    }
+
     const remainder = value % multiple;
+
     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;
+const computeUnionSlots = (fields: FieldLayoutInput[]): { slots: FieldSlot[]; size: number } => {
+    let maxSize = 0;
+    let maxAlign = 1;
+
+    const slots = fields.map((field) => {
+        maxSize = Math.max(maxSize, field.layout.size);
+        maxAlign = Math.max(maxAlign, field.layout.align);
+
+        return { byteOffset: 0, bitOffset: field.bits === undefined ? undefined : 0, bitWidth: field.bits };
+    });
+
+    return { slots, size: roundUp(maxSize, maxAlign) };
+};
+
+const pushPlainField = (state: StructLayoutState, slots: FieldSlot[], field: FieldLayoutInput, align: number): void => {
+    const byteOffset = roundUp(roundUp(state.bitCursor, 8) / 8, align);
+    slots.push({ byteOffset, bitOffset: undefined, bitWidth: undefined });
+    state.bitCursor = (byteOffset + field.layout.size) * 8;
 };
 
-/**
- * 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;
+// SysV AMD64 places a bit-field at the current bit offset whenever it still fits inside a storage
+// unit of its declared type aligned to that type's alignment, so the unit the cursor already sits in
+// may have room even though the cursor is not on a unit boundary.
+const pushBitfield = (input: {
+    state: StructLayoutState;
+    slots: FieldSlot[];
+    field: FieldLayoutInput;
+    align: number;
+    bits: number;
+}): void => {
+    const { state, slots, field, align, bits } = input;
+    const unitStart = floorDown(floorDown(state.bitCursor, 8) / 8, align);
+    const isFitsInCurrentUnit = state.bitCursor + bits <= (unitStart + field.layout.size) * 8;
+    const byteOffset = isFitsInCurrentUnit ? unitStart : roundUp(roundUp(state.bitCursor, 8) / 8, align);
+
+    if (!isFitsInCurrentUnit) {
+        state.bitCursor = byteOffset * 8;
+    }
+
+    slots.push({ byteOffset, bitOffset: state.bitCursor - byteOffset * 8, bitWidth: bits });
+    state.bitCursor += bits;
 };
 
-/**
- * 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[],
-    isUnion = false,
-): { readonly slots: readonly FieldSlot[]; readonly size: number } => {
-    if (isUnion) {
-        let maxSize = 0;
-        let maxAlign = 1;
-        const unionSlots = fields.map((field) => {
-            maxSize = Math.max(maxSize, field.layout.size);
-            maxAlign = Math.max(maxAlign, field.layout.align);
-            return { byteOffset: 0, bitOffset: field.bits === undefined ? undefined : 0, bitWidth: field.bits };
-        });
-        return { slots: unionSlots, size: roundUp(maxSize, maxAlign) };
+const processStructField = (state: StructLayoutState, slots: FieldSlot[], field: FieldLayoutInput): void => {
+    const align = Math.max(1, field.layout.align);
+
+    if (align > state.maxAlign) {
+        state.maxAlign = align;
+    }
+
+    if (field.bits === undefined) {
+        pushPlainField(state, slots, field, align);
+
+        return;
     }
+
+    pushBitfield({ state, slots, field, align, bits: field.bits });
+};
+
+const computeStructSlots = (fields: FieldLayoutInput[]): { slots: FieldSlot[]; size: number } => {
     const slots: FieldSlot[] = [];
-    let cursor = 0;
-    let maxAlign = 1;
-    let bitfieldWordOffset: number | undefined;
-    let bitfieldWordSize = 0;
-    let bitfieldUsedBits = 0;
+    const state: StructLayoutState = { bitCursor: 0, maxAlign: 1 };
+
     for (const field of fields) {
-        const align = Math.max(1, field.layout.align);
-        if (align > maxAlign) maxAlign = align;
-        if (field.bits === undefined) {
-            bitfieldWordOffset = undefined;
-            bitfieldWordSize = 0;
-            bitfieldUsedBits = 0;
-            cursor = roundUp(cursor, align);
-            slots.push({ byteOffset: cursor, bitOffset: undefined, bitWidth: undefined });
-            cursor += field.layout.size;
-            continue;
-        }
-        const wordSizeBits = field.layout.size * 8;
-        const fits =
-            bitfieldWordOffset !== undefined &&
-            bitfieldWordSize === field.layout.size &&
-            bitfieldUsedBits + field.bits <= wordSizeBits;
-        if (!fits) {
-            cursor = roundUp(cursor, align);
-            bitfieldWordOffset = cursor;
-            bitfieldWordSize = field.layout.size;
-            bitfieldUsedBits = 0;
-            cursor += field.layout.size;
-        }
-        slots.push({
-            byteOffset: bitfieldWordOffset ?? 0,
-            bitOffset: bitfieldUsedBits,
-            bitWidth: field.bits,
-        });
-        bitfieldUsedBits += field.bits;
+        processStructField(state, slots, field);
     }
-    return { slots, size: roundUp(cursor, maxAlign) };
+
+    return { slots, size: roundUp(roundUp(state.bitCursor, 8) / 8, state.maxAlign) };
 };
+
+const computeFieldSlots = (fields: FieldLayoutInput[], isUnion = false): { slots: FieldSlot[]; size: number } =>
+    isUnion ? computeUnionSlots(fields) : computeStructSlots(fields);
+
+export { layoutOfPrimitive, computeFieldSlots, type FieldLayout, type FieldSlot, type FieldLayoutInput };

package/src/gir/type-id.ts

@@ -0,0 +1,64 @@
+import type { RawNode } from "./parse.js";
+import type { PrimitiveCategory } from "./primitives.js";
+
+type TypeId = { nsId: number; id: number };
+type ListFlavor = (typeof LIST_FLAVOR_BY_NAME)[keyof typeof LIST_FLAVOR_BY_NAME];
+type PrimitiveType = { kind: "primitive"; category: PrimitiveCategory };
+type VarargsType = { kind: "varargs" };
+
+type CArrayType = {
+    kind: "carray";
+    element: TypeId;
+    elementCType: string | undefined;
+    lengthParameterIndex: number | undefined;
+    fixedSize: number | undefined;
+    zeroTerminated: boolean;
+};
+
+type ListType = {
+    kind: "list";
+    flavor: ListFlavor;
+    element: TypeId;
+};
+
+type HashTableType = {
+    kind: "hashtable";
+    key: TypeId;
+    value: TypeId;
+};
+
+type StructuralType = PrimitiveType | VarargsType | CArrayType | ListType | HashTableType;
+
+type ParseContext = {
+    nsId: number;
+    findType(name: string): TypeId;
+    addPrimitive(category: PrimitiveCategory): TypeId;
+    addVarargs(): TypeId;
+    addContainer(type: CArrayType | ListType | HashTableType): TypeId;
+    addAnonymousCallback(node: RawNode): TypeId;
+};
+
+const LIST_FLAVOR_BY_NAME = {
+    "GLib.List": "glist",
+    "GLib.SList": "gslist",
+    "GLib.PtrArray": "gptrarray",
+    "GLib.Array": "garray",
+    "GLib.ByteArray": "gbytearray",
+} as const;
+
+// An array with no length parameter, no fixed size and an explicit `zero-terminated="0"` carries no
+// way to recover its length, so it is a bare pointer rather than something that can be walked.
+const hasUnknownArrayLength = (ref: CArrayType): boolean =>
+    !ref.zeroTerminated && ref.lengthParameterIndex === undefined && ref.fixedSize === undefined;
+
+export {
+    hasUnknownArrayLength,
+    LIST_FLAVOR_BY_NAME,
+    type TypeId,
+    type ListFlavor,
+    type CArrayType,
+    type ListType,
+    type HashTableType,
+    type StructuralType,
+    type ParseContext,
+};

package/src/gir/type-ref.ts

@@ -1,180 +1,111 @@
-import { attr, attrBool, childOf, childrenOf, type RawNode } from "./parse.js";
-import { type PrimitiveCategory, primitiveCategory } from "./primitives.js";
-
-/**
- * Lazily-resolved reference to a GIR type as it appears in a `<type>` or
- * `<array>` slot.
- *
- * The reference captures everything the writers need at emission time
- * without forcing entity resolution to happen at parse time (which would
- * impose a topological-sort order on namespace loading). Resolution into a
- * concrete `GirClass` / `GirBoxed` / `GirEnum` / … is performed on demand
- * by the writers via `GirRepository.resolveNamed`.
- */
-export type GirTypeRef =
-    | PrimitiveTypeRef
-    | NamedTypeRef
-    | ArrayTypeRef
-    | ListTypeRef
-    | HashTableTypeRef
-    | InlineCallbackTypeRef
-    | VarargsTypeRef;
-
-/** A GIR scalar primitive: `gint`, `gboolean`, `utf8`, `gpointer`, etc. */
-export type PrimitiveTypeRef = {
-    readonly kind: "primitive";
-    readonly category: PrimitiveCategory;
-    readonly cType: string | undefined;
-};
+import { attr, getChild, getChildren, intAttr, isAttrTrue, nameAttr, type RawNode } from "./parse.js";
+import { primitiveCategory } from "./primitives.js";
+import { type CArrayType, LIST_FLAVOR_BY_NAME, type ListFlavor, type ParseContext, type TypeId } from "./type-id.js";
 
-/**
- * A named type that resolves to a class, interface, boxed, enum, alias, or
- * fundamental in some namespace.
- *
- * `namespaceName` is the namespace prefix from the GIR (`"GLib"`, `"Gtk"`,
- * …) or `undefined` for an unqualified reference. The unqualified form
- * implies "look in the namespace the reference appears in".
- */
-export type NamedTypeRef = {
-    readonly kind: "named";
-    readonly namespaceName: string | undefined;
-    readonly typeName: string;
-    readonly cType: string | undefined;
-};
+const LIST_FLAVOR_BY_NAME_LOOKUP: Map<string, ListFlavor> = new Map(Object.entries(LIST_FLAVOR_BY_NAME));
 
-/** A C array (`<array>`) with optional length, fixed-size, or zero-terminated metadata. */
-export type ArrayTypeRef = {
-    readonly kind: "array";
-    readonly element: GirTypeRef;
-    readonly cType: string | undefined;
-    readonly lengthParameterIndex: number | undefined;
-    readonly fixedSize: number | undefined;
-    readonly zeroTerminated: boolean;
-};
+const getElementRef = (node: RawNode, context: ParseContext): TypeId => {
+    const elementNode = getChild(node, "type");
 
-/** A GLib `GList` / `GSList` / `GPtrArray` / `GArray` / `GByteArray`. */
-export type ListTypeRef = {
-    readonly kind: "list";
-    readonly flavor: "glist" | "gslist" | "gptrarray" | "garray" | "gbytearray";
-    readonly element: GirTypeRef;
-    readonly cType: string | undefined;
+    return elementNode === undefined ? pointerFallback(context) : typeRefFromTypeNode(elementNode, context);
 };
 
-/** A GLib `GHashTable` with key and value element types. */
-export type HashTableTypeRef = {
-    readonly kind: "hashtable";
-    readonly key: GirTypeRef;
-    readonly value: GirTypeRef;
-    readonly cType: string | undefined;
-};
+const typeRefFromNode = (parent: RawNode | undefined, context: ParseContext): TypeId | undefined => {
+    if (parent === undefined) {
+        return undefined;
+    }
 
-/** An inline `<callback>` (used for vtable slots and callback parameters). */
-type InlineCallbackTypeRef = {
-    readonly kind: "callback";
-    readonly callback: RawNode;
-};
+    if (getChild(parent, "varargs") !== undefined) {
+        return context.addVarargs();
+    }
+
+    const arrayNode = getChild(parent, "array");
+
+    if (arrayNode !== undefined) {
+        return arrayTypeRefFromNode(arrayNode, context);
+    }
+
+    const typeNode = getChild(parent, "type");
+
+    if (typeNode !== undefined) {
+        return typeRefFromTypeNode(typeNode, context);
+    }
+
+    const callback = getChild(parent, "callback");
+
+    if (callback !== undefined) {
+        return context.addAnonymousCallback(callback);
+    }
 
-/** A `<varargs/>` parameter placeholder; not marshalable. */
-type VarargsTypeRef = { readonly kind: "varargs" };
-
-const LIST_KIND_BY_NAME: ReadonlyMap<string, "glist" | "gslist" | "gptrarray" | "garray" | "gbytearray"> = new Map([
-    ["GLib.List", "glist"],
-    ["GLib.SList", "gslist"],
-    ["GLib.PtrArray", "gptrarray"],
-    ["GLib.Array", "garray"],
-    ["GLib.ByteArray", "gbytearray"],
-] as const);
-
-/**
- * Builds a {@link GirTypeRef} from a parent XML node whose first `<type>`,
- * `<array>`, or `<varargs>` child describes the slot.
- *
- * Pass the parent (`<parameter>`, `<return-value>`, `<field>`, `<property>`,
- * `<constant>`, `<alias>`). The helper extracts the right child and routes
- * to {@link typeRefFromTypeNode}.
- *
- * @param parent - The element whose typed slot we are inspecting
- * @returns The reference, or `undefined` if no type slot exists
- */
-export const typeRefFromSlot = (parent: RawNode | undefined): GirTypeRef | undefined => {
-    if (parent === undefined) return undefined;
-    if (childOf(parent, "varargs") !== undefined) return { kind: "varargs" };
-    const arrayNode = childOf(parent, "array");
-    if (arrayNode !== undefined) return arrayTypeRefFromNode(arrayNode);
-    const typeNode = childOf(parent, "type");
-    if (typeNode !== undefined) return typeRefFromTypeNode(typeNode);
-    const callback = childOf(parent, "callback");
-    if (callback !== undefined) return { kind: "callback", callback };
     return undefined;
 };
 
-/**
- * Builds a {@link GirTypeRef} from a `<type>` element.
- *
- * Splits a `Namespace.TypeName` form into namespace + type, recognises GLib
- * container types (`GLib.List`, `GLib.HashTable`, …) by name and routes
- * them to the dedicated branches, otherwise produces a primitive or named
- * reference for later resolution.
- *
- * @param typeNode - A `<type>` element
- */
-const typeRefFromTypeNode = (typeNode: RawNode): GirTypeRef => {
-    const name = attr(typeNode, "name") ?? "";
-    const cType = attr(typeNode, "c:type");
-
-    const listFlavor = LIST_KIND_BY_NAME.get(name);
+const hashTableRefFromNode = (typeNode: RawNode, context: ParseContext): TypeId => {
+    const elementTypes = getChildren(typeNode, "type");
+    const keyNode = elementTypes[0];
+    const valueNode = elementTypes[1];
+
+    return context.addContainer({
+        kind: "hashtable",
+        key: keyNode === undefined ? pointerFallback(context) : typeRefFromTypeNode(keyNode, context),
+        value: valueNode === undefined ? pointerFallback(context) : typeRefFromTypeNode(valueNode, context),
+    });
+};
+
+const typeRefFromTypeNode = (typeNode: RawNode, context: ParseContext): TypeId => {
+    const name = nameAttr(typeNode);
+    const listFlavor = LIST_FLAVOR_BY_NAME_LOOKUP.get(name);
+
     if (listFlavor !== undefined) {
-        const elementNode = childOf(typeNode, "type");
-        const element = elementNode === undefined ? pointerFallback() : typeRefFromTypeNode(elementNode);
-        return { kind: "list", flavor: listFlavor, element, cType };
+        return context.addContainer({ kind: "list", flavor: listFlavor, element: getElementRef(typeNode, context) });
     }
 
     if (name === "GLib.HashTable") {
-        const elementTypes = childrenOf(typeNode, "type");
-        const keyNode = elementTypes[0];
-        const valueNode = elementTypes[1];
-        return {
-            kind: "hashtable",
-            key: keyNode === undefined ? pointerFallback() : typeRefFromTypeNode(keyNode),
-            value: valueNode === undefined ? pointerFallback() : typeRefFromTypeNode(valueNode),
-            cType,
-        };
+        return hashTableRefFromNode(typeNode, context);
     }
 
     const primitive = primitiveCategory(name);
+
     if (primitive !== undefined) {
-        return { kind: "primitive", category: primitive, cType };
+        return context.addPrimitive(primitive);
     }
 
-    const [namespaceName, typeName] = splitOptionalNamespace(name);
-    return { kind: "named", namespaceName, typeName, cType };
+    return context.findType(name);
 };
 
-const arrayTypeRefFromNode = (arrayNode: RawNode): ArrayTypeRef | ListTypeRef => {
-    const elementNode = childOf(arrayNode, "type");
-    const element: GirTypeRef = elementNode === undefined ? pointerFallback() : typeRefFromTypeNode(elementNode);
-    const cType = attr(arrayNode, "c:type");
+const arrayTypeRefFromNode = (arrayNode: RawNode, context: ParseContext): TypeId => {
+    const element = getElementRef(arrayNode, context);
     const arrayName = attr(arrayNode, "name");
-    const listFlavor = arrayName === undefined ? undefined : LIST_KIND_BY_NAME.get(arrayName);
+    const listFlavor = arrayName === undefined ? undefined : LIST_FLAVOR_BY_NAME_LOOKUP.get(arrayName);
+
     if (listFlavor !== undefined) {
-        return { kind: "list", flavor: listFlavor, element, cType };
+        return context.addContainer({ kind: "list", flavor: listFlavor, element });
     }
-    const lengthAttr = attr(arrayNode, "length");
-    const fixedSizeAttr = attr(arrayNode, "fixed-size");
-    return {
-        kind: "array",
+
+    const elementNode = getChild(arrayNode, "type");
+
+    const carray: CArrayType = {
+        kind: "carray",
         element,
-        cType,
-        lengthParameterIndex: lengthAttr === undefined ? undefined : Number.parseInt(lengthAttr, 10),
-        fixedSize: fixedSizeAttr === undefined ? undefined : Number.parseInt(fixedSizeAttr, 10),
-        zeroTerminated: attrBool(arrayNode, "zero-terminated", false),
+        elementCType: elementNode === undefined ? undefined : attr(elementNode, "c:type"),
+        lengthParameterIndex: intAttr(arrayNode, "length"),
+        fixedSize: intAttr(arrayNode, "fixed-size"),
+        zeroTerminated: isAttrTrue(arrayNode, "zero-terminated", true),
     };
+
+    return context.addContainer(carray);
 };
 
-const pointerFallback = (): PrimitiveTypeRef => ({ kind: "primitive", category: "pointer", cType: undefined });
+const pointerFallback = (context: ParseContext): TypeId => context.addPrimitive("pointer");
 
 const splitOptionalNamespace = (name: string): [string | undefined, string] => {
     const dot = name.indexOf(".");
-    if (dot === -1) return [undefined, name];
+
+    if (dot === -1) {
+        return [undefined, name];
+    }
+
     return [name.slice(0, dot), name.slice(dot + 1)];
 };
+
+export { typeRefFromNode, splitOptionalNamespace };

package/src/gir/type.ts

@@ -0,0 +1,18 @@
+import type { GirCallback } from "./callback.js";
+import type { GirClass } from "./class.js";
+import type { GirEnum } from "./enum.js";
+import type { GirAlias, GirNamespace } from "./namespace.js";
+import type { GirRecord } from "./record.js";
+import type { StructuralType } from "./type-id.js";
+
+type EntityType =
+    | { kind: "class"; namespace: GirNamespace; value: GirClass } |
+    { kind: "interface"; namespace: GirNamespace; value: GirClass } |
+    { kind: "record"; namespace: GirNamespace; value: GirRecord } |
+    { kind: "enum"; namespace: GirNamespace; value: GirEnum } |
+    { kind: "callback"; namespace: GirNamespace; value: GirCallback } |
+    { kind: "alias"; namespace: GirNamespace; value: GirAlias };
+
+type GirType = StructuralType | EntityType;
+
+export { type EntityType, type GirType };

package/src/index.ts

@@ -1,16 +1,28 @@
-/**
- * Public API of `@gtkx/codegen`.
- *
- * The package exposes a single entry point — {@link CodegenRunner} — that
- * orchestrates the GIR-driven code generation for the FFI and React
- * surfaces. Internal modules (`gir/`, `dsl/`, `writers/`, `ffi/`,
- * `react/`) are not part of the supported surface and may change in any
- * release.
- */
 export {
-    CODEGEN_VERSION,
-    type CodegenFingerprint,
-    computeFingerprint,
-    FINGERPRINT_FILENAME,
-} from "./fingerprint.js";
-export { CodegenRunner } from "./runner.js";
+    API_SYMBOL_KINDS,
+    type ApiLookupResult,
+    type ApiNamespaceSummary,
+    type ApiReference,
+    type ApiReferenceOptions,
+    type ApiSearchOptions,
+    type ApiSymbol,
+    type ApiSymbolKind,
+    loadApiReference,
+} from "./docs/api-reference.js";
+export {
+    type DocsElementLink,
+    type DocsNamespace,
+    type DocsOptions,
+    type DocsResult,
+    writeDocs,
+} from "./docs/pipeline.js";
+export { resolveGirPath } from "./gir/gir-path.js";
+export { discoverGirNamespaces, resolveLibraries } from "./gir/libraries.js";
+export {
+    type BuiltinElement,
+    type BuiltinElements,
+    type ModuleExport,
+    readBuiltinElements,
+} from "./react/element-config.js";
+export { runCodegen } from "./runner.js";
+export type { ElementProps } from "./store/jsx/element-prop-imports.js";