@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/jsx.ts

@@ -0,0 +1,70 @@
+import type { Library } from "./gir/library.js";
+import {
+    computeJsxFingerprint,
+    FINGERPRINT_FILENAME,
+    type JsxFingerprintInput,
+    jsxStoreFreshness,
+} from "./fingerprint.js";
+import { type ModuleExport, readBuiltinElements } from "./react/element-config.js";
+import { type JsxStoreOptions, writeJsxStore } from "./store/jsx-store.js";
+import { generateJsxFiles } from "./store/jsx/pipeline.js";
+
+type RunJsxCodegenOptions = {
+    getLibrary: () => Library;
+    jsx: JsxStoreOptions;
+    giStoreDir: string;
+    reactSubexports: string[];
+    userComponents: Record<string, ModuleExport>;
+    userLazyElements: string[];
+    userProps: Record<string, ModuleExport>;
+    giRegenerated: boolean;
+    force: boolean;
+};
+
+type RunJsxCodegenResult = {
+    regenerated: boolean;
+    intrinsicElementCount: number;
+};
+
+/**
+ * Generates the `@gtkx/jsx` store, reading the framework's built-in element config from the freshly
+ * linked `@gtkx/react` and layering the project's own element config over it. This is the react-importing
+ * half of codegen: it must run only after the gi store has been written and linked.
+ */
+const runJsxCodegen = async (options: RunJsxCodegenOptions): Promise<RunJsxCodegenResult> => {
+    const builtin = await readBuiltinElements(options.reactSubexports, options.giStoreDir);
+    const components = { ...builtin.components, ...options.userComponents };
+    const lazyElements = [...builtin.lazyElements, ...options.userLazyElements];
+    const props = { ...builtin.props, ...options.userProps };
+
+    const fingerprintInput: JsxFingerprintInput = {
+        reactVersion: options.jsx.version,
+        components,
+        lazyElements,
+        props,
+    };
+
+    if (!options.force && !options.giRegenerated) {
+        const { fresh, intrinsicElementCount } = jsxStoreFreshness(options.jsx.storeDir, fingerprintInput);
+
+        if (fresh) {
+            return { regenerated: false, intrinsicElementCount };
+        }
+    }
+
+    const { namespaces, metadata, intrinsicElementCount } = generateJsxFiles(options.getLibrary(), {
+        reactSubexports: options.reactSubexports,
+        components,
+        lazyElements,
+        props,
+    });
+
+    writeJsxStore(options.jsx, namespaces, metadata, {
+        relativePath: FINGERPRINT_FILENAME,
+        content: `${JSON.stringify(computeJsxFingerprint(fingerprintInput, intrinsicElementCount), null, 2)}\n`,
+    });
+
+    return { regenerated: true, intrinsicElementCount };
+};
+
+export { runJsxCodegen, type RunJsxCodegenOptions, type RunJsxCodegenResult };

package/src/khronos/args.ts

@@ -0,0 +1,271 @@
+import { toCamelIdentifier } from "@gtkx/utils";
+import type { GlCommand, GlParam } from "./model.js";
+import type { CommandPlan, GlScalar, ParamPlan } from "./plan.js";
+import {
+    tArray,
+    tBoolean,
+    tBuffer,
+    tFixedArray,
+    tInlineStruct,
+    tRef,
+    tSizedArray,
+    tString,
+    tUint64,
+} from "../analysis/descriptor.js";
+import { paramPairAt } from "./param-pair.js";
+
+type InArg = {
+    out: false;
+    name: string;
+    tsType: string;
+    descriptor: string;
+};
+
+type OutArg = {
+    out: true;
+    cellName: string;
+    seed: string;
+    tsType: string;
+    descriptor: string;
+    paramIndex: number;
+};
+
+type PlannedArg = InArg | OutArg;
+type OutArgCell = Pick<OutArg, "out" | "cellName" | "paramIndex">;
+type OutArgFields = Pick<OutArg, "seed" | "tsType" | "descriptor">;
+
+type OutArgFieldsOptions = {
+    command: GlCommand;
+    plan: ParamPlan;
+    param: GlParam;
+    cellName: string;
+    track: (alias: string) => string;
+};
+
+type BuildArgOptions = {
+    command: GlCommand;
+    index: number;
+    plan: ParamPlan;
+    outIndex: number;
+};
+
+const OUT_PLAN_KINDS: Set<string> = new Set(["ref-out", "ref-array-out", "ref-fixed-out", "string-out"]);
+
+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 === -1) {
+        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}`;
+};
+
+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 ${String(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));
+        }
+        case "ref-array-out":
+        case "ref-fixed-out":
+        case "ref-out":
+        case "string-out": {
+            throw new Error(`Plan kind ${plan.kind} is not an input parameter`);
+        }
+    }
+};
+
+const outArgFields = (options: OutArgFieldsOptions): OutArgFields => {
+    const { command, plan, param, cellName, track } = options;
+
+    switch (plan.kind) {
+        case "ref-out": {
+            return {
+                seed: `const ${cellName} = { value: 0 };`,
+                tsType: track(scalarAliasOrGroup(plan.scalar, param.group)),
+                descriptor: tRef(plan.scalar.descriptor),
+            };
+        }
+        case "ref-array-out": {
+            const sizeIndex = paramIndexByName(command, plan.lenParamName);
+            const lenIdentifier = toCamelIdentifier(plan.lenParamName);
+
+            return {
+                seed: `const ${cellName} = { value: new Array<number>(${lenIdentifier}).fill(0) };`,
+                tsType: `${track(plan.scalar.tsAlias)}[]`,
+                descriptor: tRef(tSizedArray(plan.scalar.descriptor, sizeIndex)),
+            };
+        }
+        case "ref-fixed-out": {
+            return {
+                seed: `const ${cellName} = { value: new Array<number>(${String(plan.length)}).fill(0) };`,
+                tsType: `${track(plan.scalar.tsAlias)}[]`,
+                descriptor: tRef(tFixedArray(plan.scalar.descriptor, plan.length)),
+            };
+        }
+        case "string-out": {
+            return {
+                seed: `const ${cellName} = { value: "" };`,
+                tsType: "string",
+                descriptor: tRef(tString("borrowed", toCamelIdentifier(plan.lenParamName))),
+            };
+        }
+        case "array-in":
+        case "boolean":
+        case "buffer":
+        case "byte-offset":
+        case "byte-offset-array":
+        case "scalar":
+        case "string-array-in":
+        case "string-in":
+        case "sync": {
+            throw new Error(`Plan kind ${plan.kind} is not an output 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 ${String(index)} out of range on ${command.name}`);
+    }
+
+    const cellName = `out${String(outIndex)}`;
+    const cell: OutArgCell = { out: 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 buildArg = (options: BuildArgOptions, name: string, track: (alias: string) => string): PlannedArg =>
+    isOutPlan(options.plan) ? buildOutArg(options, track) : buildInArg(options, name, track);
+
+const trackInto =
+    (usedTypes: Set<string>) =>
+        (alias: string): string => {
+            usedTypes.add(alias);
+
+            return alias;
+        };
+
+const planArgs = (
+    plan: CommandPlan & { ok: true },
+    usedTypes: Set<string>,
+): { args: PlannedArg[]; ins: InArg[]; outs: OutArg[] } => {
+    const track = trackInto(usedTypes);
+    const args: PlannedArg[] = [];
+
+    for (const [index, paramPlan] of plan.params.entries()) {
+        const param = plan.command.params[index];
+
+        if (param === undefined) {
+            throw new Error(`Parameter index ${String(index)} out of range on ${plan.command.name}`);
+        }
+
+        const options: BuildArgOptions = {
+            command: plan.command,
+            index,
+            plan: paramPlan,
+            outIndex: args.filter(isOutArg).length,
+        };
+
+        args.push(buildArg(options, toCamelIdentifier(param.name), track));
+    }
+
+    return { args, ins: args.filter(isInArg), outs: args.filter(isOutArg) };
+};
+
+const scalarPrefixArg = (
+    plan: CommandPlan & { ok: true },
+    index: number,
+    track: (alias: string) => string,
+): InArg | undefined => {
+    const { paramPlan, param } = paramPairAt(plan, index);
+
+    if (param === undefined) {
+        return undefined;
+    }
+
+    if (paramPlan?.kind !== "scalar") {
+        return undefined;
+    }
+
+    return buildInArg(
+        { command: plan.command, index, plan: paramPlan, outIndex: 0 },
+        toCamelIdentifier(param.name),
+        track,
+    );
+};
+
+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 arg = scalarPrefixArg(plan, index, track);
+
+        if (arg === undefined) {
+            return undefined;
+        }
+
+        prefix.push(arg);
+    }
+
+    return prefix;
+};
+
+export { scalarAliasOrGroup, trackInto, planArgs, scalarPrefixArgs, type InArg, type OutArg };

package/src/khronos/jsdoc.ts

@@ -0,0 +1,114 @@
+import { toCamelIdentifier } from "@gtkx/utils";
+import type { InArg, OutArg } from "./args.js";
+import type { GlCommand } from "./model.js";
+import type { ReturnPlan } from "./plan.js";
+
+type CommandJsDocOptions = {
+    command: GlCommand;
+    feature: string;
+    ins: InArg[];
+    outs: OutArg[];
+    returnPlan: ReturnPlan;
+};
+
+type SingularJsDocOptions = {
+    commandName: string;
+    feature: string;
+    summary: string;
+    body: string[];
+};
+
+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})`;
+};
+
+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 outMember = (command: GlCommand, out: OutArg): string => {
+    const param = command.params[out.paramIndex];
+
+    if (param === undefined) {
+        throw new Error(`Output parameter index ${String(out.paramIndex)} out of range on ${command.name}`);
+    }
+
+    return `\`${param.name}\` (\`${param.cType}\`)`;
+};
+
+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) {
+        members.push(outMember(command, out));
+    }
+
+    if (members.length === 0) {
+        return undefined;
+    }
+
+    const [single] = members;
+
+    if (single !== undefined && members.length === 1) {
+        return ` * @returns ${single}`;
+    }
+
+    return ` * @returns Tuple of ${members.join(", ")}`;
+};
+
+const singularJsDoc = ({ commandName, feature, summary, body }: SingularJsDocOptions): string =>
+    [
+        "/**",
+        ` * ${summary}`,
+        " *",
+        ` * Provided by \`${feature}\`.`,
+        ...body,
+        ` * @see ${REFPAGES_BASE}/${commandName}.xhtml`,
+        " */",
+    ].join("\n");
+
+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]),
+        ],
+    });
+};
+
+export { inParamDocLine, singularJsDoc, commandJsDoc };