@gtkx/codegen 0.21.0

package/src/store-fs.ts

@@ -0,0 +1,157 @@
+import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { transpileSource } from "./transpile.js";
+
+/**
+ * Filesystem primitives shared by the injected-package assemblers
+ * ({@link ../gi-store.js}, {@link ../jsx-store.js}).
+ */
+
+/**
+ * Fields every injected-package store assembler needs: where the hidden store
+ * lives, the visible alias symlink, and the version stamped onto its manifest.
+ */
+export type StoreOptions = {
+    /** Absolute path to the hidden store directory (e.g. `node_modules/.gtkx/gi`). */
+    readonly storeDir: string;
+    /** Absolute path to the visible alias symlink (e.g. `node_modules/@gtkx/gi`). */
+    readonly linkDir: string;
+    /** Version string copied onto the emitted package's `package.json`. */
+    readonly version: string;
+};
+
+/** A transpilable source destined for the store, addressed by output stem. */
+export type StoreFile = {
+    /** Output path without extension, relative to the store root. */
+    readonly stem: string;
+    /** Source filename TypeScript uses for diagnostics. */
+    readonly fileName: string;
+    /** The TypeScript source to transpile and write. */
+    readonly source: string;
+};
+
+/** A symlink to create inside the store's own bundled `node_modules`. */
+export type StoreSymlink = {
+    /** Path segments under the store root the symlink is created at. */
+    readonly segments: readonly string[];
+    /** Absolute symlink target, or `"self"` for the store root itself. */
+    readonly target: string | "self";
+};
+
+/**
+ * Assembles a store in a fresh temp directory and atomically swaps it into
+ * place: writes every file pair, the `package.json`, the bundled
+ * `node_modules` symlinks, then promotes the temp tree and re-points the
+ * visible alias. An optional {@link WriteStoreParams.validate} runs against the
+ * temp root before any file is written, so a failure aborts before the store
+ * goes live.
+ *
+ * @param params - {@link WriteStoreParams}
+ */
+export const writeStore = (params: WriteStoreParams): void => {
+    const tmp = tempStoreFor(params.storeDir);
+    params.validate?.(tmp);
+    for (const file of params.files) {
+        writeFilePair(tmp, file.stem, file.fileName, file.source);
+    }
+    writePackageJson(tmp, params.manifest);
+    for (const raw of params.rawFiles ?? []) {
+        writeFileSync(join(tmp, raw.relativePath), raw.content);
+    }
+    for (const { segments, target } of params.symlinks) {
+        symlinkRelative(join(tmp, ...segments), target === "self" ? tmp : target);
+    }
+    swapStore(tmp, params.storeDir, params.linkDir);
+};
+
+/** Inputs for {@link writeStore}. */
+export type WriteStoreParams = {
+    /** Absolute hidden store directory. */
+    readonly storeDir: string;
+    /** Absolute visible alias symlink. */
+    readonly linkDir: string;
+    /** The source files to transpile and write. */
+    readonly files: readonly StoreFile[];
+    /** The `package.json` manifest to serialize. */
+    readonly manifest: unknown;
+    /** The bundled `node_modules` symlinks to create. */
+    readonly symlinks: readonly StoreSymlink[];
+    /** Verbatim files (e.g. a fingerprint sentinel) written under the store root. */
+    readonly rawFiles?: readonly { readonly relativePath: string; readonly content: string }[];
+    /** Optional in-memory validation run on the temp root before files are written. */
+    readonly validate?: (tmp: string) => void;
+};
+
+/**
+ * Transpiles `source` and writes the resulting `.js`/`.d.ts` pair at `stem`
+ * (relative to `storeDir`), creating parent directories as needed.
+ *
+ * @param storeDir - Absolute store root the file is written under
+ * @param stem - Output path without extension, relative to `storeDir`
+ * @param fileName - Source filename TypeScript uses for diagnostics
+ * @param source - The TypeScript source to transpile
+ */
+export const writeFilePair = (storeDir: string, stem: string, fileName: string, source: string): void => {
+    const { js, dts } = transpileSource(fileName, source);
+    const jsPath = join(storeDir, `${stem}.js`);
+    mkdirSync(dirname(jsPath), { recursive: true });
+    writeFileSync(jsPath, js);
+    writeFileSync(join(storeDir, `${stem}.d.ts`), dts);
+};
+
+/**
+ * Creates (or replaces) a relative directory symlink at `linkPath` pointing at
+ * `realTarget`. Relative so the link survives the store being moved or cached.
+ *
+ * @param linkPath - Absolute path of the symlink to create
+ * @param realTarget - Absolute path the symlink resolves to
+ */
+export const symlinkRelative = (linkPath: string, realTarget: string): void => {
+    mkdirSync(dirname(linkPath), { recursive: true });
+    rmSync(linkPath, { recursive: true, force: true });
+    symlinkSync(relative(dirname(linkPath), realTarget), linkPath, "dir");
+};
+
+/**
+ * Writes a pretty-printed `package.json` into `storeDir`.
+ *
+ * @param storeDir - Absolute directory to write `package.json` into
+ * @param manifest - The manifest object to serialize
+ */
+export const writePackageJson = (storeDir: string, manifest: unknown): void => {
+    writeFileSync(join(storeDir, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+};
+
+/**
+ * Swaps a fully-assembled temp store into place and re-points the visible alias
+ * at it.
+ *
+ * The live store is renamed aside and the temp store renamed in before the old
+ * tree is deleted, so the store is unavailable only for the duration of a single
+ * rename instead of a full recursive delete. Not safe against a second codegen
+ * run swapping the same store concurrently.
+ *
+ * @param tmp - Absolute temp store directory to promote
+ * @param storeDir - Absolute final store directory
+ * @param visibleLink - Absolute path of the visible alias symlink
+ */
+export const swapStore = (tmp: string, storeDir: string, visibleLink: string): void => {
+    const previous = `${storeDir}.old`;
+    rmSync(previous, { recursive: true, force: true });
+    if (existsSync(storeDir)) {
+        renameSync(storeDir, previous);
+    }
+    renameSync(tmp, storeDir);
+    rmSync(previous, { recursive: true, force: true });
+    symlinkRelative(visibleLink, storeDir);
+};
+
+/**
+ * Creates a fresh, per-run temporary store directory next to `storeDir` and
+ * returns its path. The random suffix isolates concurrent or repeated runs so
+ * they cannot corrupt each other's in-progress trees.
+ */
+export const tempStoreFor = (storeDir: string): string => {
+    mkdirSync(dirname(storeDir), { recursive: true });
+    return mkdtempSync(`${storeDir}.tmp-`);
+};

package/src/transpile.ts

@@ -0,0 +1,80 @@
+import ts from "typescript";
+
+/**
+ * Output of a single TypeScript transpile: the stripped `.js` and the
+ * isolated-declaration `.d.ts` it produces.
+ */
+export type TranspiledFile = {
+    /** Stripped-types JavaScript output. */
+    readonly js: string;
+    /** Generated TypeScript declaration output. */
+    readonly dts: string;
+};
+
+/**
+ * The compiler options shared by the store's two TypeScript passes — the
+ * single-file transpile here and the overlay type-check in `typecheck-store.ts`.
+ * Each pass spreads these and adds its own emit/check-specific keys.
+ */
+export const baseCompilerOptions = (): ts.CompilerOptions => ({
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    target: ts.ScriptTarget.ESNext,
+    skipLibCheck: true,
+    jsx: ts.JsxEmit.ReactJSX,
+    jsxImportSource: "react",
+});
+
+const COMPILER_OPTIONS: ts.CompilerOptions = {
+    ...baseCompilerOptions(),
+    declaration: true,
+    skipDefaultLibCheck: true,
+    removeComments: false,
+    sourceMap: false,
+    declarationMap: false,
+};
+
+/**
+ * Transpiles a single TypeScript source string to a `.js` / `.d.ts` pair.
+ *
+ * Uses `ts.transpileModule` for the JS half (type-stripping only, no
+ * type checking) and `ts.transpileDeclaration` for the declaration half
+ * (single-file declaration emit). Generated sources annotate every export
+ * for isolated-declaration emit, so `transpileDeclaration` always
+ * succeeds; an error-category diagnostic from it represents a writer bug
+ * and is surfaced rather than swallowed.
+ *
+ * @param fileName - Source filename, used by TS for path resolution
+ * @param source - The TypeScript source string
+ */
+export const transpileSource = (fileName: string, source: string): TranspiledFile => {
+    const jsResult = ts.transpileModule(source, {
+        compilerOptions: COMPILER_OPTIONS,
+        fileName,
+        reportDiagnostics: false,
+    });
+    const dtsResult = ts.transpileDeclaration(source, {
+        compilerOptions: COMPILER_OPTIONS,
+        fileName,
+    });
+    const errorDiagnostics = (dtsResult.diagnostics ?? []).filter(
+        (diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error,
+    );
+    if (errorDiagnostics.length > 0) {
+        const messages = errorDiagnostics
+            .slice(0, 5)
+            .map((diagnostic) => {
+                const text = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+                if (diagnostic.file && diagnostic.start !== undefined) {
+                    const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+                    return `[${line + 1}:${character + 1}] ${text}`;
+                }
+                return text;
+            })
+            .join("\n");
+        throw new Error(
+            `transpileDeclaration produced ${errorDiagnostics.length} diagnostic(s) for ${fileName}:\n${messages}`,
+        );
+    }
+    return { js: jsResult.outputText, dts: dtsResult.outputText };
+};

package/src/typecheck-store.ts

@@ -0,0 +1,136 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import ts from "typescript";
+import { baseCompilerOptions } from "./transpile.js";
+
+/**
+ * One in-memory source destined for the injected `@gtkx/gi` store, plus whether
+ * it is a hand-written overlay (the type-check target) or a generated module
+ * declaration (checked against, but not reported on).
+ */
+export type StoreSourceFile = {
+    /** Absolute virtual path of the source, under the store root. */
+    readonly path: string;
+    /** TypeScript source text (overlay `.ts`) or declaration text (generated `.d.ts`). */
+    readonly source: string;
+    /** Whether this is a hand-written overlay/augment source. */
+    readonly overlay: boolean;
+};
+
+const GI_SPECIFIER = "@gtkx/gi/";
+
+const COMPILER_OPTIONS: ts.CompilerOptions = {
+    ...baseCompilerOptions(),
+    customConditions: ["source"],
+    strict: true,
+    noEmit: true,
+    types: [],
+};
+
+/**
+ * Source entries the overlay type-check resolves the runtime packages to.
+ */
+export type RuntimeEntries = {
+    /** Absolute path to `@gtkx/ffi`'s source entry (`src/index.ts`). */
+    readonly ffiEntry: string;
+    /** Absolute path to `@gtkx/native`'s declaration entry (`dist/index.d.ts`). */
+    readonly nativeEntry: string;
+};
+
+const buildCompilerHost = (
+    storeRoot: string,
+    virtualSources: ReadonlyMap<string, string>,
+    entries: RuntimeEntries,
+): ts.CompilerHost => {
+    const readSource = (fileName: string): string | undefined =>
+        virtualSources.get(fileName) ?? (existsSync(fileName) ? readFileSync(fileName, "utf8") : undefined);
+
+    const resolveInjected = (specifier: string): string | undefined => {
+        if (specifier === "@gtkx/ffi") return entries.ffiEntry;
+        if (specifier === "@gtkx/native") return entries.nativeEntry;
+        if (!specifier.startsWith(GI_SPECIFIER)) return undefined;
+        const stem = specifier.slice(GI_SPECIFIER.length).replace(/\.js$/, "");
+        return [`${stem}.d.ts`, `${stem}.ts`, `${stem}/index.d.ts`, `${stem}/index.ts`]
+            .map((candidate) => join(storeRoot, candidate))
+            .find((candidate) => virtualSources.has(candidate));
+    };
+
+    const moduleResolutionHost: ts.ModuleResolutionHost = {
+        fileExists: (fileName) => virtualSources.has(fileName) || existsSync(fileName),
+        readFile: readSource,
+    };
+
+    return {
+        getSourceFile: (fileName, languageVersion) => {
+            const source = readSource(fileName);
+            return source === undefined ? undefined : ts.createSourceFile(fileName, source, languageVersion, true);
+        },
+        getDefaultLibFileName: (options) => ts.getDefaultLibFilePath(options),
+        writeFile: () => {},
+        getCurrentDirectory: () => storeRoot,
+        getCanonicalFileName: (fileName) => fileName,
+        useCaseSensitiveFileNames: () => true,
+        getNewLine: () => "\n",
+        fileExists: (fileName) => virtualSources.has(fileName) || existsSync(fileName),
+        readFile: readSource,
+        resolveModuleNameLiterals: (literals, containingFile, _redirectedReference, options) =>
+            literals.map((literal) => {
+                const injected = resolveInjected(literal.text);
+                if (injected !== undefined) {
+                    return { resolvedModule: { resolvedFileName: injected, extension: ts.Extension.Ts } };
+                }
+                return {
+                    resolvedModule: ts.resolveModuleName(literal.text, containingFile, options, moduleResolutionHost)
+                        .resolvedModule,
+                };
+            }),
+    };
+};
+
+const reportOverlayErrors = (program: ts.Program, overlayPaths: readonly string[], storeRoot: string): void => {
+    const errors: ts.Diagnostic[] = [];
+    for (const path of overlayPaths) {
+        const sourceFile = program.getSourceFile(path);
+        if (!sourceFile) continue;
+        for (const diagnostic of program.getSemanticDiagnostics(sourceFile)) {
+            if (diagnostic.category === ts.DiagnosticCategory.Error) errors.push(diagnostic);
+        }
+    }
+    if (errors.length === 0) return;
+    const formatted = ts.formatDiagnosticsWithColorAndContext(errors, {
+        getCurrentDirectory: () => storeRoot,
+        getCanonicalFileName: (fileName) => fileName,
+        getNewLine: () => "\n",
+    });
+    throw new Error(`Overlay type-check failed against the generated @gtkx/gi API:\n${formatted}`);
+};
+
+/**
+ * Type-checks the hand-written overlay sources against the freshly generated
+ * `@gtkx/gi` declarations, entirely in memory.
+ *
+ * The overlay augments generated classes (e.g. installs `Value.prototype.getBoxed`),
+ * so its correctness is only meaningful relative to the exact API codegen just
+ * produced. A {@link ts.Program} is assembled over the in-memory generated
+ * declarations and overlay sources, resolving `@gtkx/gi/*` to the generated
+ * declarations and `@gtkx/ffi` to its package source; every other specifier
+ * (`react`, lib files) resolves from the real filesystem. Semantic errors on the
+ * overlay sources abort codegen rather than ship broken bindings.
+ *
+ * @param storeRoot - Absolute root the virtual source paths are rooted at.
+ * @param files - The in-memory generated declarations and overlay sources.
+ * @param entries - Absolute source entries for `@gtkx/ffi` and `@gtkx/native`.
+ * @throws When any overlay source has a semantic type error.
+ */
+export const typecheckGiStore = (
+    storeRoot: string,
+    files: readonly StoreSourceFile[],
+    entries: RuntimeEntries,
+): void => {
+    const overlayPaths = files.filter((file) => file.overlay).map((file) => file.path);
+    if (overlayPaths.length === 0) return;
+    const virtualSources = new Map(files.map((file) => [file.path, file.source]));
+    const host = buildCompilerHost(storeRoot, virtualSources, entries);
+    const program = ts.createProgram({ rootNames: files.map((file) => file.path), options: COMPILER_OPTIONS, host });
+    reportOverlayErrors(program, overlayPaths, storeRoot);
+};

package/src/writers/alias.ts

@@ -0,0 +1,19 @@
+import type { ModuleContext } from "../dsl/context.js";
+import { aliasExportName } from "../dsl/identifier.js";
+import type { GirAlias } from "../gir/namespace.js";
+import { renderTsType } from "./ts-type.js";
+
+/**
+ * Emits an `export type` declaration for a GIR `<alias>`.
+ *
+ * The alias is exported under {@link aliasExportName} — its GIR `name`, with
+ * GObject's `Type` published as `GType`.
+ *
+ * @param context - The module context
+ * @param alias - The alias to emit
+ */
+export const emitAlias = (context: ModuleContext, alias: GirAlias): void => {
+    const exportName = aliasExportName(context.namespace.name, alias.name);
+    const targetType = renderTsType(context, alias.target);
+    context.module.appendDeclaration(`export type ${exportName} = ${targetType};`);
+};

package/src/writers/async.ts

@@ -0,0 +1,44 @@
+import type { GirFunction } from "../gir/function.js";
+
+/**
+ * Detects the start half of a `Gio.AsyncReady` callable pair.
+ *
+ * Pairs follow two GIR conventions: an explicit `*_async` / `*_finish`
+ * suffix (the older style), or a base name paired with a `<root>_finish`
+ * (the modern GTK 4 style, e.g. `gtk_file_dialog_open` /
+ * `gtk_file_dialog_open_finish`).
+ *
+ * The runtime convention is to wrap the pair with `promisify(asyncFn,
+ * finishFn, cancellable, { leading })`. This detector returns the
+ * matching finish counterpart's GIR name when one exists in the same
+ * set of callables, so the class writer can wire the wrapper.
+ *
+ * @param fn - The candidate async-start callable
+ * @param siblings - Other callables on the same type to scan for the
+ *     matching `*_finish`
+ * @returns The matching `*_finish` GIR name, or `undefined` when there is
+ *     no pair
+ */
+export const matchAsyncFinishName = (fn: GirFunction, siblings: readonly GirFunction[]): string | undefined => {
+    if (fn.name.endsWith("_async")) {
+        const root = fn.name.slice(0, -"_async".length);
+        const finishName = `${root}_finish`;
+        const match = siblings.find((sibling) => sibling.name === finishName);
+        return match === undefined ? undefined : finishName;
+    }
+    if (fn.name.endsWith("_finish")) return undefined;
+    const finishName = `${fn.name}_finish`;
+    const match = siblings.find((sibling) => sibling.name === finishName);
+    if (match === undefined) return undefined;
+    if (!hasAsyncReadyCallbackParameter(fn)) return undefined;
+    return finishName;
+};
+
+const hasAsyncReadyCallbackParameter = (fn: GirFunction): boolean => {
+    for (const parameter of fn.parameters) {
+        if (parameter.scope !== undefined) return true;
+        if (parameter.type?.kind !== "named") continue;
+        if (parameter.type.typeName === "AsyncReadyCallback") return true;
+    }
+    return false;
+};

package/src/writers/boxed-constructor.ts

@@ -0,0 +1,105 @@
+import { quote, toCamelCase, toIdentifier } from "@gtkx/utils";
+import type { ModuleContext } from "../dsl/context.js";
+import { indent } from "../dsl/emit.js";
+import type { GirBoxed } from "../gir/boxed.js";
+import type { GirField } from "../gir/field.js";
+import type { GirTypeRef } from "../gir/type-ref.js";
+import { type BoxedFieldSlot, computeBoxedFieldSlots } from "./boxed-layout.js";
+import { renderTsType } from "./ts-type.js";
+import { renderFfiType } from "./value.js";
+
+/**
+ * A boxed field that carries a writable value (private, read-only, callback,
+ * and type-less fields are not settable at construction).
+ */
+type WritableFieldSlot = BoxedFieldSlot & { readonly field: GirField & { readonly type: GirTypeRef } };
+
+const isWritableFieldSlot = (entry: BoxedFieldSlot): entry is WritableFieldSlot =>
+    !entry.field.private &&
+    entry.field.writable &&
+    entry.field.callback === undefined &&
+    entry.field.type !== undefined;
+
+const isOpaque = (boxed: GirBoxed): boolean => boxed.glibGetType === undefined && boxed.disguised;
+
+/**
+ * Renders the `export interface <Boxed>ConstructorProps` declaration: the
+ * camelCase, optional, nullable form of every writable field. Opaque boxed
+ * records (disguised, no GType) have no known fields and get an empty bag.
+ *
+ * @param context - The module context
+ * @param boxed - The boxed record
+ * @param className - The local PascalCase class name
+ */
+export const renderBoxedConstructorPropsInterface = (
+    context: ModuleContext,
+    boxed: GirBoxed,
+    className: string,
+): string => {
+    if (isOpaque(boxed)) return `export interface ${className}ConstructorProps {}`;
+    const { slots } = computeBoxedFieldSlots(context, boxed.fields, boxed.isUnion);
+    const lines = slots
+        .filter(isWritableFieldSlot)
+        .map(
+            (entry) =>
+                `${toIdentifier(toCamelCase(entry.field.name))}?: ${renderTsType(context, entry.field.type, true)};`,
+        );
+    const body = lines.length === 0 ? "" : `\n${indent(lines.join("\n"), 1)}\n`;
+    return `export interface ${className}ConstructorProps {${body}}`;
+};
+
+/**
+ * Renders a boxed record's constructor.
+ *
+ * The constructor allocates zero-filled native memory of the struct's size and
+ * writes each provided field at its byte offset, threading bitfield members
+ * through a read-modify-write into their shared storage word. Opaque records
+ * have no known layout, so their constructor throws.
+ *
+ * @param context - The module context
+ * @param boxed - The boxed record
+ * @param className - The local PascalCase class name
+ */
+export const renderBoxedConstructor = (context: ModuleContext, boxed: GirBoxed, className: string): string => {
+    if (isOpaque(boxed)) {
+        return `constructor() {\n${indent(`throw new Error(${quote(`Cannot construct ${className}: opaque boxed type with no known layout`)});`, 1)}\n}`;
+    }
+    context.addNativeImport("alloc");
+    context.addRuntimeImport("setHandle");
+    const { slots, size } = computeBoxedFieldSlots(context, boxed.fields, boxed.isUnion);
+    const statements = [`const handle = alloc(${allocArgs(context, boxed, size).join(", ")});`];
+    for (const entry of slots) {
+        if (!isWritableFieldSlot(entry)) continue;
+        statements.push(renderFieldWrite(context, entry));
+    }
+    statements.push("setHandle(this, handle);");
+    const body = statements.join("\n");
+    return `constructor(props: ${className}ConstructorProps = {}) {\n${indent(body, 1)}\n}`;
+};
+
+const allocArgs = (context: ModuleContext, boxed: GirBoxed, size: number): readonly string[] => {
+    const glibTypeName = boxed.glibTypeName ?? boxed.cType;
+    const lib = context.namespace.sharedLibrary;
+    const args = [String(size)];
+    if (glibTypeName !== undefined || lib !== undefined) {
+        args.push(glibTypeName !== undefined ? quote(glibTypeName) : "undefined");
+    }
+    if (lib !== undefined) args.push(quote(lib));
+    return args;
+};
+
+const renderFieldWrite = (context: ModuleContext, entry: WritableFieldSlot): string => {
+    context.addRuntimeImport("t");
+    context.addNativeImport("write");
+    const ffiType = renderFfiType(context, entry.field.type, "none");
+    const name = toIdentifier(toCamelCase(entry.field.name));
+    const offset = entry.slot.byteOffset;
+    if (entry.slot.bitWidth === undefined) {
+        return `if (props.${name} !== undefined) write(handle, ${ffiType}, ${offset}, props.${name});`;
+    }
+    context.addNativeImport("read");
+    const mask = (1 << entry.slot.bitWidth) - 1;
+    const bitOffset = entry.slot.bitOffset ?? 0;
+    const merged = `(((read(handle, ${ffiType}, ${offset}) as number) & ~(${mask} << ${bitOffset})) | ((Number(props.${name}) & ${mask}) << ${bitOffset})) >>> 0`;
+    return `if (props.${name} !== undefined) write(handle, ${ffiType}, ${offset}, ${merged});`;
+};