@gtkx/codegen 0.21.0

package/src/dsl/context.ts

@@ -0,0 +1,146 @@
+import type { GirNamespace } from "../gir/namespace.js";
+import type { GirRepository } from "../gir/repository.js";
+import { ModuleBuilder } from "./module.js";
+
+/**
+ * Shared context handed to every writer for a single generated FFI module.
+ *
+ * Bundles the namespace the writer is emitting for, the broader repository
+ * (for cross-namespace lookups), and the in-progress {@link ModuleBuilder}.
+ * Writers also call back into this context to register cross-namespace
+ * runtime imports so individual writers do not need to know the relative
+ * path layout of the generated output.
+ *
+ * Generated bindings live in the `@gtkx/gi` package at `<ns>/<ns>.{js,d.ts}`,
+ * with a per-namespace barrel at `<ns>/index.js` and the augment overlay at
+ * `<ns>/augment/*.js`. The hand-written runtime is reached through the single
+ * `@gtkx/ffi` barrel; sibling generated namespaces are reached relative to the
+ * gi package root.
+ */
+export class ModuleContext {
+    public readonly module = new ModuleBuilder();
+
+    /**
+     * @param namespace - The namespace this module corresponds to
+     * @param repository - The repository containing every loaded namespace
+     */
+    constructor(
+        public readonly namespace: GirNamespace,
+        public readonly repository: GirRepository,
+    ) {}
+
+    /**
+     * Adds a named import from the `@gtkx/ffi` runtime barrel.
+     */
+    addRuntimeImport(name: string): void {
+        this.module.imports.addNamed("@gtkx/ffi", name);
+    }
+
+    /**
+     * Adds a type-only named import from the `@gtkx/ffi` runtime barrel
+     * (`import { type Name }`), erased from the emitted `.js`.
+     */
+    addRuntimeTypeImport(name: string): void {
+        this.module.imports.addNamed("@gtkx/ffi", name, true);
+    }
+
+    /**
+     * Adds a named import from the low-level `@gtkx/native` runtime.
+     *
+     * The transport primitives (`alloc`, `call`, `read`, `write`) live in
+     * `@gtkx/native`; generated bindings reach them directly so `@gtkx/ffi`
+     * stays the home of higher-level runtime helpers only.
+     */
+    addNativeImport(name: string): void {
+        this.module.imports.addNamed("@gtkx/native", name);
+    }
+
+    /**
+     * Adds a type-only named import from `@gtkx/native`
+     * (`import { type Name }`), erased from the emitted `.js`.
+     */
+    addNativeTypeImport(name: string): void {
+        this.module.imports.addNamed("@gtkx/native", name, true);
+    }
+
+    /** Adds the canonical `constructGObjectInstance` import from `@gtkx/ffi`. */
+    addConstructGObjectInstanceImport(): void {
+        this.module.imports.addNamed("@gtkx/ffi", "constructGObjectInstance");
+    }
+
+    /** Adds the `valueFromFfi` import from `@gtkx/ffi`. */
+    addValueFromFfiImport(): void {
+        this.module.imports.addNamed("@gtkx/ffi", "valueFromFfi");
+    }
+
+    /** Adds the `valueFromFfiOptional` import from `@gtkx/ffi`. */
+    addValueFromFfiOptionalImport(): void {
+        this.module.imports.addNamed("@gtkx/ffi", "valueFromFfiOptional");
+    }
+
+    /**
+     * Adds the canonical side-effect imports for `gobject/object.js` and
+     * `gobject/value.js`.
+     *
+     * Skipped for the `GObject` namespace itself (those modules import its
+     * generated classes) and for `GLib`, which lives below GObject in the
+     * import graph. Letting GLib bootstrap creates a runtime cycle:
+     * `gobject.js` imports `glib.js` for `GLib.Variant` return-wrapping,
+     * `glib.js`'s bootstrap re-enters `gobject/value.js`, and `value.ts`
+     * touches `Value.prototype` before `gobject.js` has finished defining
+     * `Value`. Other namespaces install the override on first import.
+     */
+    addGObjectBootstrapImports(): void {
+        if (this.namespace.name === "GObject") return;
+        if (this.namespace.name === "GLib") return;
+        this.module.imports.addSideEffect("../gobject/augment/object.js");
+        this.module.imports.addSideEffect("../gobject/augment/value.js");
+    }
+
+    /**
+     * Adds a wildcard import for another namespace and returns the local
+     * alias used.
+     *
+     * Most namespaces are routed through their hand-written `index.js` so any
+     * prototype augmentations (Cairo `Context` methods, Gdk `RGBA`, Graphene
+     * structs, …) load whenever a generated module references the namespace.
+     * The foundational `gobject` and `glib` namespaces are routed straight to
+     * their generated module instead, because their indexes pull in modules
+     * that depend on values still mid-initialization, which would deadlock the
+     * import graph.
+     *
+     * For non-foundational namespaces a side-effect import is recorded
+     * alongside the wildcard so the foreign module loads even when its alias
+     * appears only in type positions. The wildcard alias is type-stripped out
+     * of the emitted `.js` whenever it is never read as a value, which would
+     * otherwise drop the foreign module from the runtime graph and skip its
+     * eager `*_get_type` registrations. The side-effect import survives type
+     * stripping and pins the module in place. The foundational `gobject` and
+     * `glib` wildcards are always read as values (enums, base classes) and so
+     * are never stripped, needing no side-effect pin.
+     *
+     * @param namespaceName - The other namespace (e.g. `"GLib"`)
+     */
+    addCrossNamespaceImport(namespaceName: string): string {
+        if (namespaceName === this.namespace.name) return namespaceName;
+        const directory = namespaceName.toLowerCase();
+        const isFoundational = directory === "gobject" || directory === "glib";
+        const path = isFoundational ? `../${directory}/${directory}.js` : `../${directory}/index.js`;
+        if (!isFoundational) this.module.imports.addSideEffect(`../${directory}/${directory}.js`);
+        this.module.imports.addNamespace(path, namespaceName);
+        return namespaceName;
+    }
+
+    /**
+     * Renders a namespace-qualified reference to `typeName`: the bare name when
+     * it lives in this module's own namespace, otherwise `Alias.Name` with the
+     * foreign namespace imported on demand via {@link addCrossNamespaceImport}.
+     *
+     * @param namespaceName - The namespace the referenced type lives in
+     * @param typeName - The local type or export name within that namespace
+     */
+    qualify(namespaceName: string, typeName: string): string {
+        if (namespaceName === this.namespace.name) return typeName;
+        return `${this.addCrossNamespaceImport(namespaceName)}.${typeName}`;
+    }
+}

package/src/dsl/emit.ts

@@ -0,0 +1,42 @@
+/**
+ * Tiny string-builder helpers used by the writers to assemble TypeScript
+ * source. The DSL deliberately stops short of modelling expressions or
+ * statements — writers compose strings directly using these primitives.
+ */
+
+/**
+ * Indents each line of `block` by `level` four-space units.
+ *
+ * Lines that are empty stay empty (no trailing whitespace).
+ *
+ * @param block - The multi-line source fragment
+ * @param level - Number of indentation steps to apply
+ */
+export const indent = (block: string, level: number): string => {
+    if (level <= 0) return block;
+    const prefix = "    ".repeat(level);
+    return block
+        .split("\n")
+        .map((line) => (line.length === 0 ? line : `${prefix}${line}`))
+        .join("\n");
+};
+
+/**
+ * Joins `parts` with commas, dropping `undefined` entries.
+ */
+export const joinArgs = (parts: ReadonlyArray<string | undefined>): string =>
+    parts.filter((part): part is string => part !== undefined).join(", ");
+
+/**
+ * Renders an array literal multi-line, indenting each element four spaces
+ * and adding a trailing comma.
+ *
+ * Empty input renders as `[]`.
+ *
+ * @param elements - Already-rendered element expressions
+ */
+export const arrayLiteral = (elements: readonly string[]): string => {
+    if (elements.length === 0) return "[]";
+    const lines = elements.map((element) => `    ${element},`);
+    return `[\n${lines.join("\n")}\n]`;
+};

package/src/dsl/identifier.ts

@@ -0,0 +1,52 @@
+import { toCamelCase, toIdentifier } from "@gtkx/utils";
+
+/**
+ * Derives the public camelCase export name for a namespace-level callable.
+ *
+ * The GIR `name` attribute is camelCased (`quark_from_string` →
+ * `quarkFromString`); for a shadowing function it is the shadowed short name,
+ * so `g_idle_add_full` (which shadows `idle_add`) exports as `idleAdd`. When the
+ * `name` is empty the C identifier is used instead, with the namespace's
+ * `c:symbol-prefixes` value stripped (e.g. `g_` from `g_quark_from_string`).
+ * The result is escaped so it never collides with a reserved word.
+ *
+ * @param cIdentifier - The C symbol identifier from GIR
+ * @param girName - The GIR `name` attribute (shadow-resolved)
+ * @param symbolPrefixes - The namespace's `c:symbol-prefixes` values
+ */
+export const namespaceFunctionExportName = (
+    cIdentifier: string,
+    girName: string,
+    symbolPrefixes: readonly string[],
+): string => {
+    if (girName.length > 0) {
+        return toIdentifier(toCamelCase(girName));
+    }
+    const stripped = stripLongestPrefix(cIdentifier, symbolPrefixes);
+    return toIdentifier(toCamelCase(stripped));
+};
+
+/**
+ * Derives the exported identifier for a GIR `<alias>`.
+ *
+ * Aliases are surfaced under their GIR `name` (e.g. `Quark`, `Pid`,
+ * `Allocation`), matching the `@girs` convention. GObject's `Type` alias is the
+ * one exception: it is published as `GType` so it lines up with the GObject
+ * runtime's `GType` type and the references that resolve through it.
+ *
+ * @param namespaceName - The namespace the alias is declared in
+ * @param aliasName - The alias's GIR `name`
+ */
+export const aliasExportName = (namespaceName: string, aliasName: string): string =>
+    namespaceName === "GObject" && aliasName === "Type" ? "GType" : aliasName;
+
+const stripLongestPrefix = (input: string, prefixes: readonly string[]): string => {
+    let best = "";
+    for (const prefix of prefixes) {
+        const candidate = `${prefix}_`;
+        if (input.startsWith(candidate) && candidate.length > best.length) {
+            best = candidate;
+        }
+    }
+    return best.length === 0 ? input : input.slice(best.length);
+};

package/src/dsl/imports.ts

@@ -0,0 +1,109 @@
+import { quote } from "@gtkx/utils";
+
+/**
+ * Tracks imports for a single generated module.
+ *
+ * The DSL is intentionally tiny: it covers what is awkward to do with
+ * string concatenation (deduplicating named imports, sorting them, mixing
+ * side-effect and named imports from the same specifier) and leaves
+ * everything else to raw TS strings the writers compose themselves.
+ */
+export class ImportsBuilder {
+    private readonly named = new Map<string, Map<string, boolean>>();
+    private readonly defaultNames = new Map<string, string>();
+    private readonly namespaces = new Map<string, string>();
+    private readonly sideEffects = new Set<string>();
+
+    /**
+     * Records a named import: `import { foo, bar } from "lib"`.
+     *
+     * Repeated calls deduplicate; the final emit alphabetises within the
+     * braces. A name is emitted with the inline `type` modifier only when
+     * every recording of it is type-only — a single value import of the same
+     * name keeps it a value import.
+     *
+     * @param specifier - The module specifier (e.g. `"@gtkx/ffi"`)
+     * @param name - The identifier to import
+     * @param isType - Whether this recording is type-only (`import { type X }`)
+     */
+    addNamed(specifier: string, name: string, isType = false): void {
+        let bucket = this.named.get(specifier);
+        if (bucket === undefined) {
+            bucket = new Map();
+            this.named.set(specifier, bucket);
+        }
+        bucket.set(name, (bucket.get(name) ?? true) && isType);
+    }
+
+    /**
+     * Records a namespace import: `import * as Alias from "lib"`.
+     *
+     * The first call wins if a different alias is reused for the same
+     * specifier.
+     *
+     * @param specifier - The module specifier
+     * @param alias - The local alias bound by the import
+     */
+    addNamespace(specifier: string, alias: string): void {
+        if (!this.namespaces.has(specifier)) {
+            this.namespaces.set(specifier, alias);
+        }
+    }
+
+    /**
+     * Records a default import: `import Alias from "lib"`. Subsequent calls
+     * with a different alias are ignored.
+     *
+     * @param specifier - The module specifier
+     * @param alias - The local name bound to the default export
+     */
+    addDefault(specifier: string, alias: string): void {
+        if (!this.defaultNames.has(specifier)) {
+            this.defaultNames.set(specifier, alias);
+        }
+    }
+
+    /**
+     * Records a side-effect-only import: `import "lib"`.
+     *
+     * @param specifier - The module specifier
+     */
+    addSideEffect(specifier: string): void {
+        this.sideEffects.add(specifier);
+    }
+
+    /**
+     * Renders all imports as a single string ending with a trailing
+     * newline. Side-effect imports come first (in insertion order),
+     * followed by named/namespace/default imports sorted by specifier.
+     */
+    toSource(): string {
+        const lines: string[] = [];
+        for (const specifier of this.sideEffects) {
+            lines.push(`import ${quote(specifier)};`);
+        }
+        const specifiers = new Set<string>([
+            ...this.named.keys(),
+            ...this.namespaces.keys(),
+            ...this.defaultNames.keys(),
+        ]);
+        const sortedSpecifiers = [...specifiers].sort((a, b) => a.localeCompare(b));
+        for (const specifier of sortedSpecifiers) {
+            const defaultAlias = this.defaultNames.get(specifier);
+            const namespaceAlias = this.namespaces.get(specifier);
+            const namedNames = this.named.get(specifier);
+            const parts: string[] = [];
+            if (defaultAlias !== undefined) parts.push(defaultAlias);
+            if (namespaceAlias !== undefined) parts.push(`* as ${namespaceAlias}`);
+            if (namedNames !== undefined && namedNames.size > 0) {
+                const sortedNames = [...namedNames.entries()]
+                    .sort(([a], [b]) => a.localeCompare(b))
+                    .map(([name, isType]) => (isType ? `type ${name}` : name));
+                parts.push(`{ ${sortedNames.join(", ")} }`);
+            }
+            if (parts.length === 0) continue;
+            lines.push(`import ${parts.join(", ")} from ${quote(specifier)};`);
+        }
+        return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
+    }
+}

package/src/dsl/module.ts

@@ -0,0 +1,75 @@
+import { ImportsBuilder } from "./imports.js";
+
+/**
+ * Accumulator for one generated TypeScript module's source.
+ *
+ * Writers append code in three logical phases:
+ *
+ * 1. *Bindings* — the `const fn_name = t.fn(...)` block at the top.
+ * 2. *Declarations* — the class bodies, free function exports, enums,
+ *    constants.
+ * 3. *Registrations* — the trailing `registerNativeClass(...)` block.
+ *
+ * Keeping the three buckets independent removes ordering constraints
+ * between writers and lets {@link emit} stitch a final source string with
+ * the same shape every generated file uses today.
+ */
+export class ModuleBuilder {
+    /** Imports manifest the writers feed into. */
+    public readonly imports = new ImportsBuilder();
+    private readonly bindings: string[] = [];
+    private readonly bindingNames = new Set<string>();
+    private readonly declarations: string[] = [];
+    private readonly registrations: string[] = [];
+
+    /**
+     * Appends a top-level FFI binding (`const foo = t.fn(...)`).
+     *
+     * Duplicates are dropped when a `name` is supplied that matches a
+     * previously appended binding; this is the common case for GIR
+     * callables that appear both as a namespace function and as a
+     * constructor or static on a class.
+     *
+     * @param code - The source fragment, without a trailing newline
+     * @param name - Optional binding identifier used for deduplication
+     */
+    appendBinding(code: string, name?: string): void {
+        if (name !== undefined) {
+            if (this.bindingNames.has(name)) return;
+            this.bindingNames.add(name);
+        }
+        this.bindings.push(code);
+    }
+
+    /**
+     * Appends a declaration (class, function, enum, constant).
+     *
+     * @param code - The source fragment, without a trailing newline
+     */
+    appendDeclaration(code: string): void {
+        this.declarations.push(code);
+    }
+
+    /**
+     * Appends a trailing registration statement (`registerNativeClass(…)`).
+     *
+     * @param code - The source fragment, without a trailing newline
+     */
+    appendRegistration(code: string): void {
+        this.registrations.push(code);
+    }
+
+    /**
+     * Renders the full TypeScript source: imports, bindings, declarations,
+     * registrations — separated by a single blank line.
+     */
+    toSource(): string {
+        const sections: string[] = [];
+        const importsBlock = this.imports.toSource();
+        if (importsBlock.length > 0) sections.push(importsBlock.trimEnd());
+        if (this.bindings.length > 0) sections.push(this.bindings.join("\n\n"));
+        if (this.declarations.length > 0) sections.push(this.declarations.join("\n\n"));
+        if (this.registrations.length > 0) sections.push(this.registrations.join("\n\n"));
+        return `${sections.join("\n\n")}\n`;
+    }
+}

package/src/ffi/pipeline.ts

@@ -0,0 +1,113 @@
+import { ModuleContext } from "../dsl/context.js";
+import type { GirClass } from "../gir/class.js";
+import type { GirNamespace } from "../gir/namespace.js";
+import type { GirRepository } from "../gir/repository.js";
+import { emitAlias } from "../writers/alias.js";
+import { emitBoxed } from "../writers/boxed.js";
+import { emitCallback } from "../writers/callback.js";
+import { emitClass } from "../writers/class.js";
+import { emitConstant } from "../writers/constant.js";
+import { emitEnum } from "../writers/enum.js";
+import { emitNamespaceBootstrap, emitNamespaceFunction } from "../writers/function.js";
+import { emitInterface } from "../writers/interface.js";
+
+/**
+ * Generates the TypeScript source for one FFI namespace module.
+ *
+ * Walks the namespace's declared enums, boxeds, classes, interfaces,
+ * callbacks, functions, constants, and aliases, dispatching to the
+ * per-construct writers in `writers/`: bindings first, declarations second,
+ * registrations trailing.
+ *
+ * @param namespace - The namespace to emit
+ * @param repository - The full repository (for cross-namespace lookups)
+ * @returns The relative output path and the TypeScript source string
+ */
+export const generateNamespaceModule = (
+    namespace: GirNamespace,
+    repository: GirRepository,
+): { readonly path: string; readonly source: string } => {
+    const context = new ModuleContext(namespace, repository);
+    context.addGObjectBootstrapImports();
+
+    for (const enumeration of namespace.enums) {
+        emitEnum(context, enumeration);
+    }
+    for (const boxed of namespace.boxeds) {
+        emitBoxed(context, boxed);
+    }
+    for (const klass of topologicalClassOrder(namespace.classes, namespace.name)) {
+        emitClass(context, klass);
+    }
+    for (const iface of namespace.interfaces) {
+        emitInterface(context, iface);
+    }
+    for (const callback of namespace.callbacks) {
+        emitCallback(context, callback);
+    }
+    for (const fn of namespace.functions) {
+        emitNamespaceFunction(context, fn);
+    }
+    emitNamespaceBootstrap(context, namespace);
+    for (const constant of namespace.constants) {
+        emitConstant(context, constant);
+    }
+    for (const alias of namespace.aliases) {
+        emitAlias(context, alias);
+    }
+
+    const directory = namespace.name.toLowerCase();
+    return {
+        path: `${directory}/${directory}.ts`,
+        source: context.module.toSource(),
+    };
+};
+
+/**
+ * Returns the namespace's classes ordered so each class is preceded by every
+ * same-namespace ancestor it extends.
+ *
+ * Generated JS classes use `extends`, which is a runtime reference: a child
+ * class declaration that names its parent before the parent's class body runs
+ * hits a temporal dead-zone error. GIR file order is source order, which does
+ * not match the inheritance order for namespaces where a leaf type (e.g.
+ * `GObject.Binding`) is declared earlier in the file than its base (e.g.
+ * `GObject.Object`). The codegen sorts by inheritance instead.
+ *
+ * Cross-namespace parents are imported by the writer and do not participate in
+ * the sort.
+ *
+ * @param classes - The classes to order
+ * @param namespaceName - The namespace these classes live in
+ */
+const topologicalClassOrder = (classes: readonly GirClass[], namespaceName: string): readonly GirClass[] => {
+    const byLocalName = new Map<string, GirClass>();
+    for (const klass of classes) byLocalName.set(klass.name, klass);
+    const result: GirClass[] = [];
+    const placed = new Set<GirClass>();
+    const visiting = new Set<GirClass>();
+    const visit = (klass: GirClass): void => {
+        if (placed.has(klass)) return;
+        if (visiting.has(klass)) return;
+        visiting.add(klass);
+        const parent = sameNamespaceParent(klass, namespaceName, byLocalName);
+        if (parent !== undefined) visit(parent);
+        visiting.delete(klass);
+        placed.add(klass);
+        result.push(klass);
+    };
+    for (const klass of classes) visit(klass);
+    return result;
+};
+
+const sameNamespaceParent = (
+    klass: GirClass,
+    namespaceName: string,
+    byLocalName: ReadonlyMap<string, GirClass>,
+): GirClass | undefined => {
+    if (klass.parent === undefined) return undefined;
+    const dot = klass.parent.indexOf(".");
+    if (dot === -1) return byLocalName.get(klass.parent);
+    if (klass.parent.slice(0, dot) !== namespaceName) return undefined;
+    return byLocalName.get(klass.parent.slice(dot + 1));
+};

package/src/fingerprint.ts

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+/** Filename of the staleness sentinel written into the `@gtkx/gi` store root. */
+export const FINGERPRINT_FILENAME = ".codegen-fingerprint.json";
+
+/**
+ * The `@gtkx/codegen` package version, mixed into the store fingerprint so a
+ * codegen upgrade invalidates a previously-generated store.
+ */
+export const CODEGEN_VERSION: string = (require("../package.json") as { version: string }).version;
+
+/**
+ * The staleness sentinel written into the generated `@gtkx/gi` store: the
+ * fingerprint value plus the inputs that produced it, so a consumer can
+ * recompute and compare without reloading the GIR repository.
+ */
+export type CodegenFingerprint = {
+    /** The fingerprint hash of {@link CODEGEN_VERSION}, libraries, and GIR contents. */
+    readonly value: string;
+    /** Absolute paths of every loaded `.gir` file, in load order. */
+    readonly girFiles: readonly string[];
+    /** The resolved `Name-Version` library identifiers the store was built for. */
+    readonly libraries: readonly string[];
+};
+
+/**
+ * Computes a content fingerprint over the codegen version, the resolved library
+ * set, and the contents of every loaded GIR file. A change to any of these
+ * means the generated bindings are stale and must be regenerated.
+ *
+ * @param girFiles - Absolute paths of the loaded `.gir` files
+ * @param libraries - The resolved `Name-Version` library identifiers
+ */
+export const computeFingerprint = (girFiles: readonly string[], libraries: readonly string[]): string => {
+    const hash = createHash("sha256");
+    hash.update(CODEGEN_VERSION);
+    hash.update("\n");
+    hash.update([...libraries].sort((a, b) => a.localeCompare(b)).join(","));
+    for (const file of [...girFiles].sort((a, b) => a.localeCompare(b))) {
+        hash.update("\n");
+        hash.update(file);
+        hash.update("\0");
+        hash.update(readFileSync(file));
+    }
+    return hash.digest("hex");
+};