@gtkx/codegen 0.21.0 → 1.0.0-rc.1

package/src/gir/type-ref.ts

@@ -1,179 +1,74 @@
-import { attr, attrBool, childOf, childrenOf, type RawNode } from "./parse.js";
-import { type PrimitiveCategory, primitiveCategory } from "./primitives.js";
+import { attr, childOf, childrenOf, intAttr, nameAttr, type RawNode } from "./parse.js";
+import { primitiveCategory } from "./primitives.js";
+import { type CArrayType, LIST_FLAVOR_BY_NAME, type ListFlavor, type ParseContext, type TypeId } from "./type-id.js";
 
-/**
- * Lazily-resolved reference to a GIR type as it appears in a `<type>` or
- * `<array>` slot.
- *
- * The reference captures everything the writers need at emission time
- * without forcing entity resolution to happen at parse time (which would
- * impose a topological-sort order on namespace loading). Resolution into a
- * concrete `GirClass` / `GirBoxed` / `GirEnum` / … is performed on demand
- * by the writers via `GirRepository.resolveNamed`.
- */
-export type GirTypeRef =
-    | PrimitiveTypeRef
-    | NamedTypeRef
-    | ArrayTypeRef
-    | ListTypeRef
-    | HashTableTypeRef
-    | InlineCallbackTypeRef
-    | VarargsTypeRef;
+const LIST_FLAVOR_BY_NAME_LOOKUP: Map<string, ListFlavor> = new Map(Object.entries(LIST_FLAVOR_BY_NAME));
 
-/** A GIR scalar primitive: `gint`, `gboolean`, `utf8`, `gpointer`, etc. */
-export type PrimitiveTypeRef = {
-    readonly kind: "primitive";
-    readonly category: PrimitiveCategory;
-    readonly cType: string | undefined;
+const elementRefOf = (node: RawNode, context: ParseContext): TypeId => {
+    const elementNode = childOf(node, "type");
+    return elementNode === undefined ? pointerFallback(context) : typeRefFromTypeNode(elementNode, context);
 };
 
-/**
- * A named type that resolves to a class, interface, boxed, enum, alias, or
- * fundamental in some namespace.
- *
- * `namespaceName` is the namespace prefix from the GIR (`"GLib"`, `"Gtk"`,
- * …) or `undefined` for an unqualified reference. The unqualified form
- * implies "look in the namespace the reference appears in".
- */
-export type NamedTypeRef = {
-    readonly kind: "named";
-    readonly namespaceName: string | undefined;
-    readonly typeName: string;
-    readonly cType: string | undefined;
-};
-
-/** A C array (`<array>`) with optional length, fixed-size, or zero-terminated metadata. */
-export type ArrayTypeRef = {
-    readonly kind: "array";
-    readonly element: GirTypeRef;
-    readonly cType: string | undefined;
-    readonly lengthParameterIndex: number | undefined;
-    readonly fixedSize: number | undefined;
-    readonly zeroTerminated: boolean;
-};
-
-/** A GLib `GList` / `GSList` / `GPtrArray` / `GArray` / `GByteArray`. */
-export type ListTypeRef = {
-    readonly kind: "list";
-    readonly flavor: "glist" | "gslist" | "gptrarray" | "garray" | "gbytearray";
-    readonly element: GirTypeRef;
-    readonly cType: string | undefined;
-};
-
-/** A GLib `GHashTable` with key and value element types. */
-export type HashTableTypeRef = {
-    readonly kind: "hashtable";
-    readonly key: GirTypeRef;
-    readonly value: GirTypeRef;
-    readonly cType: string | undefined;
-};
-
-/** An inline `<callback>` (used for vtable slots and callback parameters). */
-type InlineCallbackTypeRef = {
-    readonly kind: "callback";
-    readonly callback: RawNode;
-};
-
-/** A `<varargs/>` parameter placeholder; not marshalable. */
-type VarargsTypeRef = { readonly kind: "varargs" };
-
-const LIST_KIND_BY_NAME: ReadonlyMap<string, "glist" | "gslist" | "gptrarray" | "garray" | "gbytearray"> = new Map([
-    ["GLib.List", "glist"],
-    ["GLib.SList", "gslist"],
-    ["GLib.PtrArray", "gptrarray"],
-    ["GLib.Array", "garray"],
-    ["GLib.ByteArray", "gbytearray"],
-] as const);
-
-/**
- * Builds a {@link GirTypeRef} from a parent XML node whose first `<type>`,
- * `<array>`, or `<varargs>` child describes the slot.
- *
- * Pass the parent (`<parameter>`, `<return-value>`, `<field>`, `<property>`,
- * `<constant>`, `<alias>`). The helper extracts the right child and routes
- * to {@link typeRefFromTypeNode}.
- *
- * @param parent - The element whose typed slot we are inspecting
- * @returns The reference, or `undefined` if no type slot exists
- */
-export const typeRefFromSlot = (parent: RawNode | undefined): GirTypeRef | undefined => {
+export const typeRefFromNode = (parent: RawNode | undefined, context: ParseContext): TypeId | undefined => {
     if (parent === undefined) return undefined;
-    if (childOf(parent, "varargs") !== undefined) return { kind: "varargs" };
+    if (childOf(parent, "varargs") !== undefined) return context.addVarargs();
     const arrayNode = childOf(parent, "array");
-    if (arrayNode !== undefined) return arrayTypeRefFromNode(arrayNode);
+    if (arrayNode !== undefined) return arrayTypeRefFromNode(arrayNode, context);
     const typeNode = childOf(parent, "type");
-    if (typeNode !== undefined) return typeRefFromTypeNode(typeNode);
+    if (typeNode !== undefined) return typeRefFromTypeNode(typeNode, context);
     const callback = childOf(parent, "callback");
-    if (callback !== undefined) return { kind: "callback", callback };
+    if (callback !== undefined) return context.addAnonymousCallback(callback);
     return undefined;
 };
 
-/**
- * Builds a {@link GirTypeRef} from a `<type>` element.
- *
- * Splits a `Namespace.TypeName` form into namespace + type, recognises GLib
- * container types (`GLib.List`, `GLib.HashTable`, …) by name and routes
- * them to the dedicated branches, otherwise produces a primitive or named
- * reference for later resolution.
- *
- * @param typeNode - A `<type>` element
- */
-const typeRefFromTypeNode = (typeNode: RawNode): GirTypeRef => {
-    const name = attr(typeNode, "name") ?? "";
-    const cType = attr(typeNode, "c:type");
+const typeRefFromTypeNode = (typeNode: RawNode, context: ParseContext): TypeId => {
+    const name = nameAttr(typeNode);
 
-    const listFlavor = LIST_KIND_BY_NAME.get(name);
+    const listFlavor = LIST_FLAVOR_BY_NAME_LOOKUP.get(name);
     if (listFlavor !== undefined) {
-        const elementNode = childOf(typeNode, "type");
-        const element = elementNode === undefined ? pointerFallback() : typeRefFromTypeNode(elementNode);
-        return { kind: "list", flavor: listFlavor, element, cType };
+        return context.addContainer({ kind: "list", flavor: listFlavor, element: elementRefOf(typeNode, context) });
     }
 
     if (name === "GLib.HashTable") {
         const elementTypes = childrenOf(typeNode, "type");
         const keyNode = elementTypes[0];
         const valueNode = elementTypes[1];
-        return {
+        return context.addContainer({
             kind: "hashtable",
-            key: keyNode === undefined ? pointerFallback() : typeRefFromTypeNode(keyNode),
-            value: valueNode === undefined ? pointerFallback() : typeRefFromTypeNode(valueNode),
-            cType,
-        };
+            key: keyNode === undefined ? pointerFallback(context) : typeRefFromTypeNode(keyNode, context),
+            value: valueNode === undefined ? pointerFallback(context) : typeRefFromTypeNode(valueNode, context),
+        });
     }
 
     const primitive = primitiveCategory(name);
     if (primitive !== undefined) {
-        return { kind: "primitive", category: primitive, cType };
+        return context.addPrimitive(primitive);
     }
 
-    const [namespaceName, typeName] = splitOptionalNamespace(name);
-    return { kind: "named", namespaceName, typeName, cType };
+    return context.findType(name);
 };
 
-const arrayTypeRefFromNode = (arrayNode: RawNode): ArrayTypeRef | ListTypeRef => {
-    const elementNode = childOf(arrayNode, "type");
-    const element: GirTypeRef = elementNode === undefined ? pointerFallback() : typeRefFromTypeNode(elementNode);
-    const cType = attr(arrayNode, "c:type");
+const arrayTypeRefFromNode = (arrayNode: RawNode, context: ParseContext): TypeId => {
+    const element = elementRefOf(arrayNode, context);
     const arrayName = attr(arrayNode, "name");
-    const listFlavor = arrayName === undefined ? undefined : LIST_KIND_BY_NAME.get(arrayName);
+    const listFlavor = arrayName === undefined ? undefined : LIST_FLAVOR_BY_NAME_LOOKUP.get(arrayName);
     if (listFlavor !== undefined) {
-        return { kind: "list", flavor: listFlavor, element, cType };
+        return context.addContainer({ kind: "list", flavor: listFlavor, element });
     }
-    const lengthAttr = attr(arrayNode, "length");
-    const fixedSizeAttr = attr(arrayNode, "fixed-size");
-    return {
-        kind: "array",
+    const elementNode = childOf(arrayNode, "type");
+    const carray: CArrayType = {
+        kind: "carray",
         element,
-        cType,
-        lengthParameterIndex: lengthAttr === undefined ? undefined : Number.parseInt(lengthAttr, 10),
-        fixedSize: fixedSizeAttr === undefined ? undefined : Number.parseInt(fixedSizeAttr, 10),
-        zeroTerminated: attrBool(arrayNode, "zero-terminated", false),
+        elementCType: elementNode === undefined ? undefined : attr(elementNode, "c:type"),
+        lengthParameterIndex: intAttr(arrayNode, "length"),
+        fixedSize: intAttr(arrayNode, "fixed-size"),
     };
+    return context.addContainer(carray);
 };
 
-const pointerFallback = (): PrimitiveTypeRef => ({ kind: "primitive", category: "pointer", cType: undefined });
+const pointerFallback = (context: ParseContext): TypeId => context.addPrimitive("pointer");
 
-const splitOptionalNamespace = (name: string): [string | undefined, string] => {
+export const splitOptionalNamespace = (name: string): [string | undefined, string] => {
     const dot = name.indexOf(".");
     if (dot === -1) return [undefined, name];
     return [name.slice(0, dot), name.slice(dot + 1)];

package/src/gir/type.ts

@@ -0,0 +1,16 @@
+import type { GirCallback } from "./callback.js";
+import type { GirClass } from "./class.js";
+import type { GirEnum } from "./enum.js";
+import type { GirAlias, GirNamespace } from "./namespace.js";
+import type { GirRecord } from "./record.js";
+import type { StructuralType } from "./type-id.js";
+
+export 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 };
+
+export type GirType = StructuralType | EntityType;

package/src/index.ts

@@ -1,16 +1,21 @@
-/**
- * Public API of `@gtkx/codegen`.
- *
- * The package exposes a single entry point — {@link CodegenRunner} — that
- * orchestrates the GIR-driven code generation for the FFI and React
- * surfaces. Internal modules (`gir/`, `dsl/`, `writers/`, `ffi/`,
- * `react/`) are not part of the supported surface and may change in any
- * release.
- */
 export {
-    CODEGEN_VERSION,
-    type CodegenFingerprint,
-    computeFingerprint,
-    FINGERPRINT_FILENAME,
-} from "./fingerprint.js";
-export { CodegenRunner } from "./runner.js";
+    API_SYMBOL_KINDS,
+    type ApiLookupResult,
+    type ApiNamespaceSummary,
+    type ApiReference,
+    type ApiReferenceOptions,
+    type ApiSearchOptions,
+    type ApiSymbol,
+    type ApiSymbolKind,
+    loadApiReference,
+} from "./docs/api-reference.js";
+export {
+    type DocsElementLink,
+    type DocsNamespace,
+    type DocsOptions,
+    type DocsResult,
+    writeDocs,
+} from "./docs/pipeline.js";
+export { resolveGirPath } from "./gir/gir-path.js";
+export { discoverGirNamespaces, resolveLibraries } from "./gir/libraries.js";
+export { runCodegen } from "./runner.js";

package/src/khronos/args.ts

@@ -0,0 +1,202 @@
+import { toCamelIdentifier } from "@gtkx/utils";
+import {
+    tArray,
+    tBoolean,
+    tBuffer,
+    tFixedArray,
+    tInlineStruct,
+    tRef,
+    tSizedArray,
+    tString,
+    tUint64,
+} from "../analysis/descriptor.js";
+import type { GlCommand } from "./model.js";
+import type { CommandPlan, GlScalar, ParamPlan } from "./plan.js";
+
+export const scalarAliasOrGroup = (scalar: GlScalar, group: string | undefined): string =>
+    group !== undefined && scalar.groupBearing === true ? group : scalar.tsAlias;
+
+const paramIndexByName = (command: GlCommand, name: string): number => {
+    const index = command.params.findIndex((param) => param.name === name);
+    if (index < 0) throw new Error(`Command ${command.name} has no parameter named ${name}`);
+    return index;
+};
+
+const arrayInTsType = (scalar: GlScalar, group: string | undefined): string => {
+    const element = scalarAliasOrGroup(scalar, group);
+    return scalar.viewType === undefined ? `${element}[]` : `${element}[] | ${scalar.viewType}`;
+};
+
+export type InArg = {
+    out: false;
+    name: string;
+    tsType: string;
+    descriptor: string;
+};
+
+export type OutArg = {
+    out: true;
+    cellName: string;
+    seed: string;
+    tsType: string;
+    descriptor: string;
+    paramIndex: number;
+};
+
+type PlannedArg = InArg | OutArg;
+
+type BuildArgOptions = {
+    command: GlCommand;
+    index: number;
+    plan: ParamPlan;
+    outIndex: number;
+};
+
+const inArg = (name: string, tsType: string, descriptor: string): InArg => ({
+    out: false,
+    name,
+    tsType,
+    descriptor,
+});
+
+const buildInArg = (options: BuildArgOptions, name: string, track: (alias: string) => string): InArg => {
+    const { command, index, plan } = options;
+    const param = command.params[index];
+    if (param === undefined) throw new Error(`Parameter index ${index} out of range on ${command.name}`);
+    switch (plan.kind) {
+        case "scalar":
+            return inArg(name, track(scalarAliasOrGroup(plan.scalar, param.group)), plan.scalar.descriptor);
+        case "boolean":
+            return inArg(name, "boolean", tBoolean);
+        case "sync":
+            return inArg(name, track("GLsync"), tInlineStruct());
+        case "string-in":
+            return inArg(name, "string", tString("borrowed"));
+        case "string-array-in":
+            return inArg(name, "string[]", tArray(tString("borrowed")));
+        case "array-in": {
+            track(scalarAliasOrGroup(plan.scalar, param.group));
+            return inArg(name, arrayInTsType(plan.scalar, param.group), tArray(plan.scalar.descriptor));
+        }
+        case "buffer":
+            return inArg(name, `ArrayBufferView | ${track("GLintptr")} | null`, tBuffer);
+        case "byte-offset":
+            return inArg(name, track("GLintptr"), tUint64);
+        case "byte-offset-array":
+            return inArg(name, `${track("GLintptr")}[]`, tArray(tUint64));
+        default:
+            throw new Error(`Plan kind ${plan.kind} is not an input parameter`);
+    }
+};
+
+const buildOutArg = (options: BuildArgOptions, track: (alias: string) => string): OutArg => {
+    const { command, index, plan, outIndex } = options;
+    const param = command.params[index];
+    if (param === undefined) throw new Error(`Parameter index ${index} out of range on ${command.name}`);
+    const cellName = `out${outIndex}`;
+    switch (plan.kind) {
+        case "ref-out":
+            return {
+                out: true,
+                cellName,
+                seed: `const ${cellName} = { value: 0 };`,
+                tsType: track(scalarAliasOrGroup(plan.scalar, param.group)),
+                descriptor: tRef(plan.scalar.descriptor),
+                paramIndex: index,
+            };
+        case "ref-array-out": {
+            const sizeIndex = paramIndexByName(command, plan.lenParamName);
+            const lenIdentifier = toCamelIdentifier(plan.lenParamName);
+            return {
+                out: true,
+                cellName,
+                seed: `const ${cellName} = { value: new Array<number>(${lenIdentifier}).fill(0) };`,
+                tsType: `${track(plan.scalar.tsAlias)}[]`,
+                descriptor: tRef(tSizedArray(plan.scalar.descriptor, sizeIndex)),
+                paramIndex: index,
+            };
+        }
+        case "ref-fixed-out":
+            return {
+                out: true,
+                cellName,
+                seed: `const ${cellName} = { value: new Array<number>(${plan.length}).fill(0) };`,
+                tsType: `${track(plan.scalar.tsAlias)}[]`,
+                descriptor: tRef(tFixedArray(plan.scalar.descriptor, plan.length)),
+                paramIndex: index,
+            };
+        case "string-out":
+            return {
+                out: true,
+                cellName,
+                seed: `const ${cellName} = { value: "" };`,
+                tsType: "string",
+                descriptor: tRef(tString("borrowed", toCamelIdentifier(plan.lenParamName))),
+                paramIndex: index,
+            };
+        default:
+            throw new Error(`Plan kind ${plan.kind} is not an output parameter`);
+    }
+};
+
+const isOutPlan = (plan: ParamPlan): boolean =>
+    plan.kind === "ref-out" ||
+    plan.kind === "ref-array-out" ||
+    plan.kind === "ref-fixed-out" ||
+    plan.kind === "string-out";
+
+export const trackInto =
+    (usedTypes: Set<string>) =>
+    (alias: string): string => {
+        usedTypes.add(alias);
+        return alias;
+    };
+
+export const planArgs = (
+    plan: CommandPlan & { ok: true },
+    usedTypes: Set<string>,
+): { args: PlannedArg[]; ins: InArg[]; outs: OutArg[] } => {
+    const track = trackInto(usedTypes);
+    const args: PlannedArg[] = [];
+    const ins: InArg[] = [];
+    const outs: OutArg[] = [];
+    plan.params.forEach((paramPlan, index) => {
+        const param = plan.command.params[index];
+        if (param === undefined) throw new Error(`Parameter index ${index} out of range on ${plan.command.name}`);
+        const options: BuildArgOptions = {
+            command: plan.command,
+            index,
+            plan: paramPlan,
+            outIndex: outs.length,
+        };
+        if (isOutPlan(paramPlan)) {
+            const arg = buildOutArg(options, track);
+            args.push(arg);
+            outs.push(arg);
+        } else {
+            const arg = buildInArg(options, toCamelIdentifier(param.name), track);
+            args.push(arg);
+            ins.push(arg);
+        }
+    });
+    return { args, ins, outs };
+};
+
+export const scalarPrefixArgs = (plan: CommandPlan & { ok: true }, usedTypes: Set<string>): InArg[] | undefined => {
+    const track = trackInto(usedTypes);
+    const prefix: InArg[] = [];
+    for (let index = 0; index < plan.params.length - 2; index++) {
+        const paramPlan = plan.params[index];
+        const param = plan.command.params[index];
+        if (param === undefined) return undefined;
+        if (paramPlan === undefined || paramPlan.kind !== "scalar") return undefined;
+        prefix.push(
+            buildInArg(
+                { command: plan.command, index, plan: paramPlan, outIndex: 0 },
+                toCamelIdentifier(param.name),
+                track,
+            ),
+        );
+    }
+    return prefix;
+};

package/src/khronos/jsdoc.ts

@@ -0,0 +1,76 @@
+import { toCamelIdentifier } from "@gtkx/utils";
+import type { InArg, OutArg } from "./args.js";
+import type { GlCommand } from "./model.js";
+import type { ReturnPlan } from "./plan.js";
+
+const REFPAGES_BASE = "https://registry.khronos.org/OpenGL-Refpages/gl4/html";
+
+const formatPrototype = (command: GlCommand): string => {
+    const params = command.params
+        .map((param) => (param.cType.endsWith("*") ? `${param.cType}${param.name}` : `${param.cType} ${param.name}`))
+        .join(", ");
+    return `${command.returnCType} ${command.name}(${params})`;
+};
+
+export const inParamDocLine = (command: GlCommand, arg: InArg): string => {
+    const param = command.params.find((candidate) => toCamelIdentifier(candidate.name) === arg.name);
+    if (param === undefined) return ` * @param ${arg.name}`;
+    const notes: string[] = [`\`${param.cType}\``];
+    if (param.group !== undefined) notes.push(`group \`${param.group}\``);
+    if (param.len !== undefined) notes.push(`length \`${param.len}\``);
+    if (param.objectClass !== undefined) notes.push(`object class \`${param.objectClass}\``);
+    return ` * @param ${arg.name} - ${notes.join(", ")}`;
+};
+
+const returnsDocLine = (command: GlCommand, returnPlan: ReturnPlan, outs: OutArg[]): string | undefined => {
+    const members: string[] = [];
+    if (returnPlan.kind !== "void") members.push(`\`${command.returnCType}\``);
+    for (const out of outs) {
+        const param = command.params[out.paramIndex];
+        if (param === undefined)
+            throw new Error(`Output parameter index ${out.paramIndex} out of range on ${command.name}`);
+        members.push(`\`${param.name}\` (\`${param.cType}\`)`);
+    }
+    if (members.length === 0) return undefined;
+    if (members.length === 1) return ` * @returns ${members[0]}`;
+    return ` * @returns Tuple of ${members.join(", ")}`;
+};
+
+type CommandJsDocOptions = {
+    command: GlCommand;
+    feature: string;
+    ins: InArg[];
+    outs: OutArg[];
+    returnPlan: ReturnPlan;
+};
+
+type SingularJsDocOptions = {
+    commandName: string;
+    feature: string;
+    summary: string;
+    body: string[];
+};
+
+export const singularJsDoc = ({ commandName, feature, summary, body }: SingularJsDocOptions): string =>
+    [
+        "/**",
+        ` * ${summary}`,
+        " *",
+        ` * Provided by \`${feature}\`.`,
+        ...body,
+        ` * @see ${REFPAGES_BASE}/${commandName}.xhtml`,
+        " */",
+    ].join("\n");
+
+export const commandJsDoc = ({ command, feature, ins, outs, returnPlan }: CommandJsDocOptions): string => {
+    const returnsLine = returnsDocLine(command, returnPlan, outs);
+    return singularJsDoc({
+        commandName: command.name,
+        feature,
+        summary: `\`${formatPrototype(command)}\``,
+        body: [
+            ...(ins.length > 0 ? [" *", ...ins.map((arg) => inParamDocLine(command, arg))] : []),
+            ...(returnsLine !== undefined ? [returnsLine] : []),
+        ],
+    });
+};