@gtkx/codegen 0.21.0 → 1.0.0-rc.1

package/src/khronos/render.ts

@@ -0,0 +1,193 @@
+import { lowerFirst, sourceStringLiteral, toCamelIdentifier } from "@gtkx/utils";
+import { tBind, tInlineStruct, tRef, tString, tUint8, tVoid } from "../analysis/descriptor.js";
+import { type OutArg, planArgs, scalarAliasOrGroup, scalarPrefixArgs, trackInto } from "./args.js";
+import { commandJsDoc, inParamDocLine, singularJsDoc } from "./jsdoc.js";
+import type { CommandPlan, ReturnPlan } from "./plan.js";
+
+const GL_LIB_EXPRESSION = "LIB";
+
+const glBind = (name: string, argList: string, returnType: string): string =>
+    tBind({
+        libExpr: GL_LIB_EXPRESSION,
+        symbolExpr: sourceStringLiteral(name),
+        argList,
+        returnType,
+    });
+
+const commandExportName = (name: string): string =>
+    toCamelIdentifier(name.startsWith("gl") ? lowerFirst(name.slice(2)) : name);
+
+const singularize = (plural: string): string =>
+    plural.endsWith("ies") ? `${plural.slice(0, -3)}y` : plural.replace(/s$/, "");
+
+const renderDescriptorList = (descriptors: string[]): string =>
+    descriptors.length === 0 ? "[]" : `[${descriptors.join(", ")}]`;
+
+export type RenderedCommand = {
+    exportName: string;
+    binding?: string;
+    declaration: string;
+};
+
+type EmittedReturn = {
+    tsType: string;
+    descriptor: string;
+    expr?: (call: string) => string;
+};
+
+const buildEmittedReturn = (
+    plan: ReturnPlan,
+    returnGroup: string | undefined,
+    usedTypes: Set<string>,
+): EmittedReturn => {
+    const track = trackInto(usedTypes);
+    switch (plan.kind) {
+        case "void":
+            return { tsType: "void", descriptor: tVoid };
+        case "scalar": {
+            const alias = track(scalarAliasOrGroup(plan.scalar, returnGroup));
+            return { tsType: alias, descriptor: plan.scalar.descriptor, expr: (call) => `${call} as ${alias}` };
+        }
+        case "boolean":
+            return { tsType: "boolean", descriptor: tUint8, expr: (call) => `(${call} as number) !== 0` };
+        case "string":
+            return { tsType: "string", descriptor: tString("borrowed"), expr: (call) => `${call} as string` };
+        case "sync":
+            return { tsType: track("GLsync"), descriptor: tInlineStruct(), expr: (call) => `${call} as GLsync` };
+        case "opaque-pointer":
+            return {
+                tsType: track("GLpointer"),
+                descriptor: tInlineStruct(),
+                expr: (call) => `${call} as GLpointer`,
+            };
+    }
+};
+
+const returnTsType = (returned: EmittedReturn, outs: OutArg[]): string => {
+    if (outs.length === 0) return returned.tsType;
+    const outTypes = outs.map((out) => out.tsType);
+    if (returned.expr === undefined) {
+        return outTypes.length === 1 && outTypes[0] !== undefined ? outTypes[0] : `[${outTypes.join(", ")}]`;
+    }
+    return `[${returned.tsType}, ${outTypes.join(", ")}]`;
+};
+
+const returnStatements = (call: string, returned: EmittedReturn, outs: OutArg[]): string[] => {
+    if (outs.length === 0) {
+        return returned.expr === undefined ? [`${call};`] : [`return ${returned.expr(call)};`];
+    }
+    const outValues = outs.map((out) => `${out.cellName}.value`);
+    if (returned.expr === undefined) {
+        const tail = outValues.length === 1 ? `return ${outValues[0]};` : `return [${outValues.join(", ")}];`;
+        return [`${call};`, tail];
+    }
+    return [`const result = ${call};`, `return [${returned.expr("result")}, ${outValues.join(", ")}];`];
+};
+
+export const renderCommand = (
+    plan: CommandPlan & { ok: true },
+    feature: string,
+    usedTypes: Set<string>,
+): RenderedCommand => {
+    const { command } = plan;
+    const exportName = commandExportName(command.name);
+    const { args, ins, outs } = planArgs(plan, usedTypes);
+    const returned = buildEmittedReturn(plan.returnPlan, command.returnGroup, usedTypes);
+    const signature = ins.map((arg) => `${arg.name}: ${arg.tsType}`).join(", ");
+    const argNames = args.map((arg) => (arg.out ? arg.cellName : arg.name)).join(", ");
+    const descriptors = renderDescriptorList(args.map((arg) => arg.descriptor));
+    const tsReturn = returnTsType(returned, outs);
+    const jsDoc = commandJsDoc({ command, feature, ins, outs, returnPlan: plan.returnPlan });
+    const seeds = outs.map((out) => out.seed);
+    const bindExpression = glBind(command.name, descriptors, returned.descriptor);
+    const inline = plan.params.some((paramPlan) => paramPlan.kind === "string-out");
+    const bindingName = inline ? "binding" : toCamelIdentifier(command.name);
+    const body = [
+        ...seeds,
+        ...(inline ? [`const ${bindingName} = ${bindExpression};`] : []),
+        ...returnStatements(`${bindingName}(${argNames})`, returned, outs),
+    ]
+        .map((line) => `    ${line}`)
+        .join("\n");
+    return {
+        exportName,
+        ...(inline ? {} : { binding: `const ${bindingName} = ${bindExpression};` }),
+        declaration: `${jsDoc}\nexport function ${exportName}(${signature}): ${tsReturn} {\n${body}\n}`,
+    };
+};
+
+const GEN_FAMILY = /^gl(Gen|Create)[A-Z][A-Za-z]*s$/;
+const DELETE_FAMILY = /^glDelete[A-Z][A-Za-z]*s$/;
+
+export const deriveGenSingular = (
+    plan: CommandPlan & { ok: true },
+    feature: string,
+    usedTypes: Set<string>,
+): RenderedCommand | undefined => {
+    if (!GEN_FAMILY.test(plan.command.name)) return undefined;
+    const countIndex = plan.params.length - 2;
+    const outIndex = plan.params.length - 1;
+    const countPlan = plan.params[countIndex];
+    const outPlan = plan.params[outIndex];
+    const countParam = plan.command.params[countIndex];
+    const outParam = plan.command.params[outIndex];
+    if (countPlan?.kind !== "scalar" || outPlan?.kind !== "ref-array-out") return undefined;
+    if (countParam === undefined || outParam === undefined) return undefined;
+    if (outPlan.lenParamName !== countParam.name || outParam.objectClass === undefined) return undefined;
+    const prefix = scalarPrefixArgs(plan, usedTypes);
+    if (prefix === undefined) return undefined;
+    const exportName = singularize(commandExportName(plan.command.name));
+    const bindingName = `${plan.command.name}Single`;
+    const descriptors = [
+        ...prefix.map((arg) => arg.descriptor),
+        countPlan.scalar.descriptor,
+        tRef(outPlan.scalar.descriptor),
+    ];
+    usedTypes.add(outPlan.scalar.tsAlias);
+    const signature = prefix.map((arg) => `${arg.name}: ${arg.tsType}`).join(", ");
+    const callArgs = [...prefix.map((arg) => arg.name), "1", "out"].join(", ");
+    const jsDoc = singularJsDoc({
+        commandName: plan.command.name,
+        feature,
+        summary: `Returns one ${outParam.objectClass} object name via \`${plan.command.name}(${prefix.length > 0 ? "..., " : ""}1, ...)\`.`,
+        body: [
+            ...prefix.map((arg) => inParamDocLine(plan.command, arg)),
+            ` * @returns The new ${outParam.objectClass} object name`,
+        ],
+    });
+    const body = [`    const out = { value: 0 };`, `    ${bindingName}(${callArgs});`, "    return out.value;"].join(
+        "\n",
+    );
+    const binding = glBind(plan.command.name, renderDescriptorList(descriptors), tVoid);
+    return {
+        exportName,
+        binding: `const ${bindingName} = ${binding};`,
+        declaration: `${jsDoc}\nexport function ${exportName}(${signature}): ${outPlan.scalar.tsAlias} {\n${body}\n}`,
+    };
+};
+
+export const deriveDeleteSingular = (
+    plan: CommandPlan & { ok: true },
+    feature: string,
+    usedTypes: Set<string>,
+): RenderedCommand | undefined => {
+    if (!DELETE_FAMILY.test(plan.command.name)) return undefined;
+    if (plan.params.length !== 2) return undefined;
+    const [countPlan, arrayPlan] = plan.params;
+    const [countParam, arrayParam] = plan.command.params;
+    if (countPlan?.kind !== "scalar" || arrayPlan?.kind !== "array-in") return undefined;
+    if (countParam === undefined || arrayParam === undefined) return undefined;
+    if (arrayParam.len !== countParam.name || arrayParam.objectClass === undefined) return undefined;
+    const exportName = singularize(commandExportName(plan.command.name));
+    usedTypes.add(arrayPlan.scalar.tsAlias);
+    const jsDoc = singularJsDoc({
+        commandName: plan.command.name,
+        feature,
+        summary: `Deletes one ${arrayParam.objectClass} object name via \`${plan.command.name}(1, ...)\`.`,
+        body: [` * @param name - The ${arrayParam.objectClass} object name to delete`],
+    });
+    return {
+        exportName,
+        declaration: `${jsDoc}\nexport function ${exportName}(name: ${arrayPlan.scalar.tsAlias}): void {\n    ${plan.command.name}(1, [name]);\n}`,
+    };
+};

package/src/khronos/select.ts

@@ -0,0 +1,67 @@
+import type { GlEnum, GlFeature, GlInterfaceBlock, GlRegistry } from "./model.js";
+
+type GlProfile = "core";
+
+export type GlSelection = {
+    api: string;
+    version: number;
+    profile: GlProfile;
+};
+
+type GlSubset = {
+    commands: Map<string, string>;
+    enums: Map<string, string>;
+};
+
+const blockApplies = (block: GlInterfaceBlock, selection: GlSelection): boolean =>
+    block.profile === undefined || block.profile === selection.profile;
+
+const applyRequires = (
+    feature: GlFeature,
+    selection: GlSelection,
+    commands: Map<string, string>,
+    enums: Map<string, string>,
+): void => {
+    for (const block of feature.requires) {
+        if (!blockApplies(block, selection)) continue;
+        for (const name of block.commands) {
+            if (!commands.has(name)) commands.set(name, feature.name);
+        }
+        for (const name of block.enums) {
+            if (!enums.has(name)) enums.set(name, feature.name);
+        }
+    }
+};
+
+const applyRemoves = (
+    feature: GlFeature,
+    selection: GlSelection,
+    commands: Map<string, string>,
+    enums: Map<string, string>,
+): void => {
+    for (const block of feature.removes) {
+        if (!blockApplies(block, selection)) continue;
+        for (const name of block.commands) commands.delete(name);
+        for (const name of block.enums) enums.delete(name);
+    }
+};
+
+export const selectSubset = (registry: GlRegistry, selection: GlSelection): GlSubset => {
+    const features = registry.features
+        .filter((feature) => feature.api === selection.api && feature.number <= selection.version)
+        .sort((a, b) => a.number - b.number);
+
+    const commands = new Map<string, string>();
+    const enums = new Map<string, string>();
+    for (const feature of features) applyRequires(feature, selection, commands, enums);
+    for (const feature of features) applyRemoves(feature, selection, commands, enums);
+    return { commands, enums };
+};
+
+export const resolveEnum = (registry: GlRegistry, name: string): GlEnum => {
+    const found = registry.enums.find((candidate) => candidate.name === name);
+    if (found === undefined) {
+        throw new Error(`Enum token ${name} has no definition in the registry`);
+    }
+    return found;
+};

package/src/runner.ts

@@ -1,89 +1,126 @@
-import { generateNamespaceModule } from "./ffi/pipeline.js";
-import { computeFingerprint } from "./fingerprint.js";
-import { type GiNamespaceInput, type GiStoreOptions, writeGiStore } from "./gi-store.js";
-import { loadGirRepository } from "./gir/repository.js";
-import { type JsxStoreOptions, writeJsxStore } from "./jsx-store.js";
-import { generateReactFiles } from "./react/pipeline.js";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ElementProp } from "@gtkx/config";
+import { checkModules } from "./compile.js";
+import { computeFingerprint, isStoreFresh } from "./fingerprint.js";
+import { Library } from "./gir/library.js";
+import { namespaceDirectory } from "./gir/namespace.js";
+import { type GlGenerationReport, generateGlModules } from "./khronos/pipeline.js";
+import { generateNamespaceModule } from "./store/gi/pipeline.js";
+import { type GiNamespaceInput, type GiStoreOptions, writeGiStore } from "./store/gi-store.js";
+import { type JsxStoreOptions, writeJsxStore } from "./store/jsx-store.js";
+import { generateJsxFiles } from "./store/react/pipeline.js";
+
+export type GlCodegenOptions = {
+    registryPath: string;
+    overrideExports: Set<string>;
+    outputDir: string;
+    resolveFrom: string;
+};
 
-/**
- * Options for {@link CodegenRunner}.
- */
 export type CodegenRunnerOptions = {
-    /** Resolved `Name-Version` namespace identifiers to generate. */
-    readonly libraries: readonly string[];
-    /** Directories searched for `.gir` files. */
-    readonly girPath: readonly string[];
-    /** Optional user slot-prop overrides keyed by JSX element name. */
-    readonly slotProps?: Readonly<Record<string, readonly string[]>>;
-    /** Target for the injected `@gtkx/gi` bindings package. */
-    readonly gi: GiStoreOptions;
-    /** Target for the injected `@gtkx/react-jsx` unit; React is skipped when omitted. */
-    readonly jsx?: JsxStoreOptions;
+    libraries?: string[];
+    girPath?: string[];
+    elementProps?: Record<string, ElementProp[]> | undefined;
+    gi?: GiStoreOptions;
+    jsx?: JsxStoreOptions | undefined;
+    gl?: GlCodegenOptions;
+    force?: boolean;
 };
 
-/**
- * Result returned from {@link CodegenRunner.run}.
- */
 export type CodegenRunnerResult = {
-    /** Number of FFI namespaces produced. */
-    readonly namespaces: number;
-    /** Number of widget intrinsics emitted into `jsx.ts`. */
-    readonly widgets: number;
-    /** Wall-clock duration in milliseconds. */
-    readonly duration: number;
+    regenerated: boolean;
+    namespaces: number;
+    intrinsicElements: number;
+    duration: number;
+    gl?: GlGenerationReport | undefined;
+};
+
+type GiEmitResult = {
+    namespaces: number;
+    intrinsicElements: number;
 };
 
 /**
- * Single-entry orchestrator for the GTKX codegen.
- *
- * Loads the GIR repository, runs the FFI pipeline per namespace, runs the
- * React pipeline once, and materializes the self-contained `@gtkx/gi` (and
- * optional `@gtkx/react-jsx`) packages into the project's `node_modules`.
- *
- * @example
- * ```ts
- * import { CodegenRunner } from "@gtkx/codegen";
+ * Runs the `@gtkx` code generators, producing the `@gtkx/gi`, `@gtkx/jsx`, and `@gtkx/gl` bindings from the
+ * configured GObject-introspection libraries and OpenGL registry. The gi store is regenerated only when its
+ * fingerprint is stale unless `options.force` is set, while the OpenGL modules are regenerated whenever
+ * `options.gl` is provided.
  *
- * await new CodegenRunner({
- *     libraries: ["Gtk-4.0", "Adw-1"],
- *     girPath: ["/usr/share/gir-1.0"],
- *     gi: { storeDir, linkDir, realFfiDir, realNativeDir, version },
- * }).run();
- * ```
+ * @param options - What to generate and where to write it.
+ * @returns A summary of what was regenerated and how long the run took.
  */
-export class CodegenRunner {
-    constructor(private readonly options: CodegenRunnerOptions) {}
-
-    /**
-     * Executes the full codegen pipeline and materializes the output packages.
-     */
-    async run(): Promise<CodegenRunnerResult> {
-        const start = Date.now();
-        const repository = loadGirRepository(this.options.libraries, this.options.girPath);
+export const runCodegen = async (options: CodegenRunnerOptions): Promise<CodegenRunnerResult> => {
+    const start = Date.now();
+    const gl = options.gl === undefined ? undefined : emitGlModules(options.gl);
+    const gi = emitGiStoreIfStale(options);
+    return {
+        regenerated: gi !== undefined,
+        namespaces: gi?.namespaces ?? 0,
+        intrinsicElements: gi?.intrinsicElements ?? 0,
+        duration: Date.now() - start,
+        gl,
+    };
+};
 
-        const namespaces: GiNamespaceInput[] = [];
-        for (const namespace of repository.namespaces.values()) {
-            const { source } = generateNamespaceModule(namespace, repository);
-            namespaces.push({ directory: namespace.name.toLowerCase(), rawSource: source });
-        }
-        const libraries = [...this.options.libraries];
-        writeGiStore(this.options.gi, namespaces, {
-            value: computeFingerprint(repository.girFiles, libraries),
-            girFiles: repository.girFiles,
-            libraries,
-        });
+const emitGlModules = (options: GlCodegenOptions): GlGenerationReport => {
+    const { files, report } = generateGlModules({
+        registryPath: options.registryPath,
+        overrideExports: options.overrideExports,
+    });
+    checkModules({
+        modules: [...files].map(([fileName, source]) => ({ fileName, source })),
+        resolveFrom: options.resolveFrom,
+        label: "the generated gl modules",
+    });
+    mkdirSync(options.outputDir, { recursive: true });
+    for (const [fileName, source] of files) {
+        writeFileSync(join(options.outputDir, fileName), source);
+    }
+    return report;
+};
 
-        let widgetCount = 0;
-        if (this.options.jsx !== undefined) {
-            const reactPipeline = generateReactFiles(repository, this.options.slotProps);
-            writeJsxStore(this.options.jsx, reactPipeline.files);
-            widgetCount = reactPipeline.widgetCount;
-        }
+const emitGiStoreIfStale = (options: CodegenRunnerOptions): GiEmitResult | undefined => {
+    const { gi, libraries, girPath } = options;
+    if (gi === undefined || libraries === undefined || girPath === undefined) return undefined;
+    const elementProps = options.elementProps ?? {};
+    if (options.force !== true && isStoreFresh(gi.storeDir, libraries, elementProps)) return undefined;
+    const library = Library.load(libraries, girPath);
+    emitGiStore(gi, libraries, elementProps, library);
+    return {
+        namespaces: library.namespaces.size,
+        intrinsicElements: emitJsxStore(options.jsx, elementProps, library),
+    };
+};
 
-        return {
-            namespaces: repository.namespaces.size,
-            widgets: widgetCount,
-            duration: Date.now() - start,
-        };
+const emitGiStore = (
+    gi: GiStoreOptions,
+    libraries: string[],
+    elementProps: Record<string, ElementProp[]>,
+    library: Library,
+): void => {
+    const namespaces: GiNamespaceInput[] = [];
+    for (const namespace of library.namespaces.values()) {
+        namespaces.push({
+            directory: namespaceDirectory(namespace),
+            rawSource: generateNamespaceModule(namespace, library),
+        });
     }
-}
+    const libs = [...libraries];
+    writeGiStore(gi, namespaces, {
+        value: computeFingerprint(library.girFiles, libs, elementProps),
+        girFiles: library.girFiles,
+        libraries: libs,
+    });
+};
+
+const emitJsxStore = (
+    jsx: JsxStoreOptions | undefined,
+    elementProps: Record<string, ElementProp[]>,
+    library: Library,
+): number => {
+    if (jsx === undefined) return 0;
+    const reactPipeline = generateJsxFiles(library, elementProps);
+    writeJsxStore(jsx, reactPipeline.namespaces, reactPipeline.metadata);
+    return reactPipeline.intrinsicElementCount;
+};

package/src/store/compile-store.ts

@@ -0,0 +1,49 @@
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { compileProject, type SourceModule } from "../compile.js";
+
+export type CompileStoreParams = {
+    storeDir: string;
+    files: SourceModule[];
+    packageName: string;
+    exports: Record<string, unknown>;
+};
+
+const EMIT_OPTIONS = {
+    declaration: true,
+    removeComments: false,
+    sourceMap: false,
+    declarationMap: false,
+    noEmitOnError: true,
+    rootDir: ".",
+    outDir: ".",
+};
+
+const selfPaths = (
+    packageName: string,
+    exportsMap: Record<string, unknown>,
+    storeDir: string,
+): Record<string, string[]> => {
+    const paths: Record<string, string[]> = {};
+    for (const [key, value] of Object.entries(exportsMap)) {
+        if (key === "./package.json" || typeof value !== "object" || value === null) continue;
+        const target = (value as { default?: unknown }).default;
+        if (typeof target !== "string") continue;
+        const stem = target.replace(/^\.\//, "").replace(/\.js$/, "");
+        paths[`${packageName}${key.slice(1)}`] = [join(storeDir, stem)];
+    }
+    return paths;
+};
+
+export const compileStore = (params: CompileStoreParams): void => {
+    compileProject({
+        projectDir: params.storeDir,
+        fileNames: params.files.map((file) => file.fileName),
+        compilerOptions: EMIT_OPTIONS,
+        paths: selfPaths(params.packageName, params.exports, params.storeDir),
+        label: `the generated ${params.packageName} store`,
+    });
+    for (const file of params.files) {
+        rmSync(join(params.storeDir, file.fileName), { force: true });
+    }
+};

package/src/store/gi/async.ts

@@ -0,0 +1,42 @@
+import { inputParameters } from "../../analysis/param-structure.js";
+import type { GirFunction } from "../../gir/function.js";
+import type { Library } from "../../gir/library.js";
+
+export const matchAsyncFinish = (
+    library: Library,
+    fn: GirFunction,
+    siblings: GirFunction[],
+): GirFunction | undefined => {
+    if (!hasCanonicalAsyncCallback(library, fn)) return undefined;
+    const finishName = matchAsyncFinishName(fn, siblings);
+    if (finishName === undefined) return undefined;
+    const finishFn = siblings.find((sibling) => sibling.name === finishName);
+    if (finishFn === undefined || !isPromisifiableFinish(library, finishFn)) return undefined;
+    return finishFn;
+};
+
+const matchAsyncFinishName = (fn: GirFunction, siblings: GirFunction[]): string | undefined => {
+    if (fn.name.endsWith("_finish")) return undefined;
+    const root = fn.name.endsWith("_async") ? fn.name.slice(0, -"_async".length) : fn.name;
+    const finishName = `${root}_finish`;
+    return siblings.some((sibling) => sibling.name === finishName) ? finishName : undefined;
+};
+
+const hasCanonicalAsyncCallback = (library: Library, fn: GirFunction): boolean => {
+    let asyncReadyCallbacks = 0;
+    let otherCallbacks = 0;
+    for (const parameter of fn.parameters) {
+        const ref = parameter.type;
+        if (ref === undefined || library.typeOf(ref)?.kind !== "callback") continue;
+        if (library.nameOf(ref)?.typeName === "AsyncReadyCallback") asyncReadyCallbacks += 1;
+        else otherCallbacks += 1;
+    }
+    return asyncReadyCallbacks === 1 && otherCallbacks === 0;
+};
+
+const isPromisifiableFinish = (library: Library, finishFn: GirFunction): boolean => {
+    const inputs = inputParameters(library, finishFn);
+    if (inputs.length !== 1) return false;
+    const only = inputs[0];
+    return only?.parameter.type !== undefined && library.nameOf(only.parameter.type)?.typeName === "AsyncResult";
+};