@gtkx/codegen 1.0.0-rc.4 → 1.0.0

package/src/khronos/modules.ts

@@ -1,50 +1,132 @@
 import { sortStrings, sortStringsBy } from "@gtkx/utils";
-import type { GlEnum } from "./model.js";
+import type { GlDocContext } from "./doc-context.js";
+import type { GlEnum, GlType } from "./model.js";
 import type { RenderedCommand } from "./render.js";
+import type { GlSymbolProvenance } from "./select.js";
 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\";";
+type EnumRow = {
+    token: GlEnum;
+    exportName: string;
+    literal: string;
+    provenance: GlSymbolProvenance;
+};
 
-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: Set<string> = new Set(["boolean", "string", "void", "number"]);
 
-const quotedGroupList = (groups: string[]): string => groups.map((group) => `\`${group}\``).join(", ");
+const attributionLine = (line: string): string => (line.length === 0 ? " *" : ` * ${line}`);
 
-const renderEnumsModule = (
-    tokens: { token: GlEnum; exportName: string; literal: string; feature: string }[],
-): string => {
-    const builder = new ModuleBuilder();
+const attributionLines = (registryComment: string | undefined): string[] =>
+    registryComment === undefined
+        ? []
+        : [" *", ...registryComment.split("\n").map((line) => attributionLine(line))];
+
+const generatedHeader = (docs: GlDocContext): string =>
+    [
+        "/**",
+        " * GENERATED FILE: do not edit.",
+        " *",
+        " * Derived from the Khronos OpenGL registry (gl.xml).",
+        ...attributionLines(docs.registryComment),
+        " */",
+    ].join("\n");
+
+const groupsLine = (groups: string[]): string[] => (groups.length === 0 ? [] : [` * Groups: ${backtickList(groups)}.`]);
 
-    for (const { token, exportName, literal, feature } of tokens) {
-        const groupNote = token.groups.length > 0 ? ` Groups: ${quotedGroupList(token.groups)}.` : "";
+const rangePhrase = (vendor: string | undefined): string =>
+    vendor === undefined ? "Registry enumerant block" : `Allocated from the ${backtick(vendor)} enumerant range`;
 
-        builder.appendDeclaration(
-            `/** \`${token.name}\`, provided by \`${feature}\`.${groupNote} */\n` +
-            `export const ${exportName} = ${literal};`,
-        );
+const rangeLine = ({ vendor, blockComment }: GlEnum): string[] => {
+    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: Map<string, string>): string => {
+const tokenNoteLines = (token: GlEnum): string[] => [
+    ...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 }: EnumRow, docs: GlDocContext): string =>
+    [
+        "/**",
+        ` * ${backtick(token.name)}.`,
+        " *",
+        ...provenanceLines(provenance, docs.extensionEnums.get(token.name) ?? []),
+        ...tokenNoteLines(token),
+        " */",
+    ].join("\n");
+
+const renderEnumsModule = (tokens: EnumRow[], docs: GlDocContext): 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>;",
-    );
+    for (const row of tokens) {
+        builder.appendDeclaration(`${enumJsDoc(row, docs)}\nexport const ${row.exportName} = ${row.literal};`);
+    }
 
-    builder.appendDeclaration(
-        "/** An opaque native pointer handle (e.g. a `glMapBufferRange` mapping). */\n" +
-        "export type GLpointer = ExternalObject<Handle>;",
-    );
+    return `${generatedHeader(docs)}\n\n${builder.toSource()}`;
+};
+
+const scalarSentences = (alias: string, type: GlType): string[] => [
+    `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: string, docs: GlDocContext): string => {
+    const type = docs.types.get(alias);
+
+    if (type === undefined) {
+        return `/** The C ${backtick(alias)} scalar. */`;
+    }
 
+    return `/** ${scalarSentences(alias, type).join(" ")} */`;
+};
+
+const syncJsDoc = (docs: GlDocContext): string => {
+    const type = docs.types.get("GLsync");
+
+    if (type === undefined) {
+        return `/** ${SYNC_SUMMARY}. */`;
+    }
+
+    return `/** ${SYNC_SUMMARY}: ${backtick(type.declaration)}. */`;
+};
+
+const groupSummary = (group: string, isBitmask: boolean): string =>
+    isBitmask
+        ? `Registry enum group ${backtick(group)}, declared as a bitmask: members are combined with \`|\`.`
+        : `Registry enum group ${backtick(group)}.`;
+
+const memberLines = (members: string[]): string[] =>
+    members.length === 0 ? [] : [" *", ` * Members: ${backtickList(members)}.`];
+
+const groupAliasJsDoc = (group: string, base: string, docs: GlDocContext): string =>
+    [
+        "/**",
+        ` * ${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: ModuleBuilder, docs: GlDocContext): void => {
     const seen: Set<string> = new Set();
 
     for (const scalar of GL_SCALARS.values()) {
@@ -53,22 +135,33 @@ const renderTypesModule = (groupAliases: Map<string, string>): string => {
         }
 
         seen.add(scalar.tsAlias);
-
-        builder.appendDeclaration(
-            `/** The C \`${scalar.tsAlias}\` scalar. */\nexport type ${scalar.tsAlias} = number;`,
-        );
+        builder.appendDeclaration(`${scalarJsDoc(scalar.tsAlias, docs)}\nexport type ${scalar.tsAlias} = number;`);
     }
+};
 
-    const sortedAliases = sortStringsBy(groupAliases.entries(), ([key]) => key);
+const appendGroupAliases = (builder: ModuleBuilder, groupAliases: Map<string, string>, docs: GlDocContext): void => {
+    const sorted = 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};`,
-        );
+    for (const [group, base] of sorted) {
+        builder.appendDeclaration(`${groupAliasJsDoc(group, base, docs)}\nexport type ${group} = ${base};`);
     }
+};
+
+const renderTypesModule = (groupAliases: Map<string, string>, docs: GlDocContext): string => {
+    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>;",
+    );
+
+    appendScalarAliases(builder, docs);
+    appendGroupAliases(builder, groupAliases, docs);
 
-    return `${GENERATED_HEADER}\n\n${builder.toSource()}`;
+    return `${generatedHeader(docs)}\n\n${builder.toSource()}`;
 };
 
 const appendTypeImports = (builder: ModuleBuilder, usedTypes: Set<string>): void => {
@@ -99,6 +192,7 @@ const renderCommandsModule = (
     rendered: RenderedCommand[],
     singulars: RenderedCommand[],
     usedTypes: Set<string>,
+    docs: GlDocContext,
 ): string => {
     const builder = new ModuleBuilder();
     builder.imports.addNamed("@gtkx/runtime", "t");
@@ -109,7 +203,7 @@ const renderCommandsModule = (
     appendCommandDeclarations(builder, rendered);
     appendCommandDeclarations(builder, singulars);
 
-    return `${GENERATED_HEADER}\n\n${builder.toSource()}`;
+    return `${generatedHeader(docs)}\n\n${builder.toSource()}`;
 };
 
-export { renderEnumsModule, renderTypesModule, renderCommandsModule };
+export { renderEnumsModule, renderTypesModule, renderCommandsModule, type EnumRow };

package/src/khronos/notes.ts

@@ -0,0 +1,74 @@
+import { lowerFirst, toCamelIdentifier } from "@gtkx/utils";
+import type { GlExtensionAttribution } from "./extensions.js";
+import type { GlRemoval, GlSymbolProvenance } from "./select.js";
+
+type MetadataNotesOptions = {
+    type: string;
+    group?: string;
+    len?: string;
+    objectClass?: string;
+    kinds: string[];
+    note?: string;
+};
+
+const commandExportName = (name: string): string =>
+    toCamelIdentifier(name.startsWith("gl") ? lowerFirst(name.slice(2)) : name);
+
+const backtick = (text: string): string => `\`${text}\``;
+const backtickList = (values: string[]): string => values.map((value) => backtick(value)).join(", ");
+const asSentence = (text: string): string => (text.endsWith(".") ? text : `${text}.`);
+
+const removalPhrase = (removal: GlRemoval): string =>
+    removal.comment === undefined
+        ? backtick(removal.feature)
+        : `${backtick(removal.feature)} (${removal.comment})`;
+
+const removalLine = (provenance: GlSymbolProvenance): string => {
+    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: GlExtensionAttribution[]): string => {
+    const names = backtickList(extensions.map((extension) => extension.name));
+
+    return ` * Also provided by the ${names} extension${extensions.length === 1 ? "" : "s"}.`;
+};
+
+const extensionNoteLines = (extensions: GlExtensionAttribution[]): string[] =>
+    extensions.flatMap((extension) =>
+        extension.notes.map((note) => ` * ${backtick(extension.name)} note: ${asSentence(note)}`));
+
+const extensionLines = (extensions: GlExtensionAttribution[]): string[] =>
+    extensions.length === 0 ? [] : [extensionLine(extensions), ...extensionNoteLines(extensions)];
+
+const provenanceLines = (provenance: GlSymbolProvenance, extensions: GlExtensionAttribution[]): string[] => [
+    ` * 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 }: MetadataNotesOptions): string =>
+    [
+        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: string[], table: Map<string, string>): string =>
+    kinds.flatMap((kind) => table.get(kind) ?? []).join(" ");
+
+export {
+    asSentence,
+    backtick,
+    backtickList,
+    commandExportName,
+    kindDescriptions,
+    metadataNotes,
+    type MetadataNotesOptions,
+    provenanceLines,
+};

package/src/khronos/param-pair.ts

@@ -6,7 +6,7 @@ type ParamPair = {
     param: GlParam | undefined;
 };
 
-const paramPairAt = (plan: CommandPlan & { ok: true }, index: number): ParamPair => ({
+const paramPairAt = (plan: CommandPlan & { isOk: true }, index: number): ParamPair => ({
     paramPlan: plan.params[index],
     param: plan.command.params[index],
 });

package/src/khronos/pipeline.ts

@@ -1,6 +1,8 @@
 import { sanitizeIdentifier, sortStrings, sortStringsBy } from "@gtkx/utils";
+import { buildDocContext, type GlDocContext } from "./doc-context.js";
+import { buildExtensionIndex } from "./extensions.js";
 import { type GlEnum, loadGlRegistry } from "./model.js";
-import { renderCommandsModule, renderEnumsModule, renderTypesModule } from "./modules.js";
+import { type EnumRow, renderCommandsModule, renderEnumsModule, renderTypesModule } from "./modules.js";
 import { paramPairAt } from "./param-pair.js";
 import {
     type CommandPlan,
@@ -11,7 +13,7 @@ import {
     planCommand,
 } from "./plan.js";
 import { deriveDeleteSingular, deriveGenSingular, renderCommand, type RenderedCommand } from "./render.js";
-import { type GlSelection, resolveEnum, selectSubset } from "./select.js";
+import { type GlSelection, type GlSubset, type GlSymbolProvenance, resolveEnum, selectSubset } from "./select.js";
 
 type GlExclusion = {
     command: string;
@@ -24,6 +26,8 @@ type GlGenerationReport = {
     emittedCommands: number;
     derivedSingulars: number;
     exclusions: GlExclusion[];
+    enumExclusions: string[];
+    coreRemovals: GlSubset["removed"];
 };
 
 type GlGenerationResult = {
@@ -31,26 +35,29 @@ type GlGenerationResult = {
     report: GlGenerationReport;
 };
 
-type GroupBearingParamPlan = Extract<ParamPlan, { kind: "scalar" | "array-in" | "ref-out" }>;
+type GroupBearingParamPlan = Extract<ParamPlan, { kind: "scalar" | "array-in" | "ref-out" | "ref-array-out" }>;
 
 type GlGenerationOptions = {
     registryPath: string;
     overrideExports: Set<string>;
 };
 
-type OkPlan = CommandPlan & { ok: true };
+type OkPlan = CommandPlan & { isOk: true };
 
 type PlannedSelection = {
     okPlans: OkPlan[];
-    planFeatures: Map<string, string>;
+    planFeatures: Map<string, GlSymbolProvenance>;
     exclusions: GlExclusion[];
 };
 
-type EnumRow = {
-    token: GlEnum;
-    exportName: string;
-    literal: string;
-    feature: string;
+type EnumSelection = {
+    rows: EnumRow[];
+    enumExclusions: string[];
+};
+
+type RenderedCommands = {
+    rendered: RenderedCommand[];
+    singulars: RenderedCommand[];
 };
 
 const BYTE_OFFSET_PARAMS: Set<string> = new Set([
@@ -103,7 +110,14 @@ const PLAN_POLICY: GlPlanPolicy = {
 };
 
 const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
-const GROUP_BEARING_PARAM_KINDS: Set<ParamPlan["kind"]> = new Set(["scalar", "array-in", "ref-out"]);
+
+const GROUP_BEARING_PARAM_KINDS: Set<ParamPlan["kind"]> = new Set([
+    "scalar",
+    "array-in",
+    "ref-out",
+    "ref-array-out",
+]);
+
 const GL_SELECTION: GlSelection = { api: "gl", version: 4.6, profile: "core" };
 
 const enumExportName = (name: string): string =>
@@ -204,7 +218,7 @@ const planSelectedCommand = (registry: ReturnType<typeof loadGlRegistry>, name:
 
     const plan = planCommand(command, PLAN_POLICY);
 
-    if (!plan.ok) {
+    if (!plan.isOk) {
         return { command: name, reason: plan.reason };
     }
 
@@ -213,19 +227,19 @@ const planSelectedCommand = (registry: ReturnType<typeof loadGlRegistry>, name:
 
 const planSelectedCommands = (
     registry: ReturnType<typeof loadGlRegistry>,
-    commandNames: Map<string, string>,
+    commandNames: Map<string, GlSymbolProvenance>,
 ): PlannedSelection => {
     const exclusions: GlExclusion[] = [];
     const okPlans: OkPlan[] = [];
-    const planFeatures: Map<string, string> = new Map();
+    const planFeatures: Map<string, GlSymbolProvenance> = 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);
         }
@@ -234,22 +248,62 @@ const planSelectedCommands = (
     return { okPlans, planFeatures, exclusions };
 };
 
-const buildEnumRows = (registry: ReturnType<typeof loadGlRegistry>, enumNames: Map<string, string>): EnumRow[] => {
-    const enumRows: EnumRow[] = [];
+const buildEnumRows = (
+    registry: ReturnType<typeof loadGlRegistry>,
+    enumNames: Map<string, GlSymbolProvenance>,
+    selection: GlSelection,
+): EnumSelection => {
+    const rows: EnumRow[] = [];
+    const enumExclusions: string[] = [];
     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 { rows, enumExclusions };
+};
+
+const provenanceFor = (planFeatures: Map<string, GlSymbolProvenance>, name: string): GlSymbolProvenance => {
+    const found = planFeatures.get(name);
+
+    if (found === undefined) {
+        throw new Error(`Command ${name} was planned without a selection provenance`);
     }
 
-    return enumRows;
+    return found;
+};
+
+const renderCommands = (
+    plans: OkPlan[],
+    planFeatures: Map<string, GlSymbolProvenance>,
+    usedTypes: Set<string>,
+    docs: GlDocContext,
+): RenderedCommands => {
+    const rendered: RenderedCommand[] = [];
+    const singulars: RenderedCommand[] = [];
+
+    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: Map<string, string>, name: string, owner: string): void => {
@@ -299,27 +353,24 @@ const generateGlModules = (options: GlGenerationOptions): GlGenerationResult =>
     const registry = loadGlRegistry(options.registryPath);
     const subset = selectSubset(registry, selection);
     const { okPlans, planFeatures, exclusions } = planSelectedCommands(registry, subset.commands);
-    const usedTypes: Set<string> = new Set();
-    const rendered: RenderedCommand[] = [];
-    const singulars: RenderedCommand[] = [];
+    const { rows, enumExclusions } = buildEnumRows(registry, subset.enums, selection);
+    const groupAliases = collectGroupAliases(okPlans);
 
-    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 docs = buildDocContext({
+        registry,
+        extensions: buildExtensionIndex(registry, selection),
+        plans: okPlans,
+        enumRows: rows,
+    });
 
-    const enumRows = buildEnumRows(registry, subset.enums);
-    assertExportNamesDisjoint(rendered, singulars, enumRows, options.overrideExports);
+    const usedTypes: Set<string> = new Set();
+    const { rendered, singulars } = renderCommands(okPlans, planFeatures, usedTypes, docs);
+    assertExportNamesDisjoint(rendered, singulars, rows, options.overrideExports);
 
     const files: Map<string, string> = 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 {
@@ -330,6 +381,8 @@ const generateGlModules = (options: GlGenerationOptions): GlGenerationResult =>
             emittedCommands: rendered.length,
             derivedSingulars: singulars.length,
             exclusions,
+            enumExclusions,
+            coreRemovals: subset.removed,
         },
     };
 };

package/src/khronos/plan.ts

@@ -51,12 +51,12 @@ type GlPlanPolicy = {
 
 type CommandPlan =
     | {
-        ok: true;
+        isOk: true;
         command: GlCommand;
         params: ParamPlan[];
         returnPlan: ReturnPlan;
     } |
-    { ok: false; command: GlCommand; reason: GlExclusionReason };
+    { isOk: false; command: GlCommand; reason: GlExclusionReason };
 
 type ParamOutcome = { plan: ParamPlan } | { reason: GlExclusionReason };
 
@@ -317,13 +317,13 @@ const planCommand = (command: GlCommand, policy: GlPlanPolicy): CommandPlan => {
         const outcome = planParam(command, param, policy);
 
         if ("reason" in outcome) {
-            return { ok: false, command, reason: outcome.reason };
+            return { isOk: false, command, reason: outcome.reason };
         }
 
         params.push(outcome.plan);
     }
 
-    return { ok: true, command, params, returnPlan: planReturn(command) };
+    return { isOk: true, command, params, returnPlan: planReturn(command) };
 };
 
 export {
@@ -331,7 +331,6 @@ export {
     parseCType,
     planCommand,
     type GlScalar,
-    type ParsedCType,
     type ParamPlan,
     type ReturnPlan,
     type GlExclusionReason,