@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/store/gi/pipeline.ts

@@ -0,0 +1,135 @@
+import type { GirClass } from "../../gir/class.js";
+import type { Library } from "../../gir/library.js";
+import type { GirAlias, GirNamespace } from "../../gir/namespace.js";
+import { renderTsType } from "../../analysis/ts-type.js";
+import { PRIMITIVE_TS_TYPE, primitiveCategory } from "../../gir/primitives.js";
+import { splitOptionalNamespace } from "../../gir/type-ref.js";
+import { ModuleContext } from "../../writer/context.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import { generateCallback } from "./callback.js";
+import { generateClass } from "./class.js";
+import { generateConstant } from "./constant.js";
+import { generateEnum } from "./enum.js";
+import { generateNamespaceBootstrap, generateNamespaceFunction } from "./function.js";
+import { generateInterface } from "./interface.js";
+import { generateRecord } from "./record.js";
+
+type TopologicalState = {
+    namespaceName: string;
+    byLocalName: Map<string, GirClass>;
+    placed: Set<GirClass>;
+    visiting: Set<GirClass>;
+    result: GirClass[];
+};
+
+const generateNamespaceModule = (namespace: GirNamespace, library: Library): string => {
+    const context = new ModuleContext(namespace, library);
+    context.addGObjectBootstrapImports();
+    generateNamespaceTypes(context, namespace);
+    generateNamespaceMembers(context, namespace);
+
+    return context.module.toSource();
+};
+
+const generateNamespaceTypes = (context: ModuleContext, namespace: GirNamespace): void => {
+    for (const enumeration of namespace.enums) {
+        generateEnum(context, enumeration);
+    }
+
+    for (const record of namespace.records) {
+        generateRecord(context, record);
+    }
+
+    for (const klass of topologicalClassOrder(namespace.classes, namespace.name)) {
+        generateClass(context, klass);
+    }
+
+    for (const iface of namespace.interfaces) {
+        generateInterface(context, iface);
+    }
+};
+
+const generateNamespaceMembers = (context: ModuleContext, namespace: GirNamespace): void => {
+    for (const callback of namespace.callbacks) {
+        generateCallback(context, callback);
+    }
+
+    for (const fn of namespace.functions) {
+        generateNamespaceFunction(context, fn);
+    }
+
+    generateNamespaceBootstrap(context, namespace);
+
+    for (const constant of namespace.constants) {
+        generateConstant(context, constant);
+    }
+
+    for (const alias of namespace.aliases) {
+        generateAlias(context, alias);
+    }
+};
+
+const generateAlias = (context: ModuleContext, alias: GirAlias): void => {
+    const category = alias.cType === undefined ? undefined : primitiveCategory(alias.cType);
+    const targetType = category === "gtype" ? PRIMITIVE_TS_TYPE.gtype : renderTsType(context, alias.target);
+    context.module.appendDeclaration(`${renderJsDoc(alias.doc)}export type ${alias.name} = ${targetType};`);
+};
+
+const visitClass = (state: TopologicalState, klass: GirClass): void => {
+    if (state.placed.has(klass) || state.visiting.has(klass)) {
+        return;
+    }
+
+    state.visiting.add(klass);
+    const parent = sameNamespaceParent(klass, state.namespaceName, state.byLocalName);
+
+    if (parent !== undefined) {
+        visitClass(state, parent);
+    }
+
+    state.visiting.delete(klass);
+    state.placed.add(klass);
+    state.result.push(klass);
+};
+
+const topologicalClassOrder = (classes: GirClass[], namespaceName: string): GirClass[] => {
+    const byLocalName: Map<string, GirClass> = new Map();
+
+    for (const klass of classes) {
+        byLocalName.set(klass.name, klass);
+    }
+
+    const state: TopologicalState = {
+        namespaceName,
+        byLocalName,
+        placed: new Set<GirClass>(),
+        visiting: new Set<GirClass>(),
+        result: [],
+    };
+
+    for (const klass of classes) {
+        visitClass(state, klass);
+    }
+
+    return state.result;
+};
+
+const sameNamespaceParent = (
+    klass: GirClass,
+    namespaceName: string,
+    byLocalName: Map<string, GirClass>,
+): GirClass | undefined => {
+    if (klass.parent === undefined) {
+        return undefined;
+    }
+
+    const [parentNamespace, typeName] = splitOptionalNamespace(klass.parent);
+
+    if (parentNamespace !== undefined && parentNamespace !== namespaceName) {
+        return undefined;
+    }
+
+    return byLocalName.get(typeName);
+};
+
+export { generateNamespaceModule };

package/src/store/gi/properties.ts

@@ -0,0 +1,50 @@
+import type { GirClass } from "../../gir/class.js";
+import type { ModuleContext } from "../../writer/context.js";
+import { collectInterfaceProperties } from "../../analysis/inheritance.js";
+import { renderBracedOrEmpty } from "../../writer/emit.js";
+import { parentCompanionRef } from "./companion.js";
+import { type ResolvedAccessor, resolveOwnerAccessor } from "./property-accessor.js";
+
+const PROPERTIES_SUFFIX = "Properties";
+
+const propertyEntry = (accessor: ResolvedAccessor): string => `${accessor.jsName}: ${accessor.tsType};`;
+
+const interfaceEntries = (context: ModuleContext, klass: GirClass): string[] => {
+    const entries: string[] = [];
+
+    for (const { owner, property } of collectInterfaceProperties(context, klass)) {
+        const accessor = resolveOwnerAccessor(context, property, owner.methods);
+
+        if (!accessor?.hasGetter) {
+            continue;
+        }
+
+        entries.push(propertyEntry(accessor));
+    }
+
+    return entries;
+};
+
+const renderPropertyDeclarations = (
+    context: ModuleContext,
+    klass: GirClass,
+    className: string,
+    accessors: ResolvedAccessor[],
+): string[] => {
+    const parentRef = parentCompanionRef(context, klass, PROPERTIES_SUFFIX);
+    const extendsClause = parentRef === undefined ? "" : ` extends ${parentRef}`;
+
+    const entries = [
+        ...accessors.filter((accessor) => accessor.hasGetter).map((accessor) => propertyEntry(accessor)),
+        ...interfaceEntries(context, klass),
+    ];
+
+    const map = `${className}${PROPERTIES_SUFFIX}`;
+
+    return [
+        renderBracedOrEmpty(`export interface ${map}${extendsClause}`, entries.join("\n")),
+        renderBracedOrEmpty(`export interface ${className}`, `__properties__: ${map};`),
+    ];
+};
+
+export { renderPropertyDeclarations };

package/src/store/gi/property-accessor.ts

@@ -0,0 +1,302 @@
+import { camelCase, sourceStringLiteral, toCamelIdentifier } from "@gtkx/utils";
+import type { GirFunction } from "../../gir/function.js";
+import type { TypeId } from "../../gir/type-id.js";
+import type { ModuleContext } from "../../writer/context.js";
+import { renderDescriptor } from "../../analysis/descriptor-render.js";
+import { inputParameters } from "../../analysis/param-structure.js";
+import { renderTsType } from "../../analysis/ts-type.js";
+import { type GirProperty, isConstructableProperty } from "../../gir/property.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import { renderBlock } from "../../writer/emit.js";
+import { isEmittableCallable } from "./callables.js";
+import { methodExportName, renderMethodReturnType } from "./method.js";
+
+type ResolvedAccessor = {
+    jsName: string;
+    tsType: string;
+    hasGetter: boolean;
+    writable: boolean;
+    getterMember: string | undefined;
+    getterMethod: GirFunction | undefined;
+    setterMember: string | undefined;
+};
+
+type PropertyAccessorArgs = {
+    context: ModuleContext;
+    property: GirProperty;
+    claimedNames: Set<string>;
+    methodByName: Map<string, GirFunction>;
+    inheritedType?: string | undefined;
+};
+
+type AccessorDelegate = { member: string | undefined; method: GirFunction | undefined };
+
+type GetterBodyOptions = {
+    context: ModuleContext;
+    property: GirProperty;
+    getterMember: string | undefined;
+    getterMethod: GirFunction | undefined;
+    tsType: string;
+};
+
+const isNullablePropertyType = (context: ModuleContext, type: TypeId | undefined): boolean => {
+    if (type === undefined) {
+        return false;
+    }
+
+    const resolved = context.library.typeFor(type);
+
+    if (resolved === undefined) {
+        return true;
+    }
+
+    if (resolved.kind === "primitive") {
+        return false;
+    }
+
+    if (resolved.kind === "enum") {
+        return false;
+    }
+
+    if (resolved.kind === "alias") {
+        return isNullablePropertyType(context, resolved.value.target);
+    }
+
+    return true;
+};
+
+const resolveDelegate = (
+    args: PropertyAccessorArgs,
+    attribute: string | undefined,
+    member: string | undefined,
+    isDelegatable: (method: GirFunction) => boolean,
+): AccessorDelegate => {
+    const method = member !== undefined && attribute !== undefined ? args.methodByName.get(attribute) : undefined;
+    const canDelegate = method === undefined || isDelegatable(method);
+
+    return canDelegate ? { member, method } : { member: undefined, method: undefined };
+};
+
+const resolveGetterDelegate = (args: PropertyAccessorArgs, jsName: string): AccessorDelegate => {
+    const { context, property, claimedNames } = args;
+    const member = delegateMember(property.getter, jsName, claimedNames);
+
+    return resolveDelegate(
+        args,
+        property.getter,
+        member,
+        (method) =>
+            inputParameters(context.library, method).length === 0 &&
+            !renderMethodReturnType(context, method).startsWith("["),
+    );
+};
+
+const resolveSetterDelegate = (args: PropertyAccessorArgs, jsName: string, isWritable: boolean): AccessorDelegate => {
+    const { context, property, claimedNames } = args;
+    const member = isWritable ? delegateMember(property.setter, jsName, claimedNames) : undefined;
+
+    return resolveDelegate(
+        args,
+        property.setter,
+        member,
+        (method) => inputParameters(context.library, method).length === 1,
+    );
+};
+
+const resolveOwnType = (
+    context: ModuleContext,
+    property: GirProperty,
+    getterMethod: GirFunction | undefined,
+    setterMethod: GirFunction | undefined,
+): string => {
+    const setterParam = setterMethod?.parameters[0];
+
+    if (setterParam !== undefined) {
+        return renderTsType(context, setterParam.type, setterParam.nullable || setterParam.optional);
+    }
+
+    if (getterMethod !== undefined) {
+        return renderMethodReturnType(context, getterMethod);
+    }
+
+    return renderTsType(context, property.type, isNullablePropertyType(context, property.type));
+};
+
+const isSkippedAccessor = (property: GirProperty, jsName: string, claimedNames: Set<string>): boolean =>
+    !property.introspectable || claimedNames.has(jsName) || jsName === "constructor";
+
+const resolveTsType = (inheritedType: string | undefined, ownType: string): string =>
+    inheritedType !== undefined && inheritedType !== ownType ? inheritedType : ownType;
+
+const resolveAccessor = (args: PropertyAccessorArgs): ResolvedAccessor | undefined => {
+    const { context, property, claimedNames } = args;
+    const jsName = toCamelIdentifier(property.name);
+
+    if (isSkippedAccessor(property, jsName, claimedNames)) {
+        return undefined;
+    }
+
+    // `g_object_set_property` rejects a construct-only pspec with a critical and drops the write, so
+    // the property is settable at construction time only and must not advertise a setter.
+    const isWritable = isConstructableProperty(property) && !property.constructOnly;
+    const { member: getterMember, method: getterMethod } = resolveGetterDelegate(args, jsName);
+    const { member: setterMember, method: setterMethod } = resolveSetterDelegate(args, jsName, isWritable);
+    const hasGetter = property.readable || getterMember !== undefined;
+
+    if (!hasGetter && !isWritable) {
+        return undefined;
+    }
+
+    const ownType = resolveOwnType(context, property, getterMethod, setterMethod);
+    const tsType = resolveTsType(args.inheritedType, ownType);
+
+    return { jsName, tsType, hasGetter, writable: isWritable, getterMember, getterMethod, setterMember };
+};
+
+const resolveOwnerAccessor = (
+    context: ModuleContext,
+    property: GirProperty,
+    methods: GirFunction[],
+): ResolvedAccessor | undefined => {
+    const methodByName: Map<string, GirFunction> = new Map();
+    const claimedNames: Set<string> = new Set();
+
+    for (const method of methods) {
+        if (!isEmittableCallable(context, method)) {
+            continue;
+        }
+
+        methodByName.set(method.name, method);
+        claimedNames.add(methodExportName(method));
+    }
+
+    return resolveAccessor({ context, property, claimedNames, methodByName });
+};
+
+const resolveAccessorType = (
+    context: ModuleContext,
+    property: GirProperty,
+    methods: GirFunction[],
+): string | undefined => resolveOwnerAccessor(context, property, methods)?.tsType;
+
+const withAccessor = (
+    args: PropertyAccessorArgs,
+    render: (accessor: ResolvedAccessor) => string,
+): string | undefined => {
+    const accessor = resolveAccessor(args);
+
+    if (accessor === undefined) {
+        return undefined;
+    }
+
+    return render(accessor);
+};
+
+const renderResolvedPropertyAccessor = (
+    context: ModuleContext,
+    property: GirProperty,
+    accessor: ResolvedAccessor,
+): string => {
+    const { jsName, tsType, hasGetter, writable, getterMember, getterMethod, setterMember } = accessor;
+    const blocks: string[] = [];
+
+    if (hasGetter) {
+        const getterBody = renderGetterBody({ context, property, getterMember, getterMethod, tsType });
+        blocks.push(renderBlock(`get ${jsName}(): ${tsType}`, getterBody));
+    }
+
+    if (writable) {
+        const setterBody =
+            setterMember === undefined ? renderGenericSetBody(context, property) : `this.${setterMember}(value);`;
+
+        blocks.push(renderBlock(`set ${jsName}(value: ${tsType})`, setterBody));
+    }
+
+    return `${renderJsDoc(property.doc)}${blocks.join("\n\n")}`;
+};
+
+const renderPropertyAccessor = (args: PropertyAccessorArgs): string | undefined =>
+    withAccessor(args, (accessor) => renderResolvedPropertyAccessor(args.context, args.property, accessor));
+
+const renderPropertyAccessorSignature = (args: PropertyAccessorArgs): string | undefined =>
+    withAccessor(args, ({ jsName, tsType, hasGetter, writable }) => {
+        const doc = renderJsDoc(args.property.doc);
+
+        if (hasGetter && writable) {
+            return `${doc}${jsName}: ${tsType};`;
+        }
+
+        if (hasGetter) {
+            return `${doc}get ${jsName}(): ${tsType};`;
+        }
+
+        return `${doc}set ${jsName}(value: ${tsType});`;
+    });
+
+const renderPropertyDescriptor = (context: ModuleContext, property: GirProperty): string =>
+    renderDescriptor(context, property.type, property.transferOwnership);
+
+const renderGenericGetBody = (context: ModuleContext, property: GirProperty, tsType: string): string => {
+    context.addRuntimeImport("getObjectProperty");
+    context.addRuntimeImport("t");
+    const descriptor = renderPropertyDescriptor(context, property);
+
+    return `return getObjectProperty(this, ${sourceStringLiteral(property.name)}, ${descriptor}) as ${tsType};`;
+};
+
+const renderGenericSetBody = (context: ModuleContext, property: GirProperty): string => {
+    context.addRuntimeImport("setObjectProperty");
+    context.addRuntimeImport("t");
+    const descriptor = renderPropertyDescriptor(context, property);
+
+    return `setObjectProperty(this, ${sourceStringLiteral(property.name)}, ${descriptor}, value);`;
+};
+
+const renderGetterBody = (options: GetterBodyOptions): string => {
+    const { context, property, getterMember, getterMethod, tsType } = options;
+
+    if (getterMember === undefined) {
+        return renderGenericGetBody(context, property, tsType);
+    }
+
+    if (getterMethod === undefined) {
+        return `return this.${getterMember}() as ${tsType};`;
+    }
+
+    const getterType = renderMethodReturnType(context, getterMethod);
+
+    return getterType === tsType ? `return this.${getterMember}();` : `return this.${getterMember}() as ${tsType};`;
+};
+
+const delegateMember = (
+    attribute: string | undefined,
+    accessorName: string,
+    claimedNames: Set<string>,
+): string | undefined => {
+    if (attribute === undefined) {
+        return undefined;
+    }
+
+    const member = camelCase(attribute);
+
+    if (member === accessorName) {
+        return undefined;
+    }
+
+    if (!claimedNames.has(member)) {
+        return undefined;
+    }
+
+    return member;
+};
+
+export {
+    resolveAccessor,
+    resolveOwnerAccessor,
+    resolveAccessorType,
+    renderResolvedPropertyAccessor,
+    renderPropertyAccessor,
+    renderPropertyAccessorSignature,
+    type ResolvedAccessor,
+    type PropertyAccessorArgs,
+};

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

@@ -0,0 +1,119 @@
+import { sourceStringLiteral, toCamelIdentifier } from "@gtkx/utils";
+import type { GirField } from "../../gir/field.js";
+import type { GirRecord } from "../../gir/record.js";
+import type { TypeId } from "../../gir/type-id.js";
+import type { ModuleContext } from "../../writer/context.js";
+import { renderDescriptor } from "../../analysis/descriptor-render.js";
+import { renderTsType } from "../../analysis/ts-type.js";
+import { renderBlock, renderBracedOrEmpty } from "../../writer/emit.js";
+import { renderSourceGtype } from "./gtype-binding.js";
+import { emitFieldWrite, isEmittableField } from "./record-field-accessor.js";
+import { computeRecordFieldSlots, type RecordFieldSlot } from "./record-layout.js";
+
+type WritableFieldSlot = RecordFieldSlot & { field: GirField & { type: TypeId } };
+
+const isWritableFieldSlot = (context: ModuleContext, entry: RecordFieldSlot): entry is WritableFieldSlot =>
+    entry.field.writable && isEmittableField(context, entry.field);
+
+const isOpaque = (record: GirRecord): boolean => record.opaque || record.disguised;
+
+const renderRecordConstructorPropsInterface = (
+    context: ModuleContext,
+    record: GirRecord,
+    className: string,
+): string => {
+    const head = `export interface ${className}ConstructorProps`;
+
+    if (isOpaque(record)) {
+        return renderBracedOrEmpty(head, "");
+    }
+
+    const { slots } = computeRecordFieldSlots(context, record.fields, record.isUnion);
+
+    const lines = slots
+        .filter((entry): entry is WritableFieldSlot => isWritableFieldSlot(context, entry))
+        .map((entry) => `${toCamelIdentifier(entry.field.name)}?: ${renderTsType(context, entry.field.type, true)};`);
+
+    return renderBracedOrEmpty(head, lines.join("\n"));
+};
+
+const renderOpaqueConstructor = (className: string, superCall: string[]): string => {
+    const message = sourceStringLiteral(`Cannot construct ${className}: opaque boxed type with no known layout`);
+
+    return renderBlock("constructor()", [...superCall, `throw new globalThis.Error(${message});`].join("\n"));
+};
+
+const renderEmptyConstructor = (className: string, isErrorSubclass: boolean): string =>
+    isErrorSubclass
+        ? renderBlock(`constructor(props: ${className}ConstructorProps = {})`, "super();")
+        : `constructor(props: ${className}ConstructorProps = {}) {}`;
+
+const renderFieldWrites = (context: ModuleContext, slots: RecordFieldSlot[]): string[] => {
+    const statements: string[] = [];
+
+    for (const entry of slots) {
+        if (isWritableFieldSlot(context, entry)) {
+            statements.push(renderFieldWrite(context, entry));
+        }
+    }
+
+    return statements;
+};
+
+const renderRecordConstructor = (
+    context: ModuleContext,
+    record: GirRecord,
+    className: string,
+    isErrorSubclass = false,
+): string => {
+    const superCall = isErrorSubclass ? ["super();"] : [];
+
+    if (isOpaque(record)) {
+        return renderOpaqueConstructor(className, superCall);
+    }
+
+    const { slots, size } = computeRecordFieldSlots(context, record.fields, record.isUnion);
+
+    if (size === 0) {
+        return renderEmptyConstructor(className, isErrorSubclass);
+    }
+
+    context.addRuntimeImport("alloc");
+    context.addRuntimeImport("setHandle");
+
+    const statements = [
+        ...superCall,
+        `const handle = alloc(${allocArgs(context, record, size).join(", ")});`,
+        ...renderFieldWrites(context, slots),
+        "setHandle(this, handle);",
+    ];
+
+    return renderBlock(`constructor(props: ${className}ConstructorProps = {})`, statements.join("\n"));
+};
+
+const allocArgs = (context: ModuleContext, record: GirRecord, size: number): string[] => {
+    const args = [String(size)];
+
+    if (renderSourceGtype(context, record) !== undefined) {
+        args.push("this.__type__");
+    }
+
+    return args;
+};
+
+const renderFieldWrite = (context: ModuleContext, entry: WritableFieldSlot): string => {
+    context.addRuntimeImport("t");
+    const descriptor = context.hoistDescriptor(renderDescriptor(context, entry.field.type, "none"));
+    const name = toCamelIdentifier(entry.field.name);
+
+    const write = emitFieldWrite(context, {
+        descriptor,
+        slot: entry.slot,
+        targetExpr: "handle",
+        valueExpr: `props.${name}`,
+    });
+
+    return `if (props.${name} !== undefined) ${write}`;
+};
+
+export { renderRecordConstructorPropsInterface, renderRecordConstructor };