@gtkx/codegen 1.0.0-rc.3 → 1.0.0

package/src/store/gi/record-layout.ts

@@ -20,10 +20,6 @@ type RecordFieldSlot = {
 const POINTER_LAYOUT: FieldLayout = { size: 8, align: 8 };
 const recordLayoutCache: Map<string, FieldLayout> = new Map();
 
-// GIR carries no alignment attribute, and a type whose alignment exceeds its widest member cannot be
-// derived from the field list: Graphene models `graphene_simd4f_t` as four `gfloat`, which computes
-// to align 4 while the real type is a 16-byte SIMD vector. Keying the override on `c:type` keeps it
-// to the handful of types where the XML genuinely cannot express the ABI.
 const ALIGNMENT_OVERRIDES: Map<string, FieldLayout> = new Map([
     ["graphene_simd4f_t", { size: 16, align: 16 }],
     ["graphene_simd4x4f_t", { size: 64, align: 16 }],
@@ -70,7 +66,7 @@ const mergeBitfield = (readExpr: string, valueExpr: string, mask: number, shift:
 
 const fieldLayoutInput = (context: ModuleContext, field: GirField, visited: Set<string>): FieldLayoutInput => {
     if (field.inlineMembers !== undefined) {
-        const layout = inlineMemberLayout(context, field.inlineMembers, field.inlineIsUnion, visited);
+        const layout = inlineMemberLayout(context, field.inlineMembers, field.isInlineUnion, visited);
 
         return { layout, bits: undefined };
     }

package/src/store/gi/record.ts

@@ -1,8 +1,8 @@
 import type { GirRecord } from "../../gir/record.js";
 import type { ModuleContext } from "../../writer/context.js";
-import { renderJsDoc } from "../../writer/doc.js";
 import { indentMembers } from "../../writer/emit.js";
 import { type Callables, dedupeCallables, generateBindings, renderPlainTypeMembers } from "./callables.js";
+import { getDoc } from "./doc-spec.js";
 import { renderSourceGtype } from "./gtype-binding.js";
 import { renderRecordConstructor, renderRecordConstructorPropsInterface } from "./record-constructor.js";
 import { renderRecordFieldAccessor } from "./record-field-accessor.js";
@@ -34,7 +34,13 @@ const generateRecord = (context: ModuleContext, record: GirRecord): void => {
     const members = renderRecordMembers(context, record, className, callables);
     const body = indentMembers(members);
     const heritage = isErrorSubclass ? " extends globalThis.Error" : "";
-    context.module.appendDeclaration(`${renderJsDoc(record.doc)}export class ${className}${heritage} {\n${body}\n}`);
+    const doc = getDoc(record);
+
+    context.module.appendDeclaration(
+        `${doc}export class ${className}${heritage} {\n${body}\n}`,
+        context.declaredType(className),
+    );
+
     context.module.appendDeclaration(renderRecordConstructorPropsInterface(context, record, className));
     const gtypeExpr = renderSourceGtype(context, record);
 

package/src/store/gi/registration.ts

@@ -10,7 +10,7 @@ type InterfaceRegistration = {
     className: string;
     makerName: string;
     gtypeExpr?: string | undefined;
-    vfuncs?: string | undefined;
+    layout?: string | undefined;
 };
 
 const appendWrapperClassRegistration = (
@@ -29,7 +29,7 @@ const appendWrapperClassRegistration = (
 };
 
 const appendInterfaceRegistration = (context: ModuleContext, registration: InterfaceRegistration): void => {
-    const { className, makerName, gtypeExpr, vfuncs } = registration;
+    const { className, makerName, gtypeExpr, layout } = registration;
 
     if (gtypeExpr === undefined) {
         return;
@@ -37,7 +37,7 @@ const appendInterfaceRegistration = (context: ModuleContext, registration: Inter
 
     context.addRuntimeImport("registerInterface");
     const base = `${className}, ${gtypeExpr}, ${makerName}`;
-    const args = vfuncs === undefined ? base : `${base}, ${vfuncs}`;
+    const args = layout === undefined ? base : `${base}, ${layout}`;
     context.module.appendRegistration(`registerInterface(${args});`);
 };
 

package/src/store/gi/return-wrap.ts

@@ -6,14 +6,14 @@ import { renderTsType } from "../../analysis/ts-type.js";
 
 type WrapReturnOptions = {
     ref: TypeId | undefined;
-    nullable: boolean;
+    isNullable: boolean;
     valueExpression: string;
 };
 
 const BIGINT_CATEGORIES: Set<PrimitiveCategory> = new Set(["gtype", "bigint64", "biguint64"]);
 
 const wrapReturnValue = (context: ModuleContext, options: WrapReturnOptions): string => {
-    const { ref, nullable, valueExpression } = options;
+    const { ref, isNullable, valueExpression } = options;
 
     if (ref === undefined) {
         return valueExpression;
@@ -27,7 +27,7 @@ const wrapReturnValue = (context: ModuleContext, options: WrapReturnOptions): st
 
     switch (type.kind) {
         case "primitive": {
-            return wrapPrimitive(type.category, nullable, valueExpression);
+            return wrapPrimitive(type.category, isNullable, valueExpression);
         }
         case "varargs": {
             return `(${valueExpression} as unknown[])`;
@@ -39,7 +39,7 @@ const wrapReturnValue = (context: ModuleContext, options: WrapReturnOptions): st
             return `(${valueExpression} as number)`;
         }
         case "alias": {
-            return wrapAlias(context, type.value.target, nullable, valueExpression);
+            return wrapAlias(context, type.value.target, isNullable, valueExpression);
         }
         case "carray":
         case "class":
@@ -65,7 +65,7 @@ const wrapAlias = (
 ): string =>
     target === undefined
         ? valueExpression
-        : wrapReturnValue(context, { ref: target, nullable: isNullable, valueExpression });
+        : wrapReturnValue(context, { ref: target, isNullable, valueExpression });
 
 const wrapValue = (context: ModuleContext, ref: TypeId, valueExpression: string): string => {
     context.addRuntimeImport("fromNative");

package/src/store/gi/runtime-override.ts

@@ -5,6 +5,7 @@ type RuntimeOverride = {
     signature: string;
     returnType: string;
     body: string;
+    renames?: [string, string][];
 };
 
 const RUNTIME_OVERRIDES: Map<string, RuntimeOverride> = new Map([
@@ -23,16 +24,22 @@ const RUNTIME_OVERRIDES: Map<string, RuntimeOverride> = new Map([
             signature: "boxed: object | null",
             returnType: "void",
             body: 'throw new Error("g_value_set_boxed: runtime override not installed");',
+            renames: [["v_boxed", "boxed"]],
         },
     ],
 ]);
 
-const renderRuntimeOverride = (callable: GirFunction, memberName: string): string | undefined => {
-    if (callable.cIdentifier === undefined) {
-        return undefined;
-    }
+const runtimeOverrideFor = (callable: GirFunction): RuntimeOverride | undefined =>
+    callable.cIdentifier === undefined ? undefined : RUNTIME_OVERRIDES.get(callable.cIdentifier);
+
+const runtimeOverrideRenames = (callable: GirFunction): Map<string, string> | undefined => {
+    const renames = runtimeOverrideFor(callable)?.renames;
 
-    const override = RUNTIME_OVERRIDES.get(callable.cIdentifier);
+    return renames === undefined ? undefined : new Map(renames);
+};
+
+const renderRuntimeOverride = (callable: GirFunction, memberName: string): string | undefined => {
+    const override = runtimeOverrideFor(callable);
 
     if (override === undefined) {
         return undefined;
@@ -43,4 +50,4 @@ const renderRuntimeOverride = (callable: GirFunction, memberName: string): strin
     return `${memberName}${generics}(${override.signature}): ${override.returnType} {\n    ${override.body}\n}`;
 };
 
-export { renderRuntimeOverride };
+export { renderRuntimeOverride, runtimeOverrideRenames };

package/src/store/gi/signal.ts

@@ -13,22 +13,23 @@ import { tCallback, tObject, tVoid } from "../../analysis/descriptor.js";
 import {
     collectInterfaceProperties,
     forEachAncestor,
-    resolveImplementedInterface,
     resolvePrerequisiteReference,
 } from "../../analysis/inheritance.js";
 import { renderHandlerParameters, renderHandlerResultType } from "../../analysis/param-structure.js";
 import { renderTsType } from "../../analysis/ts-type.js";
+import { resolveInterfaces } from "../../gir/ancestry.js";
 import { isCallerAllocatedOut, isOutParameter } from "../../gir/parameter.js";
 import { renderJsDoc } from "../../writer/doc.js";
 import { indent, renderBlock, renderBracedOrEmpty } from "../../writer/emit.js";
 import { parentCompanionRef } from "./companion.js";
+import { getDoc, handlerSpec } from "./doc-spec.js";
 import { isRecordCallerOut, isRecordInout } from "./param-marshal.js";
 
 type SignalMapSpec = {
     context: ModuleContext;
     klass: GirClass;
     className: string;
-    parentlessExtendsObject: boolean;
+    isParentlessObjectSubclass: boolean;
     suffix: string;
     renderEntry: (context: ModuleContext, signal: GirCallable) => string;
 };
@@ -66,7 +67,7 @@ const renderSignalMembers = (context: ModuleContext, klass: GirClass): string[]
 
     const connectDefault = isRootObject
         ? "default:\n    throw new globalThis.Error(\"Unknown signal '\" + signal + \"'\");"
-        : "default:\n    return super.connect(signal, handler, after);";
+        : "default:\n    return super.connect(signal, handler, isAfter);";
 
     const emitDefault = isRootObject
         ? "default:\n    throw new globalThis.Error(\"Unknown signal '\" + sigName + \"'\");"
@@ -78,7 +79,10 @@ const renderSignalMembers = (context: ModuleContext, klass: GirClass): string[]
     const emitSwitch = `switch (getSignalBaseName(sigName)) {\n${emitBody}\n}`;
 
     return [
-        renderBlock(`connect(signal: string, handler: ${SIGNAL_HANDLER_TYPE}, after?: boolean): number`, connectSwitch),
+        renderBlock(
+            `connect(signal: string, handler: ${SIGNAL_HANDLER_TYPE}, isAfter?: boolean): number`,
+            connectSwitch,
+        ),
         renderBlock("emit(sigName: string, ...args: unknown[]): unknown", emitSwitch),
     ];
 };
@@ -89,7 +93,7 @@ const renderSignalDeclarations = (
     className: string,
     isParentlessObjectSubclass: boolean,
 ): string[] => {
-    const base = { context, klass, className, parentlessExtendsObject: isParentlessObjectSubclass };
+    const base = { context, klass, className, isParentlessObjectSubclass };
 
     const declarations = [
         renderSignalMap({ ...base, suffix: SIGNALS_SUFFIX, renderEntry: renderSignalHandlerType }),
@@ -110,28 +114,30 @@ const renderSignalDeclarations = (
 };
 
 const renderSignalMap = (spec: SignalMapSpec): string => {
-    const { context, klass, className, parentlessExtendsObject, suffix, renderEntry } = spec;
-    const extendsRefs = signalMapParentRefs(context, klass, parentlessExtendsObject, suffix);
+    const { context, klass, className, isParentlessObjectSubclass, suffix, renderEntry } = spec;
+    const extendsRefs = signalMapParentRefs(context, klass, isParentlessObjectSubclass, suffix);
     const extendsClause = extendsRefs.length === 0 ? "" : ` extends ${extendsRefs.join(", ")}`;
 
-    const signalEntries = collectClassSignals(context, klass).map((signal) => {
-        const entry = `${sourceStringLiteral(signal.name)}: ${renderEntry(context, signal)};`;
-
-        return suffix === SIGNALS_SUFFIX ? `${renderJsDoc(signal.doc)}${entry}` : entry;
-    });
+    const signalEntries = collectClassSignals(context, klass).map(
+        (signal) => `${signalDoc(signal)}${sourceStringLiteral(signal.name)}: ${renderEntry(context, signal)};`,
+    );
 
     const entries = [...signalEntries, ...renderNotifyDetailEntries(context, klass, suffix)];
 
     return renderBracedOrEmpty(`export interface ${className}${suffix}${extendsClause}`, entries.join("\n"));
 };
 
+const signalDoc = (signal: GirCallable): string =>
+    renderJsDoc(signal.doc, undefined, handlerSpec(signal, signal.parameters));
+
 const renderNotifyDetailEntries = (context: ModuleContext, klass: GirClass, suffix: string): string[] => {
     const notifyValue = `${gobjectObjectMapRef(context, suffix)}["notify"]`;
 
-    return collectNotifyDetails(context, klass).map((name) => {
-        const detailedSignal = `notify::${name}`;
+    return collectNotifyDetails(context, klass).map((property) => {
+        const detailedSignal = `notify::${property.name}`;
+        const doc = getDoc(property);
 
-        return `${sourceStringLiteral(detailedSignal)}: ${notifyValue};`;
+        return `${doc}${sourceStringLiteral(detailedSignal)}: ${notifyValue};`;
     });
 };
 
@@ -177,8 +183,8 @@ const renderSignalConnectInterface = (className: string, isRootObject: boolean):
 
     const lines = [
         `__signals__?: ${map};`,
-        `connect<K extends keyof ${map}>(signal: K, handler: ${map}[K], after?: boolean): number;`,
-        `connect(signal: string, handler: ${SIGNAL_HANDLER_TYPE}, after?: boolean): number;`,
+        `connect<K extends keyof ${map}>(signal: K, handler: ${map}[K], isAfter?: boolean): number;`,
+        `connect(signal: string, handler: ${SIGNAL_HANDLER_TYPE}, isAfter?: boolean): number;`,
         `emit<K extends keyof ${emitMap}>(sigName: K, ...args: ${emitMap}[K]["args"]): ${emitMap}[K]["result"];`,
         "emit(sigName: string, ...args: unknown[]): unknown;",
     ];
@@ -193,7 +199,7 @@ const renderSignalConnectInterface = (className: string, isRootObject: boolean):
             }
         };
 
-        chainable(["on", "once", "addEventListener"], ", after?: boolean");
+        chainable(["on", "once", "addEventListener"], ", isAfter?: boolean");
         chainable(["off", "removeEventListener"], "");
     }
 
@@ -216,8 +222,8 @@ const renderResultType = (
         library: context.library,
         signal,
         renderType: (ref, nullable) => renderTsType(context, ref, nullable),
-        includeCallerAllocated: shouldIncludeCallerAllocated,
-        optOut: isOptOut,
+        shouldIncludeCallerAllocated,
+        isOptOut,
     });
 
 const renderSignalEmitEntry = (context: ModuleContext, signal: GirCallable): string => {
@@ -237,7 +243,7 @@ const nonVarargParameters = (signal: GirCallable): GirParameter[] =>
 
 const renderConnectCase = (context: ModuleContext, signal: GirCallable): string => {
     const callback = renderCallback(context, signal);
-    const body = `return connectSignal(this, signal, { callback: ${callback}, handler, after: after ?? false });`;
+    const body = `return connectSignal(this, signal, { callback: ${callback}, handler, isAfter: isAfter ?? false });`;
 
     return renderBlock(`case ${sourceStringLiteral(signal.name)}:`, body);
 };
@@ -260,7 +266,7 @@ const renderEmitArgLiteral = (options: EmitArgOptions): { literal: string; nextA
         const value = renderCallerOutAllocation(context, parameter);
 
         return {
-            literal: `{ type: ${descriptor}, direction: "out", callerAllocated: true, value: ${value} }`,
+            literal: `{ type: ${descriptor}, direction: "out", isCallerAllocated: true, value: ${value} }`,
             nextArgIndex: argIndex,
         };
     }
@@ -268,7 +274,7 @@ const renderEmitArgLiteral = (options: EmitArgOptions): { literal: string; nextA
     if (isRecordInout(context, parameter)) {
         return {
             literal:
-                `{ type: ${descriptor}, direction: "inout", callerAllocated: true, ` +
+                `{ type: ${descriptor}, direction: "inout", isCallerAllocated: true, ` +
                 `value: args[${String(argIndex)}] }`,
             nextArgIndex: argIndex + 1,
         };
@@ -328,9 +334,6 @@ const renderCallerOutAllocation = (context: ModuleContext, parameter: GirParamet
 const renderCallback = (context: ModuleContext, signal: GirCallable): string => {
     const params = nonVarargParameters(signal);
 
-    // The emitted argument list prepends the instance the signal was raised on, so every index a
-    // parameter descriptor carries (an array's `sizeParamIndex`, above all) sits one slot further
-    // right than the position GIR assigned it.
     const callbackParamDescriptors = params.map((parameter) =>
         renderParamDescriptor(context, parameter, parameter.type, { argIndexOffset: 1 }),
     );
@@ -342,11 +345,13 @@ const renderCallback = (context: ModuleContext, signal: GirCallable): string =>
         : renderDescriptor(context, signal.returnValue.type, signal.returnValue.transferOwnership);
 
     const callbackArgs = [tObject("borrowed"), ...callbackParamDescriptors, tVoid];
+    const userDataIndex = String(params.length + 1);
+    const destroy = "hasDestroy: true, destroyKind: \"closureNotify\"";
 
     return tCallback(
         callbackArgs,
         returnDescriptor,
-        `{ hasDestroy: true, userDataIndex: ${String(params.length + 1)} }`,
+        `{ ${destroy}, hasUserData: true, userDataIndex: ${userDataIndex} }`,
     );
 };
 
@@ -355,13 +360,7 @@ const forEachInterfaceSignal = (
     klass: GirClass,
     consider: (signal: GirCallable) => void,
 ): void => {
-    for (const implementName of klass.implements) {
-        const iface = resolveImplementedInterface(context, implementName);
-
-        if (iface === undefined) {
-            continue;
-        }
-
+    for (const iface of resolveInterfaces(context.library, context.namespace.name, klass.implements)) {
         for (const signal of iface.klass.signals) {
             consider(signal);
         }
@@ -420,10 +419,10 @@ const collectInheritedMemberNames = (
 const collectInheritedSignalNames = (context: ModuleContext, klass: GirClass): Set<string> =>
     collectInheritedMemberNames(context, klass, (source) => source.signals);
 
-const collectNotifyDetails = (context: ModuleContext, klass: GirClass): string[] => {
+const collectNotifyDetails = (context: ModuleContext, klass: GirClass): GirProperty[] => {
     const inherited = collectInheritedMemberNames(context, klass, (source) => source.properties);
     const seen: Set<string> = new Set();
-    const result: string[] = [];
+    const result: GirProperty[] = [];
 
     const consider = (property: GirProperty): void => {
         const name = camelCase(property.name);
@@ -433,7 +432,7 @@ const collectNotifyDetails = (context: ModuleContext, klass: GirClass): string[]
         }
 
         seen.add(name);
-        result.push(property.name);
+        result.push(property);
     };
 
     for (const property of klass.properties) {

package/src/store/gi/value-marshalable.ts

@@ -7,7 +7,6 @@ import type { ModuleContext } from "../../writer/context.js";
 
 type Scope = { context: ModuleContext; seen: Set<string> };
 
-/** Primitive categories that are a pointer at the C level, so copying the bytes aliases the pointee. */
 const POINTER_CATEGORIES: Set<PrimitiveCategory> = new Set<PrimitiveCategory>(["string", "pointer"]);
 
 const recordKey = (namespaceName: string, record: GirRecord): string => `${namespaceName}.${record.name}`;
@@ -79,18 +78,10 @@ function isValueSafeRecord(scope: Scope, namespaceName: string, record: GirRecor
     return isSafe;
 }
 
-/**
- * Whether a record can be copied by value. A plain struct is duplicated with a byte-wise `g_memdup2`,
- * which shallow-copies whatever the bytes hold, so only a record whose every field is transitively a
- * scalar can be owned, allocated or written into an inline slot. A pointer, a string, a function
- * pointer or an opaque record makes it borrow-only. Records that carry their own copy/free pair are
- * duplicated through that instead and never reach the byte-wise path.
- */
 const isValueMarshalable = (context: ModuleContext, namespaceName: string, record: GirRecord): boolean =>
     isValueSafeRecord({ context, seen: new Set<string>() }, namespaceName, record);
 
-/** Whether a record can be allocated and populated from JavaScript. */
 const isConstructibleRecord = (context: ModuleContext, namespaceName: string, record: GirRecord): boolean =>
     hasOwnCopySemantics(record) || isValueMarshalable(context, namespaceName, record);
 
-export { hasOwnCopySemantics, isConstructibleRecord, isValueMarshalable };
+export { isConstructibleRecord, isValueMarshalable };