@gtkx/codegen 1.0.0-rc.4 → 1.1.0

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/guards.ts

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

package/src/internal.ts

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

package/src/json.ts

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

package/src/khronos/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 };