@gtkx/codegen 1.0.0 → 1.1.0

package/src/docs/symbol-page.ts

@@ -1,4 +1,4 @@
-import { pascalCase, sortStringsBy, upperFirst } from "@gtkx/utils";
+import { sanitizeTypeIdentifier, sortStringsBy, upperFirst } from "@gtkx/utils";
 import type { GirAnnotations } from "../gir/annotations.js";
 import type { GirClass } from "../gir/class.js";
 import type { EnumMember, GirEnum } from "../gir/enum.js";
@@ -51,6 +51,7 @@ import {
     type OriginSignatureEntry,
     plainText,
     propertyMetaLine,
+    qualifiedClassName,
     renderDocsSignalHandlerType,
     renderDocsType,
     signalTags,
@@ -202,9 +203,6 @@ const pageHeader = (entry: GiSymbolEntry, kindLabel: string): string[] => [
     importBlock(entry),
 ];
 
-const qualifiedClassName = (namespaceName: string, className: string): string =>
-    `${namespaceName}.${pascalCase(className)}`;
-
 const elementNote = (entry: ClassSymbol, options: SymbolPageOptions): string[] => {
     const glibName = options.elementNameFor(entry.namespace.name, entry.klass.name);
 
@@ -354,7 +352,7 @@ const memberOwners = (entry: ClassSymbol, library: Library): MemberOwner[] => [
 
 const interfaceMethodNames = (library: Library, owner: MemberOwner): string[] => {
     const context = docsSignatureContext(owner.namespace, library);
-    const className = pascalCase(owner.klass.name);
+    const className = sanitizeTypeIdentifier(owner.klass.name);
     const methods = dedupeCallables(owner.klass.methods);
 
     const scope = instanceScope(className, {
@@ -402,9 +400,16 @@ const getAccessNotes = (accessor: ResolvedAccessor): string[] => {
         return ["read-only"];
     }
 
-    return accessor.hasGetter ? [] : ["write-only"];
+    if (!accessor.hasGetter) {
+        return ["write-only"];
+    }
+
+    return accessor.readType === accessor.writeType ? [] : [`writes \`${accessor.writeType}\``];
 };
 
+const documentedAccessorType = (accessor: ResolvedAccessor): string =>
+    accessor.hasGetter ? accessor.readType : accessor.writeType;
+
 const ownerPropertyEntries = (owner: MemberOwner, setup: PropertyAccessorSetup, seen: Set<string>): MetaDocEntry[] => {
     const entries: MetaDocEntry[] = [];
 
@@ -425,7 +430,7 @@ const ownerPropertyEntries = (owner: MemberOwner, setup: PropertyAccessorSetup,
         entries.push({
             name: accessor.jsName,
             meta: propertyMetaLine({
-                type: accessor.tsType,
+                type: documentedAccessorType(accessor),
                 property,
                 accessNotes: getAccessNotes(accessor),
                 origin: owner.origin,

package/src/fingerprint.ts

@@ -1,9 +1,11 @@
 import { sortStrings } from "@gtkx/utils";
 import { createHash } from "node:crypto";
 import { type Dirent, existsSync, readdirSync, readFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import packageManifest from "../package.json" with { type: "json" };
+import { arrayGuard, hasFields, isNumber, isString, optionalGuard } from "./guards.js";
+import { readJsonFile } from "./json.js";
 
 type GiFingerprint = {
     value: string;
@@ -14,6 +16,17 @@ type GiFingerprint = {
 
 type ModuleExport = { module: string; export: string };
 
+type DocsFingerprintInput = {
+    basePath: string;
+    props: Record<string, ModuleExport>;
+    omittedProps: Record<string, string[]>;
+};
+
+type DocsFingerprint = {
+    value: string;
+    gi: GiFingerprint;
+};
+
 type JsxFingerprintInput = {
     reactVersion: string;
     components: Record<string, ModuleExport>;
@@ -27,9 +40,8 @@ type JsxFingerprint = {
     intrinsicElementCount: number;
 };
 
-const require = createRequire(import.meta.url);
 const FINGERPRINT_FILENAME = ".codegen-fingerprint.json";
-const CODEGEN_VERSION: string = (require("../package.json") as { version: string }).version;
+const CODEGEN_VERSION: string = packageManifest.version;
 const OVERRIDES_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "overrides");
 
 const sortAlpha = (values: string[]): string => sortStrings(values).join(",");
@@ -75,39 +87,87 @@ const computeGiFingerprint = (
     girPath,
 });
 
-const isGiStoreFresh = (
-    giStoreDir: string,
-    libraries: string[],
-    girPath: string[],
-): boolean => {
-    const sentinelPath = join(giStoreDir, FINGERPRINT_FILENAME);
+const readSentinel = (storeDir: string): unknown => readJsonFile(join(storeDir, FINGERPRINT_FILENAME));
 
-    if (!existsSync(sentinelPath)) {
-        return false;
-    }
+const isGiFingerprint = (value: unknown): value is GiFingerprint =>
+    hasFields<GiFingerprint>(value, {
+        value: isString,
+        girFiles: arrayGuard(isString),
+        libraries: arrayGuard(isString),
+        girPath: optionalGuard(arrayGuard(isString)),
+    });
 
-    let sentinel: GiFingerprint;
+const isDocsFingerprint = (value: unknown): value is DocsFingerprint =>
+    hasFields<DocsFingerprint>(value, { value: isString, gi: isGiFingerprint });
 
-    try {
-        sentinel = JSON.parse(readFileSync(sentinelPath, "utf8")) as GiFingerprint;
-    } catch {
-        return false;
-    }
+const isJsxFingerprint = (value: unknown): value is JsxFingerprint =>
+    hasFields<JsxFingerprint>(value, { value: isString, intrinsicElementCount: isNumber });
 
+const recordedGiValue = (sentinel: GiFingerprint, libraries: string[], girPath: string[]): string | undefined => {
     if (!hasMatchingRecordedInputs(sentinel, libraries, girPath)) {
-        return false;
+        return undefined;
     }
 
     try {
-        return hashGi(sentinel.girFiles, sentinel.libraries, girPath) === sentinel.value;
+        return hashGi(sentinel.girFiles, sentinel.libraries, girPath);
     } catch {
-        return false;
+        return undefined;
     }
 };
 
+const isGiStoreFresh = (
+    giStoreDir: string,
+    libraries: string[],
+    girPath: string[],
+): boolean => {
+    const sentinel = readSentinel(giStoreDir);
+
+    return isGiFingerprint(sentinel) && recordedGiValue(sentinel, libraries, girPath) === sentinel.value;
+};
+
 const hasMatchingRecordedInputs = (sentinel: GiFingerprint, libraries: string[], girPath: string[]): boolean =>
     sortAlpha(sentinel.libraries) === sortAlpha(libraries) && sortAlpha(sentinel.girPath ?? []) === sortAlpha(girPath);
 
+const hashDocs = (giValue: string, input: DocsFingerprintInput): string =>
+    createHash("sha256")
+        .update(
+            JSON.stringify([
+                giValue,
+                input.basePath,
+                serializeModuleExports(input.props),
+                serializeOmittedProps(input.omittedProps),
+            ]),
+        )
+        .digest("hex");
+
+const computeDocsFingerprint = (
+    girFiles: string[],
+    libraries: string[],
+    girPath: string[],
+    input: DocsFingerprintInput,
+): DocsFingerprint => {
+    const gi = computeGiFingerprint(girFiles, libraries, girPath);
+
+    return { value: hashDocs(gi.value, input), gi };
+};
+
+const isDocsOutputFresh = (
+    outDir: string,
+    libraries: string[],
+    girPath: string[],
+    input: DocsFingerprintInput,
+): boolean => {
+    const sentinel = readSentinel(outDir);
+
+    if (!isDocsFingerprint(sentinel)) {
+        return false;
+    }
+
+    const giValue = recordedGiValue(sentinel.gi, libraries, girPath);
+
+    return giValue !== undefined && hashDocs(giValue, input) === sentinel.value;
+};
+
 const serializeModuleExports = (map: Record<string, ModuleExport>): [string, string, string][] =>
     sortStrings(Object.keys(map)).map((type) => [type, map[type]?.module ?? "", map[type]?.export ?? ""]);
 
@@ -137,17 +197,9 @@ const jsxStoreFreshness = (
     jsxStoreDir: string,
     input: JsxFingerprintInput,
 ): { isFresh: boolean; intrinsicElementCount: number } => {
-    const sentinelPath = join(jsxStoreDir, FINGERPRINT_FILENAME);
-
-    if (!existsSync(sentinelPath)) {
-        return { isFresh: false, intrinsicElementCount: 0 };
-    }
+    const sentinel = readSentinel(jsxStoreDir);
 
-    let sentinel: JsxFingerprint;
-
-    try {
-        sentinel = JSON.parse(readFileSync(sentinelPath, "utf8")) as JsxFingerprint;
-    } catch {
+    if (!isJsxFingerprint(sentinel)) {
         return { isFresh: false, intrinsicElementCount: 0 };
     }
 
@@ -159,9 +211,12 @@ const jsxStoreFreshness = (
 export {
     FINGERPRINT_FILENAME,
     computeGiFingerprint,
+    computeDocsFingerprint,
     isGiStoreFresh,
+    isDocsOutputFresh,
     computeJsxFingerprint,
     jsxStoreFreshness,
+    type DocsFingerprintInput,
     type GiFingerprint,
     type JsxFingerprintInput,
 };

package/src/gi.ts

@@ -17,6 +17,7 @@ const runGiCodegen = (library: Library, options: GiCodegenOptions): number => {
     const namespaces: GiNamespaceInput[] = Array.from(library.namespaces.values(), (namespace) => ({
         directory: namespaceDirectory(namespace),
         rawSource: generateNamespaceModule(namespace, library),
+        girFile: namespace.girFile,
     }));
 
     const fingerprint = computeGiFingerprint(library.girFiles, [...libraries], [...girPath]);

package/src/gir/ancestry.ts

@@ -1,12 +1,28 @@
 import type { GirClass } from "./class.js";
 import type { Library } from "./library.js";
 import type { GirType } from "./type.js";
+import { splitOptionalNamespace } from "./type-ref.js";
 
 type ResolvedAncestor = {
     klass: GirClass;
     namespaceName: string;
 };
 
+type ParentRef = {
+    namespaceName: string | undefined;
+    typeName: string;
+};
+
+const getParentRef = (klass: GirClass): ParentRef | undefined => {
+    if (klass.parent === undefined) {
+        return undefined;
+    }
+
+    const [namespaceName, typeName] = splitOptionalNamespace(klass.parent);
+
+    return { namespaceName, typeName };
+};
+
 const getAncestor = (resolved: GirType | undefined): ResolvedAncestor | undefined =>
     resolved !== undefined && (resolved.kind === "class" || resolved.kind === "interface")
         ? { klass: resolved.value, namespaceName: resolved.namespace.name }
@@ -64,4 +80,4 @@ function* ancestorChain(library: Library, klass: GirClass, namespaceName: string
     }
 }
 
-export { resolveInterfaces, ancestorChain, type ResolvedAncestor };
+export { resolveClassOrInterface, resolveInterfaces, ancestorChain, getParentRef, type ResolvedAncestor };

package/src/gir/annotations.ts

@@ -34,4 +34,4 @@ const documentedFromNode = (node: RawNode): DocumentedNode => ({
 const hasAnnotations = (annotations: GirAnnotations): boolean =>
     annotations.since !== undefined || annotations.isDeprecated || annotations.deprecatedSince !== undefined;
 
-export { annotationsFromNode, documentedFromNode, hasAnnotations, type GirAnnotations };
+export { documentedFromNode, hasAnnotations, type GirAnnotations };

package/src/gir/cursor-overrides.ts

@@ -0,0 +1,12 @@
+type CursorParameterNames = {
+    cursor: string;
+    base: string;
+    length: string;
+};
+
+const PARAMETERS_MISSING_ARRAY_EXTENT: Map<string, CursorParameterNames[]> = new Map([
+    ["g_utf8_validate", [{ cursor: "end", base: "str", length: "max_len" }]],
+    ["g_utf8_validate_len", [{ cursor: "end", base: "str", length: "max_len" }]],
+]);
+
+export { PARAMETERS_MISSING_ARRAY_EXTENT, type CursorParameterNames };

package/src/gir/emittable.ts

@@ -0,0 +1,8 @@
+type NamedEntity = {
+    name: string;
+    introspectable?: boolean | undefined;
+};
+
+const isEmittableEntity = (entity: NamedEntity): boolean => entity.name.length > 0 && entity.introspectable !== false;
+
+export { isEmittableEntity };

package/src/gir/function.ts

@@ -1,5 +1,6 @@
 import type { GirAnnotations } from "./annotations.js";
 import type { ParseContext } from "./type-id.js";
+import { type CursorParameterNames, PARAMETERS_MISSING_ARRAY_EXTENT } from "./cursor-overrides.js";
 import { PARAMETERS_MISSING_NULLABLE_ANNOTATION } from "./nullable-overrides.js";
 import { type GirParameter, type GirReturnValue, parameterFromNode, parseCallable } from "./parameter.js";
 import { attr, getChild, type RawNode } from "./parse.js";
@@ -50,18 +51,53 @@ const relaxMissingNullable = (fn: GirFunction): GirFunction => {
     return fn;
 };
 
+const parameterIndexFor = (parameters: GirParameter[], name: string): number => {
+    const index = parameters.findIndex((parameter) => parameter.name === name);
+
+    if (index === -1) {
+        throw new Error(`A cursor correction names a parameter the GIR does not declare: ${name}`);
+    }
+
+    return index;
+};
+
+const bindCursorParameters = (parameters: GirParameter[], corrections: CursorParameterNames[]): void => {
+    for (const names of corrections) {
+        const parameter = parameters[parameterIndexFor(parameters, names.cursor)];
+
+        if (parameter !== undefined) {
+            parameter.cursor = {
+                baseIndex: parameterIndexFor(parameters, names.base),
+                lengthIndex: parameterIndexFor(parameters, names.length),
+            };
+        }
+    }
+};
+
+const bindMissingArrayExtent = (fn: GirFunction): GirFunction => {
+    const corrections = fn.cIdentifier === undefined ? undefined : PARAMETERS_MISSING_ARRAY_EXTENT.get(fn.cIdentifier);
+
+    if (corrections !== undefined) {
+        bindCursorParameters(fn.parameters, corrections);
+    }
+
+    return fn;
+};
+
 const functionFromNode = (node: RawNode, context: ParseContext): GirFunction => {
     const instanceNode = getChild(getChild(node, "parameters"), "instance-parameter");
 
-    return relaxMissingNullable({
-        ...parseCallable(node, context),
-        name: attr(node, "shadows") ?? attr(node, "name") ?? "",
-        cIdentifier: attr(node, "c:identifier"),
-        movedTo: attr(node, "moved-to"),
-        shadowedBy: attr(node, "shadowed-by"),
-        finishFunc: attr(node, "glib:finish-func"),
-        instance: instanceNode === undefined ? undefined : parameterFromNode(instanceNode, context),
-    });
+    return bindMissingArrayExtent(
+        relaxMissingNullable({
+            ...parseCallable(node, context),
+            name: attr(node, "shadows") ?? attr(node, "name") ?? "",
+            cIdentifier: attr(node, "c:identifier"),
+            movedTo: attr(node, "moved-to"),
+            shadowedBy: attr(node, "shadowed-by"),
+            finishFunc: attr(node, "glib:finish-func"),
+            instance: instanceNode === undefined ? undefined : parameterFromNode(instanceNode, context),
+        }),
+    );
 };
 
 export { functionFromNode, type GirFunction };

package/src/gir/library.ts

@@ -294,7 +294,7 @@ class Library {
         seen.add(namespaceName);
         const path = locateGirFile(identifier, girPath);
         girFiles.push(path);
-        const header = parseNamespaceHeader(readRepositoryNode(path));
+        const header = parseNamespaceHeader(readRepositoryNode(path), path);
         const shell = this.registerNamespace(header);
         discovered.push({ header, shell });
 

package/src/gir/namespace.ts

@@ -44,6 +44,8 @@ type GirNamespace = {
     id: number;
     /** Namespace name as it appears in the GIR, such as `Gtk`. */
     name: string;
+    /** Path of the `.gir` file the namespace was parsed from, named by every diagnostic the namespace causes. */
+    girFile: string;
     /** The `shared-library` attribute verbatim: the objects to load symbols from, separated by commas. */
     sharedLibrary: string | undefined;
     /** Prefixes stripped off C identifiers to derive export names, such as `gtk`. */
@@ -78,6 +80,8 @@ type NamespaceInclude = {
 type NamespaceHeader = {
     /** Namespace name as it appears in the GIR, such as `Gtk`. */
     name: string;
+    /** Path of the `.gir` file the header was read from. */
+    girFile: string;
     /** The `shared-library` attribute verbatim: the objects to load symbols from, separated by commas. */
     sharedLibrary: string | undefined;
     /** Prefixes stripped off C identifiers to derive export names, such as `gtk`. */
@@ -90,7 +94,7 @@ type NamespaceHeader = {
 
 const namespaceDirectory = (namespace: Pick<GirNamespace, "name">): string => namespace.name.toLowerCase();
 
-const parseNamespaceHeader = (repositoryNode: RawNode): NamespaceHeader => {
+const parseNamespaceHeader = (repositoryNode: RawNode, path: string): NamespaceHeader => {
     const includes = getChildren(repositoryNode, "include").map<NamespaceInclude>((include) => ({
         name: nameAttr(include),
         version: attr(include, "version") ?? "",
@@ -99,11 +103,12 @@ const parseNamespaceHeader = (repositoryNode: RawNode): NamespaceHeader => {
     const namespaceNode = getChildren(repositoryNode, "namespace")[0];
 
     if (namespaceNode === undefined) {
-        throw new Error("GIR repository has no <namespace> child");
+        throw new Error(`GIR file at ${path} has no <namespace> child in its <repository>`);
     }
 
     return {
         name: nameAttr(namespaceNode),
+        girFile: path,
         sharedLibrary: attr(namespaceNode, "shared-library"),
         cSymbolPrefixes: splitPrefixes(attr(namespaceNode, "c:symbol-prefixes")),
         includes,
@@ -114,6 +119,7 @@ const parseNamespaceHeader = (repositoryNode: RawNode): NamespaceHeader => {
 const createNamespaceShell = (header: NamespaceHeader, id: number): GirNamespace => ({
     id,
     name: header.name,
+    girFile: header.girFile,
     sharedLibrary: header.sharedLibrary,
     cSymbolPrefixes: header.cSymbolPrefixes,
     classes: [],

package/src/gir/parameter.ts

@@ -23,6 +23,17 @@ type ParameterTransfer = "none" | "full" | "container";
  */
 type CallbackScope = "call" | "notified" | "async" | "forever";
 
+/**
+ * Bounds of an out parameter that points into the buffer of a sibling parameter instead of to an
+ * array of its own, which GIR describes as an array with no extent of any kind.
+ */
+type GirCursorBounds = {
+    /** Position of the parameter holding the buffer the pointer points into. */
+    baseIndex: number;
+    /** Position of the parameter carrying that buffer's element count. */
+    lengthIndex: number;
+};
+
 /** A parameter of a {@link GirCallable}, with the annotations that decide how it is marshalled. */
 type GirParameter = {
     /** The name GIR gives the parameter. */
@@ -51,6 +62,8 @@ type GirParameter = {
     destroyIndex: number | undefined;
     /** Whether the parameter is the `...` varargs marker. */
     isVarargs: boolean;
+    /** Where the buffer is that the parameter points into, when it carries a cursor rather than an array. */
+    cursor: GirCursorBounds | undefined;
 };
 
 /** What a {@link GirCallable} hands back, with the annotations that decide how it is marshalled. */
@@ -118,6 +131,7 @@ const parameterFromNode = (node: RawNode, context: ParseContext): GirParameter =
     closureIndex: intAttr(node, "closure"),
     destroyIndex: intAttr(node, "destroy"),
     isVarargs: getChild(node, "varargs") !== undefined,
+    cursor: undefined,
 });
 
 const isOutParameter = (parameter: GirParameter): boolean =>
@@ -163,6 +177,7 @@ export {
     isInoutParameter,
     parseCallable,
     type ParameterTransfer,
+    type GirCursorBounds,
     type GirParameter,
     type GirReturnValue,
     type GirCallable,

package/src/gir/parse.ts

@@ -1,9 +1,10 @@
-import { readFileSync } from "node:fs";
-import { createXmlParser } from "../xml.js";
+import { createXmlParser, parseXmlFile } from "../xml.js";
 
 /** An element of the parsed GIR XML: attributes under `@_`-prefixed keys, children under their tag names. */
 type RawNode = Record<string, unknown>;
 
+const GIR_LABEL = "GIR file";
+
 const MULTI_TAGS: Set<string> = new Set([
     "include",
     "class",
@@ -42,11 +43,8 @@ function renameReservedTag(tag: string): string {
     return RESERVED_TAG_RENAMES.get(tag) ?? tag;
 }
 
-const parseGirFile = (path: string): RawNode => {
-    const xml = readFileSync(path, "utf8");
-
-    return PARSER.parse(xml) as RawNode;
-};
+const parseGirFile = (path: string): RawNode =>
+    parseXmlFile({ parser: PARSER, label: GIR_LABEL, path }) as RawNode;
 
 const attr = (node: RawNode | undefined, name: string): string | undefined => {
     if (node === undefined) {

package/src/guards.ts

@@ -0,0 +1,23 @@
+import { isRecord } from "@gtkx/utils";
+
+type Guard<T> = (value: unknown) => value is T;
+type OptionalGuard<T> = Guard<T | undefined> & { __optional__: true };
+type FieldGuard<T> = [undefined] extends [T] ? OptionalGuard<NonNullable<T>> : Guard<T>;
+type FieldGuards<T> = { [K in keyof Required<T>]: FieldGuard<T[K]> };
+
+const isBoolean = (value: unknown): value is boolean => typeof value === "boolean";
+const isNumber = (value: unknown): value is number => typeof value === "number";
+const isString = (value: unknown): value is string => typeof value === "string";
+
+const arrayGuard = <T>(isEntry: Guard<T>): Guard<T[]> =>
+    (value: unknown): value is T[] => Array.isArray(value) && value.every((entry: unknown) => isEntry(entry));
+
+const optionalGuard = <T>(isPresent: Guard<T>): OptionalGuard<T> =>
+    Object.assign((value: unknown): value is T | undefined => value === undefined || isPresent(value), {
+        __optional__: true as const,
+    });
+
+const hasFields = <T extends object>(value: unknown, guards: FieldGuards<T>): value is T =>
+    isRecord(value) && Object.entries(guards).every(([name, guard]) => (guard as Guard<unknown>)(value[name]));
+
+export { arrayGuard, hasFields, isBoolean, isNumber, isString, optionalGuard };

package/src/internal.ts

@@ -1,2 +1,4 @@
 export { writeDocs } from "./docs/pipeline.js";
 export { runGlCodegen } from "./runner.js";
+export { getShadowingStorePaths, sweepProjectStaging } from "./store/resolve-store.js";
+export { ensureStoreLinks } from "./store/store-links.js";

package/src/json.ts

@@ -0,0 +1,11 @@
+import { readFileSync } from "node:fs";
+
+const readJsonFile = (path: string): unknown => {
+    try {
+        return JSON.parse(readFileSync(path, "utf8")) as unknown;
+    } catch {
+        return undefined;
+    }
+};
+
+export { readJsonFile };

package/src/khronos/modules.ts

@@ -76,7 +76,10 @@ const renderEnumsModule = (tokens: EnumRow[], docs: GlDocContext): string => {
     const builder = new ModuleBuilder();
 
     for (const row of tokens) {
-        builder.appendDeclaration(`${enumJsDoc(row, docs)}\nexport const ${row.exportName} = ${row.literal};`);
+        builder.appendDeclaration({
+            name: row.exportName,
+            code: `${enumJsDoc(row, docs)}\nexport const ${row.exportName} = ${row.literal};`,
+        });
     }
 
     return `${generatedHeader(docs)}\n\n${builder.toSource()}`;
@@ -135,7 +138,11 @@ const appendScalarAliases = (builder: ModuleBuilder, docs: GlDocContext): void =
         }
 
         seen.add(scalar.tsAlias);
-        builder.appendDeclaration(`${scalarJsDoc(scalar.tsAlias, docs)}\nexport type ${scalar.tsAlias} = number;`);
+
+        builder.appendDeclaration({
+            name: scalar.tsAlias,
+            code: `${scalarJsDoc(scalar.tsAlias, docs)}\nexport type ${scalar.tsAlias} = number;`,
+        });
     }
 };
 
@@ -143,7 +150,10 @@ const appendGroupAliases = (builder: ModuleBuilder, groupAliases: Map<string, st
     const sorted = sortStringsBy(groupAliases.entries(), ([key]) => key);
 
     for (const [group, base] of sorted) {
-        builder.appendDeclaration(`${groupAliasJsDoc(group, base, docs)}\nexport type ${group} = ${base};`);
+        builder.appendDeclaration({
+            name: group,
+            code: `${groupAliasJsDoc(group, base, docs)}\nexport type ${group} = ${base};`,
+        });
     }
 };
 
@@ -151,12 +161,18 @@ const renderTypesModule = (groupAliases: Map<string, string>, docs: GlDocContext
     const builder = new ModuleBuilder();
     builder.imports.addNamed("@gtkx/native", "ExternalObject", true);
     builder.imports.addNamed("@gtkx/native", "Handle", true);
-    builder.appendDeclaration(`${syncJsDoc(docs)}\nexport type GLsync = ExternalObject<Handle>;`);
 
-    builder.appendDeclaration(
-        "/** An opaque native pointer handle (e.g. a `glMapBufferRange` mapping). */\n" +
-        "export type GLpointer = ExternalObject<Handle>;",
-    );
+    builder.appendDeclaration({
+        name: "GLsync",
+        code: `${syncJsDoc(docs)}\nexport type GLsync = ExternalObject<Handle>;`,
+    });
+
+    builder.appendDeclaration({
+        name: "GLpointer",
+        code:
+            "/** An opaque native pointer handle (e.g. a `glMapBufferRange` mapping). */\n" +
+            "export type GLpointer = ExternalObject<Handle>;",
+    });
 
     appendScalarAliases(builder, docs);
     appendGroupAliases(builder, groupAliases, docs);
@@ -184,7 +200,7 @@ const appendCommandBindings = (builder: ModuleBuilder, commands: RenderedCommand
 
 const appendCommandDeclarations = (builder: ModuleBuilder, commands: RenderedCommand[]): void => {
     for (const command of commands) {
-        builder.appendDeclaration(command.declaration);
+        builder.appendDeclaration({ name: command.exportName, code: command.declaration });
     }
 };
 

package/src/khronos/parse.ts

@@ -1,10 +1,10 @@
-import { readFileSync } from "node:fs";
-import { createXmlParser } from "../xml.js";
+import { createXmlParser, parseXmlFile } from "../xml.js";
 
 type OrderedNode = Record<string, unknown>;
 
 const ATTRIBUTES_KEY = ":@";
 const TEXT_KEY = "#text";
+const REGISTRY_LABEL = "OpenGL registry";
 
 const PARSER = createXmlParser({
     trimValues: false,
@@ -12,8 +12,7 @@ const PARSER = createXmlParser({
 });
 
 const parseRegistryFile = (path: string): OrderedNode[] => {
-    const xml = readFileSync(path, "utf8");
-    const documentNodes = PARSER.parse(xml) as OrderedNode[];
+    const documentNodes = parseXmlFile({ parser: PARSER, label: REGISTRY_LABEL, path }) as OrderedNode[];
 
     for (const node of documentNodes) {
         if (nodeTag(node) === "registry") {

package/src/khronos/pipeline.ts

@@ -387,4 +387,4 @@ const generateGlModules = (options: GlGenerationOptions): GlGenerationResult =>
     };
 };
 
-export { generateGlModules, type GlGenerationReport, type GlGenerationResult };
+export { generateGlModules, type GlGenerationReport };

package/src/khronos/plan.ts

@@ -328,7 +328,6 @@ const planCommand = (command: GlCommand, policy: GlPlanPolicy): CommandPlan => {
 
 export {
     GL_SCALARS,
-    parseCType,
     planCommand,
     type GlScalar,
     type ParamPlan,