@gjsify/node-gi 0.41.0 → 0.42.0

package/gtk-runtime.js

@@ -399,14 +399,22 @@ export function maybeWireGtkWindowingEnv() {
     setIfUnset('GSETTINGS_SCHEMA_DIR', schemaDir);
 
     // MODULE_FILE is the load-bearing one on BOTH platforms — it is the cache, and the
-    // cache is what names the modules. MODULEDIR only resolves a RELATIVE module path in
-    // that cache, and only where gdk-pixbuf was built relocatable: measured on macOS with
-    // Homebrew's gdk-pixbuf 2.44.7, the string `GDK_PIXBUF_MODULEDIR` is not in the dylib
-    // at all, so the darwin bundle's cache instead names each module `@loader_path/…`
-    // (relative to the image that dlopens it, i.e. the bundle's lib/) and resolves with no
-    // env beyond this file. gvsbuild's win32 build IS relocatable, so MODULEDIR is what
-    // its bare-leaf cache needs — hence both are set, and neither platform depends on the
-    // other's mechanism.
+    // cache is what names the modules. It is also the ONLY variable gdk-pixbuf's runtime
+    // reads: `GDK_PIXBUF_MODULEDIR` is read by queryloaders.c, the GENERATOR, where it
+    // merely picks the directory to scan. This comment used to claim the opposite — that
+    // MODULEDIR is "what its bare-leaf cache needs" on win32 — and the win32 builder wrote
+    // a bare-leaf cache on the strength of it. gdk-pixbuf 2.44.6's `build_module_path()`
+    // joins a relative cache entry with the bundle TOPLEVEL instead, so every leaf resolved
+    // to `<bundle>\<leaf>` and no SVG icon has ever decoded from a win32 bundle (#996).
+    // The cache is written toplevel-relative now; see scripts/pixbuf-loader-cache.mjs.
+    //
+    // darwin needs neither: Homebrew's gdk-pixbuf 2.44.7 has no `GDK_PIXBUF_MODULEDIR`
+    // string in the dylib at all, so that cache names each module `@loader_path/…`
+    // (relative to the image that dlopens it, i.e. the bundle's lib/) and dyld resolves it
+    // with no env beyond this file.
+    //
+    // MODULEDIR is still set, and still only if unset: it costs nothing, and it is what a
+    // consumer regenerating the cache in-process would need. Nothing here depends on it.
     const loaderCache = join(bundle.dir, 'lib', 'gdk-pixbuf-2.0', '2.10.0', 'loaders.cache');
     if (existsSync(loaderCache)) {
         setIfUnset('GDK_PIXBUF_MODULEDIR', join(bundle.dir, 'lib', 'gdk-pixbuf-2.0', '2.10.0', 'loaders'));

package/load-diagnostics.js

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: MIT
 // @gjsify/node-gi/load-diagnostics — what a user is told when the addon FILE is
-// present and still will not load.
+// present and still will not load. TWO causes reach the same catch and they get
+// DIFFERENT answers: the loader could not resolve the specifier, or it resolved
+// it and the OS refused the binary. Only the second is about GTK.
 //
 // A MODULE OF ITS OWN, and that is the point: `index.js` loads the native addon
 // at evaluation time, so anything living there can only be imported by a process
@@ -13,6 +15,41 @@
 import { hostTarget } from './native-paths.js';
 import { gtkSource } from './gtk-runtime.js';
 
+/**
+ * Did the loader fail to RESOLVE the specifier, rather than to load the binary?
+ *
+ * Two entirely different failures arrive at the same `catch`, and only one of
+ * them is about GTK:
+ *
+ *   • dlopen/LoadLibrary said no — the file was found, and its dependency
+ *     closure (or its ABI) is the problem. That is the case the long GTK
+ *     explanation below describes.
+ *   • `require()` never got as far as the file. The specifier was neither
+ *     absolute nor `./`-led, so it was looked up as a MODULE — against this
+ *     package's directory and node_modules, never against the process's cwd that
+ *     the `existsSync()` one line earlier had just resolved it against.
+ *
+ * THE INCIDENT (#996 / PR #1239), and why this discriminator exists at all:
+ * node-gi.yml hands the GTK bundle builder a repo-relative `--stage`, the builder
+ * passed that straight through as `NODE_GI_NATIVE`, and all four darwin bundle
+ * legs failed with `Cannot find module 'packages/node-gi/…'` underneath a
+ * confident five-line account of the Homebrew dependency closure ending in
+ * "Reinstall @gjsify/gtk-runtime-darwin-arm64". Every word of that advice was
+ * wrong for the cause, and it is the advice a stranger would have followed. The
+ * path bug itself is fixed in `native-paths.js#nativeCandidates()`; this stays
+ * because the next relative path to reach a `require()` will not come from there.
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+function isResolutionFailure(err) {
+    if (!err || typeof err !== 'object') return false;
+    const { code, message } = /** @type {{ code?: unknown, message?: unknown }} */ (err);
+    if (code === 'MODULE_NOT_FOUND' || code === 'ERR_MODULE_NOT_FOUND') return true;
+    // Bun, Deno and the GJS napi shim raise the same condition without Node's
+    // code, so the message is a fallback rather than the primary test.
+    return typeof message === 'string' && /cannot find module|module not found/i.test(message);
+}
+
 /**
  * Turn a failed addon load into something the reader can act on.
  *
@@ -34,6 +71,27 @@ export function describeAddonLoadFailure(addonPath, err, ctx = {}) {
     const target = ctx.target ?? hostTarget();
     const reason = err instanceof Error ? err.message : String(err);
 
+    // A resolution failure gets no GTK answer. Returning early is what keeps the
+    // dependency-closure explanation for the case it actually describes — see
+    // isResolutionFailure() for what it cost when the two shared one message.
+    if (isResolutionFailure(err)) {
+        return [
+            `@gjsify/node-gi: the native addon path could not be RESOLVED.`,
+            `  addon: ${addonPath}`,
+            `  cause: ${reason}`,
+            '',
+            `This is a module-RESOLUTION failure, NOT a missing GTK dependency: the`,
+            `loader never reached the file, so nothing here is evidence about glib,`,
+            `gobject, girepository or a runtime bundle. A path that is neither absolute`,
+            `nor written with a leading ./ is resolved by require() as a MODULE`,
+            `specifier — against @gjsify/node-gi's own directory and node_modules,`,
+            `never against the working directory of the process that set it.`,
+            '',
+            `Pass an ABSOLUTE path:`,
+            `  NODE_GI_NATIVE=/absolute/path/to/node_gi.node`,
+        ].join('\n');
+    }
+
     const lines = [
         `@gjsify/node-gi: the native addon exists but could not be loaded.`,
         `  addon: ${addonPath}`,

package/native-paths.js

@@ -26,7 +26,7 @@
 // definitions; this file is the authority for node-gi's own binary, and the third
 // copy is the one that must never be written.
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 
 /**
  * The package root. This module sits beside `index.js`, so its own directory IS
@@ -89,6 +89,15 @@ export function buildAddonPath(flavor = 'Release') {
  * Default order: prefer a shipped prebuild so a consumer needs no C toolchain and
  * no node-gyp — the only install path Deno supports (it runs no postinstall build
  * script). Fall back to a locally built addon (Release, then Debug).
+ *
+ * Every candidate is ABSOLUTE, including a pinned one, and that is load-bearing
+ * rather than tidiness: `loadNative()` tests a candidate with `existsSync()` (which
+ * reads a relative path against the CWD) and hands the SAME string to `require()`
+ * (which reads a bare one as a MODULE specifier, against this package's directory).
+ * A relative pin therefore passed the check and failed the load. Resolving HERE,
+ * where the string enters the package, is what makes the two ask about one file.
+ * The incident it cost, and the misdiagnosis it wore: load-diagnostics.js
+ * `isResolutionFailure`.
  * @param {Record<string, string | undefined>} [env] defaults to `process.env`
  * @returns {string[]}
  */
@@ -99,6 +108,9 @@ export function nativeCandidates(env = process.env) {
     const prefer = env.NODE_GI_NATIVE;
     if (prefer === 'build') return [release, debug, prebuild];
     if (prefer === 'prebuild') return [prebuild];
-    if (prefer) return [prefer]; // an explicit path to a node_gi.node
+    // An explicit path to a node_gi.node. `resolve()` keeps an absolute path
+    // byte-identical and gives a relative one the cwd meaning `existsSync` would
+    // have read into it anyway — so the check and the load name the same file.
+    if (prefer) return [resolve(prefer)];
     return [prebuild, release, debug];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "GObject-Introspection runtime for Node.js — load gi:// namespaces (GLib/GObject/Gio/…) with GJS-compatible semantics. Vendored + rewritten from node-gtk under MIT.",
   "type": "module",
   "license": "MIT",

package/system-gi.js

@@ -84,8 +84,14 @@ const PROBED_GI_LIBDIRS = {
     darwin: ['/opt/homebrew/lib', '/usr/local/lib', '/opt/local/lib'],
 };
 
-/** The subdir GI installs typelibs into — historically `1.0` even for the girepository-2.0 API. */
-const TYPELIB_SUBDIR = 'girepository-1.0';
+/**
+ * The subdir GI installs typelibs into — historically `1.0` even for the girepository-2.0 API.
+ *
+ * Exported so `gi-typelib.ts` shares it rather than keeping a third copy of the
+ * one string this whole layout rule turns on. Both mirrors export it, so the
+ * agreement suite still compares two files that differ only in language.
+ */
+export const TYPELIB_SUBDIR = 'girepository-1.0';
 
 /** Memoized `pkg-config` answer: the spawn happens at most once per process. */
 let pkgConfigDirsCache = null;