@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/gir/function.ts

@@ -1,67 +1,52 @@
-import { type GirParameter, type GirReturnValue, parameterFromNode, returnValueFromNode } from "./parameter.js";
-import { attr, attrBool, childOf, childrenOf, type RawNode } from "./parse.js";
+import type { ParseContext } from "./type-id.js";
+import { PARAMETERS_MISSING_NULLABLE_ANNOTATION } from "./nullable-overrides.js";
+import { type GirParameter, type GirReturnValue, parameterFromNode, parseCallable } from "./parameter.js";
+import { attr, getChild, type RawNode } from "./parse.js";
 
-/**
- * Whether this callable is a free function, a static method on a type, an
- * instance method, a constructor, or a virtual method.
- *
- * The kind controls call-site shape in the writers: instance methods pass
- * `self` as the first FFI argument, constructors return a fresh native
- * handle, etc.
- */
-export type FunctionKind = "function" | "method" | "constructor" | "virtual-method";
+type GirFunction = {
+    name: string;
+    doc: string | undefined;
+    cIdentifier: string | undefined;
+    throws: boolean;
+    introspectable: boolean;
+    movedTo: string | undefined;
+    shadowedBy: string | undefined;
+    finishFunc: string | undefined;
+    instance: GirParameter | undefined;
+    parameters: GirParameter[];
+    returnValue: GirReturnValue;
+};
+
+const relaxParameters = (parameters: GirParameter[], names: string[]): void => {
+    for (const parameter of parameters) {
+        if (names.includes(parameter.name)) {
+            parameter.nullable = true;
+        }
+    }
+};
+
+const relaxMissingNullable = (fn: GirFunction): GirFunction => {
+    const names = fn.cIdentifier === undefined ? undefined : PARAMETERS_MISSING_NULLABLE_ANNOTATION.get(fn.cIdentifier);
+
+    if (names !== undefined) {
+        relaxParameters(fn.parameters, names);
+    }
 
-/**
- * A callable declaration: `<function>`, `<method>`, `<constructor>`, or
- * `<virtual-method>`.
- */
-export type GirFunction = {
-    readonly kind: FunctionKind;
-    /** GIR `name`, snake_case (e.g. `"set_label"`). */
-    readonly name: string;
-    /** C symbol identifier passed to `t.fn(library, symbol, …)`. */
-    readonly cIdentifier: string | undefined;
-    /** `throws="1"` — appends an implicit `GError**` out-parameter. */
-    readonly throws: boolean;
-    /** `introspectable="0"` — the function is skipped in JS output. */
-    readonly introspectable: boolean;
-    /** Indicates the function is the preferred binding for the named method. */
-    readonly shadows: string | undefined;
-    /** Indicates a different function is the preferred binding (the shadower). */
-    readonly shadowedBy: string | undefined;
-    /** Marker that re-homes a namespace function onto a type method. */
-    readonly movedTo: string | undefined;
-    /** The instance parameter for methods; `undefined` otherwise. */
-    readonly instance: GirParameter | undefined;
-    /** Regular parameters (no instance and no implicit GError). */
-    readonly parameters: readonly GirParameter[];
-    readonly returnValue: GirReturnValue;
-    /** Linked invoker method when this is a `<virtual-method>`. */
-    readonly invoker: string | undefined;
+    return fn;
 };
 
-/**
- * Builds a {@link GirFunction} from a callable element.
- *
- * @param node - The XML element
- * @param kind - The callable kind matching the element name
- */
-export const functionFromNode = (node: RawNode, kind: FunctionKind): GirFunction => {
-    const parametersNode = childOf(node, "parameters");
-    const instanceNode = childOf(parametersNode, "instance-parameter");
-    const parameterNodes = childrenOf(parametersNode, "parameter");
-    return {
-        kind,
+const functionFromNode = (node: RawNode, context: ParseContext): GirFunction => {
+    const instanceNode = getChild(getChild(node, "parameters"), "instance-parameter");
+
+    return relaxMissingNullable({
+        ...parseCallable(node, context),
         name: attr(node, "shadows") ?? attr(node, "name") ?? "",
         cIdentifier: attr(node, "c:identifier"),
-        throws: attrBool(node, "throws"),
-        introspectable: attr(node, "introspectable") !== "0",
-        shadows: attr(node, "shadows"),
-        shadowedBy: attr(node, "shadowed-by"),
         movedTo: attr(node, "moved-to"),
-        instance: instanceNode === undefined ? undefined : parameterFromNode(instanceNode, true),
-        parameters: parameterNodes.map((parameter) => parameterFromNode(parameter, false)),
-        returnValue: returnValueFromNode(childOf(node, "return-value")),
-        invoker: attr(node, "invoker"),
-    };
+        shadowedBy: attr(node, "shadowed-by"),
+        finishFunc: attr(node, "glib:finish-func"),
+        instance: instanceNode === undefined ? undefined : parameterFromNode(instanceNode, context),
+    });
 };
+
+export { functionFromNode, type GirFunction };

package/src/gir/gir-path.ts

@@ -0,0 +1,73 @@
+import { formatChildProcessError, resolveExecutable } from "@gtkx/utils";
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+const SYSTEM_GIR_PATH = "/usr/share/gir-1.0";
+
+const resolveGirPath = (configGirPath: string[] | undefined): string[] => {
+    const paths: string[] = [];
+
+    if (configGirPath) {
+        paths.push(...configGirPath);
+    }
+
+    const envPath = process.env.GTKX_GIR_PATH;
+
+    if (envPath) {
+        paths.push(...envPath.split(":").filter((path) => path.length > 0));
+    }
+
+    if (existsSync(SYSTEM_GIR_PATH)) {
+        paths.push(SYSTEM_GIR_PATH);
+    }
+
+    const pkgConfigPath = queryPkgConfigGirDir();
+
+    if (pkgConfigPath !== undefined && existsSync(pkgConfigPath)) {
+        paths.push(pkgConfigPath);
+    }
+
+    return [...new Set(paths)];
+};
+
+const pkgConfigGirDirError = (error: unknown): Error => {
+    const details = formatChildProcessError(error);
+    const suffix = details ? `:\n${details}` : "";
+
+    return new Error(`pkg-config failed querying gobject-introspection-1.0 girdir${suffix}`, { cause: error });
+};
+
+const resolvePkgConfig = (): string | undefined => {
+    try {
+        return resolveExecutable("pkg-config");
+    } catch {
+        return undefined;
+    }
+};
+
+const queryPkgConfigGirDir = (): string | undefined => {
+    const pkgConfig = resolvePkgConfig();
+
+    if (pkgConfig === undefined) {
+        return undefined;
+    }
+
+    try {
+        const output = execFileSync(pkgConfig, ["--variable=girdir", "gobject-introspection-1.0"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+
+        const trimmed = output.trim();
+
+        return trimmed.length > 0 ? trimmed : undefined;
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+            return;
+        }
+
+        throw pkgConfigGirDirError(error);
+    }
+};
+
+export { resolveGirPath };

package/src/gir/libraries.ts

@@ -0,0 +1,102 @@
+import type { Config } from "@gtkx/config";
+import { GIR_LIBRARY_PATTERN, LIBRARIES_WILDCARD } from "@gtkx/config/internal";
+import { sortStrings } from "@gtkx/utils";
+import { readdirSync } from "node:fs";
+
+type GirNamespace = { name: string; version: string; identifier: string };
+
+const DEFAULT_LIBRARIES: string[] = ["Gtk-4.0"];
+const GIR_FILE_SUFFIX = ".gir";
+
+const resolveLibraries = (libraries: Config["libraries"], girPath: string[]): string[] => {
+    if (libraries === undefined) {
+        return [...DEFAULT_LIBRARIES];
+    }
+
+    if (libraries === LIBRARIES_WILDCARD) {
+        const discovered = discoverGirNamespaces(girPath);
+
+        if (discovered.length === 0) {
+            throw new Error(
+                `gtkx.config.ts: \`libraries: "*"\` matched no .gir files in [${girPath.join(", ")}]. ` +
+                "Install gobject-introspection data packages, or list the libraries explicitly.",
+            );
+        }
+
+        return discovered;
+    }
+
+    const hasGtk = libraries.some((library) => library.startsWith("Gtk-"));
+
+    return [...new Set([...(hasGtk ? [] : DEFAULT_LIBRARIES), ...libraries])];
+};
+
+const readDirEntries = (dir: string): string[] => {
+    try {
+        return readdirSync(dir);
+    } catch {
+        return [];
+    }
+};
+
+const parseGirNamespace = (entry: string): GirNamespace | undefined => {
+    if (!entry.endsWith(GIR_FILE_SUFFIX)) {
+        return undefined;
+    }
+
+    const identifier = entry.slice(0, -GIR_FILE_SUFFIX.length);
+
+    if (!GIR_LIBRARY_PATTERN.test(identifier)) {
+        return undefined;
+    }
+
+    const separator = identifier.indexOf("-");
+
+    return { name: identifier.slice(0, separator), version: identifier.slice(separator + 1), identifier };
+};
+
+const recordHighest = (highestByName: Map<string, GirNamespace>, parsed: GirNamespace): void => {
+    const existing = highestByName.get(parsed.name);
+
+    if (existing === undefined || compareVersions(parsed.version, existing.version) > 0) {
+        highestByName.set(parsed.name, parsed);
+    }
+};
+
+const collectDirNamespaces = (highestByName: Map<string, GirNamespace>, dir: string): void => {
+    for (const entry of readDirEntries(dir)) {
+        const parsed = parseGirNamespace(entry);
+
+        if (parsed !== undefined) {
+            recordHighest(highestByName, parsed);
+        }
+    }
+};
+
+const discoverGirNamespaces = (girPath: string[]): string[] => {
+    const highestByName: Map<string, GirNamespace> = new Map();
+
+    for (const dir of girPath) {
+        collectDirNamespaces(highestByName, dir);
+    }
+
+    return sortStrings(highestByName.values().map(({ identifier }) => identifier));
+};
+
+const compareVersions = (a: string, b: string): number => {
+    const aParts = a.split(".");
+    const bParts = b.split(".");
+    const length = Math.max(aParts.length, bParts.length);
+
+    for (let index = 0; index < length; index += 1) {
+        const difference = Number(aParts[index] ?? 0) - Number(bParts[index] ?? 0);
+
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+
+    return 0;
+};
+
+export { resolveLibraries, discoverGirNamespaces };

package/src/gir/library.ts

@@ -0,0 +1,351 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { PrimitiveCategory } from "./primitives.js";
+import type { CArrayType, HashTableType, ListType, ParseContext, TypeId } from "./type-id.js";
+import type { GirType } from "./type.js";
+import { callbackFromNode } from "./callback.js";
+import {
+    createNamespaceShell,
+    type GirNamespace,
+    type NamespaceHeader,
+    parseNamespaceHeader,
+    populateNamespaceBody,
+} from "./namespace.js";
+import { parseGirFile, type RawNode } from "./parse.js";
+import { splitOptionalNamespace } from "./type-ref.js";
+
+type TypeTable = {
+    types: (GirType | undefined)[];
+    names: (string | undefined)[];
+    index: Map<string, number>;
+};
+
+type DiscoveredNamespace = { header: NamespaceHeader; shell: GirNamespace };
+
+const INTERNAL_NS_ID = 0;
+
+const readRepositoryNode = (path: string): RawNode => {
+    const root = parseGirFile(path);
+    const repository = root.repository;
+
+    if (typeof repository !== "object" || repository === null) {
+        throw new Error(`GIR file at ${path} has no <repository> root`);
+    }
+
+    return repository as RawNode;
+};
+
+const locateGirFile = (identifier: string, girPath: string[]): string => {
+    const filename = `${identifier}.gir`;
+
+    for (const directory of girPath) {
+        const candidate = join(directory, filename);
+
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+
+    const tried = girPath.map((directory) => join(directory, filename)).join(", ");
+    throw new Error(`GIR file ${filename} not found on girPath. Tried: ${tried}`);
+};
+
+class Library {
+    private static drive(library: Library, libraries: string[], girPath: string[]): void {
+        const { discovered, girFiles } = library.discoverNamespaces(libraries, girPath);
+
+        for (const { header, shell } of discovered) {
+            populateNamespaceBody(shell, header.namespaceNode, library.parseContext(shell.id));
+        }
+
+        for (const { shell } of discovered) {
+            library.addDeclarations(shell);
+        }
+
+        library.girFilesValue = girFiles;
+    }
+
+    static load(libraries: string[], girPath: string[]): Library {
+        const library = new Library();
+        this.drive(library, libraries, girPath);
+
+        return library;
+    }
+
+    private namespacesByName: Map<string, GirNamespace> = new Map();
+    private namespaceById: (GirNamespace | undefined)[] = [];
+    private nsNameById: string[] = [];
+    private nsIdByName: Map<string, number> = new Map();
+    private typeTables: TypeTable[] = [];
+    private girFilesValue: string[] = [];
+
+    constructor() {
+        this.typeTables[INTERNAL_NS_ID] = { types: [], names: [], index: new Map() };
+        this.namespaceById[INTERNAL_NS_ID] = undefined;
+        this.nsNameById[INTERNAL_NS_ID] = "$internal";
+    }
+
+    private ensureNsId(name: string): number {
+        const existing = this.nsIdByName.get(name);
+
+        if (existing !== undefined) {
+            return existing;
+        }
+
+        const nsId = this.typeTables.length;
+        this.typeTables[nsId] = { types: [], names: [], index: new Map() };
+        this.namespaceById[nsId] = undefined;
+        this.nsNameById[nsId] = name;
+        this.nsIdByName.set(name, nsId);
+
+        return nsId;
+    }
+
+    private registerNamespace(header: NamespaceHeader): GirNamespace {
+        const nsId = this.ensureNsId(header.name);
+        const shell = createNamespaceShell(header, nsId);
+        this.namespaceById[nsId] = shell;
+        this.namespacesByName.set(header.name, shell);
+
+        return shell;
+    }
+
+    private namespaceFor(nsId: number): GirNamespace {
+        const namespace = this.namespaceById[nsId];
+
+        if (namespace === undefined) {
+            throw new Error(`No namespace registered for type table id ${String(nsId)}`);
+        }
+
+        return namespace;
+    }
+
+    private typeTableFor(nsId: number): TypeTable {
+        const typeTable = this.typeTables[nsId];
+
+        if (typeTable === undefined) {
+            throw new Error(`No type table for namespace id ${String(nsId)}`);
+        }
+
+        return typeTable;
+    }
+
+    private insertIntoTypeTable(
+        typeTable: TypeTable,
+        slot: { type: GirType | undefined; indexKey?: string; displayName?: string },
+    ): number {
+        const id = typeTable.types.length;
+        typeTable.types.push(slot.type);
+        typeTable.names.push(slot.displayName);
+
+        if (slot.indexKey !== undefined) {
+            typeTable.index.set(slot.indexKey, id);
+        }
+
+        return id;
+    }
+
+    private resolveTypeId(nsId: number, name: string, type: GirType | undefined): number {
+        const typeTable = this.typeTableFor(nsId);
+        const existing = typeTable.index.get(name);
+
+        if (existing !== undefined) {
+            return existing;
+        }
+
+        return this.insertIntoTypeTable(typeTable, { type, indexKey: name, displayName: name });
+    }
+
+    private addType(nsId: number, name: string, type: GirType): void {
+        this.typeTableFor(nsId).types[this.resolveTypeId(nsId, name, type)] = type;
+    }
+
+    private findType(nsId: number, name: string): TypeId {
+        return { nsId, id: this.resolveTypeId(nsId, name, undefined) };
+    }
+
+    private addAnonymousType(nsId: number, type: GirType): TypeId {
+        const typeTable = this.typeTableFor(nsId);
+        const id = this.insertIntoTypeTable(typeTable, { type });
+
+        return { nsId, id };
+    }
+
+    private findTypeByName(currentNsId: number, name: string): TypeId {
+        const [namespaceName, localName] = splitOptionalNamespace(name);
+        const targetNsId = namespaceName === undefined ? currentNsId : this.ensureNsId(namespaceName);
+
+        return this.findType(targetNsId, localName);
+    }
+
+    private parseContext(nsId: number): ParseContext {
+        const context: ParseContext = {
+            nsId,
+            findType: (name) => this.findTypeByName(nsId, name),
+            addPrimitive: (category) => this.addPrimitive(category),
+            addVarargs: () => this.addVarargs(),
+            addContainer: (type: CArrayType | ListType | HashTableType) => this.addAnonymousType(nsId, type),
+            addAnonymousCallback: (node) =>
+                this.addAnonymousType(nsId, {
+                    kind: "callback",
+                    namespace: this.namespaceFor(nsId),
+                    value: callbackFromNode(node, context),
+                }),
+        };
+
+        return context;
+    }
+
+    private addPrimitive(category: PrimitiveCategory): TypeId {
+        return this.findOrAddContainer(`primitive:${category}`, { kind: "primitive", category });
+    }
+
+    private addVarargs(): TypeId {
+        return this.findOrAddContainer("varargs", { kind: "varargs" });
+    }
+
+    private findOrAddContainer(key: string, type: GirType): TypeId {
+        const typeTable = this.typeTableFor(INTERNAL_NS_ID);
+        const existing = typeTable.index.get(key);
+
+        if (existing !== undefined) {
+            return { nsId: INTERNAL_NS_ID, id: existing };
+        }
+
+        const id = this.insertIntoTypeTable(typeTable, { type, indexKey: key });
+
+        return { nsId: INTERNAL_NS_ID, id };
+    }
+
+    private addDeclarations(shell: GirNamespace): void {
+        this.addClassDeclarations(shell);
+        this.addValueDeclarations(shell);
+    }
+
+    private addClassDeclarations(shell: GirNamespace): void {
+        const nsId = shell.id;
+
+        for (const value of shell.classes) {
+            this.addType(nsId, value.name, { kind: "class", namespace: shell, value });
+        }
+
+        for (const value of shell.interfaces) {
+            this.addType(nsId, value.name, { kind: "interface", namespace: shell, value });
+        }
+
+        for (const value of shell.records) {
+            this.addType(nsId, value.name, { kind: "record", namespace: shell, value });
+        }
+    }
+
+    private addValueDeclarations(shell: GirNamespace): void {
+        const nsId = shell.id;
+
+        for (const value of shell.enums) {
+            this.addType(nsId, value.name, { kind: "enum", namespace: shell, value });
+        }
+
+        for (const value of shell.callbacks) {
+            this.addType(nsId, value.name, { kind: "callback", namespace: shell, value });
+        }
+
+        for (const alias of shell.aliases) {
+            this.addType(nsId, alias.name, { kind: "alias", namespace: shell, value: alias });
+        }
+    }
+
+    private processIdentifier(input: {
+        identifier: string;
+        girPath: string[];
+        seen: Set<string>;
+        queue: string[];
+        girFiles: string[];
+        discovered: DiscoveredNamespace[];
+    }): void {
+        const { identifier, girPath, seen, queue, girFiles, discovered } = input;
+        const namespaceName = identifier.split("-", 1)[0] ?? identifier;
+
+        if (seen.has(namespaceName)) {
+            return;
+        }
+
+        seen.add(namespaceName);
+        const path = locateGirFile(identifier, girPath);
+        girFiles.push(path);
+        const header = parseNamespaceHeader(readRepositoryNode(path));
+        const shell = this.registerNamespace(header);
+        discovered.push({ header, shell });
+
+        for (const include of header.includes) {
+            queue.push(`${include.name}-${include.version}`);
+        }
+    }
+
+    private discoverNamespaces(
+        libraries: string[],
+        girPath: string[],
+    ): { discovered: DiscoveredNamespace[]; girFiles: string[] } {
+        const queue: string[] = [...libraries];
+        const seen: Set<string> = new Set();
+        const discovered: DiscoveredNamespace[] = [];
+        const girFiles: string[] = [];
+
+        while (queue.length > 0) {
+            const identifier = queue.shift();
+
+            if (identifier !== undefined) {
+                this.processIdentifier({ identifier, girPath, seen, queue, girFiles, discovered });
+            }
+        }
+
+        return { discovered, girFiles };
+    }
+
+    public get namespaces(): Map<string, GirNamespace> {
+        return this.namespacesByName;
+    }
+
+    public get girFiles(): string[] {
+        return this.girFilesValue;
+    }
+
+    typeFor(tid: TypeId): GirType | undefined {
+        return this.typeTables[tid.nsId]?.types[tid.id];
+    }
+
+    nameFor(tid: TypeId): { namespaceName: string; typeName: string } | undefined {
+        const typeName = this.typeTables[tid.nsId]?.names[tid.id];
+        const namespaceName = this.nsNameById[tid.nsId];
+
+        if (typeName === undefined || namespaceName === undefined) {
+            return undefined;
+        }
+
+        return { namespaceName, typeName };
+    }
+
+    resolveType(currentNamespaceName: string, name: string): GirType | undefined {
+        const currentNsId = this.nsIdByName.get(currentNamespaceName);
+
+        if (currentNsId === undefined) {
+            return undefined;
+        }
+
+        const [namespaceName, localName] = splitOptionalNamespace(name);
+        const targetNsId = namespaceName === undefined ? currentNsId : this.nsIdByName.get(namespaceName);
+
+        if (targetNsId === undefined) {
+            return undefined;
+        }
+
+        const id = this.typeTableFor(targetNsId).index.get(localName);
+
+        if (id === undefined) {
+            return undefined;
+        }
+
+        return this.typeTableFor(targetNsId).types[id];
+    }
+}
+
+export { Library };