@gtkx/codegen 1.0.0-rc.4 → 1.1.0

package/dist/khronos/modules.js

@@ -1,42 +1,127 @@
 import { sortStrings, sortStringsBy } from "@gtkx/utils";
 import { ModuleBuilder } from "../writer/module.js";
+import { asSentence, backtick, backtickList, provenanceLines } from "./notes.js";
 import { GL_SCALARS } from "./plan.js";
-const LIB_CONSTANT = "export const LIB = \"libGL.so.1\";";
-const GENERATED_HEADER = `/**
- * GENERATED FILE: do not edit.
- */`;
+const LIB_CONSTANT = "/** The shared library the generated OpenGL bindings are loaded from. */\n" +
+    "export const LIB = \"libGL.so.1\";";
+const SYNC_SUMMARY = "An opaque `GLsync` fence handle";
 const TS_PRIMITIVES = new Set(["boolean", "string", "void", "number"]);
-const quotedGroupList = (groups) => groups.map((group) => `\`${group}\``).join(", ");
-const renderEnumsModule = (tokens) => {
-    const builder = new ModuleBuilder();
-    for (const { token, exportName, literal, feature } of tokens) {
-        const groupNote = token.groups.length > 0 ? ` Groups: ${quotedGroupList(token.groups)}.` : "";
-        builder.appendDeclaration(`/** \`${token.name}\`, provided by \`${feature}\`.${groupNote} */\n` +
-            `export const ${exportName} = ${literal};`);
+const attributionLine = (line) => (line.length === 0 ? " *" : ` * ${line}`);
+const attributionLines = (registryComment) => registryComment === undefined
+    ? []
+    : [" *", ...registryComment.split("\n").map((line) => attributionLine(line))];
+const generatedHeader = (docs) => [
+    "/**",
+    " * GENERATED FILE: do not edit.",
+    " *",
+    " * Derived from the Khronos OpenGL registry (gl.xml).",
+    ...attributionLines(docs.registryComment),
+    " */",
+].join("\n");
+const groupsLine = (groups) => (groups.length === 0 ? [] : [` * Groups: ${backtickList(groups)}.`]);
+const rangePhrase = (vendor) => vendor === undefined ? "Registry enumerant block" : `Allocated from the ${backtick(vendor)} enumerant range`;
+const rangeLine = ({ vendor, blockComment }) => {
+    if (vendor === undefined && blockComment === undefined) {
+        return [];
     }
-    return `${GENERATED_HEADER}\n\n${builder.toSource()}`;
+    const phrase = rangePhrase(vendor);
+    const text = blockComment === undefined ? phrase : `${phrase}: ${blockComment}`;
+    return [` * ${asSentence(text)}`];
 };
-const renderTypesModule = (groupAliases) => {
+const tokenNoteLines = (token) => [
+    ...groupsLine(token.groups),
+    ...(token.comment === undefined ? [] : [` * Token note: ${asSentence(token.comment)}`]),
+    ...(token.alias === undefined ? [] : [` * Also known as ${backtick(token.alias)}.`]),
+    ...(token.valueType === undefined ? [] : [` * Tagged ${backtick(token.valueType)} in the registry.`]),
+    ...rangeLine(token),
+];
+const enumJsDoc = ({ token, provenance }, docs) => [
+    "/**",
+    ` * ${backtick(token.name)}.`,
+    " *",
+    ...provenanceLines(provenance, docs.extensionEnums.get(token.name) ?? []),
+    ...tokenNoteLines(token),
+    " */",
+].join("\n");
+const renderEnumsModule = (tokens, docs) => {
     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). */\n" +
-        "export type GLpointer = ExternalObject<Handle>;");
+    for (const row of tokens) {
+        builder.appendDeclaration({
+            name: row.exportName,
+            code: `${enumJsDoc(row, docs)}\nexport const ${row.exportName} = ${row.literal};`,
+        });
+    }
+    return `${generatedHeader(docs)}\n\n${builder.toSource()}`;
+};
+const scalarSentences = (alias, type) => [
+    `The C ${backtick(alias)} scalar: ${backtick(type.declaration)}.`,
+    ...(type.requires === undefined ? [] : [`Requires the ${backtick(type.requires)} header.`]),
+    ...(type.comment === undefined ? [] : [`Registry note: ${asSentence(type.comment)}`]),
+];
+const scalarJsDoc = (alias, docs) => {
+    const type = docs.types.get(alias);
+    if (type === undefined) {
+        return `/** The C ${backtick(alias)} scalar. */`;
+    }
+    return `/** ${scalarSentences(alias, type).join(" ")} */`;
+};
+const syncJsDoc = (docs) => {
+    const type = docs.types.get("GLsync");
+    if (type === undefined) {
+        return `/** ${SYNC_SUMMARY}. */`;
+    }
+    return `/** ${SYNC_SUMMARY}: ${backtick(type.declaration)}. */`;
+};
+const groupSummary = (group, isBitmask) => isBitmask
+    ? `Registry enum group ${backtick(group)}, declared as a bitmask: members are combined with \`|\`.`
+    : `Registry enum group ${backtick(group)}.`;
+const memberLines = (members) => members.length === 0 ? [] : [" *", ` * Members: ${backtickList(members)}.`];
+const groupAliasJsDoc = (group, base, docs) => [
+    "/**",
+    ` * ${groupSummary(group, docs.bitmaskGroups.has(group))}`,
+    " *",
+    ` * Open and documentation-only; any ${backtick(base)} value is accepted.`,
+    ...memberLines(docs.groupMembers.get(group) ?? []),
+    " */",
+].join("\n");
+const appendScalarAliases = (builder, docs) => {
     const seen = new Set();
     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;`);
+        builder.appendDeclaration({
+            name: scalar.tsAlias,
+            code: `${scalarJsDoc(scalar.tsAlias, docs)}\nexport type ${scalar.tsAlias} = number;`,
+        });
     }
-    const sortedAliases = sortStringsBy(groupAliases.entries(), ([key]) => key);
-    for (const [group, base] of sortedAliases) {
-        builder.appendDeclaration(`/** Registry enum group \`${group}\`; open and documentation-only, ` +
-            `any \`${base}\` value is accepted. */\nexport type ${group} = ${base};`);
+};
+const appendGroupAliases = (builder, groupAliases, docs) => {
+    const sorted = sortStringsBy(groupAliases.entries(), ([key]) => key);
+    for (const [group, base] of sorted) {
+        builder.appendDeclaration({
+            name: group,
+            code: `${groupAliasJsDoc(group, base, docs)}\nexport type ${group} = ${base};`,
+        });
     }
-    return `${GENERATED_HEADER}\n\n${builder.toSource()}`;
+};
+const renderTypesModule = (groupAliases, docs) => {
+    const builder = new ModuleBuilder();
+    builder.imports.addNamed("@gtkx/native", "ExternalObject", true);
+    builder.imports.addNamed("@gtkx/native", "Handle", true);
+    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);
+    return `${generatedHeader(docs)}\n\n${builder.toSource()}`;
 };
 const appendTypeImports = (builder, usedTypes) => {
     for (const alias of sortStrings(usedTypes)) {
@@ -55,10 +140,10 @@ const appendCommandBindings = (builder, commands) => {
 };
 const appendCommandDeclarations = (builder, commands) => {
     for (const command of commands) {
-        builder.appendDeclaration(command.declaration);
+        builder.appendDeclaration({ name: command.exportName, code: command.declaration });
     }
 };
-const renderCommandsModule = (rendered, singulars, usedTypes) => {
+const renderCommandsModule = (rendered, singulars, usedTypes, docs) => {
     const builder = new ModuleBuilder();
     builder.imports.addNamed("@gtkx/runtime", "t");
     appendTypeImports(builder, usedTypes);
@@ -67,7 +152,7 @@ const renderCommandsModule = (rendered, singulars, usedTypes) => {
     appendCommandBindings(builder, singulars);
     appendCommandDeclarations(builder, rendered);
     appendCommandDeclarations(builder, singulars);
-    return `${GENERATED_HEADER}\n\n${builder.toSource()}`;
+    return `${generatedHeader(docs)}\n\n${builder.toSource()}`;
 };
 export { renderEnumsModule, renderTypesModule, renderCommandsModule };
 //# sourceMappingURL=modules.js.map

package/dist/khronos/modules.js.map

@@ -1 +1 @@
-{"version":3,"file":"modules.js","sourceRoot":"","sources":["../../src/khronos/modules.ts"],"names":[],"mappings":"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","sourcesContent":["import { sortStrings, sortStringsBy } from \"@gtkx/utils\";\nimport type { GlEnum } from \"./model.js\";\nimport type { RenderedCommand } from \"./render.js\";\nimport { ModuleBuilder } from \"../writer/module.js\";\nimport { GL_SCALARS } from \"./plan.js\";\n\nconst LIB_CONSTANT = \"export const LIB = \\\"libGL.so.1\\\";\";\n\nconst GENERATED_HEADER = `/**\n * GENERATED FILE: do not edit.\n */`;\n\nconst TS_PRIMITIVES: Set<string> = new Set([\"boolean\", \"string\", \"void\", \"number\"]);\n\nconst quotedGroupList = (groups: string[]): string => groups.map((group) => `\\`${group}\\``).join(\", \");\n\nconst renderEnumsModule = (\n    tokens: { token: GlEnum; exportName: string; literal: string; feature: string }[],\n): string => {\n    const builder = new ModuleBuilder();\n\n    for (const { token, exportName, literal, feature } of tokens) {\n        const groupNote = token.groups.length > 0 ? ` Groups: ${quotedGroupList(token.groups)}.` : \"\";\n\n        builder.appendDeclaration(\n            `/** \\`${token.name}\\`, provided by \\`${feature}\\`.${groupNote} */\\n` +\n            `export const ${exportName} = ${literal};`,\n        );\n    }\n\n    return `${GENERATED_HEADER}\\n\\n${builder.toSource()}`;\n};\n\nconst renderTypesModule = (groupAliases: Map<string, string>): string => {\n    const builder = new ModuleBuilder();\n    builder.imports.addNamed(\"@gtkx/native\", \"ExternalObject\", true);\n    builder.imports.addNamed(\"@gtkx/native\", \"Handle\", true);\n\n    builder.appendDeclaration(\n        \"/** An opaque `GLsync` fence handle. */\\nexport type GLsync = ExternalObject<Handle>;\",\n    );\n\n    builder.appendDeclaration(\n        \"/** An opaque native pointer handle (e.g. a `glMapBufferRange` mapping). */\\n\" +\n        \"export type GLpointer = ExternalObject<Handle>;\",\n    );\n\n    const seen: Set<string> = new Set();\n\n    for (const scalar of GL_SCALARS.values()) {\n        if (seen.has(scalar.tsAlias)) {\n            continue;\n        }\n\n        seen.add(scalar.tsAlias);\n\n        builder.appendDeclaration(\n            `/** The C \\`${scalar.tsAlias}\\` scalar. */\\nexport type ${scalar.tsAlias} = number;`,\n        );\n    }\n\n    const sortedAliases = sortStringsBy(groupAliases.entries(), ([key]) => key);\n\n    for (const [group, base] of sortedAliases) {\n        builder.appendDeclaration(\n            `/** Registry enum group \\`${group}\\`; open and documentation-only, ` +\n            `any \\`${base}\\` value is accepted. */\\nexport type ${group} = ${base};`,\n        );\n    }\n\n    return `${GENERATED_HEADER}\\n\\n${builder.toSource()}`;\n};\n\nconst appendTypeImports = (builder: ModuleBuilder, usedTypes: Set<string>): void => {\n    for (const alias of sortStrings(usedTypes)) {\n        if (TS_PRIMITIVES.has(alias)) {\n            continue;\n        }\n\n        builder.imports.addNamed(\"./types.js\", alias, true);\n    }\n};\n\nconst appendCommandBindings = (builder: ModuleBuilder, commands: RenderedCommand[]): void => {\n    for (const command of commands) {\n        if (command.binding !== undefined) {\n            builder.appendBinding(command.binding, command.binding);\n        }\n    }\n};\n\nconst appendCommandDeclarations = (builder: ModuleBuilder, commands: RenderedCommand[]): void => {\n    for (const command of commands) {\n        builder.appendDeclaration(command.declaration);\n    }\n};\n\nconst renderCommandsModule = (\n    rendered: RenderedCommand[],\n    singulars: RenderedCommand[],\n    usedTypes: Set<string>,\n): string => {\n    const builder = new ModuleBuilder();\n    builder.imports.addNamed(\"@gtkx/runtime\", \"t\");\n    appendTypeImports(builder, usedTypes);\n    builder.appendBinding(LIB_CONSTANT);\n    appendCommandBindings(builder, rendered);\n    appendCommandBindings(builder, singulars);\n    appendCommandDeclarations(builder, rendered);\n    appendCommandDeclarations(builder, singulars);\n\n    return `${GENERATED_HEADER}\\n\\n${builder.toSource()}`;\n};\n\nexport { renderEnumsModule, renderTypesModule, renderCommandsModule };\n"]}
+{"version":3,"file":"modules.js","sourceRoot":"","sources":["../../src/khronos/modules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAKzD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AASvC,MAAM,YAAY,GACd,4EAA4E;IAC5E,oCAAoC,CAAC;AAEzC,MAAM,YAAY,GAAG,iCAAiC,CAAC;AACvD,MAAM,aAAa,GAAgB,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEpF,MAAM,eAAe,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;AAE5F,MAAM,gBAAgB,GAAG,CAAC,eAAmC,EAAY,EAAE,CACvE,eAAe,KAAK,SAAS;IACzB,CAAC,CAAC,EAAE;IACJ,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAEtF,MAAM,eAAe,GAAG,CAAC,IAAkB,EAAU,EAAE,CACnD;IACI,KAAK;IACL,iCAAiC;IACjC,IAAI;IACJ,uDAAuD;IACvD,GAAG,gBAAgB,CAAC,IAAI,CAAC,eAAe,CAAC;IACzC,KAAK;CACR,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEjB,MAAM,UAAU,GAAG,CAAC,MAAgB,EAAY,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,cAAc,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;AAExH,MAAM,WAAW,GAAG,CAAC,MAA0B,EAAU,EAAE,CACvD,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,sBAAsB,QAAQ,CAAC,MAAM,CAAC,kBAAkB,CAAC;AAEjH,MAAM,SAAS,GAAG,CAAC,EAAE,MAAM,EAAE,YAAY,EAAU,EAAY,EAAE;IAC7D,IAAI,MAAM,KAAK,SAAS,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QACrD,OAAO,EAAE,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,KAAK,YAAY,EAAE,CAAC;IAEhF,OAAO,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACtC,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,KAAa,EAAY,EAAE,CAAC;IAChD,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,kBAAkB,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACvF,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,oBAAoB,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpF,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC;IACrG,GAAG,SAAS,CAAC,KAAK,CAAC;CACtB,CAAC;AAEF,MAAM,SAAS,GAAG,CAAC,EAAE,KAAK,EAAE,UAAU,EAAW,EAAE,IAAkB,EAAU,EAAE,CAC7E;IACI,KAAK;IACL,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG;IAC7B,IAAI;IACJ,GAAG,eAAe,CAAC,UAAU,EAAE,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACzE,GAAG,cAAc,CAAC,KAAK,CAAC;IACxB,KAAK;CACR,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEjB,MAAM,iBAAiB,GAAG,CAAC,MAAiB,EAAE,IAAkB,EAAU,EAAE;IACxE,MAAM,OAAO,GAAG,IAAI,aAAa,EAAE,CAAC;IAEpC,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACvB,OAAO,CAAC,iBAAiB,CAAC;YACtB,IAAI,EAAE,GAAG,CAAC,UAAU;YACpB,IAAI,EAAE,GAAG,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,kBAAkB,GAAG,CAAC,UAAU,MAAM,GAAG,CAAC,OAAO,GAAG;SACpF,CAAC,CAAC;IACP,CAAC;IAED,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;AAC/D,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,KAAa,EAAE,IAAY,EAAY,EAAE,CAAC;IAC/D,SAAS,QAAQ,CAAC,KAAK,CAAC,YAAY,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG;IACjE,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,gBAAgB,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC3F,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,kBAAkB,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;CACxF,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,KAAa,EAAE,IAAkB,EAAU,EAAE;IAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAEnC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACrB,OAAO,aAAa,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC;IACrD,CAAC;IAED,OAAO,OAAO,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;AAC9D,CAAC,CAAC;AAEF,MAAM,SAAS,GAAG,CAAC,IAAkB,EAAU,EAAE;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAEtC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACrB,OAAO,OAAO,YAAY,MAAM,CAAC;IACrC,CAAC;IAED,OAAO,OAAO,YAAY,KAAK,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;AACpE,CAAC,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,KAAa,EAAE,SAAkB,EAAU,EAAE,CAC/D,SAAS;IACL,CAAC,CAAC,uBAAuB,QAAQ,CAAC,KAAK,CAAC,2DAA2D;IACnG,CAAC,CAAC,uBAAuB,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC;AAEpD,MAAM,WAAW,GAAG,CAAC,OAAiB,EAAY,EAAE,CAChD,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,eAAe,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;AAEhF,MAAM,eAAe,GAAG,CAAC,KAAa,EAAE,IAAY,EAAE,IAAkB,EAAU,EAAE,CAChF;IACI,KAAK;IACL,MAAM,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE;IAC1D,IAAI;IACJ,uCAAuC,QAAQ,CAAC,IAAI,CAAC,qBAAqB;IAC1E,GAAG,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAClD,KAAK;CACR,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEjB,MAAM,mBAAmB,GAAG,CAAC,OAAsB,EAAE,IAAkB,EAAQ,EAAE;IAC7E,MAAM,IAAI,GAAgB,IAAI,GAAG,EAAE,CAAC;IAEpC,KAAK,MAAM,MAAM,IAAI,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,SAAS;QACb,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAEzB,OAAO,CAAC,iBAAiB,CAAC;YACtB,IAAI,EAAE,MAAM,CAAC,OAAO;YACpB,IAAI,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,iBAAiB,MAAM,CAAC,OAAO,YAAY;SACxF,CAAC,CAAC;IACP,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,kBAAkB,GAAG,CAAC,OAAsB,EAAE,YAAiC,EAAE,IAAkB,EAAQ,EAAE;IAC/G,MAAM,MAAM,GAAG,aAAa,CAAC,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;IAErE,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,MAAM,EAAE,CAAC;QACjC,OAAO,CAAC,iBAAiB,CAAC;YACtB,IAAI,EAAE,KAAK;YACX,IAAI,EAAE,GAAG,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,iBAAiB,KAAK,MAAM,IAAI,GAAG;SACjF,CAAC,CAAC;IACP,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,iBAAiB,GAAG,CAAC,YAAiC,EAAE,IAAkB,EAAU,EAAE;IACxF,MAAM,OAAO,GAAG,IAAI,aAAa,EAAE,CAAC;IACpC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,EAAE,gBAAgB,EAAE,IAAI,CAAC,CAAC;IACjE,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;IAEzD,OAAO,CAAC,iBAAiB,CAAC;QACtB,IAAI,EAAE,QAAQ;QACd,IAAI,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,gDAAgD;KAC3E,CAAC,CAAC;IAEH,OAAO,CAAC,iBAAiB,CAAC;QACtB,IAAI,EAAE,WAAW;QACjB,IAAI,EACA,+EAA+E;YAC/E,iDAAiD;KACxD,CAAC,CAAC;IAEH,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACnC,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;IAEhD,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;AAC/D,CAAC,CAAC;AAEF,MAAM,iBAAiB,GAAG,CAAC,OAAsB,EAAE,SAAsB,EAAQ,EAAE;IAC/E,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;QACzC,IAAI,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,SAAS;QACb,CAAC;QAED,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IACxD,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,qBAAqB,GAAG,CAAC,OAAsB,EAAE,QAA2B,EAAQ,EAAE;IACxF,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC7B,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAChC,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QAC5D,CAAC;IACL,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,yBAAyB,GAAG,CAAC,OAAsB,EAAE,QAA2B,EAAQ,EAAE;IAC5F,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC7B,OAAO,CAAC,iBAAiB,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACvF,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,oBAAoB,GAAG,CACzB,QAA2B,EAC3B,SAA4B,EAC5B,SAAsB,EACtB,IAAkB,EACZ,EAAE;IACR,MAAM,OAAO,GAAG,IAAI,aAAa,EAAE,CAAC;IACpC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;IAC/C,iBAAiB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACtC,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;IACpC,qBAAqB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACzC,qBAAqB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC1C,yBAAyB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC7C,yBAAyB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAE9C,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;AAC/D,CAAC,CAAC;AAEF,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,oBAAoB,EAAgB,CAAC","sourcesContent":["import { sortStrings, sortStringsBy } from \"@gtkx/utils\";\nimport type { GlDocContext } from \"./doc-context.js\";\nimport type { GlEnum, GlType } from \"./model.js\";\nimport type { RenderedCommand } from \"./render.js\";\nimport type { GlSymbolProvenance } from \"./select.js\";\nimport { ModuleBuilder } from \"../writer/module.js\";\nimport { asSentence, backtick, backtickList, provenanceLines } from \"./notes.js\";\nimport { GL_SCALARS } from \"./plan.js\";\n\ntype EnumRow = {\n    token: GlEnum;\n    exportName: string;\n    literal: string;\n    provenance: GlSymbolProvenance;\n};\n\nconst LIB_CONSTANT =\n    \"/** The shared library the generated OpenGL bindings are loaded from. */\\n\" +\n    \"export const LIB = \\\"libGL.so.1\\\";\";\n\nconst SYNC_SUMMARY = \"An opaque `GLsync` fence handle\";\nconst TS_PRIMITIVES: Set<string> = new Set([\"boolean\", \"string\", \"void\", \"number\"]);\n\nconst attributionLine = (line: string): string => (line.length === 0 ? \" *\" : ` * ${line}`);\n\nconst attributionLines = (registryComment: string | undefined): string[] =>\n    registryComment === undefined\n        ? []\n        : [\" *\", ...registryComment.split(\"\\n\").map((line) => attributionLine(line))];\n\nconst generatedHeader = (docs: GlDocContext): string =>\n    [\n        \"/**\",\n        \" * GENERATED FILE: do not edit.\",\n        \" *\",\n        \" * Derived from the Khronos OpenGL registry (gl.xml).\",\n        ...attributionLines(docs.registryComment),\n        \" */\",\n    ].join(\"\\n\");\n\nconst groupsLine = (groups: string[]): string[] => (groups.length === 0 ? [] : [` * Groups: ${backtickList(groups)}.`]);\n\nconst rangePhrase = (vendor: string | undefined): string =>\n    vendor === undefined ? \"Registry enumerant block\" : `Allocated from the ${backtick(vendor)} enumerant range`;\n\nconst rangeLine = ({ vendor, blockComment }: GlEnum): string[] => {\n    if (vendor === undefined && blockComment === undefined) {\n        return [];\n    }\n\n    const phrase = rangePhrase(vendor);\n    const text = blockComment === undefined ? phrase : `${phrase}: ${blockComment}`;\n\n    return [` * ${asSentence(text)}`];\n};\n\nconst tokenNoteLines = (token: GlEnum): string[] => [\n    ...groupsLine(token.groups),\n    ...(token.comment === undefined ? [] : [` * Token note: ${asSentence(token.comment)}`]),\n    ...(token.alias === undefined ? [] : [` * Also known as ${backtick(token.alias)}.`]),\n    ...(token.valueType === undefined ? [] : [` * Tagged ${backtick(token.valueType)} in the registry.`]),\n    ...rangeLine(token),\n];\n\nconst enumJsDoc = ({ token, provenance }: EnumRow, docs: GlDocContext): string =>\n    [\n        \"/**\",\n        ` * ${backtick(token.name)}.`,\n        \" *\",\n        ...provenanceLines(provenance, docs.extensionEnums.get(token.name) ?? []),\n        ...tokenNoteLines(token),\n        \" */\",\n    ].join(\"\\n\");\n\nconst renderEnumsModule = (tokens: EnumRow[], docs: GlDocContext): string => {\n    const builder = new ModuleBuilder();\n\n    for (const row of tokens) {\n        builder.appendDeclaration({\n            name: row.exportName,\n            code: `${enumJsDoc(row, docs)}\\nexport const ${row.exportName} = ${row.literal};`,\n        });\n    }\n\n    return `${generatedHeader(docs)}\\n\\n${builder.toSource()}`;\n};\n\nconst scalarSentences = (alias: string, type: GlType): string[] => [\n    `The C ${backtick(alias)} scalar: ${backtick(type.declaration)}.`,\n    ...(type.requires === undefined ? [] : [`Requires the ${backtick(type.requires)} header.`]),\n    ...(type.comment === undefined ? [] : [`Registry note: ${asSentence(type.comment)}`]),\n];\n\nconst scalarJsDoc = (alias: string, docs: GlDocContext): string => {\n    const type = docs.types.get(alias);\n\n    if (type === undefined) {\n        return `/** The C ${backtick(alias)} scalar. */`;\n    }\n\n    return `/** ${scalarSentences(alias, type).join(\" \")} */`;\n};\n\nconst syncJsDoc = (docs: GlDocContext): string => {\n    const type = docs.types.get(\"GLsync\");\n\n    if (type === undefined) {\n        return `/** ${SYNC_SUMMARY}. */`;\n    }\n\n    return `/** ${SYNC_SUMMARY}: ${backtick(type.declaration)}. */`;\n};\n\nconst groupSummary = (group: string, isBitmask: boolean): string =>\n    isBitmask\n        ? `Registry enum group ${backtick(group)}, declared as a bitmask: members are combined with \\`|\\`.`\n        : `Registry enum group ${backtick(group)}.`;\n\nconst memberLines = (members: string[]): string[] =>\n    members.length === 0 ? [] : [\" *\", ` * Members: ${backtickList(members)}.`];\n\nconst groupAliasJsDoc = (group: string, base: string, docs: GlDocContext): string =>\n    [\n        \"/**\",\n        ` * ${groupSummary(group, docs.bitmaskGroups.has(group))}`,\n        \" *\",\n        ` * Open and documentation-only; any ${backtick(base)} value is accepted.`,\n        ...memberLines(docs.groupMembers.get(group) ?? []),\n        \" */\",\n    ].join(\"\\n\");\n\nconst appendScalarAliases = (builder: ModuleBuilder, docs: GlDocContext): void => {\n    const seen: Set<string> = new Set();\n\n    for (const scalar of GL_SCALARS.values()) {\n        if (seen.has(scalar.tsAlias)) {\n            continue;\n        }\n\n        seen.add(scalar.tsAlias);\n\n        builder.appendDeclaration({\n            name: scalar.tsAlias,\n            code: `${scalarJsDoc(scalar.tsAlias, docs)}\\nexport type ${scalar.tsAlias} = number;`,\n        });\n    }\n};\n\nconst appendGroupAliases = (builder: ModuleBuilder, groupAliases: Map<string, string>, docs: GlDocContext): void => {\n    const sorted = sortStringsBy(groupAliases.entries(), ([key]) => key);\n\n    for (const [group, base] of sorted) {\n        builder.appendDeclaration({\n            name: group,\n            code: `${groupAliasJsDoc(group, base, docs)}\\nexport type ${group} = ${base};`,\n        });\n    }\n};\n\nconst renderTypesModule = (groupAliases: Map<string, string>, docs: GlDocContext): string => {\n    const builder = new ModuleBuilder();\n    builder.imports.addNamed(\"@gtkx/native\", \"ExternalObject\", true);\n    builder.imports.addNamed(\"@gtkx/native\", \"Handle\", true);\n\n    builder.appendDeclaration({\n        name: \"GLsync\",\n        code: `${syncJsDoc(docs)}\\nexport type GLsync = ExternalObject<Handle>;`,\n    });\n\n    builder.appendDeclaration({\n        name: \"GLpointer\",\n        code:\n            \"/** An opaque native pointer handle (e.g. a `glMapBufferRange` mapping). */\\n\" +\n            \"export type GLpointer = ExternalObject<Handle>;\",\n    });\n\n    appendScalarAliases(builder, docs);\n    appendGroupAliases(builder, groupAliases, docs);\n\n    return `${generatedHeader(docs)}\\n\\n${builder.toSource()}`;\n};\n\nconst appendTypeImports = (builder: ModuleBuilder, usedTypes: Set<string>): void => {\n    for (const alias of sortStrings(usedTypes)) {\n        if (TS_PRIMITIVES.has(alias)) {\n            continue;\n        }\n\n        builder.imports.addNamed(\"./types.js\", alias, true);\n    }\n};\n\nconst appendCommandBindings = (builder: ModuleBuilder, commands: RenderedCommand[]): void => {\n    for (const command of commands) {\n        if (command.binding !== undefined) {\n            builder.appendBinding(command.binding, command.binding);\n        }\n    }\n};\n\nconst appendCommandDeclarations = (builder: ModuleBuilder, commands: RenderedCommand[]): void => {\n    for (const command of commands) {\n        builder.appendDeclaration({ name: command.exportName, code: command.declaration });\n    }\n};\n\nconst renderCommandsModule = (\n    rendered: RenderedCommand[],\n    singulars: RenderedCommand[],\n    usedTypes: Set<string>,\n    docs: GlDocContext,\n): string => {\n    const builder = new ModuleBuilder();\n    builder.imports.addNamed(\"@gtkx/runtime\", \"t\");\n    appendTypeImports(builder, usedTypes);\n    builder.appendBinding(LIB_CONSTANT);\n    appendCommandBindings(builder, rendered);\n    appendCommandBindings(builder, singulars);\n    appendCommandDeclarations(builder, rendered);\n    appendCommandDeclarations(builder, singulars);\n\n    return `${generatedHeader(docs)}\\n\\n${builder.toSource()}`;\n};\n\nexport { renderEnumsModule, renderTypesModule, renderCommandsModule, type EnumRow };\n"]}

package/dist/khronos/notes.d.ts

@@ -0,0 +1,19 @@
+import type { GlExtensionAttribution } from "./extensions.js";
+import type { GlSymbolProvenance } from "./select.js";
+type MetadataNotesOptions = {
+    type: string;
+    group?: string;
+    len?: string;
+    objectClass?: string;
+    kinds: string[];
+    note?: string;
+};
+declare const commandExportName: (name: string) => string;
+declare const backtick: (text: string) => string;
+declare const backtickList: (values: string[]) => string;
+declare const asSentence: (text: string) => string;
+declare const provenanceLines: (provenance: GlSymbolProvenance, extensions: GlExtensionAttribution[]) => string[];
+declare const metadataNotes: ({ type, group, len, objectClass, kinds, note }: MetadataNotesOptions) => string;
+declare const kindDescriptions: (kinds: string[], table: Map<string, string>) => string;
+export { asSentence, backtick, backtickList, commandExportName, kindDescriptions, metadataNotes, type MetadataNotesOptions, provenanceLines, };
+//# sourceMappingURL=notes.d.ts.map

package/dist/khronos/notes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notes.d.ts","sourceRoot":"","sources":["../../src/khronos/notes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAa,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjE,KAAK,oBAAoB,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,QAAA,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,MACqC,CAAC;AAEhF,QAAA,MAAM,QAAQ,GAAI,MAAM,MAAM,KAAG,MAAuB,CAAC;AACzD,QAAA,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,KAAG,MAA2D,CAAC;AACrG,QAAA,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,MAAkD,CAAC;AA0BtF,QAAA,MAAM,eAAe,GAAI,YAAY,kBAAkB,EAAE,YAAY,sBAAsB,EAAE,KAAG,MAAM,EAKrG,CAAC;AAEF,QAAA,MAAM,aAAa,GAAI,gDAAgD,oBAAoB,KAAG,MAQ9E,CAAC;AAEjB,QAAA,MAAM,gBAAgB,GAAI,OAAO,MAAM,EAAE,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MACZ,CAAC;AAE7D,OAAO,EACH,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,KAAK,oBAAoB,EACzB,eAAe,GAClB,CAAC"}

package/dist/khronos/notes.js

@@ -0,0 +1,35 @@
+import { lowerFirst, toCamelIdentifier } from "@gtkx/utils";
+const commandExportName = (name) => toCamelIdentifier(name.startsWith("gl") ? lowerFirst(name.slice(2)) : name);
+const backtick = (text) => `\`${text}\``;
+const backtickList = (values) => values.map((value) => backtick(value)).join(", ");
+const asSentence = (text) => (text.endsWith(".") ? text : `${text}.`);
+const removalPhrase = (removal) => removal.comment === undefined
+    ? backtick(removal.feature)
+    : `${backtick(removal.feature)} (${removal.comment})`;
+const removalLine = (provenance) => {
+    const phrases = provenance.removals.map((removal) => removalPhrase(removal)).join(", ");
+    return ` * Removed from the core profile by ${phrases}, then restored by ${backtick(provenance.feature)}.`;
+};
+const extensionLine = (extensions) => {
+    const names = backtickList(extensions.map((extension) => extension.name));
+    return ` * Also provided by the ${names} extension${extensions.length === 1 ? "" : "s"}.`;
+};
+const extensionNoteLines = (extensions) => extensions.flatMap((extension) => extension.notes.map((note) => ` * ${backtick(extension.name)} note: ${asSentence(note)}`));
+const extensionLines = (extensions) => extensions.length === 0 ? [] : [extensionLine(extensions), ...extensionNoteLines(extensions)];
+const provenanceLines = (provenance, extensions) => [
+    ` * Provided by ${backtick(provenance.feature)}.`,
+    ...(provenance.removals.length > 0 ? [removalLine(provenance)] : []),
+    ...(provenance.requireComment === undefined ? [] : [` * Registry note: ${provenance.requireComment}`]),
+    ...extensionLines(extensions),
+];
+const metadataNotes = ({ type, group, len, objectClass, kinds, note }) => [
+    backtick(type),
+    ...(group === undefined ? [] : [`group ${backtick(group)}`]),
+    ...(len === undefined ? [] : [`length ${backtick(len)}`]),
+    ...(objectClass === undefined ? [] : [`object class ${backtick(objectClass)}`]),
+    ...kinds.map((kind) => `kind ${backtick(kind)}`),
+    ...(note === undefined ? [] : [note]),
+].join(", ");
+const kindDescriptions = (kinds, table) => kinds.flatMap((kind) => table.get(kind) ?? []).join(" ");
+export { asSentence, backtick, backtickList, commandExportName, kindDescriptions, metadataNotes, provenanceLines, };
+//# sourceMappingURL=notes.js.map

package/dist/khronos/notes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notes.js","sourceRoot":"","sources":["../../src/khronos/notes.ts"],"names":[],"mappings":"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","sourcesContent":["import { lowerFirst, toCamelIdentifier } from \"@gtkx/utils\";\nimport type { GlExtensionAttribution } from \"./extensions.js\";\nimport type { GlRemoval, GlSymbolProvenance } from \"./select.js\";\n\ntype MetadataNotesOptions = {\n    type: string;\n    group?: string;\n    len?: string;\n    objectClass?: string;\n    kinds: string[];\n    note?: string;\n};\n\nconst commandExportName = (name: string): string =>\n    toCamelIdentifier(name.startsWith(\"gl\") ? lowerFirst(name.slice(2)) : name);\n\nconst backtick = (text: string): string => `\\`${text}\\``;\nconst backtickList = (values: string[]): string => values.map((value) => backtick(value)).join(\", \");\nconst asSentence = (text: string): string => (text.endsWith(\".\") ? text : `${text}.`);\n\nconst removalPhrase = (removal: GlRemoval): string =>\n    removal.comment === undefined\n        ? backtick(removal.feature)\n        : `${backtick(removal.feature)} (${removal.comment})`;\n\nconst removalLine = (provenance: GlSymbolProvenance): string => {\n    const phrases = provenance.removals.map((removal) => removalPhrase(removal)).join(\", \");\n\n    return ` * Removed from the core profile by ${phrases}, then restored by ${backtick(provenance.feature)}.`;\n};\n\nconst extensionLine = (extensions: GlExtensionAttribution[]): string => {\n    const names = backtickList(extensions.map((extension) => extension.name));\n\n    return ` * Also provided by the ${names} extension${extensions.length === 1 ? \"\" : \"s\"}.`;\n};\n\nconst extensionNoteLines = (extensions: GlExtensionAttribution[]): string[] =>\n    extensions.flatMap((extension) =>\n        extension.notes.map((note) => ` * ${backtick(extension.name)} note: ${asSentence(note)}`));\n\nconst extensionLines = (extensions: GlExtensionAttribution[]): string[] =>\n    extensions.length === 0 ? [] : [extensionLine(extensions), ...extensionNoteLines(extensions)];\n\nconst provenanceLines = (provenance: GlSymbolProvenance, extensions: GlExtensionAttribution[]): string[] => [\n    ` * Provided by ${backtick(provenance.feature)}.`,\n    ...(provenance.removals.length > 0 ? [removalLine(provenance)] : []),\n    ...(provenance.requireComment === undefined ? [] : [` * Registry note: ${provenance.requireComment}`]),\n    ...extensionLines(extensions),\n];\n\nconst metadataNotes = ({ type, group, len, objectClass, kinds, note }: MetadataNotesOptions): string =>\n    [\n        backtick(type),\n        ...(group === undefined ? [] : [`group ${backtick(group)}`]),\n        ...(len === undefined ? [] : [`length ${backtick(len)}`]),\n        ...(objectClass === undefined ? [] : [`object class ${backtick(objectClass)}`]),\n        ...kinds.map((kind) => `kind ${backtick(kind)}`),\n        ...(note === undefined ? [] : [note]),\n    ].join(\", \");\n\nconst kindDescriptions = (kinds: string[], table: Map<string, string>): string =>\n    kinds.flatMap((kind) => table.get(kind) ?? []).join(\" \");\n\nexport {\n    asSentence,\n    backtick,\n    backtickList,\n    commandExportName,\n    kindDescriptions,\n    metadataNotes,\n    type MetadataNotesOptions,\n    provenanceLines,\n};\n"]}

package/dist/khronos/param-pair.d.ts

@@ -5,7 +5,7 @@ type ParamPair = {
     param: GlParam | undefined;
 };
 declare const paramPairAt: (plan: CommandPlan & {
-    ok: true;
+    isOk: true;
 }, index: number) => ParamPair;
 export { paramPairAt };
 //# sourceMappingURL=param-pair.d.ts.map

package/dist/khronos/param-pair.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"param-pair.d.ts","sourceRoot":"","sources":["../../src/khronos/param-pair.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAExD,KAAK,SAAS,GAAG;IACb,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IACjC,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;CAC9B,CAAC;AAEF,QAAA,MAAM,WAAW,GAAI,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,EAAE,OAAO,MAAM,KAAG,SAGrE,CAAC;AAEH,OAAO,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"param-pair.d.ts","sourceRoot":"","sources":["../../src/khronos/param-pair.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAExD,KAAK,SAAS,GAAG;IACb,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IACjC,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;CAC9B,CAAC;AAEF,QAAA,MAAM,WAAW,GAAI,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,EAAE,OAAO,MAAM,KAAG,SAGvE,CAAC;AAEH,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/khronos/param-pair.js.map

@@ -1 +1 @@
-{"version":3,"file":"param-pair.js","sourceRoot":"","sources":["../../src/khronos/param-pair.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,GAAG,CAAC,IAAgC,EAAE,KAAa,EAAa,EAAE,CAAC,CAAC;IACjF,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;IAC7B,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;CACpC,CAAC,CAAC;AAEH,OAAO,EAAE,WAAW,EAAE,CAAC","sourcesContent":["import type { GlParam } from \"./model.js\";\nimport type { CommandPlan, ParamPlan } from \"./plan.js\";\n\ntype ParamPair = {\n    paramPlan: ParamPlan | undefined;\n    param: GlParam | undefined;\n};\n\nconst paramPairAt = (plan: CommandPlan & { ok: true }, index: number): ParamPair => ({\n    paramPlan: plan.params[index],\n    param: plan.command.params[index],\n});\n\nexport { paramPairAt };\n"]}
+{"version":3,"file":"param-pair.js","sourceRoot":"","sources":["../../src/khronos/param-pair.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,GAAG,CAAC,IAAkC,EAAE,KAAa,EAAa,EAAE,CAAC,CAAC;IACnF,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;IAC7B,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;CACpC,CAAC,CAAC;AAEH,OAAO,EAAE,WAAW,EAAE,CAAC","sourcesContent":["import type { GlParam } from \"./model.js\";\nimport type { CommandPlan, ParamPlan } from \"./plan.js\";\n\ntype ParamPair = {\n    paramPlan: ParamPlan | undefined;\n    param: GlParam | undefined;\n};\n\nconst paramPairAt = (plan: CommandPlan & { isOk: true }, index: number): ParamPair => ({\n    paramPlan: plan.params[index],\n    param: plan.command.params[index],\n});\n\nexport { paramPairAt };\n"]}

package/dist/khronos/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/khronos/parse.ts"],"names":[],"mappings":"AAGA,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAU3C,QAAA,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,WAAW,EAWpD,CAAC;AAEF,QAAA,MAAM,OAAO,GAAI,MAAM,WAAW,KAAG,MAQpC,CAAC;AAEF,QAAA,MAAM,YAAY,GAAI,MAAM,WAAW,KAAG,WAAW,EAUpD,CAAC;AAEF,QAAA,MAAM,QAAQ,GAAI,MAAM,WAAW,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,SAU5D,CAAC;AAQF,QAAA,MAAM,WAAW,GAAI,MAAM,WAAW,EAAE,UAAU,GAAG,CAAC,MAAM,CAAC,KAAG,MAiB/D,CAAC;AAEF,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,CAAC"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/khronos/parse.ts"],"names":[],"mappings":"AAEA,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAW3C,QAAA,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,WAAW,EAUpD,CAAC;AAEF,QAAA,MAAM,OAAO,GAAI,MAAM,WAAW,KAAG,MAQpC,CAAC;AAEF,QAAA,MAAM,YAAY,GAAI,MAAM,WAAW,KAAG,WAAW,EAUpD,CAAC;AAEF,QAAA,MAAM,QAAQ,GAAI,MAAM,WAAW,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,SAU5D,CAAC;AAQF,QAAA,MAAM,WAAW,GAAI,MAAM,WAAW,EAAE,UAAU,GAAG,CAAC,MAAM,CAAC,KAAG,MAiB/D,CAAC;AAEF,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,CAAC"}

package/dist/khronos/parse.js

@@ -1,14 +1,13 @@
-import { readFileSync } from "node:fs";
-import { createXmlParser } from "../xml.js";
+import { createXmlParser, parseXmlFile } from "../xml.js";
 const ATTRIBUTES_KEY = ":@";
 const TEXT_KEY = "#text";
+const REGISTRY_LABEL = "OpenGL registry";
 const PARSER = createXmlParser({
     trimValues: false,
     preserveOrder: true,
 });
 const parseRegistryFile = (path) => {
-    const xml = readFileSync(path, "utf8");
-    const documentNodes = PARSER.parse(xml);
+    const documentNodes = parseXmlFile({ parser: PARSER, label: REGISTRY_LABEL, path });
     for (const node of documentNodes) {
         if (nodeTag(node) === "registry") {
             return nodeChildren(node);

package/dist/khronos/parse.js.map

@@ -1 +1 @@
-{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/khronos/parse.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFileSync } from \"node:fs\";\nimport { createXmlParser } from \"../xml.js\";\n\ntype OrderedNode = Record<string, unknown>;\n\nconst ATTRIBUTES_KEY = \":@\";\nconst TEXT_KEY = \"#text\";\n\nconst PARSER = createXmlParser({\n    trimValues: false,\n    preserveOrder: true,\n});\n\nconst parseRegistryFile = (path: string): OrderedNode[] => {\n    const xml = readFileSync(path, \"utf8\");\n    const documentNodes = PARSER.parse(xml) as OrderedNode[];\n\n    for (const node of documentNodes) {\n        if (nodeTag(node) === \"registry\") {\n            return nodeChildren(node);\n        }\n    }\n\n    throw new Error(`No <registry> root element found in ${path}`);\n};\n\nconst nodeTag = (node: OrderedNode): string => {\n    for (const key of Object.keys(node)) {\n        if (key !== ATTRIBUTES_KEY && key !== TEXT_KEY) {\n            return key;\n        }\n    }\n\n    return TEXT_KEY;\n};\n\nconst nodeChildren = (node: OrderedNode): OrderedNode[] => {\n    const tag = nodeTag(node);\n\n    if (tag === TEXT_KEY) {\n        return [];\n    }\n\n    const children = node[tag];\n\n    return Array.isArray(children) ? (children as OrderedNode[]) : [];\n};\n\nconst nodeAttr = (node: OrderedNode, name: string): string | undefined => {\n    const attributes = node[ATTRIBUTES_KEY];\n\n    if (typeof attributes !== \"object\" || attributes === null) {\n        return undefined;\n    }\n\n    const value = (attributes as Record<string, unknown>)[`@_${name}`];\n\n    return typeof value === \"string\" ? value : undefined;\n};\n\nconst nodeText = (node: OrderedNode): string | undefined => {\n    const value = node[TEXT_KEY];\n\n    return typeof value === \"string\" ? value : undefined;\n};\n\nconst collectText = (node: OrderedNode, skipTags: Set<string>): string => {\n    let text = \"\";\n\n    for (const child of nodeChildren(node)) {\n        const childText = nodeText(child);\n\n        if (childText !== undefined) {\n            text += childText;\n            continue;\n        }\n\n        if (!skipTags.has(nodeTag(child))) {\n            text += collectText(child, skipTags);\n        }\n    }\n\n    return text;\n};\n\nexport { parseRegistryFile, nodeTag, nodeChildren, nodeAttr, collectText, type OrderedNode };\n"]}
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/khronos/parse.ts"],"names":[],"mappings":"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","sourcesContent":["import { createXmlParser, parseXmlFile } from \"../xml.js\";\n\ntype OrderedNode = Record<string, unknown>;\n\nconst ATTRIBUTES_KEY = \":@\";\nconst TEXT_KEY = \"#text\";\nconst REGISTRY_LABEL = \"OpenGL registry\";\n\nconst PARSER = createXmlParser({\n    trimValues: false,\n    preserveOrder: true,\n});\n\nconst parseRegistryFile = (path: string): OrderedNode[] => {\n    const documentNodes = parseXmlFile({ parser: PARSER, label: REGISTRY_LABEL, path }) as OrderedNode[];\n\n    for (const node of documentNodes) {\n        if (nodeTag(node) === \"registry\") {\n            return nodeChildren(node);\n        }\n    }\n\n    throw new Error(`No <registry> root element found in ${path}`);\n};\n\nconst nodeTag = (node: OrderedNode): string => {\n    for (const key of Object.keys(node)) {\n        if (key !== ATTRIBUTES_KEY && key !== TEXT_KEY) {\n            return key;\n        }\n    }\n\n    return TEXT_KEY;\n};\n\nconst nodeChildren = (node: OrderedNode): OrderedNode[] => {\n    const tag = nodeTag(node);\n\n    if (tag === TEXT_KEY) {\n        return [];\n    }\n\n    const children = node[tag];\n\n    return Array.isArray(children) ? (children as OrderedNode[]) : [];\n};\n\nconst nodeAttr = (node: OrderedNode, name: string): string | undefined => {\n    const attributes = node[ATTRIBUTES_KEY];\n\n    if (typeof attributes !== \"object\" || attributes === null) {\n        return undefined;\n    }\n\n    const value = (attributes as Record<string, unknown>)[`@_${name}`];\n\n    return typeof value === \"string\" ? value : undefined;\n};\n\nconst nodeText = (node: OrderedNode): string | undefined => {\n    const value = node[TEXT_KEY];\n\n    return typeof value === \"string\" ? value : undefined;\n};\n\nconst collectText = (node: OrderedNode, skipTags: Set<string>): string => {\n    let text = \"\";\n\n    for (const child of nodeChildren(node)) {\n        const childText = nodeText(child);\n\n        if (childText !== undefined) {\n            text += childText;\n            continue;\n        }\n\n        if (!skipTags.has(nodeTag(child))) {\n            text += collectText(child, skipTags);\n        }\n    }\n\n    return text;\n};\n\nexport { parseRegistryFile, nodeTag, nodeChildren, nodeAttr, collectText, type OrderedNode };\n"]}

package/dist/khronos/pipeline.d.ts

@@ -1,5 +1,5 @@
 import { type GlExclusionReason } from "./plan.js";
-import { type GlSelection } from "./select.js";
+import { type GlSelection, type GlSubset } from "./select.js";
 type GlExclusion = {
     command: string;
     reason: GlExclusionReason;
@@ -10,6 +10,8 @@ type GlGenerationReport = {
     emittedCommands: number;
     derivedSingulars: number;
     exclusions: GlExclusion[];
+    enumExclusions: string[];
+    coreRemovals: GlSubset["removed"];
 };
 type GlGenerationResult = {
     files: Map<string, string>;
@@ -20,5 +22,5 @@ type GlGenerationOptions = {
     overrideExports: Set<string>;
 };
 declare const generateGlModules: (options: GlGenerationOptions) => GlGenerationResult;
-export { generateGlModules, type GlGenerationReport, type GlGenerationResult };
+export { generateGlModules, type GlGenerationReport };
 //# sourceMappingURL=pipeline.d.ts.map

package/dist/khronos/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/khronos/pipeline.ts"],"names":[],"mappings":"AAIA,OAAO,EAEH,KAAK,iBAAiB,EAKzB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,KAAK,WAAW,EAA6B,MAAM,aAAa,CAAC;AAE1E,KAAK,WAAW,GAAG;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,iBAAiB,CAAC;CAC7B,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACtB,SAAS,EAAE,WAAW,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,WAAW,EAAE,CAAC;CAC7B,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACtB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,MAAM,EAAE,kBAAkB,CAAC;CAC9B,CAAC;AAIF,KAAK,mBAAmB,GAAG;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAChC,CAAC;AAkQF,QAAA,MAAM,iBAAiB,GAAI,SAAS,mBAAmB,KAAG,kBAsCzD,CAAC;AAEF,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,CAAC"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/khronos/pipeline.ts"],"names":[],"mappings":"AAMA,OAAO,EAEH,KAAK,iBAAiB,EAKzB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAsD,MAAM,aAAa,CAAC;AAElH,KAAK,WAAW,GAAG;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,iBAAiB,CAAC;CAC7B,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACtB,SAAS,EAAE,WAAW,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;CACrC,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACtB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,MAAM,EAAE,kBAAkB,CAAC;CAC9B,CAAC;AAIF,KAAK,mBAAmB,GAAG;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAChC,CAAC;AAoTF,QAAA,MAAM,iBAAiB,GAAI,SAAS,mBAAmB,KAAG,kBAqCzD,CAAC;AAEF,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,CAAC"}

package/dist/khronos/pipeline.js

@@ -1,4 +1,6 @@
 import { sanitizeIdentifier, sortStrings, sortStringsBy } from "@gtkx/utils";
+import { buildDocContext } from "./doc-context.js";
+import { buildExtensionIndex } from "./extensions.js";
 import { loadGlRegistry } from "./model.js";
 import { renderCommandsModule, renderEnumsModule, renderTypesModule } from "./modules.js";
 import { paramPairAt } from "./param-pair.js";
@@ -51,7 +53,12 @@ const PLAN_POLICY = {
     singleValuedQueries: SINGLE_VALUED_QUERIES,
 };
 const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
-const GROUP_BEARING_PARAM_KINDS = new Set(["scalar", "array-in", "ref-out"]);
+const GROUP_BEARING_PARAM_KINDS = new Set([
+    "scalar",
+    "array-in",
+    "ref-out",
+    "ref-array-out",
+]);
 const GL_SELECTION = { api: "gl", version: 4.6, profile: "core" };
 const enumExportName = (name) => sanitizeIdentifier((name.startsWith("GL_") ? name.slice(3) : name).toUpperCase());
 const enumLiteral = (token) => {
@@ -124,7 +131,7 @@ const planSelectedCommand = (registry, name) => {
         return { command: name, reason: "override-owned" };
     }
     const plan = planCommand(command, PLAN_POLICY);
-    if (!plan.ok) {
+    if (!plan.isOk) {
         return { command: name, reason: plan.reason };
     }
     return plan;
@@ -134,11 +141,11 @@ const planSelectedCommands = (registry, commandNames) => {
     const okPlans = [];
     const planFeatures = new Map();
     const sortedCommands = sortStringsBy(commandNames.entries(), ([key]) => key);
-    for (const [name, feature] of sortedCommands) {
+    for (const [name, provenance] of sortedCommands) {
         const result = planSelectedCommand(registry, name);
-        if ("ok" in result) {
+        if ("isOk" in result) {
             okPlans.push(result);
-            planFeatures.set(name, feature);
+            planFeatures.set(name, provenance);
         }
         else {
             exclusions.push(result);
@@ -146,18 +153,42 @@ const planSelectedCommands = (registry, commandNames) => {
     }
     return { okPlans, planFeatures, exclusions };
 };
-const buildEnumRows = (registry, enumNames) => {
-    const enumRows = [];
+const buildEnumRows = (registry, enumNames, selection) => {
+    const rows = [];
+    const enumExclusions = [];
     const sortedEnums = sortStringsBy(enumNames.entries(), ([key]) => key);
-    for (const [name, feature] of sortedEnums) {
-        const token = resolveEnum(registry, name);
+    for (const [name, provenance] of sortedEnums) {
+        const token = resolveEnum(registry, name, selection.api);
         const literal = enumLiteral(token);
         if (literal === undefined) {
-            continue;
+            enumExclusions.push(name);
+        }
+        else {
+            rows.push({ token, exportName: enumExportName(name), literal, provenance });
         }
-        enumRows.push({ token, exportName: enumExportName(name), literal, feature });
     }
-    return enumRows;
+    return { rows, enumExclusions };
+};
+const provenanceFor = (planFeatures, name) => {
+    const found = planFeatures.get(name);
+    if (found === undefined) {
+        throw new Error(`Command ${name} was planned without a selection provenance`);
+    }
+    return found;
+};
+const renderCommands = (plans, planFeatures, usedTypes, docs) => {
+    const rendered = [];
+    const singulars = [];
+    for (const plan of plans) {
+        const provenance = provenanceFor(planFeatures, plan.command.name);
+        rendered.push(renderCommand(plan, provenance, usedTypes, docs));
+        const singular = deriveGenSingular(plan, provenance, usedTypes, docs) ??
+            deriveDeleteSingular(plan, provenance, usedTypes, docs);
+        if (singular !== undefined) {
+            singulars.push(singular);
+        }
+    }
+    return { rendered, singulars };
 };
 const claimExportName = (exportNames, name, owner) => {
     const existing = exportNames.get(name);
@@ -190,23 +221,21 @@ const generateGlModules = (options) => {
     const registry = loadGlRegistry(options.registryPath);
     const subset = selectSubset(registry, selection);
     const { okPlans, planFeatures, exclusions } = planSelectedCommands(registry, subset.commands);
+    const { rows, enumExclusions } = buildEnumRows(registry, subset.enums, selection);
+    const groupAliases = collectGroupAliases(okPlans);
+    const docs = buildDocContext({
+        registry,
+        extensions: buildExtensionIndex(registry, selection),
+        plans: okPlans,
+        enumRows: rows,
+    });
     const usedTypes = new Set();
-    const rendered = [];
-    const singulars = [];
-    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 { rendered, singulars } = renderCommands(okPlans, planFeatures, usedTypes, docs);
+    assertExportNamesDisjoint(rendered, singulars, rows, options.overrideExports);
     const files = new Map([
-        ["types.ts", renderTypesModule(collectGroupAliases(okPlans))],
-        ["enums.ts", renderEnumsModule(enumRows)],
-        ["commands.ts", renderCommandsModule(rendered, singulars, usedTypes)],
+        ["types.ts", renderTypesModule(groupAliases, docs)],
+        ["enums.ts", renderEnumsModule(rows, docs)],
+        ["commands.ts", renderCommandsModule(rendered, singulars, usedTypes, docs)],
     ]);
     return {
         files,
@@ -216,6 +245,8 @@ const generateGlModules = (options) => {
             emittedCommands: rendered.length,
             derivedSingulars: singulars.length,
             exclusions,
+            enumExclusions,
+            coreRemovals: subset.removed,
         },
     };
 };