@gtkx/codegen 1.0.0-rc.1 → 1.0.0-rc.3

package/src/gir/record.ts

@@ -1,9 +1,9 @@
-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";
+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";
 
-export type GirRecord = {
+type GirRecord = {
     isVtable: boolean;
     name: string;
     doc: string | undefined;
@@ -24,7 +24,7 @@ export type GirRecord = {
     isUnion: boolean;
 };
 
-export const recordFromNode = (
+const recordFromNode = (
     node: RawNode,
     isVtable: boolean,
     isUnion: boolean,
@@ -32,7 +32,7 @@ export const recordFromNode = (
 ): GirRecord => ({
     isVtable,
     name: attr(node, "name") ?? attr(node, "glib:name") ?? "",
-    doc: docOf(node),
+    doc: getDoc(node),
     cType: attr(node, "c:type"),
     glibTypeName: attr(node, "glib:type-name"),
     glibGetType: attr(node, "glib:get-type"),
@@ -40,14 +40,16 @@ export const recordFromNode = (
     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)),
+    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,
 });
 
-export const isVtableRecord = (node: RawNode): boolean => attr(node, "glib:is-gtype-struct-for") !== undefined;
+const isVtableRecord = (node: RawNode): boolean => attr(node, "glib:is-gtype-struct-for") !== undefined;
+
+export { recordFromNode, isVtableRecord, type GirRecord };

package/src/gir/size.ts

@@ -1,82 +1,115 @@
 import { PRIMITIVE_SIZE, type PrimitiveCategory } from "./primitives.js";
 
-export type FieldLayout = {
+type FieldLayout = {
     size: number;
     align: number;
 };
 
-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);
 };
 
-export type FieldSlot = {
-    byteOffset: number;
-    bitOffset: number | undefined;
-    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) };
 };
 
-export type FieldLayoutInput = {
-    layout: FieldLayout;
-    bits: number | undefined;
+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;
 };
 
-export const computeFieldSlots = (
-    fields: FieldLayoutInput[],
-    isUnion = false,
-): { slots: FieldSlot[]; 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) };
+// 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;
+};
+
+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

@@ -1,45 +1,35 @@
 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 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" };
 
-export type CArrayType = {
+type CArrayType = {
     kind: "carray";
     element: TypeId;
     elementCType: string | undefined;
     lengthParameterIndex: number | undefined;
     fixedSize: number | undefined;
+    zeroTerminated: boolean;
 };
 
-export type ListType = {
+type ListType = {
     kind: "list";
     flavor: ListFlavor;
     element: TypeId;
 };
 
-export type HashTableType = {
+type HashTableType = {
     kind: "hashtable";
     key: TypeId;
     value: TypeId;
 };
 
-export type StructuralType = PrimitiveType | VarargsType | CArrayType | ListType | HashTableType;
+type StructuralType = PrimitiveType | VarargsType | CArrayType | ListType | HashTableType;
 
-export type ParseContext = {
+type ParseContext = {
     nsId: number;
     findType(name: string): TypeId;
     addPrimitive(category: PrimitiveCategory): TypeId;
@@ -47,3 +37,28 @@ export type ParseContext = {
     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,46 +1,71 @@
-import { attr, childOf, childrenOf, intAttr, nameAttr, type RawNode } from "./parse.js";
+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";
 
 const LIST_FLAVOR_BY_NAME_LOOKUP: Map<string, ListFlavor> = new Map(Object.entries(LIST_FLAVOR_BY_NAME));
 
-const elementRefOf = (node: RawNode, context: ParseContext): TypeId => {
-    const elementNode = childOf(node, "type");
+const getElementRef = (node: RawNode, context: ParseContext): TypeId => {
+    const elementNode = getChild(node, "type");
+
     return elementNode === undefined ? pointerFallback(context) : typeRefFromTypeNode(elementNode, context);
 };
 
-export const typeRefFromNode = (parent: RawNode | undefined, context: ParseContext): TypeId | undefined => {
-    if (parent === undefined) return undefined;
-    if (childOf(parent, "varargs") !== undefined) return context.addVarargs();
-    const arrayNode = childOf(parent, "array");
-    if (arrayNode !== undefined) return arrayTypeRefFromNode(arrayNode, context);
-    const typeNode = childOf(parent, "type");
-    if (typeNode !== undefined) return typeRefFromTypeNode(typeNode, context);
-    const callback = childOf(parent, "callback");
-    if (callback !== undefined) return context.addAnonymousCallback(callback);
+const typeRefFromNode = (parent: RawNode | undefined, context: ParseContext): TypeId | undefined => {
+    if (parent === undefined) {
+        return undefined;
+    }
+
+    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);
+    }
+
     return undefined;
 };
 
+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) {
-        return context.addContainer({ kind: "list", flavor: listFlavor, element: elementRefOf(typeNode, context) });
+        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 context.addContainer({
-            kind: "hashtable",
-            key: keyNode === undefined ? pointerFallback(context) : typeRefFromTypeNode(keyNode, context),
-            value: valueNode === undefined ? pointerFallback(context) : typeRefFromTypeNode(valueNode, context),
-        });
+        return hashTableRefFromNode(typeNode, context);
     }
 
     const primitive = primitiveCategory(name);
+
     if (primitive !== undefined) {
         return context.addPrimitive(primitive);
     }
@@ -49,27 +74,38 @@ const typeRefFromTypeNode = (typeNode: RawNode, context: ParseContext): TypeId =
 };
 
 const arrayTypeRefFromNode = (arrayNode: RawNode, context: ParseContext): TypeId => {
-    const element = elementRefOf(arrayNode, context);
+    const element = getElementRef(arrayNode, context);
     const arrayName = attr(arrayNode, "name");
     const listFlavor = arrayName === undefined ? undefined : LIST_FLAVOR_BY_NAME_LOOKUP.get(arrayName);
+
     if (listFlavor !== undefined) {
         return context.addContainer({ kind: "list", flavor: listFlavor, element });
     }
-    const elementNode = childOf(arrayNode, "type");
+
+    const elementNode = getChild(arrayNode, "type");
+
     const carray: CArrayType = {
         kind: "carray",
         element,
         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 = (context: ParseContext): TypeId => context.addPrimitive("pointer");
 
-export const splitOptionalNamespace = (name: string): [string | undefined, string] => {
+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

@@ -5,12 +5,14 @@ import type { GirAlias, GirNamespace } from "./namespace.js";
 import type { GirRecord } from "./record.js";
 import type { StructuralType } from "./type-id.js";
 
-export 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 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 };
 
-export type GirType = StructuralType | EntityType;
+type GirType = StructuralType | EntityType;
+
+export { type EntityType, type GirType };

package/src/index.ts

@@ -18,4 +18,12 @@ export {
 } 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";
+export { mergeOmitProps, type OmittedProps } from "./store/jsx/omitted-props.js";

package/src/jsx.ts

@@ -0,0 +1,75 @@
+import type { Library } from "./gir/library.js";
+import {
+    computeJsxFingerprint,
+    FINGERPRINT_FILENAME,
+    type JsxFingerprintInput,
+    jsxStoreFreshness,
+} from "./fingerprint.js";
+import { type ModuleExport, readBuiltinElements } from "./react/element-config.js";
+import { type JsxStoreOptions, writeJsxStore } from "./store/jsx-store.js";
+import { mergeOmitProps, type OmittedProps } from "./store/jsx/omitted-props.js";
+import { generateJsxFiles } from "./store/jsx/pipeline.js";
+
+type RunJsxCodegenOptions = {
+    getLibrary: () => Library;
+    jsx: JsxStoreOptions;
+    giStoreDir: string;
+    reactSubexports: string[];
+    userComponents: Record<string, ModuleExport>;
+    userLazyElements: string[];
+    userProps: Record<string, ModuleExport>;
+    userOmitProps: OmittedProps;
+    giRegenerated: boolean;
+    force: boolean;
+};
+
+type RunJsxCodegenResult = {
+    regenerated: boolean;
+    intrinsicElementCount: number;
+};
+
+/**
+ * Generates the `@gtkx/jsx` store, reading the framework's built-in element config from the freshly
+ * linked `@gtkx/react` and layering the project's own element config over it. This is the react-importing
+ * half of codegen: it must run only after the gi store has been written and linked.
+ */
+const runJsxCodegen = async (options: RunJsxCodegenOptions): Promise<RunJsxCodegenResult> => {
+    const builtin = await readBuiltinElements(options.reactSubexports, options.giStoreDir);
+    const components = { ...builtin.components, ...options.userComponents };
+    const lazyElements = [...builtin.lazyElements, ...options.userLazyElements];
+    const props = { ...builtin.props, ...options.userProps };
+    const omitProps = mergeOmitProps(builtin.omitProps, options.userOmitProps);
+
+    const fingerprintInput: JsxFingerprintInput = {
+        reactVersion: options.jsx.version,
+        components,
+        lazyElements,
+        props,
+        omitProps,
+    };
+
+    if (!options.force && !options.giRegenerated) {
+        const { fresh, intrinsicElementCount } = jsxStoreFreshness(options.jsx.storeDir, fingerprintInput);
+
+        if (fresh) {
+            return { regenerated: false, intrinsicElementCount };
+        }
+    }
+
+    const { namespaces, metadata, intrinsicElementCount } = generateJsxFiles(options.getLibrary(), {
+        reactSubexports: options.reactSubexports,
+        components,
+        lazyElements,
+        props,
+        omitProps,
+    });
+
+    writeJsxStore(options.jsx, namespaces, metadata, {
+        relativePath: FINGERPRINT_FILENAME,
+        content: `${JSON.stringify(computeJsxFingerprint(fingerprintInput, intrinsicElementCount), null, 2)}\n`,
+    });
+
+    return { regenerated: true, intrinsicElementCount };
+};
+
+export { runJsxCodegen, type RunJsxCodegenOptions, type RunJsxCodegenResult };