@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/runner.ts

@@ -1,89 +1,162 @@
-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 { GiStoreOptions } from "./store/gi-store.js";
+import type { JsxStoreOptions } from "./store/jsx-store.js";
+import { checkModules } from "./compile.js";
+import { isGiStoreFresh } from "./fingerprint.js";
+import { runGiCodegen } from "./gi.js";
+import { Library } from "./gir/library.js";
+import { generateGlModules, type GlGenerationReport } from "./khronos/pipeline.js";
 
-/**
- * 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;
+type ModuleExport = { module: string; export: string };
+
+type GlCodegenOptions = {
+    registryPath: string;
+    overrideExports: Set<string>;
+    outputDir: string;
+    resolveFrom: string;
 };
 
-/**
- * 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;
+type CodegenRunnerOptions = {
+    libraries?: string[];
+    girPath?: string[];
+    gi?: GiStoreOptions;
+    jsx?: JsxStoreOptions | undefined;
+    reactSubexports?: string[];
+    userComponents?: Record<string, ModuleExport>;
+    userLazyElements?: string[];
+    userProps?: Record<string, ModuleExport>;
+    gl?: GlCodegenOptions;
+    force?: boolean;
+};
+
+type CodegenRunnerResult = {
+    regenerated: boolean;
+    namespaces: number;
+    intrinsicElements: number;
+    duration: number;
+    gl?: GlGenerationReport | undefined;
+};
+
+type StoreResult = {
+    regenerated: boolean;
+    namespaces: number;
+    intrinsicElements: number;
 };
 
 /**
- * Single-entry orchestrator for the 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, then the jsx store is regenerated when the gi store or
+ * the React element config changed; the OpenGL modules are regenerated whenever `options.gl` is provided.
  *
- * 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";
- *
- * 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);
-
-        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,
-        });
-
-        let widgetCount = 0;
-        if (this.options.jsx !== undefined) {
-            const reactPipeline = generateReactFiles(repository, this.options.slotProps);
-            writeJsxStore(this.options.jsx, reactPipeline.files);
-            widgetCount = reactPipeline.widgetCount;
-        }
-
-        return {
-            namespaces: repository.namespaces.size,
-            widgets: widgetCount,
-            duration: Date.now() - start,
-        };
+const runCodegen = async (options: CodegenRunnerOptions): Promise<CodegenRunnerResult> => {
+    const start = Date.now();
+    const gl = options.gl === undefined ? undefined : emitGlModules(options.gl);
+    const store = await emitStores(options);
+
+    return {
+        regenerated: store.regenerated,
+        namespaces: store.namespaces,
+        intrinsicElements: store.intrinsicElements,
+        duration: Date.now() - start,
+        gl,
+    };
+};
+
+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;
+};
+
+const jsxUserOptions = (
+    options: CodegenRunnerOptions,
+): {
+    reactSubexports: string[];
+    userComponents: Record<string, ModuleExport>;
+    userLazyElements: string[];
+    userProps: Record<string, ModuleExport>;
+} => ({
+    reactSubexports: options.reactSubexports ?? [],
+    userComponents: options.userComponents ?? {},
+    userLazyElements: options.userLazyElements ?? [],
+    userProps: options.userProps ?? {},
+});
+
+const emitJsxStore = async (input: {
+    options: CodegenRunnerOptions;
+    jsx: JsxStoreOptions;
+    gi: GiStoreOptions;
+    loadLibrary: () => Library;
+    giRegenerated: boolean;
+    namespaces: number;
+}): Promise<StoreResult> => {
+    const { options, jsx, gi, loadLibrary, giRegenerated, namespaces } = input;
+    const { runJsxCodegen } = await import("./jsx.js");
+
+    const jsxResult = await runJsxCodegen({
+        getLibrary: loadLibrary,
+        jsx,
+        giStoreDir: gi.storeDir,
+        ...jsxUserOptions(options),
+        giRegenerated,
+        force: options.force === true,
+    });
+
+    return {
+        regenerated: giRegenerated || jsxResult.regenerated,
+        namespaces,
+        intrinsicElements: jsxResult.intrinsicElementCount,
+    };
+};
+
+const emitStoresWithConfig = async (config: {
+    options: CodegenRunnerOptions;
+    gi: GiStoreOptions;
+    jsx: JsxStoreOptions | undefined;
+    libraries: string[];
+    girPath: string[];
+}): Promise<StoreResult> => {
+    const { options, gi, jsx, libraries, girPath } = config;
+    let library: Library | undefined;
+    const loadLibrary = (): Library => (library ??= Library.load(libraries, girPath));
+    const isGiRegenerated = options.force === true || !isGiStoreFresh(gi.storeDir, libraries, girPath);
+    const namespaces = isGiRegenerated ? runGiCodegen(loadLibrary(), gi, libraries, girPath) : 0;
+
+    if (jsx === undefined) {
+        return { regenerated: isGiRegenerated, namespaces, intrinsicElements: 0 };
+    }
+
+    return emitJsxStore({ options, jsx, gi, loadLibrary, giRegenerated: isGiRegenerated, namespaces });
+};
+
+const emitStores = async (options: CodegenRunnerOptions): Promise<StoreResult> => {
+    const { gi, jsx, libraries, girPath } = options;
+
+    if (gi === undefined || libraries === undefined || girPath === undefined) {
+        return { regenerated: false, namespaces: 0, intrinsicElements: 0 };
+    }
+
+    return emitStoresWithConfig({ options, gi, jsx, libraries, girPath });
+};
+
+export { runCodegen, type GlCodegenOptions, type CodegenRunnerOptions, type CodegenRunnerResult };

package/src/store/compile-store.ts

@@ -0,0 +1,55 @@
+import { rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { compileProject, type SourceModule } from "../compile.js";
+
+type CompileStoreParams = {
+    storeDir: string;
+    files: SourceModule[];
+    packageName: string;
+    /** Declare `virtual:gtkx-config` for the typecheck, needed when it follows imports into `@gtkx/react` source. */
+    configEnv?: boolean;
+};
+
+const EMIT_OPTIONS = {
+    declaration: true,
+    removeComments: false,
+    sourceMap: false,
+    declarationMap: false,
+    rootDir: ".",
+    outDir: ".",
+};
+
+const ENV_REFERENCE_FILE = "__gtkx-env__.d.ts";
+
+const writeEnvReference = (storeDir: string): (() => void) => {
+    writeFileSync(join(storeDir, ENV_REFERENCE_FILE), "/// <reference types=\"@gtkx/react/env\" />\n");
+
+    return () => {
+        rmSync(join(storeDir, ENV_REFERENCE_FILE), { force: true });
+    };
+};
+
+const compileStore = (params: CompileStoreParams): void => {
+    const fileNames = params.files.map((file) => file.fileName);
+
+    const removeEnvReference = params.configEnv === true
+        ? writeEnvReference(params.storeDir)
+        : (): void => undefined;
+
+    try {
+        compileProject({
+            projectDir: params.storeDir,
+            fileNames: params.configEnv === true ? [ENV_REFERENCE_FILE, ...fileNames] : fileNames,
+            compilerOptions: EMIT_OPTIONS,
+            label: `the generated ${params.packageName} store`,
+        });
+    } finally {
+        removeEnvReference();
+    }
+
+    for (const file of params.files) {
+        rmSync(join(params.storeDir, file.fileName), { force: true });
+    }
+};
+
+export { compileStore, type CompileStoreParams };

package/src/store/gi/async.ts

@@ -0,0 +1,69 @@
+import type { GirFunction } from "../../gir/function.js";
+import type { Library } from "../../gir/library.js";
+import type { TypeId } from "../../gir/type-id.js";
+import { inputParameters } from "../../analysis/param-structure.js";
+
+const matchAsyncFinish = (
+    library: Library,
+    fn: GirFunction,
+    siblings: GirFunction[],
+): GirFunction | undefined => {
+    if (!hasCanonicalAsyncCallback(library, fn)) {
+        return undefined;
+    }
+
+    const finishFn = findFinishSibling(fn, siblings);
+
+    if (finishFn === undefined || !isPromisifiableFinish(library, finishFn)) {
+        return undefined;
+    }
+
+    return finishFn;
+};
+
+const findFinishSibling = (fn: GirFunction, siblings: GirFunction[]): GirFunction | undefined => {
+    const annotated = fn.finishFunc;
+
+    if (annotated !== undefined) {
+        return siblings.find((sibling) => sibling.name === annotated || sibling.cIdentifier === annotated);
+    }
+
+    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.find((sibling) => sibling.name === finishName);
+};
+
+const callbackParameterName = (library: Library, ref: TypeId | undefined): string | undefined => {
+    if (ref === undefined || library.typeFor(ref)?.kind !== "callback") {
+        return undefined;
+    }
+
+    return library.nameFor(ref)?.typeName;
+};
+
+const hasCanonicalAsyncCallback = (library: Library, fn: GirFunction): boolean => {
+    const callbackNames = fn.parameters
+        .map((parameter) => callbackParameterName(library, parameter.type))
+        .filter((name): name is string => name !== undefined);
+
+    return callbackNames.length === 1 && callbackNames[0] === "AsyncReadyCallback";
+};
+
+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.nameFor(only.parameter.type)?.typeName === "AsyncResult";
+};
+
+export { matchAsyncFinish };