@gtkx/codegen 1.0.0-rc.1 → 1.0.0-rc.2

package/src/fingerprint.ts

@@ -1,61 +1,159 @@
+import { sortStrings } from "@gtkx/utils";
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { type Dirent, existsSync, readdirSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { join } from "node:path";
-import type { ElementProp } from "@gtkx/config";
-import { sortStrings } from "@gtkx/utils";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
-const require = createRequire(import.meta.url);
+/** The freshness sentinel of the `@gtkx/gi` store, derived purely from the GIR inputs. */
+type GiFingerprint = {
+    value: string;
+    girFiles: string[];
+    libraries: string[];
+    girPath?: string[];
+};
 
-export const FINGERPRINT_FILENAME = ".codegen-fingerprint.json";
+type ModuleExport = { module: string; export: string };
 
-const CODEGEN_VERSION: string = (require("../package.json") as { version: string }).version;
+/** The `@gtkx/react` element config that shapes the generated `@gtkx/jsx` store. */
+type JsxFingerprintInput = {
+    reactVersion: string;
+    components: Record<string, ModuleExport>;
+    lazyElements: string[];
+    props: Record<string, ModuleExport>;
+};
 
-export type CodegenFingerprint = {
+/** The freshness sentinel of the `@gtkx/jsx` store, derived from the React element config. */
+type JsxFingerprint = {
     value: string;
-    girFiles: string[];
-    libraries: string[];
+    intrinsicElementCount: number;
+};
+
+const require = createRequire(import.meta.url);
+const FINGERPRINT_FILENAME = ".codegen-fingerprint.json";
+const CODEGEN_VERSION: string = (require("../package.json") as { version: string }).version;
+const OVERRIDES_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "overrides");
+
+const sortAlpha = (values: string[]): string => sortStrings(values).join(",");
+
+// The overrides are copied verbatim into the store, so editing one changes the output even though no
+// GIR file moved. Without them in the hash a stale override survives every non-forced run.
+const overrideFiles = (): string[] => {
+    if (!existsSync(OVERRIDES_ROOT)) {
+        return [];
+    }
+
+    return readdirSync(OVERRIDES_ROOT, { recursive: true, withFileTypes: true })
+        .filter((entry: Dirent) => entry.isFile())
+        .map((entry: Dirent) => join(entry.parentPath, entry.name));
 };
 
-export const computeFingerprint = (
-    girFiles: string[],
-    libraries: string[],
-    elementProps: Record<string, ElementProp[]>,
-): string => {
+const hashGi = (girFiles: string[], libraries: string[], girPath: string[]): string => {
     const hash = createHash("sha256");
     hash.update(CODEGEN_VERSION);
     hash.update("\n");
-    hash.update(JSON.stringify(elementProps));
+    hash.update(sortAlpha(libraries));
     hash.update("\n");
-    hash.update(sortStrings(libraries).join(","));
-    for (const file of sortStrings(girFiles)) {
+    hash.update(sortAlpha(girPath));
+    const hashedFiles = sortStrings([...girFiles, ...overrideFiles()]);
+
+    for (const file of hashedFiles) {
         hash.update("\n");
         hash.update(file);
         hash.update("\0");
         hash.update(readFileSync(file));
     }
+
     return hash.digest("hex");
 };
 
-const sortAlpha = (values: string[]): string => sortStrings(values).join(",");
+const computeGiFingerprint = (girFiles: string[], libraries: string[], girPath: string[]): GiFingerprint => ({
+    value: hashGi(girFiles, libraries, girPath),
+    girFiles,
+    libraries,
+    girPath,
+});
 
-export const isStoreFresh = (
-    giStoreDir: string,
-    libraries: string[],
-    elementProps: Record<string, ElementProp[]>,
-): boolean => {
+const isGiStoreFresh = (giStoreDir: string, libraries: string[], girPath: string[]): boolean => {
     const sentinelPath = join(giStoreDir, FINGERPRINT_FILENAME);
-    if (!existsSync(sentinelPath)) return false;
-    let sentinel: CodegenFingerprint;
+
+    if (!existsSync(sentinelPath)) {
+        return false;
+    }
+
+    let sentinel: GiFingerprint;
+
     try {
-        sentinel = JSON.parse(readFileSync(sentinelPath, "utf8")) as CodegenFingerprint;
+        sentinel = JSON.parse(readFileSync(sentinelPath, "utf8")) as GiFingerprint;
     } catch {
         return false;
     }
-    if (sortAlpha(sentinel.libraries) !== sortAlpha(libraries)) return false;
+
+    if (!hasMatchingRecordedInputs(sentinel, libraries, girPath)) {
+        return false;
+    }
+
     try {
-        return computeFingerprint(sentinel.girFiles, sentinel.libraries, elementProps) === sentinel.value;
+        return hashGi(sentinel.girFiles, sentinel.libraries, girPath) === sentinel.value;
     } catch {
         return false;
     }
 };
+
+const hasMatchingRecordedInputs = (sentinel: GiFingerprint, libraries: string[], girPath: string[]): boolean =>
+    sortAlpha(sentinel.libraries) === sortAlpha(libraries) && sortAlpha(sentinel.girPath ?? []) === sortAlpha(girPath);
+
+const serializeModuleExports = (map: Record<string, ModuleExport>): [string, string, string][] =>
+    sortStrings(Object.keys(map)).map((type) => [type, map[type]?.module ?? "", map[type]?.export ?? ""]);
+
+const hashJsx = (input: JsxFingerprintInput): string =>
+    createHash("sha256")
+        .update(
+            JSON.stringify([
+                CODEGEN_VERSION,
+                input.reactVersion,
+                serializeModuleExports(input.components),
+                sortStrings(input.lazyElements),
+                serializeModuleExports(input.props),
+            ]),
+        )
+        .digest("hex");
+
+const computeJsxFingerprint = (input: JsxFingerprintInput, intrinsicElementCount: number): JsxFingerprint => ({
+    value: hashJsx(input),
+    intrinsicElementCount,
+});
+
+const jsxStoreFreshness = (
+    jsxStoreDir: string,
+    input: JsxFingerprintInput,
+): { fresh: boolean; intrinsicElementCount: number } => {
+    const sentinelPath = join(jsxStoreDir, FINGERPRINT_FILENAME);
+
+    if (!existsSync(sentinelPath)) {
+        return { fresh: false, intrinsicElementCount: 0 };
+    }
+
+    let sentinel: JsxFingerprint;
+
+    try {
+        sentinel = JSON.parse(readFileSync(sentinelPath, "utf8")) as JsxFingerprint;
+    } catch {
+        return { fresh: false, intrinsicElementCount: 0 };
+    }
+
+    return sentinel.value === hashJsx(input)
+        ? { fresh: true, intrinsicElementCount: sentinel.intrinsicElementCount }
+        : { fresh: false, intrinsicElementCount: 0 };
+};
+
+export {
+    FINGERPRINT_FILENAME,
+    computeGiFingerprint,
+    isGiStoreFresh,
+    computeJsxFingerprint,
+    jsxStoreFreshness,
+    type GiFingerprint,
+    type JsxFingerprintInput,
+    type JsxFingerprint,
+};

package/src/gi.ts

@@ -0,0 +1,26 @@
+import type { Library } from "./gir/library.js";
+import { computeGiFingerprint } from "./fingerprint.js";
+import { namespaceDirectory } from "./gir/namespace.js";
+import { type GiNamespaceInput, type GiStoreOptions, writeGiStore } from "./store/gi-store.js";
+import { generateNamespaceModule } from "./store/gi/pipeline.js";
+
+/**
+ * Generates the `@gtkx/gi` store from the loaded GIR library and links it into the project. This is the
+ * react-free half of codegen: it can run before `@gtkx/gi` (or `@gtkx/react`) exists, since it produces them.
+ *
+ * @returns The number of namespaces written.
+ */
+const runGiCodegen = (library: Library, gi: GiStoreOptions, libraries: string[], girPath: string[]): number => {
+    const namespaces: GiNamespaceInput[] = Array.from(library.namespaces.values(), (namespace) => ({
+        directory: namespaceDirectory(namespace),
+        rawSource: generateNamespaceModule(namespace, library),
+    }));
+
+    writeGiStore(gi, namespaces, computeGiFingerprint(library.girFiles, [...libraries], [...girPath]));
+
+    return library.namespaces.size;
+};
+
+export { isGiStoreFresh } from "./fingerprint.js";
+export type { GiStoreOptions } from "./store/gi-store.js";
+export { runGiCodegen };

package/src/gir/ancestry.ts

@@ -1,41 +1,53 @@
 import type { GirClass } from "./class.js";
 import type { Library } from "./library.js";
+import type { GirType } from "./type.js";
 
-export type ResolvedAncestor = {
+type ResolvedAncestor = {
     klass: GirClass;
     namespaceName: string;
 };
 
+const getAncestor = (resolved: GirType | undefined): ResolvedAncestor | undefined =>
+    resolved !== undefined && (resolved.kind === "class" || resolved.kind === "interface")
+        ? { klass: resolved.value, namespaceName: resolved.namespace.name }
+        : undefined;
+
 const resolveClassOrInterface = (
     library: Library,
     defaultNamespace: string,
     name: string,
-): ResolvedAncestor | undefined => {
-    const resolved = library.resolveType(defaultNamespace, name);
-    if (resolved === undefined) return undefined;
-    if (resolved.kind !== "class" && resolved.kind !== "interface") return undefined;
-    return { klass: resolved.value, namespaceName: resolved.namespace.name };
-};
+): ResolvedAncestor | undefined => getAncestor(library.resolveType(defaultNamespace, name));
 
-export const resolveInterface = (
+const resolveInterface = (
     library: Library,
     defaultNamespace: string,
     name: string,
 ): ResolvedAncestor | undefined => {
     const resolved = library.resolveType(defaultNamespace, name);
-    if (resolved?.kind !== "interface") return undefined;
-    return { klass: resolved.value, namespaceName: resolved.namespace.name };
+
+    return resolved?.kind === "interface" ? getAncestor(resolved) : undefined;
 };
 
-export function* ancestorChain(library: Library, klass: GirClass, namespaceName: string): Generator<ResolvedAncestor> {
-    const visited = new Set<string>();
+function* ancestorChain(library: Library, klass: GirClass, namespaceName: string): Generator<ResolvedAncestor> {
+    const visited: Set<string> = new Set();
     let current: ResolvedAncestor | undefined = { klass, namespaceName };
+
     while (current !== undefined) {
         const key = `${current.namespaceName}.${current.klass.name}`;
-        if (visited.has(key)) return;
+
+        if (visited.has(key)) {
+            return;
+        }
+
         visited.add(key);
         yield current;
-        if (current.klass.parent === undefined) return;
+
+        if (current.klass.parent === undefined) {
+            return;
+        }
+
         current = resolveClassOrInterface(library, current.namespaceName, current.klass.parent);
     }
 }
+
+export { resolveInterface, ancestorChain, type ResolvedAncestor };

package/src/gir/callback.ts

@@ -1,29 +1,24 @@
 import type { GirFunction } from "./function.js";
-import { type GirParameter, type GirReturnValue, parseCallable } from "./parameter.js";
-import { attrBool, type RawNode } from "./parse.js";
+import type { RawNode } from "./parse.js";
 import type { ParseContext } from "./type-id.js";
+import { type GirCallable, parseCallable } from "./parameter.js";
 
-export type GirCallback = {
-    name: string;
-    doc: string | undefined;
-    parameters: GirParameter[];
-    returnValue: GirReturnValue;
-    introspectable: boolean;
-};
+type GirCallback = GirCallable;
 
-export const callbackFromNode = (node: RawNode, context: ParseContext): GirCallback => ({
-    ...parseCallable(node, context),
-    introspectable: attrBool(node, "introspectable", true),
-});
+const callbackFromNode = (node: RawNode, context: ParseContext): GirCallback => parseCallable(node, context);
 
-export const callbackAsFunction = (callback: GirCallback): GirFunction => ({
+const callbackAsFunction = (callback: GirCallback): GirFunction => ({
     name: callback.name,
     doc: callback.doc,
     cIdentifier: undefined,
-    throws: false,
+    movedTo: undefined,
+    throws: callback.throws,
     introspectable: callback.introspectable,
     shadowedBy: undefined,
+    finishFunc: undefined,
     instance: undefined,
     parameters: callback.parameters,
     returnValue: callback.returnValue,
 });
+
+export { callbackFromNode, callbackAsFunction, type GirCallback };

package/src/gir/class.ts

@@ -1,10 +1,10 @@
+import type { ParseContext } from "./type-id.js";
 import { functionFromNode, type GirFunction } from "./function.js";
-import { type GirSignal, parseCallable } from "./parameter.js";
-import { attr, attrBool, childrenOf, docOf, GIR_CONSTRUCTOR_TAG, nameAttr, type RawNode } from "./parse.js";
+import { type GirCallable, parseCallable } from "./parameter.js";
+import { attr, getChildren, getDoc, GIR_CONSTRUCTOR_TAG, isAttrTrue, nameAttr, type RawNode } from "./parse.js";
 import { type GirProperty, propertyFromNode } from "./property.js";
-import type { ParseContext } from "./type-id.js";
 
-export type GirClass = {
+type GirClass = {
     name: string;
     doc: string | undefined;
     cType: string | undefined;
@@ -15,6 +15,7 @@ export type GirClass = {
     glibRefFunc: string | undefined;
     glibUnrefFunc: string | undefined;
     fundamental: boolean;
+    isAbstract: boolean;
     isInterface: boolean;
     introspectable: boolean;
     implements: string[];
@@ -23,12 +24,12 @@ export type GirClass = {
     constructors: GirFunction[];
     functions: GirFunction[];
     properties: GirProperty[];
-    signals: GirSignal[];
+    signals: GirCallable[];
 };
 
-export const classFromNode = (node: RawNode, isInterface: boolean, context: ParseContext): GirClass => ({
+const classFromNode = (node: RawNode, isInterface: boolean, context: ParseContext): GirClass => ({
     name: nameAttr(node),
-    doc: docOf(node),
+    doc: getDoc(node),
     cType: attr(node, "c:type"),
     parent: attr(node, "parent"),
     glibTypeName: attr(node, "glib:type-name"),
@@ -36,18 +37,21 @@ export const classFromNode = (node: RawNode, isInterface: boolean, context: Pars
     glibTypeStruct: attr(node, "glib:type-struct"),
     glibRefFunc: attr(node, "glib:ref-func"),
     glibUnrefFunc: attr(node, "glib:unref-func"),
-    fundamental: attrBool(node, "glib:fundamental"),
+    fundamental: isAttrTrue(node, "glib:fundamental"),
+    isAbstract: isAttrTrue(node, "abstract"),
     isInterface,
-    introspectable: attrBool(node, "introspectable", true),
-    implements: childrenOf(node, "implements")
+    introspectable: isAttrTrue(node, "introspectable", true),
+    implements: getChildren(node, "implements")
         .map((implement) => attr(implement, "name"))
         .filter((name): name is string => name !== undefined),
-    prerequisites: childrenOf(node, "prerequisite")
+    prerequisites: getChildren(node, "prerequisite")
         .map((prerequisite) => attr(prerequisite, "name"))
         .filter((name): name is string => name !== undefined),
-    methods: childrenOf(node, "method").map((method) => functionFromNode(method, context)),
-    constructors: childrenOf(node, GIR_CONSTRUCTOR_TAG).map((ctor) => functionFromNode(ctor, context)),
-    functions: childrenOf(node, "function").map((function_) => functionFromNode(function_, context)),
-    properties: childrenOf(node, "property").map((property) => propertyFromNode(property, context)),
-    signals: childrenOf(node, "glib:signal").map((signal) => parseCallable(signal, context)),
+    methods: getChildren(node, "method").map((method) => functionFromNode(method, context)),
+    constructors: getChildren(node, GIR_CONSTRUCTOR_TAG).map((ctor) => functionFromNode(ctor, context)),
+    functions: getChildren(node, "function").map((fn) => functionFromNode(fn, context)),
+    properties: getChildren(node, "property").map((property) => propertyFromNode(property, context)),
+    signals: getChildren(node, "glib:signal").map((signal) => parseCallable(signal, context)),
 });
+
+export { classFromNode, type GirClass };

package/src/gir/enum.ts

@@ -1,4 +1,4 @@
-import { attr, attrBool, childrenOf, docOf, nameAttr, type RawNode } from "./parse.js";
+import { attr, getChildren, getDoc, isAttrTrue, nameAttr, type RawNode } from "./parse.js";
 
 type EnumMember = {
     name: string;
@@ -9,7 +9,7 @@ type EnumMember = {
 
 type EnumKind = "enumeration" | "bitfield";
 
-export type GirEnum = {
+type GirEnum = {
     kind: EnumKind;
     name: string;
     doc: string | undefined;
@@ -20,18 +20,20 @@ export type GirEnum = {
     members: EnumMember[];
 };
 
-export const enumFromNode = (node: RawNode, kind: EnumKind): GirEnum => ({
+const enumFromNode = (node: RawNode, kind: EnumKind): GirEnum => ({
     kind,
     name: nameAttr(node),
-    doc: docOf(node),
+    doc: getDoc(node),
     glibTypeName: attr(node, "glib:type-name"),
     glibGetType: attr(node, "glib:get-type"),
     errorDomain: attr(node, "glib:error-domain"),
-    introspectable: attrBool(node, "introspectable", true),
-    members: childrenOf(node, "member").map((member) => ({
+    introspectable: isAttrTrue(node, "introspectable", true),
+    members: getChildren(node, "member").map((member) => ({
         name: nameAttr(member),
-        doc: docOf(member),
+        doc: getDoc(member),
         value: attr(member, "value") ?? "0",
         cIdentifier: attr(member, "c:identifier"),
     })),
 });
+
+export { enumFromNode, type GirEnum };

package/src/gir/field.ts

@@ -1,8 +1,8 @@
-import { attr, attrBool, childOf, docOf, intAttr, nameAttr, type RawNode } from "./parse.js";
 import type { ParseContext, TypeId } from "./type-id.js";
+import { attr, getChild, getChildren, getDoc, intAttr, isAttrTrue, nameAttr, type RawNode } from "./parse.js";
 import { typeRefFromNode } from "./type-ref.js";
 
-export type GirField = {
+type GirField = {
     name: string;
     doc: string | undefined;
     type: TypeId | undefined;
@@ -11,15 +11,44 @@ export type GirField = {
     writable: boolean;
     private: boolean;
     bits: number | undefined;
+    /** Members of an anonymous nested `<union>`/`<record>`, which occupies a slot but has no type. */
+    inlineMembers: GirField[] | undefined;
+    inlineIsUnion: boolean;
 };
 
-export const fieldFromNode = (node: RawNode, context: ParseContext): GirField => ({
+const fieldFromNode = (node: RawNode, context: ParseContext): GirField => ({
     name: nameAttr(node),
-    doc: docOf(node),
+    doc: getDoc(node),
     type: typeRefFromNode(node, context),
-    cType: attr(childOf(node, "type"), "c:type"),
-    readable: attrBool(node, "readable", true),
-    writable: attrBool(node, "writable", false),
-    private: attrBool(node, "private", false),
+    cType: attr(getChild(node, "type"), "c:type"),
+    readable: isAttrTrue(node, "readable", true),
+    writable: isAttrTrue(node, "writable", false),
+    private: isAttrTrue(node, "private", false),
     bits: intAttr(node, "bits"),
+    inlineMembers: undefined,
+    inlineIsUnion: false,
 });
+
+// A record may embed an anonymous `<union>` or `<record>` instead of naming a type for it. The
+// member occupies a real slot and contributes its own size and alignment, but carries no `<type>`,
+// so it has to be admitted as a field whose layout comes from its own children.
+const anonymousMemberFromNode = (node: RawNode, isUnion: boolean, context: ParseContext): GirField => ({
+    name: nameAttr(node),
+    doc: getDoc(node),
+    type: undefined,
+    cType: undefined,
+    readable: false,
+    writable: false,
+    private: true,
+    bits: undefined,
+    inlineMembers: collectFields(node, context),
+    inlineIsUnion: isUnion,
+});
+
+const collectFields = (node: RawNode, context: ParseContext): GirField[] => [
+    ...getChildren(node, "field").map((field) => fieldFromNode(field, context)),
+    ...getChildren(node, "union").map((member) => anonymousMemberFromNode(member, true, context)),
+    ...getChildren(node, "record").map((member) => anonymousMemberFromNode(member, false, context)),
+];
+
+export { collectFields, fieldFromNode, type GirField };

package/src/gir/function.ts

@@ -1,28 +1,52 @@
-import { type GirParameter, type GirReturnValue, parameterFromNode, parseCallable } from "./parameter.js";
-import { attr, attrBool, childOf, 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";
 
-export type GirFunction = {
+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;
 };
 
-export const functionFromNode = (node: RawNode, context: ParseContext): GirFunction => {
-    const instanceNode = childOf(childOf(node, "parameters"), "instance-parameter");
-    return {
+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);
+    }
+
+    return fn;
+};
+
+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: attrBool(node, "introspectable", true),
+        movedTo: attr(node, "moved-to"),
         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

@@ -1,10 +1,10 @@
+import { formatChildProcessError, resolveExecutable } from "@gtkx/utils";
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { formatChildProcessError } from "@gtkx/utils";
 
 const SYSTEM_GIR_PATH = "/usr/share/gir-1.0";
 
-export const resolveGirPath = (configGirPath: string[] | undefined): string[] => {
+const resolveGirPath = (configGirPath: string[] | undefined): string[] => {
     const paths: string[] = [];
 
     if (configGirPath) {
@@ -12,6 +12,7 @@ export const resolveGirPath = (configGirPath: string[] | undefined): string[] =>
     }
 
     const envPath = process.env.GTKX_GIR_PATH;
+
     if (envPath) {
         paths.push(...envPath.split(":").filter((path) => path.length > 0));
     }
@@ -21,6 +22,7 @@ export const resolveGirPath = (configGirPath: string[] | undefined): string[] =>
     }
 
     const pkgConfigPath = queryPkgConfigGirDir();
+
     if (pkgConfigPath !== undefined && existsSync(pkgConfigPath)) {
         paths.push(pkgConfigPath);
     }
@@ -28,22 +30,44 @@ export const resolveGirPath = (configGirPath: string[] | undefined): string[] =>
     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("pkg-config", ["--variable=girdir", "gobject-introspection-1.0"], {
-            encoding: "utf-8",
+        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 undefined;
-        const details = formatChildProcessError(error);
-        throw new Error(
-            `pkg-config failed querying gobject-introspection-1.0 girdir${details ? `:\n${details}` : ""}`,
-            {
-                cause: error,
-            },
-        );
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+            return;
+        }
+
+        throw pkgConfigGirDirError(error);
     }
 };
+
+export { resolveGirPath };