@gtkx/codegen 1.0.0-rc.4 → 1.0.0

package/src/gir/parse.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { createXmlParser } 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 MULTI_TAGS: Set<string> = new Set([
@@ -16,6 +17,7 @@ const MULTI_TAGS: Set<string> = new Set([
     "alias",
     "union",
     "method",
+    "virtual-method",
     "constructor",
     "property",
     "field",
@@ -141,12 +143,12 @@ const docTextFromObject = (value: object): string | undefined => {
     return typeof text === "string" ? normalizeDoc(text) : undefined;
 };
 
-const getDoc = (node: RawNode | undefined): string | undefined => {
+const docElementText = (node: RawNode | undefined, tag: string): string | undefined => {
     if (node === undefined) {
         return undefined;
     }
 
-    const value = firstDocValue(node.doc);
+    const value = firstDocValue(node[tag]);
 
     if (typeof value === "string") {
         return normalizeDoc(value);
@@ -159,6 +161,9 @@ const getDoc = (node: RawNode | undefined): string | undefined => {
     return docTextFromObject(value);
 };
 
+const getDoc = (node: RawNode | undefined): string | undefined => docElementText(node, "doc");
+const getDocDeprecated = (node: RawNode | undefined): string | undefined => docElementText(node, "doc-deprecated");
+
 export {
     GIR_CONSTRUCTOR_TAG,
     parseGirFile,
@@ -170,5 +175,6 @@ export {
     getChildren,
     getChild,
     getDoc,
+    getDocDeprecated,
     type RawNode,
 };

package/src/gir/primitives.ts

@@ -1,3 +1,4 @@
+/** A fundamental C type GIR can name, collapsed to the marshalling category GTKX treats it as. */
 type PrimitiveCategory =
     | "void" |
     "boolean" |

package/src/gir/property.ts

@@ -1,20 +1,36 @@
 import type { ParseContext, TypeId } from "./type-id.js";
+import { documentedFromNode, type GirAnnotations } from "./annotations.js";
 import { type ParameterTransfer, transferOwnership } from "./parameter.js";
-import { attr, getDoc, isAttrTrue, nameAttr, type RawNode } from "./parse.js";
+import { attr, isAttrTrue, type RawNode } from "./parse.js";
 import { typeRefFromNode } from "./type-ref.js";
 
+/** A GObject property declared on a class or interface, with the annotations its accessors are generated from. */
 type GirProperty = {
+    /** Canonical property name, dashed the way GObject registers it. */
     name: string;
+    /** Documentation prose from GIR, emitted as the accessor's JSDoc. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the property. */
+    annotations: GirAnnotations;
+    /** The property's value type, absent when GIR declares none. */
     type: TypeId | undefined;
+    /** Whether GObject exposes the value for reading, which admits a generated getter. */
     readable: boolean;
+    /** Whether GObject accepts a value for the property, which admits a generated setter. */
     writable: boolean;
+    /** Whether GObject sets the property during construction, using its default when none is supplied. */
     construct: boolean;
+    /** Whether the property can only be set at construction. */
     constructOnly: boolean;
+    /** Whether GIR exposes the property to bindings. */
     introspectable: boolean;
+    /** How ownership of the value transfers, which decides the descriptor the accessors marshal through. */
     transferOwnership: ParameterTransfer;
+    /** Method GIR names as reading the property, which the generated getter delegates to. */
     getter: string | undefined;
+    /** Method GIR names as writing the property, which the generated setter delegates to. */
     setter: string | undefined;
+    /** The property's default, as GIR spells it. */
     defaultValue: string | undefined;
 };
 
@@ -22,8 +38,7 @@ const isConstructableProperty = (property: GirProperty): boolean =>
     property.writable || property.construct || property.constructOnly;
 
 const propertyFromNode = (node: RawNode, context: ParseContext): GirProperty => ({
-    name: nameAttr(node),
-    doc: getDoc(node),
+    ...documentedFromNode(node),
     type: typeRefFromNode(node, context),
     readable: isAttrTrue(node, "readable", true),
     writable: isAttrTrue(node, "writable"),

package/src/gir/record.ts

@@ -1,26 +1,48 @@
 import type { ParseContext } from "./type-id.js";
+import { documentedFromNode, type GirAnnotations } from "./annotations.js";
 import { collectFields, type GirField } from "./field.js";
 import { functionFromNode, type GirFunction } from "./function.js";
-import { attr, getChildren, getDoc, GIR_CONSTRUCTOR_TAG, isAttrTrue, type RawNode } from "./parse.js";
+import { attr, getChildren, GIR_CONSTRUCTOR_TAG, isAttrTrue, type RawNode } from "./parse.js";
 
+/** A C struct or union declared by a GIR namespace: a plain record, a boxed type, or a GObject vtable. */
 type GirRecord = {
+    /** Whether the record is the class or interface struct holding another type's virtual methods. */
     isVtable: boolean;
+    /** Name within the declaring namespace, such as `"TextIter"`. */
     name: string;
+    /** Raw gtk-doc text from the GIR, undefined when the record is undocumented. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the record. */
+    annotations: GirAnnotations;
+    /** C struct name, such as `"GtkTextIter"`. */
     cType: string | undefined;
+    /** GLib type name the record is registered under, present when it is a boxed type. */
     glibTypeName: string | undefined;
+    /** Name of the function registering the record's GType, such as `"gtk_text_iter_get_type"`. */
     glibGetType: string | undefined;
+    /** Name of the function taking a reference, for reference-counted records. */
     glibRefFunc: string | undefined;
+    /** Name of the function dropping a reference, for reference-counted records. */
     glibUnrefFunc: string | undefined;
+    /** Name of the function duplicating an instance, used when the record has no ref function. */
     copyFunc: string | undefined;
+    /** Name of the function releasing an instance, used when the record has no unref function. */
     freeFunc: string | undefined;
+    /** Whether the struct is only ever handled behind a pointer, so its layout stays hidden. */
     disguised: boolean;
+    /** Whether the struct's fields are private, so instances cannot be allocated or read directly. */
     opaque: boolean;
+    /** Whether the record is exposed to language bindings. */
     introspectable: boolean;
+    /** Struct members: the named fields first, then the anonymous inline unions, then the inline records. */
     fields: GirField[];
+    /** Functions taking an instance of the record as their first argument. */
     methods: GirFunction[];
+    /** Functions returning a new instance of the record. */
     constructors: GirFunction[];
+    /** Functions scoped to the record but taking no instance. */
     functions: GirFunction[];
+    /** Whether the record is a union, so its fields overlap instead of following one another. */
     isUnion: boolean;
 };
 
@@ -31,8 +53,8 @@ const recordFromNode = (
     context: ParseContext,
 ): GirRecord => ({
     isVtable,
+    ...documentedFromNode(node),
     name: attr(node, "name") ?? attr(node, "glib:name") ?? "",
-    doc: getDoc(node),
     cType: attr(node, "c:type"),
     glibTypeName: attr(node, "glib:type-name"),
     glibGetType: attr(node, "glib:get-type"),

package/src/gir/size.ts

@@ -11,6 +11,11 @@ type FieldSlot = {
     bitWidth: number | undefined;
 };
 
+type FieldSlots = {
+    slots: FieldSlot[];
+    size: number;
+};
+
 type FieldLayoutInput = {
     layout: FieldLayout;
     bits: number | undefined;
@@ -39,7 +44,7 @@ const roundUp = (value: number, multiple: number): number => {
     return remainder === 0 ? value : value + (multiple - remainder);
 };
 
-const computeUnionSlots = (fields: FieldLayoutInput[]): { slots: FieldSlot[]; size: number } => {
+const computeUnionSlots = (fields: FieldLayoutInput[]): FieldSlots => {
     let maxSize = 0;
     let maxAlign = 1;
 
@@ -95,7 +100,7 @@ const processStructField = (state: StructLayoutState, slots: FieldSlot[], field:
     pushBitfield({ state, slots, field, align, bits: field.bits });
 };
 
-const computeStructSlots = (fields: FieldLayoutInput[]): { slots: FieldSlot[]; size: number } => {
+const computeStructSlots = (fields: FieldLayoutInput[]): FieldSlots => {
     const slots: FieldSlot[] = [];
     const state: StructLayoutState = { bitCursor: 0, maxAlign: 1 };
 
@@ -106,7 +111,7 @@ const computeStructSlots = (fields: FieldLayoutInput[]): { slots: FieldSlot[]; s
     return { slots, size: roundUp(roundUp(state.bitCursor, 8) / 8, state.maxAlign) };
 };
 
-const computeFieldSlots = (fields: FieldLayoutInput[], isUnion = false): { slots: FieldSlot[]; size: number } =>
+const computeFieldSlots = (fields: FieldLayoutInput[], isUnion = false): FieldSlots =>
     isUnion ? computeUnionSlots(fields) : computeStructSlots(fields);
 
 export { layoutOfPrimitive, computeFieldSlots, type FieldLayout, type FieldSlot, type FieldLayoutInput };

package/src/gir/type-id.ts

@@ -1,43 +1,89 @@
 import type { RawNode } from "./parse.js";
 import type { PrimitiveCategory } from "./primitives.js";
 
-type TypeId = { nsId: number; id: number };
+/** A reference to a parsed type: the type table holding it, and its slot in that table. */
+type TypeId = {
+    /** Id of the table holding the type: a namespace's, or the internal one primitives and varargs intern into. */
+    nsId: number;
+    /** Slot the type occupies in that table. */
+    id: number;
+};
+
+/** Which GLib container a {@link ListType} is. */
 type ListFlavor = (typeof LIST_FLAVOR_BY_NAME)[keyof typeof LIST_FLAVOR_BY_NAME];
-type PrimitiveType = { kind: "primitive"; category: PrimitiveCategory };
-type VarargsType = { kind: "varargs" };
 
+/** A type that marshals directly as a value, such as `gint` or `utf8`. */
+type PrimitiveType = {
+    /** Discriminates {@link StructuralType}. */
+    kind: "primitive";
+    /** The scalar the type marshals as. */
+    category: PrimitiveCategory;
+};
+
+/** The trailing `...` argument list of a variadic C function. */
+type VarargsType = {
+    /** Discriminates {@link StructuralType}. */
+    kind: "varargs";
+};
+
+/** A C array, along with whatever the GIR says about how its length is determined. */
 type CArrayType = {
+    /** Discriminates {@link StructuralType}. */
     kind: "carray";
+    /** Type of the array's elements, paired with `elementCType` to build the element descriptor. */
     element: TypeId;
+    /** C declaration of an element, which tells an inline struct apart from a pointer to one. */
     elementCType: string | undefined;
+    /** C declaration of the array itself. */
+    arrayCType: string | undefined;
+    /** Index of the parameter, or of the sibling record field, carrying the length. */
     lengthParameterIndex: number | undefined;
+    /** Element count when the array has a fixed size. */
     fixedSize: number | undefined;
+    /** Whether the array ends at a null element. */
     isZeroTerminated: boolean;
 };
 
+/** A GLib list or array container over a single element type. */
 type ListType = {
+    /** Discriminates {@link StructuralType}. */
     kind: "list";
+    /** Which container the type is. */
     flavor: ListFlavor;
+    /** Type the container's elements marshal as, which the list descriptor wraps. */
     element: TypeId;
 };
 
+/** A `GLib.HashTable`. */
 type HashTableType = {
+    /** Discriminates {@link StructuralType}. */
     kind: "hashtable";
+    /** Type the keys marshal as, rendered as the key half of a `Record` or `Map`. */
     key: TypeId;
+    /** Type the values marshal as, rendered as the value half of a `Record` or `Map`. */
     value: TypeId;
 };
 
+/** A type the GIR describes by its structure rather than by a name it declares. */
 type StructuralType = PrimitiveType | VarargsType | CArrayType | ListType | HashTableType;
 
+/** The hooks the GIR parsers use to reference and register types while walking one namespace. */
 type ParseContext = {
+    /** Id of the namespace being parsed. */
     nsId: number;
+    /** Resolves a GIR type name, optionally namespace-qualified, reserving a slot when it is not parsed yet. */
     findType(name: string): TypeId;
+    /** Interns a primitive type and returns its id. */
     addPrimitive(category: PrimitiveCategory): TypeId;
+    /** Interns the varargs type and returns its id. */
     addVarargs(): TypeId;
+    /** Registers an unnamed container type in the namespace and returns its id. */
     addContainer(type: CArrayType | ListType | HashTableType): TypeId;
+    /** Parses an inline `<callback>` node, registers it as an unnamed type, and returns its id. */
     addAnonymousCallback(node: RawNode): TypeId;
 };
 
+/** GIR type names of the GLib containers, mapped to the {@link ListFlavor} each one parses to. */
 const LIST_FLAVOR_BY_NAME = {
     "GLib.List": "glist",
     "GLib.SList": "gslist",

package/src/gir/type-ref.ts

@@ -88,6 +88,7 @@ const arrayTypeRefFromNode = (arrayNode: RawNode, context: ParseContext): TypeId
         kind: "carray",
         element,
         elementCType: elementNode === undefined ? undefined : attr(elementNode, "c:type"),
+        arrayCType: attr(arrayNode, "c:type"),
         lengthParameterIndex: intAttr(arrayNode, "length"),
         fixedSize: intAttr(arrayNode, "fixed-size"),
         isZeroTerminated: isAttrTrue(arrayNode, "zero-terminated", true),

package/src/gir/type.ts

@@ -5,14 +5,58 @@ import type { GirAlias, GirNamespace } from "./namespace.js";
 import type { GirRecord } from "./record.js";
 import type { StructuralType } from "./type-id.js";
 
+/** A named entity a GIR namespace declares, discriminated by `kind` and carrying the parsed node. */
 type EntityType =
-    | { kind: "class"; namespace: GirNamespace; value: GirClass } |
-    { kind: "interface"; namespace: GirNamespace; value: GirClass } |
-    { kind: "record"; namespace: GirNamespace; value: GirRecord } |
-    { kind: "enum"; namespace: GirNamespace; value: GirEnum } |
-    { kind: "callback"; namespace: GirNamespace; value: GirCallback } |
-    { kind: "alias"; namespace: GirNamespace; value: GirAlias };
+    | {
+        /** Discriminates {@link EntityType}. */
+        kind: "class";
+        /** Namespace declaring the class. */
+        namespace: GirNamespace;
+        /** Parsed class, carrying its GType metadata and the members it declares. */
+        value: GirClass;
+    } |
+    {
+        /** Discriminates {@link EntityType}. */
+        kind: "interface";
+        /** Namespace declaring the interface. */
+        namespace: GirNamespace;
+        /** Parsed interface, modeled the same way as a class. */
+        value: GirClass;
+    } |
+    {
+        /** Discriminates {@link EntityType}. */
+        kind: "record";
+        /** Namespace declaring the record. */
+        namespace: GirNamespace;
+        /** Parsed record, either a struct or a union. */
+        value: GirRecord;
+    } |
+    {
+        /** Discriminates {@link EntityType}. */
+        kind: "enum";
+        /** Namespace declaring the enumeration. */
+        namespace: GirNamespace;
+        /** Parsed enumeration or bitfield. */
+        value: GirEnum;
+    } |
+    {
+        /** Discriminates {@link EntityType}. */
+        kind: "callback";
+        /** Namespace declaring the callback. */
+        namespace: GirNamespace;
+        /** Parsed callback signature. */
+        value: GirCallback;
+    } |
+    {
+        /** Discriminates {@link EntityType}. */
+        kind: "alias";
+        /** Namespace declaring the alias. */
+        namespace: GirNamespace;
+        /** Parsed alias, holding the type it stands for. */
+        value: GirAlias;
+    };
 
+/** What a GIR type reference resolves to: a structural type, or an entity a namespace declares. */
 type GirType = StructuralType | EntityType;
 
 export { type EntityType, type GirType };

package/src/khronos/args.ts

@@ -1,6 +1,6 @@
 import { toCamelIdentifier } from "@gtkx/utils";
 import type { GlCommand, GlParam } from "./model.js";
-import type { CommandPlan, GlScalar, ParamPlan } from "./plan.js";
+import type { CommandPlan, GlScalar, ParamPlan, ReturnPlan } from "./plan.js";
 import {
     tArray,
     tBoolean,
@@ -15,14 +15,14 @@ import {
 import { paramPairAt } from "./param-pair.js";
 
 type InArg = {
-    out: false;
+    isOut: false;
     name: string;
     tsType: string;
     descriptor: string;
 };
 
 type OutArg = {
-    out: true;
+    isOut: true;
     cellName: string;
     seed: string;
     tsType: string;
@@ -31,7 +31,7 @@ type OutArg = {
 };
 
 type PlannedArg = InArg | OutArg;
-type OutArgCell = Pick<OutArg, "out" | "cellName" | "paramIndex">;
+type OutArgCell = Pick<OutArg, "isOut" | "cellName" | "paramIndex">;
 type OutArgFields = Pick<OutArg, "seed" | "tsType" | "descriptor">;
 
 type OutArgFieldsOptions = {
@@ -54,6 +54,29 @@ const OUT_PLAN_KINDS: Set<string> = new Set(["ref-out", "ref-array-out", "ref-fi
 const scalarAliasOrGroup = (scalar: GlScalar, group: string | undefined): string =>
     group !== undefined && scalar.isGroupBearing === true ? group : scalar.tsAlias;
 
+const returnPlanTsType = (plan: ReturnPlan, group: string | undefined): string => {
+    switch (plan.kind) {
+        case "void": {
+            return "void";
+        }
+        case "scalar": {
+            return scalarAliasOrGroup(plan.scalar, group);
+        }
+        case "boolean": {
+            return "boolean";
+        }
+        case "string": {
+            return "string";
+        }
+        case "sync": {
+            return "GLsync";
+        }
+        case "opaque-pointer": {
+            return "GLpointer";
+        }
+    }
+};
+
 const paramIndexByName = (command: GlCommand, name: string): number => {
     const index = command.params.findIndex((param) => param.name === name);
 
@@ -71,7 +94,7 @@ const arrayInTsType = (scalar: GlScalar, group: string | undefined): string => {
 };
 
 const inArg = (name: string, tsType: string, descriptor: string): InArg => ({
-    out: false,
+    isOut: false,
     name,
     tsType,
     descriptor,
@@ -141,7 +164,7 @@ const outArgFields = (options: OutArgFieldsOptions): OutArgFields => {
 
             return {
                 seed: `const ${cellName} = { value: new Array<number>(${lenIdentifier}).fill(0) };`,
-                tsType: `${track(plan.scalar.tsAlias)}[]`,
+                tsType: `${track(scalarAliasOrGroup(plan.scalar, param.group))}[]`,
                 descriptor: tRef(tSizedArray(plan.scalar.descriptor, sizeIndex)),
             };
         }
@@ -182,14 +205,14 @@ const buildOutArg = (options: BuildArgOptions, track: (alias: string) => string)
     }
 
     const cellName = `out${String(outIndex)}`;
-    const cell: OutArgCell = { out: true, cellName, paramIndex: index };
+    const cell: OutArgCell = { isOut: true, cellName, paramIndex: index };
 
     return { ...cell, ...outArgFields({ command, plan, param, cellName, track }) };
 };
 
 const isOutPlan = (plan: ParamPlan): boolean => OUT_PLAN_KINDS.has(plan.kind);
-const isInArg = (arg: PlannedArg): arg is InArg => !arg.out;
-const isOutArg = (arg: PlannedArg): arg is OutArg => arg.out;
+const isInArg = (arg: PlannedArg): arg is InArg => !arg.isOut;
+const isOutArg = (arg: PlannedArg): arg is OutArg => arg.isOut;
 
 const buildArg = (options: BuildArgOptions, name: string, track: (alias: string) => string): PlannedArg =>
     isOutPlan(options.plan) ? buildOutArg(options, track) : buildInArg(options, name, track);
@@ -203,7 +226,7 @@ const trackInto =
         };
 
 const planArgs = (
-    plan: CommandPlan & { ok: true },
+    plan: CommandPlan & { isOk: true },
     usedTypes: Set<string>,
 ): { args: PlannedArg[]; ins: InArg[]; outs: OutArg[] } => {
     const track = trackInto(usedTypes);
@@ -230,7 +253,7 @@ const planArgs = (
 };
 
 const scalarPrefixArg = (
-    plan: CommandPlan & { ok: true },
+    plan: CommandPlan & { isOk: true },
     index: number,
     track: (alias: string) => string,
 ): InArg | undefined => {
@@ -251,7 +274,7 @@ const scalarPrefixArg = (
     );
 };
 
-const scalarPrefixArgs = (plan: CommandPlan & { ok: true }, usedTypes: Set<string>): InArg[] | undefined => {
+const scalarPrefixArgs = (plan: CommandPlan & { isOk: true }, usedTypes: Set<string>): InArg[] | undefined => {
     const track = trackInto(usedTypes);
     const prefix: InArg[] = [];
 
@@ -268,4 +291,4 @@ const scalarPrefixArgs = (plan: CommandPlan & { ok: true }, usedTypes: Set<strin
     return prefix;
 };
 
-export { scalarAliasOrGroup, trackInto, planArgs, scalarPrefixArgs, type InArg, type OutArg };
+export { returnPlanTsType, scalarAliasOrGroup, trackInto, planArgs, scalarPrefixArgs, type InArg, type OutArg };

package/src/khronos/doc-context.ts

@@ -0,0 +1,62 @@
+import { sortStrings } from "@gtkx/utils";
+import type { GlExtensionAttribution, GlExtensionIndex } from "./extensions.js";
+import type { GlEnum, GlRegistry, GlType } from "./model.js";
+import type { CommandPlan } from "./plan.js";
+
+type GlDocEnumRow = {
+    token: GlEnum;
+    exportName: string;
+};
+
+type GlDocContext = {
+    registryComment?: string;
+    kinds: Map<string, string>;
+    types: Map<string, GlType>;
+    aliasTargets: Map<string, string[]>;
+    extensionCommands: Map<string, GlExtensionAttribution[]>;
+    extensionEnums: Map<string, GlExtensionAttribution[]>;
+    bitmaskGroups: Set<string>;
+    emittedCommands: Set<string>;
+    groupMembers: Map<string, string[]>;
+};
+
+type BuildDocContextOptions = {
+    registry: GlRegistry;
+    extensions: GlExtensionIndex;
+    plans: (CommandPlan & { isOk: true })[];
+    enumRows: GlDocEnumRow[];
+};
+
+const buildGroupMembers = (rows: GlDocEnumRow[]): Map<string, string[]> => {
+    const members: Map<string, string[]> = new Map();
+
+    for (const row of rows) {
+        for (const group of row.token.groups) {
+            members.set(group, [...(members.get(group) ?? []), row.exportName]);
+        }
+    }
+
+    for (const [group, names] of members) {
+        members.set(group, sortStrings(names));
+    }
+
+    return members;
+};
+
+const buildDocContext = (options: BuildDocContextOptions): GlDocContext => {
+    const { registry, extensions, plans, enumRows } = options;
+
+    return {
+        ...(registry.comment !== undefined && { registryComment: registry.comment }),
+        kinds: registry.kinds,
+        types: registry.types,
+        aliasTargets: registry.aliasTargets,
+        extensionCommands: extensions.commands,
+        extensionEnums: extensions.enums,
+        bitmaskGroups: registry.bitmaskGroups,
+        emittedCommands: new Set(plans.map((plan) => plan.command.name)),
+        groupMembers: buildGroupMembers(enumRows),
+    };
+};
+
+export { buildDocContext, type GlDocContext };

package/src/khronos/extensions.ts

@@ -0,0 +1,85 @@
+import { sortStrings } from "@gtkx/utils";
+import type { GlExtension, GlInterfaceBlock, GlRegistry } from "./model.js";
+import type { GlSelection } from "./select.js";
+
+type GlExtensionAttribution = {
+    name: string;
+    notes: string[];
+};
+
+type GlExtensionIndex = {
+    commands: Map<string, GlExtensionAttribution[]>;
+    enums: Map<string, GlExtensionAttribution[]>;
+};
+
+type PendingIndex = Map<string, Map<string, string[]>>;
+
+type PendingExtensionIndex = {
+    commands: PendingIndex;
+    enums: PendingIndex;
+};
+
+const SUPPORTED_APIS: Set<string> = new Set(["gl", "glcore"]);
+
+const isExtensionSupported = (extension: GlExtension): boolean =>
+    extension.supported.some((api) => SUPPORTED_APIS.has(api));
+
+const isBlockIncluded = (block: GlInterfaceBlock, selection: GlSelection): boolean =>
+    block.kind === "require" &&
+    (block.api === undefined || block.api === selection.api) &&
+    (block.profile === undefined || block.profile === selection.profile);
+
+const blockNotes = (extension: GlExtension, block: GlInterfaceBlock): string[] => [
+    ...(extension.comment === undefined ? [] : [extension.comment]),
+    ...(block.comment === undefined ? [] : [block.comment]),
+];
+
+const appendMembers = (index: PendingIndex, names: string[], extension: string, notes: string[]): void => {
+    for (const name of names) {
+        const byExtension = index.get(name) ?? new Map<string, string[]>();
+        byExtension.set(extension, [...(byExtension.get(extension) ?? []), ...notes]);
+        index.set(name, byExtension);
+    }
+};
+
+const indexExtension = (index: PendingExtensionIndex, extension: GlExtension, selection: GlSelection): void => {
+    for (const block of extension.blocks) {
+        if (!isBlockIncluded(block, selection)) {
+            continue;
+        }
+
+        const notes = blockNotes(extension, block);
+        appendMembers(index.commands, block.commands, extension.name, notes);
+        appendMembers(index.enums, block.enums, extension.name, notes);
+    }
+};
+
+const attributionsFor = (byExtension: Map<string, string[]>): GlExtensionAttribution[] =>
+    sortStrings(byExtension.keys()).map((name) => ({
+        name,
+        notes: [...new Set(byExtension.get(name))],
+    }));
+
+const finalizeIndex = (pending: PendingIndex): Map<string, GlExtensionAttribution[]> => {
+    const index: Map<string, GlExtensionAttribution[]> = new Map();
+
+    for (const [name, byExtension] of pending) {
+        index.set(name, attributionsFor(byExtension));
+    }
+
+    return index;
+};
+
+const buildExtensionIndex = (registry: GlRegistry, selection: GlSelection): GlExtensionIndex => {
+    const pending: PendingExtensionIndex = { commands: new Map(), enums: new Map() };
+
+    for (const extension of registry.extensions) {
+        if (isExtensionSupported(extension)) {
+            indexExtension(pending, extension, selection);
+        }
+    }
+
+    return { commands: finalizeIndex(pending.commands), enums: finalizeIndex(pending.enums) };
+};
+
+export { buildExtensionIndex, type GlExtensionAttribution, type GlExtensionIndex };