@gtkx/codegen 0.21.0 → 1.0.0-rc.1

package/src/khronos/model.ts

@@ -0,0 +1,166 @@
+import { collectText, nodeAttr, nodeChildren, nodeTag, type OrderedNode, parseRegistryFile } from "./parse.js";
+
+export type GlParam = {
+    name: string;
+    cType: string;
+    group?: string;
+    len?: string;
+    objectClass?: string;
+};
+
+export type GlCommand = {
+    name: string;
+    returnCType: string;
+    returnGroup?: string;
+    params: GlParam[];
+};
+
+export type GlEnum = {
+    name: string;
+    value: string;
+    groups: string[];
+};
+
+export type GlInterfaceBlock = {
+    profile?: string;
+    commands: string[];
+    enums: string[];
+};
+
+export type GlFeature = {
+    api: string;
+    name: string;
+    number: number;
+    requires: GlInterfaceBlock[];
+    removes: GlInterfaceBlock[];
+};
+
+export type GlRegistry = {
+    commands: Map<string, GlCommand>;
+    enums: GlEnum[];
+    features: GlFeature[];
+};
+
+const NAME_TAG = "name";
+const SKIP_IN_C_TYPE: Set<string> = new Set([NAME_TAG, "comment"]);
+
+const normalizeWhitespace = (text: string): string => text.replace(/\s+/g, " ").trim();
+
+const childNamed = (node: OrderedNode, tag: string): OrderedNode | undefined => {
+    for (const child of nodeChildren(node)) {
+        if (nodeTag(child) === tag) return child;
+    }
+    return undefined;
+};
+
+const elementName = (node: OrderedNode): string => {
+    const nameChild = childNamed(node, NAME_TAG);
+    if (nameChild === undefined) return "";
+    return normalizeWhitespace(collectText(nameChild, new Set()));
+};
+
+const parseParam = (node: OrderedNode): GlParam => {
+    const param: GlParam = {
+        name: elementName(node),
+        cType: normalizeWhitespace(collectText(node, SKIP_IN_C_TYPE)),
+    };
+    const group = nodeAttr(node, "group");
+    const len = nodeAttr(node, "len");
+    const objectClass = nodeAttr(node, "class");
+    return {
+        ...param,
+        ...(group !== undefined ? { group } : {}),
+        ...(len !== undefined ? { len } : {}),
+        ...(objectClass !== undefined ? { objectClass } : {}),
+    };
+};
+
+const parseCommand = (node: OrderedNode): GlCommand | undefined => {
+    const proto = childNamed(node, "proto");
+    if (proto === undefined) return undefined;
+    const params: GlParam[] = [];
+    for (const child of nodeChildren(node)) {
+        if (nodeTag(child) === "param") params.push(parseParam(child));
+    }
+    const returnGroup = nodeAttr(proto, "group");
+    return {
+        name: elementName(proto),
+        returnCType: normalizeWhitespace(collectText(proto, SKIP_IN_C_TYPE)),
+        ...(returnGroup !== undefined ? { returnGroup } : {}),
+        params,
+    };
+};
+
+const parseEnums = (node: OrderedNode, into: GlEnum[]): void => {
+    for (const child of nodeChildren(node)) {
+        if (nodeTag(child) !== "enum") continue;
+        const name = nodeAttr(child, "name");
+        const value = nodeAttr(child, "value");
+        if (name === undefined || value === undefined) continue;
+        const group = nodeAttr(child, "group");
+        into.push({
+            name,
+            value,
+            groups: group === undefined ? [] : group.split(",").map((part) => part.trim()),
+        });
+    }
+};
+
+const parseInterfaceBlock = (node: OrderedNode): GlInterfaceBlock => {
+    const commands: string[] = [];
+    const enums: string[] = [];
+    for (const child of nodeChildren(node)) {
+        const name = nodeAttr(child, "name");
+        if (name === undefined) continue;
+        const tag = nodeTag(child);
+        if (tag === "command") commands.push(name);
+        else if (tag === "enum") enums.push(name);
+    }
+    const profile = nodeAttr(node, "profile");
+    return {
+        ...(profile !== undefined ? { profile } : {}),
+        commands,
+        enums,
+    };
+};
+
+const parseFeature = (node: OrderedNode): GlFeature | undefined => {
+    const api = nodeAttr(node, "api");
+    const name = nodeAttr(node, "name");
+    const number = nodeAttr(node, "number");
+    if (api === undefined || name === undefined || number === undefined) return undefined;
+    const requires: GlInterfaceBlock[] = [];
+    const removes: GlInterfaceBlock[] = [];
+    for (const child of nodeChildren(node)) {
+        const tag = nodeTag(child);
+        if (tag === "require") requires.push(parseInterfaceBlock(child));
+        else if (tag === "remove") removes.push(parseInterfaceBlock(child));
+    }
+    return { api, name, number: Number.parseFloat(number), requires, removes };
+};
+
+const parseCommandsSection = (section: OrderedNode, into: Map<string, GlCommand>): void => {
+    for (const child of nodeChildren(section)) {
+        if (nodeTag(child) !== "command") continue;
+        const command = parseCommand(child);
+        if (command !== undefined && command.name.length > 0) into.set(command.name, command);
+    }
+};
+
+export const loadGlRegistry = (path: string): GlRegistry => {
+    const commands = new Map<string, GlCommand>();
+    const enums: GlEnum[] = [];
+    const features: GlFeature[] = [];
+    for (const section of parseRegistryFile(path)) {
+        const tag = nodeTag(section);
+        if (tag === "commands") {
+            parseCommandsSection(section, commands);
+        } else if (tag === "enums") {
+            parseEnums(section, enums);
+        } else if (tag === "feature") {
+            const feature = parseFeature(section);
+            if (feature !== undefined) features.push(feature);
+        }
+    }
+    return { commands, enums, features };
+};

package/src/khronos/modules.ts

@@ -0,0 +1,75 @@
+import { sortStrings, sortStringsBy } from "@gtkx/utils";
+import { ModuleBuilder } from "../writer/module.js";
+import type { GlEnum } from "./model.js";
+import { GL_SCALARS } from "./plan.js";
+import type { RenderedCommand } from "./render.js";
+
+const LIB_CONSTANT = `export const LIB = "libGL.so.1";`;
+
+const GENERATED_HEADER = `/**
+ * GENERATED FILE: do not edit.
+ */`;
+
+export const renderEnumsModule = (
+    tokens: { token: GlEnum; exportName: string; literal: string; feature: string }[],
+): string => {
+    const builder = new ModuleBuilder();
+    for (const { token, exportName, literal, feature } of tokens) {
+        const groupNote = token.groups.length > 0 ? ` Groups: ${token.groups.map((g) => `\`${g}\``).join(", ")}.` : "";
+        builder.appendDeclaration(
+            `/** \`${token.name}\`, provided by \`${feature}\`.${groupNote} */\nexport const ${exportName} = ${literal};`,
+        );
+    }
+    return `${GENERATED_HEADER}\n\n${builder.toSource()}`;
+};
+
+export const renderTypesModule = (groupAliases: Map<string, string>): string => {
+    const builder = new ModuleBuilder();
+    builder.imports.addNamed("@gtkx/native", "ExternalObject", true);
+    builder.imports.addNamed("@gtkx/native", "Handle", true);
+    builder.appendDeclaration(
+        `/** An opaque \`GLsync\` fence handle. */\nexport type GLsync = ExternalObject<Handle>;`,
+    );
+    builder.appendDeclaration(
+        `/** An opaque native pointer handle (e.g. a \`glMapBufferRange\` mapping). */\nexport type GLpointer = ExternalObject<Handle>;`,
+    );
+    const seen = new Set<string>();
+    for (const scalar of GL_SCALARS.values()) {
+        if (seen.has(scalar.tsAlias)) continue;
+        seen.add(scalar.tsAlias);
+        builder.appendDeclaration(
+            `/** The C \`${scalar.tsAlias}\` scalar. */\nexport type ${scalar.tsAlias} = number;`,
+        );
+    }
+    for (const [group, base] of sortStringsBy(groupAliases.entries(), ([key]) => key)) {
+        builder.appendDeclaration(
+            `/** Registry enum group \`${group}\`; open and documentation-only, any \`${base}\` value is accepted. */\nexport type ${group} = ${base};`,
+        );
+    }
+    return `${GENERATED_HEADER}\n\n${builder.toSource()}`;
+};
+
+const TS_PRIMITIVES: Set<string> = new Set(["boolean", "string", "void", "number"]);
+
+export const renderCommandsModule = (
+    rendered: RenderedCommand[],
+    singulars: RenderedCommand[],
+    usedTypes: Set<string>,
+): string => {
+    const builder = new ModuleBuilder();
+    builder.imports.addNamed("@gtkx/runtime", "t");
+    for (const alias of sortStrings(usedTypes)) {
+        if (TS_PRIMITIVES.has(alias)) continue;
+        builder.imports.addNamed("./types.js", alias, true);
+    }
+    builder.appendBinding(LIB_CONSTANT);
+    for (const command of rendered) {
+        if (command.binding !== undefined) builder.appendBinding(command.binding, command.binding);
+    }
+    for (const singular of singulars) {
+        if (singular.binding !== undefined) builder.appendBinding(singular.binding, singular.binding);
+    }
+    for (const command of rendered) builder.appendDeclaration(command.declaration);
+    for (const singular of singulars) builder.appendDeclaration(singular.declaration);
+    return `${GENERATED_HEADER}\n\n${builder.toSource()}`;
+};

package/src/khronos/parse.ts

@@ -0,0 +1,66 @@
+import { readFileSync } from "node:fs";
+import { XMLParser } from "fast-xml-parser";
+
+export type OrderedNode = { [key: string]: unknown };
+
+const ATTRIBUTES_KEY = ":@";
+const TEXT_KEY = "#text";
+
+const PARSER = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    parseAttributeValue: false,
+    parseTagValue: false,
+    trimValues: false,
+    preserveOrder: true,
+});
+
+export const parseRegistryFile = (path: string): OrderedNode[] => {
+    const xml = readFileSync(path, "utf-8");
+    const documentNodes = PARSER.parse(xml) as OrderedNode[];
+    for (const node of documentNodes) {
+        if (nodeTag(node) === "registry") return nodeChildren(node);
+    }
+    throw new Error(`No <registry> root element found in ${path}`);
+};
+
+export const nodeTag = (node: OrderedNode): string => {
+    for (const key of Object.keys(node)) {
+        if (key !== ATTRIBUTES_KEY && key !== TEXT_KEY) return key;
+    }
+    return TEXT_KEY;
+};
+
+export const nodeChildren = (node: OrderedNode): OrderedNode[] => {
+    const tag = nodeTag(node);
+    if (tag === TEXT_KEY) return [];
+    const children = node[tag];
+    return Array.isArray(children) ? (children as OrderedNode[]) : [];
+};
+
+export const nodeAttr = (node: OrderedNode, name: string): string | undefined => {
+    const attributes = node[ATTRIBUTES_KEY];
+    if (typeof attributes !== "object" || attributes === null) return undefined;
+    const value = (attributes as Record<string, unknown>)[`@_${name}`];
+    return typeof value === "string" ? value : undefined;
+};
+
+const nodeText = (node: OrderedNode): string | undefined => {
+    const value = node[TEXT_KEY];
+    return typeof value === "string" ? value : undefined;
+};
+
+export const collectText = (node: OrderedNode, skipTags: Set<string>): string => {
+    let text = "";
+    for (const child of nodeChildren(node)) {
+        const childText = nodeText(child);
+        if (childText !== undefined) {
+            text += childText;
+            continue;
+        }
+        if (!skipTags.has(nodeTag(child))) {
+            text += collectText(child, skipTags);
+        }
+    }
+    return text;
+};

package/src/khronos/pipeline.ts

@@ -0,0 +1,234 @@
+import { sanitizeIdentifier, sortStrings, sortStringsBy } from "@gtkx/utils";
+import { type GlEnum, loadGlRegistry } from "./model.js";
+import { renderCommandsModule, renderEnumsModule, renderTypesModule } from "./modules.js";
+import { type CommandPlan, type GlExclusionReason, type GlPlanPolicy, type GlScalar, planCommand } from "./plan.js";
+import { deriveDeleteSingular, deriveGenSingular, type RenderedCommand, renderCommand } from "./render.js";
+import { type GlSelection, resolveEnum, selectSubset } from "./select.js";
+
+const BYTE_OFFSET_PARAMS: Set<string> = new Set([
+    "glVertexAttribPointer:pointer",
+    "glVertexAttribIPointer:pointer",
+    "glVertexAttribLPointer:pointer",
+    "glDrawElements:indices",
+    "glDrawRangeElements:indices",
+    "glDrawElementsBaseVertex:indices",
+    "glDrawRangeElementsBaseVertex:indices",
+    "glDrawElementsInstanced:indices",
+    "glDrawElementsInstancedBaseVertex:indices",
+    "glDrawElementsInstancedBaseInstance:indices",
+    "glDrawElementsInstancedBaseVertexBaseInstance:indices",
+    "glMultiDrawElements:indices",
+    "glMultiDrawElementsBaseVertex:indices",
+    "glDrawArraysIndirect:indirect",
+    "glDrawElementsIndirect:indirect",
+    "glMultiDrawArraysIndirect:indirect",
+    "glMultiDrawElementsIndirect:indirect",
+]);
+
+const SINGLE_VALUED_QUERIES: Set<string> = new Set([
+    "glGetShaderiv",
+    "glGetProgramiv",
+    "glGetProgramPipelineiv",
+    "glGetBufferParameteriv",
+    "glGetBufferParameteri64v",
+    "glGetRenderbufferParameteriv",
+    "glGetFramebufferParameteriv",
+    "glGetFramebufferAttachmentParameteriv",
+    "glGetQueryiv",
+    "glGetQueryObjectiv",
+    "glGetQueryObjectuiv",
+    "glGetQueryObjecti64v",
+    "glGetQueryObjectui64v",
+    "glGetTransformFeedbackiv",
+    "glGetVertexArrayiv",
+]);
+
+const OVERRIDE_OWNED: Set<string> = new Set([
+    "glGetShaderInfoLog",
+    "glGetProgramInfoLog",
+    "glGetProgramPipelineInfoLog",
+]);
+
+const PLAN_POLICY: GlPlanPolicy = {
+    byteOffsetParams: BYTE_OFFSET_PARAMS,
+    singleValuedQueries: SINGLE_VALUED_QUERIES,
+};
+
+type GlExclusion = {
+    command: string;
+    reason: GlExclusionReason;
+};
+
+export type GlGenerationReport = {
+    selection: GlSelection;
+    selectedCommands: number;
+    emittedCommands: number;
+    derivedSingulars: number;
+    exclusions: GlExclusion[];
+};
+
+export type GlGenerationResult = {
+    files: Map<string, string>;
+    report: GlGenerationReport;
+};
+
+const enumExportName = (name: string): string =>
+    sanitizeIdentifier((name.startsWith("GL_") ? name.slice(3) : name).toUpperCase());
+
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+
+const enumLiteral = (token: GlEnum): string | undefined => {
+    const text = token.value.trim();
+    let value: bigint;
+    try {
+        value = BigInt(text);
+    } catch {
+        return undefined;
+    }
+    if (value > MAX_SAFE) return undefined;
+    if (/^0[xX]/.test(text)) return `0x${text.slice(2).toLowerCase()}`;
+    return text;
+};
+
+const collectGroupAliases = (plans: (CommandPlan & { ok: true })[]): Map<string, string> => {
+    const aliases = new Map<string, string>();
+    const consider = (scalar: GlScalar, group: string | undefined): void => {
+        if (group === undefined) return;
+        if (scalar.groupBearing !== true) return;
+        const existing = aliases.get(group);
+        if (existing === "GLbitfield") return;
+        aliases.set(group, scalar.tsAlias === "GLbitfield" ? "GLbitfield" : (existing ?? "GLenum"));
+    };
+    for (const plan of plans) {
+        plan.params.forEach((paramPlan, index) => {
+            const param = plan.command.params[index];
+            if (param === undefined) return;
+            if (paramPlan.kind === "scalar" || paramPlan.kind === "array-in" || paramPlan.kind === "ref-out") {
+                consider(paramPlan.scalar, param.group);
+            }
+        });
+        if (plan.returnPlan.kind === "scalar") consider(plan.returnPlan.scalar, plan.command.returnGroup);
+    }
+    return aliases;
+};
+
+type GlGenerationOptions = {
+    registryPath: string;
+    overrideExports: Set<string>;
+};
+
+const GL_SELECTION: GlSelection = { api: "gl", version: 4.6, profile: "core" };
+
+type OkPlan = CommandPlan & { ok: true };
+
+type PlannedSelection = {
+    okPlans: OkPlan[];
+    planFeatures: Map<string, string>;
+    exclusions: GlExclusion[];
+};
+
+const planSelectedCommands = (
+    registry: ReturnType<typeof loadGlRegistry>,
+    commandNames: Map<string, string>,
+): PlannedSelection => {
+    const exclusions: GlExclusion[] = [];
+    const okPlans: OkPlan[] = [];
+    const planFeatures = new Map<string, string>();
+    for (const [name, feature] of sortStringsBy(commandNames.entries(), ([key]) => key)) {
+        const command = registry.commands.get(name);
+        if (command === undefined) throw new Error(`Selected command ${name} is not defined in the registry`);
+        if (OVERRIDE_OWNED.has(name)) {
+            exclusions.push({ command: name, reason: "override-owned" });
+            continue;
+        }
+        const plan = planCommand(command, PLAN_POLICY);
+        if (!plan.ok) {
+            exclusions.push({ command: name, reason: plan.reason });
+            continue;
+        }
+        okPlans.push(plan);
+        planFeatures.set(name, feature);
+    }
+    return { okPlans, planFeatures, exclusions };
+};
+
+type EnumRow = {
+    token: GlEnum;
+    exportName: string;
+    literal: string;
+    feature: string;
+};
+
+const buildEnumRows = (registry: ReturnType<typeof loadGlRegistry>, enumNames: Map<string, string>): EnumRow[] => {
+    const enumRows: EnumRow[] = [];
+    for (const [name, feature] of sortStringsBy(enumNames.entries(), ([key]) => key)) {
+        const token = resolveEnum(registry, name);
+        const literal = enumLiteral(token);
+        if (literal === undefined) continue;
+        enumRows.push({ token, exportName: enumExportName(name), literal, feature });
+    }
+    return enumRows;
+};
+
+const assertExportNamesDisjoint = (
+    rendered: RenderedCommand[],
+    singulars: RenderedCommand[],
+    enumRows: EnumRow[],
+    overrideExports: Set<string>,
+): void => {
+    const exportNames = new Map<string, string>();
+    const claim = (name: string, owner: string): void => {
+        const existing = exportNames.get(name);
+        if (existing !== undefined) {
+            throw new Error(`Generated export name collision: ${name} (${existing} vs ${owner})`);
+        }
+        exportNames.set(name, owner);
+    };
+    for (const command of rendered) claim(command.exportName, "command");
+    for (const singular of singulars) claim(singular.exportName, "derived singular");
+    for (const row of enumRows) claim(row.exportName, "enum constant");
+
+    const overrideCollisions = [...exportNames.keys()].filter((name) => overrideExports.has(name));
+    if (overrideCollisions.length > 0) {
+        throw new Error(
+            `Override module exports collide with generated exports: ${sortStrings(overrideCollisions).join(", ")}`,
+        );
+    }
+};
+
+export const generateGlModules = (options: GlGenerationOptions): GlGenerationResult => {
+    const selection = GL_SELECTION;
+    const registry = loadGlRegistry(options.registryPath);
+    const subset = selectSubset(registry, selection);
+    const { okPlans, planFeatures, exclusions } = planSelectedCommands(registry, subset.commands);
+
+    const usedTypes = new Set<string>();
+    const rendered: RenderedCommand[] = [];
+    const singulars: RenderedCommand[] = [];
+    for (const plan of okPlans) {
+        const feature = planFeatures.get(plan.command.name) ?? "unknown feature";
+        rendered.push(renderCommand(plan, feature, usedTypes));
+        const singular = deriveGenSingular(plan, feature, usedTypes) ?? deriveDeleteSingular(plan, feature, usedTypes);
+        if (singular !== undefined) singulars.push(singular);
+    }
+
+    const enumRows = buildEnumRows(registry, subset.enums);
+    assertExportNamesDisjoint(rendered, singulars, enumRows, options.overrideExports);
+
+    const files = new Map<string, string>([
+        ["types.ts", renderTypesModule(collectGroupAliases(okPlans))],
+        ["enums.ts", renderEnumsModule(enumRows)],
+        ["commands.ts", renderCommandsModule(rendered, singulars, usedTypes)],
+    ]);
+
+    return {
+        files,
+        report: {
+            selection,
+            selectedCommands: subset.commands.size,
+            emittedCommands: rendered.length,
+            derivedSingulars: singulars.length,
+            exclusions,
+        },
+    };
+};