@gjsify/rolldown-plugin-gjsify 0.23.0 → 0.24.2

package/lib/plugins/napi-node-addon.js

@@ -38,9 +38,12 @@
 // LOCATE the `.node` but cannot rescue that body. So when the entry of a napi-rs
 // package resolves, we replace the WHOLE module with
 // `module.exports = loadAddon('<abs platform .node>')` (the `napi-rs-entry`
-// kind) — the platform `.node` is the current-triple sibling package
-// (`@scope/pkg-<triple>`, only the host's optionalDependency is installed) or a
-// local `pkg.<triple>.node`. Detection is CONSERVATIVE (package.json signal +
+// kind) — the platform `.node` is the current-triple sibling package (only the
+// host's optionalDependency is installed) or a local `pkg.<triple>.node`. The
+// sibling is named `<self>-<triple>` OR `<napi.packageName>-<triple>`; both
+// schemes ship in the wild and `isNapiRsSibling` knows both, which is what
+// makes `rolldown`/`oxfmt`/`oxlint` (all `@<scope>/binding-<triple>`) reachable
+// and not just `lightningcss`/`@node-rs/*`. Detection is CONSERVATIVE (package.json signal +
 // the file must be the package's own native `main` entry + a real host `.node`
 // must resolve) so it never rewrites an unrelated package's entry; when no
 // current-platform `.node` resolves we fall through to normal resolution rather
@@ -66,7 +69,8 @@
 // plugin is correct even when the filter does not pre-filter.
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-const NAPI_ADDON_VIRTUAL_PREFIX = '\0gjsify-napi-addon:';
+import { GJSIFY_VIRTUAL_PREFIX } from '../utils/virtual-module-id.js';
+const NAPI_ADDON_VIRTUAL_PREFIX = `${GJSIFY_VIRTUAL_PREFIX}napi-addon:`;
 /** Bare specifier the shims import — resolved + bundled from the consumer graph. */
 const NAPI_BARE_SPECIFIER = '@gjsify/napi';
 /**
@@ -78,8 +82,41 @@ const NAPI_BARE_SPECIFIER = '@gjsify/napi';
  * `this.resolve` probes on ordinary deps.
  */
 const NAPI_RS_TRIPLE_RE = /-(?:linux|darwin|win32|freebsd|openbsd|sunos|android|aix)-(?:x64|arm64|arm|ia32|ppc64|s390x|riscv64|loong64)(?:-(?:gnu|musl|msvc|eabi|eabihf|androideabi|gnueabihf))?$/;
-/** Fast-path filter (superset of what `claimSpecifier` claims). Handler re-checks. */
-const ADDON_FILTER_RE = new RegExp([
+/**
+ * A BARE package specifier (`lightningcss`, `@rolldown/binding-…`) — no leading
+ * `.`/`/`/`\`, no protocol (`node:fs`, `gi://Gtk`, `data:…`, `C:\…`), not a
+ * `\0` virtual id.
+ *
+ * Needed because a napi-rs generated loader acquires its binary through a
+ * specifier the bundler CANNOT see: `require(`lightningcss-${parts.join('-')}`)`
+ * / `require(`../lightningcss.${parts.join('-')}.node`)` are template literals
+ * computed at runtime. So neither the sibling nor the direct-`.node`
+ * interception can fire, and the only lever is replacing the loader ENTRY —
+ * which the caller reaches by its BARE name. Matching only path-shaped ids (as
+ * before) meant `import { transform } from 'lightningcss'` was never even
+ * offered to the handler, and the addon gate had to hand-alias every bare
+ * specifier to its native entry to get coverage.
+ *
+ * PORTABILITY, and it is load-bearing: this source feeds `ADDON_FILTER_RE`,
+ * which `@gjsify/rolldown-native` hands to the Rust core as an `idFilter`
+ * STRING. Rust's `regex` crate has no lookaround and no `\0` escape, and it
+ * rejects the WHOLE combined filter rather than the offending branch — which
+ * silently disables every interception under the GJS engine while npm
+ * `rolldown` on Node keeps working. So: no `(?!…)`, and NUL is spelled `\x00`.
+ * The asymmetry is invisible to the addon gate, which drives the Node CLI
+ * entry, so only a real `--app gjs` build under `gjs` catches a regression here.
+ */
+// oxlint-disable-next-line no-control-regex -- the NUL is the point: it marks a bundler VIRTUAL id (`\0gjsify-…`), which is never a package specifier and must not be probed.
+const BARE_SPECIFIER_RE = /^[^.\\/:\s\x00][^:\s\x00]*$/;
+/**
+ * Fast-path filter (superset of what `claimSpecifier` claims). Handler re-checks.
+ *
+ * Exported so `napi-node-addon.spec.ts` can assert its Rust-compatibility (see
+ * {@link BARE_SPECIFIER_RE}) — a JS-only construct here disables the plugin
+ * entirely under `@gjsify/rolldown-native`, and no build-level test would see
+ * it, because every addon gate drives the Node CLI entry.
+ */
+export const ADDON_FILTER_RE = new RegExp([
     /\.node$/.source, // direct .node
     /^node-gyp-build(?:\/index\.js)?$/.source, // node-gyp-build helper
     /^bindings(?:\/bindings\.js)?$/.source, // bindings helper
@@ -89,6 +126,9 @@ const ADDON_FILTER_RE = new RegExp([
     // `index.*`, not every `.js`) — the handler's `detectNapiRsEntry` gate
     // (package.json signal + native-main match) is the load-bearing check.
     /[/\\]index\.[cm]?js$/.source,
+    // A bare specifier, so the handler can resolve it and test the RESOLVED
+    // file. Broad by design; the handler's fast rejects keep it cheap.
+    BARE_SPECIFIER_RE.source,
 ].join('|'));
 function isMusl(platform) {
     // Match node-gyp-build's isAlpine() probe.
@@ -351,11 +391,13 @@ export function classifySpecifier(source) {
  *   (a) a top-level `napi` config OBJECT (`{ binaryName, targets, … }`) — the
  *       napi-rs CLI's own build block. An ordinary npm package never declares a
  *       `napi` object at the manifest root.
- *   (b) at least one `optionalDependencies` entry named `<self>-<triple>` — the
- *       napi-rs prebuilt-binary convention (`@node-rs/argon2` ships
- *       `@node-rs/argon2-linux-x64-gnu`, …). The key MUST start with the
- *       package's own name plus `-` AND end in a platform triple, so a normal
- *       optional dep (`fsevents`) can't match.
+ *   (b) at least one `optionalDependencies` entry that is a platform SIBLING
+ *       (see {@link isNapiRsSibling}) — the napi-rs prebuilt-binary convention,
+ *       under either naming scheme: `<self>-<triple>` (`@node-rs/argon2` ships
+ *       `@node-rs/argon2-linux-x64-gnu`) or `<napi.packageName>-<triple>`
+ *       (`rolldown` ships `@rolldown/binding-linux-x64-gnu`). The key MUST
+ *       carry a known prefix AND end in a platform triple, so a normal optional
+ *       dep (`fsevents`) can't match.
  *
  * Neither fires on a normal package, so pairing this with the "resolved file IS
  * the package's own native main entry" check (see {@link detectNapiRsEntry})
@@ -364,11 +406,10 @@ export function classifySpecifier(source) {
 export function isNapiRsPackageJson(pkg) {
     if (pkg && typeof pkg.napi === 'object' && pkg.napi !== null)
         return true;
-    const self = pkg?.name;
     const opt = pkg?.optionalDependencies;
-    if (self && opt) {
+    if (opt) {
         for (const dep of Object.keys(opt)) {
-            if (dep.startsWith(`${self}-`) && NAPI_RS_TRIPLE_RE.test(dep))
+            if (isNapiRsSibling(pkg, dep))
                 return true;
         }
     }
@@ -399,13 +440,79 @@ export function detectNapiRsEntry(entryFile) {
     const pkg = readPackageJsonSafe(pkgRoot);
     if (pkg === null || !isNapiRsPackageJson(pkg))
         return null;
-    // The resolved file must be the package's OWN native main entry — reject a
-    // `browser`/wasm fallback or any deep module inside the package.
-    const mainEntry = resolve(pkgRoot, pkg.main ?? 'index.js');
-    if (resolve(entryFile) !== mainEntry)
+    // The resolved file must be one of the package's OWN native entry points —
+    // reject a `browser`/wasm fallback or any deep module inside the package.
+    const target = stripJsExt(resolve(entryFile));
+    const isNativeEntry = nativeEntrySpecs(pkg).some((spec) => stripJsExt(resolve(pkgRoot, spec)) === target);
+    if (!isNativeEntry)
         return null;
     return { pkgRoot, pkg };
 }
+/** Drop a trailing `.js` / `.mjs` / `.cjs` — see {@link nativeEntrySpecs}. */
+function stripJsExt(p) {
+    return p.replace(/\.[cm]?js$/, '');
+}
+/**
+ * Every path a napi-rs manifest names as its NATIVE entry — `main`, `module`,
+ * and the `exports["."]` target(s) — with the `browser` condition deliberately
+ * excluded (that is the wasm / pure-JS fallback, which must keep resolving
+ * normally: it needs no addon and works on GJS as-is).
+ *
+ * Both halves of this matter, and each was a real miss:
+ *
+ *   - `main` ALONE is not enough. A dual package declares the CJS twin in
+ *     `main` while a bundler resolves the ESM one — `lightningcss` says
+ *     `main: "node/index.js"` and ships `node/index.mjs` beside it, which is
+ *     what `--app gjs` actually loads. Comparing only against `main` rejected
+ *     the very file being bundled, so the rewrite silently never happened and
+ *     the generated loader's runtime `require(\`lightningcss-${…}\`)` shipped
+ *     into the bundle.
+ *   - Matching is therefore extension-INSENSITIVE (`stripJsExt`): the `.js` /
+ *     `.mjs` / `.cjs` twins of a declared entry are the same generated loader.
+ *     It stays narrow because the path itself must still be one the manifest
+ *     names — a deep module inside the package never matches.
+ *
+ * Defaults to `index.js` (node's own default `main`) when the manifest names
+ * nothing at all.
+ */
+function nativeEntrySpecs(pkg) {
+    const specs = [];
+    const add = (v) => {
+        if (typeof v === 'string' && v && !specs.includes(v))
+            specs.push(v);
+    };
+    add(pkg.main);
+    add(pkg.module);
+    // `exports["."]` is a string, or a condition object whose values are
+    // strings / nested condition objects. Walk it, skipping `browser`.
+    const walk = (node, depth) => {
+        if (typeof node === 'string')
+            return add(node);
+        if (depth > 4 || node === null || typeof node !== 'object' || Array.isArray(node))
+            return;
+        for (const [condition, value] of Object.entries(node)) {
+            if (condition === 'browser' || condition === 'types')
+                continue;
+            walk(value, depth + 1);
+        }
+    };
+    const exportsField = pkg.exports;
+    if (typeof exportsField === 'string') {
+        add(exportsField);
+    }
+    else if (exportsField !== null && typeof exportsField === 'object' && !Array.isArray(exportsField)) {
+        const map = exportsField;
+        // Two legal shapes: a SUBPATH map (keys start with `.`) — then only `.`
+        // is the package entry — or a bare CONDITION object, which IS the entry.
+        // Distinguishing them matters: walking a subpath map wholesale would
+        // make `./some-subpath` a candidate entry.
+        const isSubpathMap = Object.keys(map).some((k) => k.startsWith('.'));
+        walk(isSubpathMap ? map['.'] : map, 0);
+    }
+    if (specs.length === 0)
+        specs.push('index.js');
+    return specs;
+}
 /** napi-rs binaryName (from `napi.binaryName`/`napi.name`, else the unscoped pkg name). */
 function napiBinaryName(pkg) {
     const napi = pkg.napi;
@@ -419,13 +526,66 @@ function napiBinaryName(pkg) {
         return pkg.name.replace(/^@[^/]+\//, '');
     return null;
 }
+/**
+ * The name PREFIXES a napi-rs package's platform siblings can carry, most
+ * specific first. A sibling is always `<prefix>-<triple>`.
+ *
+ * Two conventions are in the wild, and only knowing both covers the toolchain
+ * this project builds on:
+ *
+ *   - `<self>-<triple>` — the sibling is named after the package itself
+ *     (`lightningcss` → `lightningcss-linux-x64-gnu`; `@node-rs/argon2` →
+ *     `@node-rs/argon2-linux-x64-gnu`). This was the only shape handled.
+ *   - `<napi.packageName>-<triple>` — napi-rs lets a package publish its
+ *     binaries under a SEPARATE scope, declared in the manifest's own napi
+ *     block. `rolldown` ships `@rolldown/binding-linux-x64-gnu`, `oxfmt`
+ *     ships `@oxfmt/binding-linux-x64-gnu`, `oxlint` ships
+ *     `@oxlint/binding-linux-x64-gnu` — none of which starts with the
+ *     package's own name, so the `<self>-` test missed every one of them.
+ *
+ * That gap is why the three packages at the centre of this build chain
+ * (bundler, formatter, linter) could not load transparently under GJS while
+ * `lightningcss` could: `isNapiRsPackageJson` recognises all four (they all
+ * carry a `napi` config object), so the ENTRY is detected — but with no
+ * sibling resolvable, `resolveNapiRsEntryAddon` returns null and the rewrite
+ * is skipped, leaving the generated loader's CJS body to ship into the bundle
+ * and throw. Conservative by construction either way: a prefix only matters
+ * when it also resolves to a real `.node`.
+ *
+ * `napi.packageName` is read defensively — an arbitrary manifest may put
+ * anything there, and a non-string must not poison the prefix list.
+ */
+function napiSiblingPrefixes(pkg) {
+    const prefixes = [];
+    const napi = pkg.napi;
+    if (napi && typeof napi === 'object') {
+        const { packageName } = napi;
+        if (typeof packageName === 'string' && packageName)
+            prefixes.push(packageName);
+    }
+    if (typeof pkg.name === 'string' && pkg.name && !prefixes.includes(pkg.name))
+        prefixes.push(pkg.name);
+    return prefixes;
+}
+/**
+ * Is `dep` a platform sibling of `pkg` — `<prefix>-<triple>` for one of the
+ * prefixes above? Both halves must hold: a bare prefix match would claim an
+ * ordinary dependency, and a bare triple match would claim an unrelated
+ * package's binaries. Exported for the unit tests.
+ */
+export function isNapiRsSibling(pkg, dep) {
+    if (!NAPI_RS_TRIPLE_RE.test(dep))
+        return false;
+    return napiSiblingPrefixes(pkg).some((prefix) => dep.startsWith(`${prefix}-`));
+}
 /**
  * The napi-rs short platform triple for the CURRENT host (`linux-x64-gnu`,
  * `darwin-arm64`, `win32-x64-msvc`, …) — the tail napi-rs stamps into a sibling
  * package name (`@node-rs/argon2-linux-x64-gnu`) and a local binary
- * (`argon2.linux-x64-gnu.node`). Used ONLY for the deterministic local-file
- * fallback; the sibling path never needs it (npm installs only the matching
- * optionalDependency). Returns null for a host napi-rs doesn't name.
+ * (`argon2.linux-x64-gnu.node`). Selects BOTH the sibling package and the
+ * local-file fallback — see `resolveNapiRsEntryAddon` for why the sibling path
+ * cannot just take whatever resolves. Returns null for a host napi-rs doesn't
+ * name, and the caller then widens rather than guessing.
  */
 function hostNapiRsTriple() {
     const platform = process.platform;
@@ -477,24 +637,29 @@ function rawAddonPath(id) {
  * DOES NOT rewrite, so we never shim over a missing file.
  */
 async function resolveNapiRsEntryAddon(ctx, pkgRoot, pkg, importer) {
-    const self = pkg.name;
-    const opt = pkg.optionalDependencies ?? {};
-    if (self) {
-        for (const dep of Object.keys(opt)) {
-            if (!dep.startsWith(`${self}-`) || !NAPI_RS_TRIPLE_RE.test(dep))
-                continue;
-            const resolved = await ctx.resolve(dep, importer, { skipSelf: true });
-            if (!resolved)
-                continue;
-            const abs = rawAddonPath(resolved.id);
-            if (abs.endsWith('.node') && existsSync(abs))
-                return abs;
-        }
+    const siblings = Object.keys(pkg.optionalDependencies ?? {}).filter((dep) => isNapiRsSibling(pkg, dep));
+    const triple = hostNapiRsTriple();
+    // HOST TRIPLE FIRST, and alone whenever we can name it. The older code took
+    // the first sibling that resolved, on the premise that "npm installs only
+    // the host's optionalDependency, so the one that resolves is the host's".
+    // That premise does not hold here: `gjsify install` materialises EVERY
+    // platform package, so `lightningcss`'s `darwin-x64` sibling resolves on a
+    // Linux box and won — baking a Mach-O `.dylib`-bearing `.node` into a linux
+    // GJS bundle, which `loadAddon` can only fail on at runtime. Selecting by
+    // the host triple is also what node-gyp-build and napi-rs' own generated
+    // loaders do, so this matches the binary Node would have loaded.
+    const ordered = triple === null ? siblings : siblings.filter((dep) => dep.endsWith(`-${triple}`));
+    for (const dep of ordered) {
+        const resolved = await ctx.resolve(dep, importer, { skipSelf: true });
+        if (!resolved)
+            continue;
+        const abs = rawAddonPath(resolved.id);
+        if (abs.endsWith('.node') && existsSync(abs))
+            return abs;
     }
     // Local in-package binary (`<binaryName>.<host-triple>.node`) — deterministic
     // host-triple match so a wrong-platform local file is never picked.
     const binaryName = napiBinaryName(pkg);
-    const triple = hostNapiRsTriple();
     if (binaryName && triple) {
         const local = join(pkgRoot, `${binaryName}.${triple}.node`);
         if (existsSync(local))
@@ -555,28 +720,107 @@ export function napiNodeAddonPlugin(options = {}) {
         napiEntryCache.set(entryFile, info);
         return info;
     }
-    async function warnIfNapiMissing(ctx, importer) {
-        if (!warnOnMissingNapi || missingNapiChecked)
-            return;
-        missingNapiChecked = true; // check once per build — interception is rare
+    // Bare-specifier → entry-file resolution, memoized per (specifier, importer
+    // DIRECTORY) since that pair is what node resolution actually depends on.
+    // The widened filter offers every bare import here and almost none of them
+    // is a native addon, so this cache is what keeps the extra `ctx.resolve` to
+    // one per unique pair rather than one per import site.
+    const bareEntryCache = new Map();
+    /**
+     * The FILE a specifier denotes, for napi-rs entry detection:
+     *   - absolute path  → itself (an already-resolved or hand-aliased entry).
+     *   - bare specifier → resolved through the full chain (so aliases and
+     *     export conditions apply — under `--app gjs` that is what picks a
+     *     package's `browser`/wasm fallback over its native entry, and
+     *     `detectNapiRsEntry` then correctly declines to rewrite it).
+     *   - anything else (relative paths) → null, unchanged from before.
+     */
+    async function entryFileFor(ctx, source, importer) {
+        if (isAbsolute(source))
+            return source;
+        if (!BARE_SPECIFIER_RE.test(source))
+            return null;
+        // Never recurse through our own shims' import.
+        if (source === NAPI_BARE_SPECIFIER || source.startsWith(`${NAPI_BARE_SPECIFIER}/`))
+            return null;
+        const key = `${source}\0${importer === undefined ? '' : dirname(importer)}`;
+        const cached = bareEntryCache.get(key);
+        if (cached !== undefined)
+            return cached;
+        let file = null;
         try {
-            const found = await ctx.resolve(NAPI_BARE_SPECIFIER, importer, { skipSelf: true });
-            if (!found) {
-                warnSafe(ctx, `[gjsify-napi-addon] a native .node addon was intercepted but '${NAPI_BARE_SPECIFIER}' ` +
-                    `is not resolvable — the bundle will fail at load. Install it: gjsify install ${NAPI_BARE_SPECIFIER}`);
-            }
+            const resolved = await ctx.resolve(source, importer, { skipSelf: true });
+            // An external / virtual / unresolvable id is not a file on disk.
+            if (resolved && isAbsolute(resolved.id) && existsSync(resolved.id))
+                file = resolved.id;
         }
         catch {
-            /* best-effort probe */
+            /* resolution failure is not our error to raise — fall through */
         }
+        bareEntryCache.set(key, file);
+        return file;
+    }
+    /**
+     * Is `@gjsify/napi` resolvable from the consumer graph? This is the GATE on
+     * every rewrite, not a diagnostic — installing it (`gjsify install
+     * @gjsify/napi`) is what a project uses to opt into napi routing.
+     *
+     * It used to only WARN, and the warning said the quiet part out loud: "the
+     * bundle will fail at load". Emitting a knowingly-unloadable artifact is
+     * never better than declining to rewrite — the untouched module at least
+     * gets the default resolution, and a package with a JS/wasm fallback then
+     * works. Two concrete failures made this a gate rather than a nicety:
+     *
+     *   - The CLI's own `--app gjs` bundle reaches npm `lightningcss` through
+     *     `css-as-string`'s Node fallback branch (under GJS it deliberately
+     *     prefers `@gjsify/lightningcss-native`). Rewriting that branch put a
+     *     `require('@gjsify/napi')` into a bundle whose package does not depend
+     *     on `@gjsify/napi` at all.
+     *   - Worse, it made the COMMITTED bundle environment-dependent: with the
+     *     package present the shim inlines, without it the import goes external,
+     *     and the two module graphs minify to different variable names. That is
+     *     a `verify-committed-bundles` failure — the artifact stops reproducing
+     *     from its own source.
+     *
+     * Probed once per build (interception is rare) and cached, so the extra
+     * resolve costs nothing on the common path.
+     */
+    let napiAvailable = null;
+    async function ensureNapiAvailable(ctx, importer) {
+        if (napiAvailable !== null)
+            return napiAvailable;
+        let found = false;
+        try {
+            found = Boolean(await ctx.resolve(NAPI_BARE_SPECIFIER, importer, { skipSelf: true }));
+        }
+        catch {
+            /* best-effort probe — treat a resolver throw as "not available" */
+        }
+        napiAvailable = found;
+        if (!found && warnOnMissingNapi && !missingNapiChecked) {
+            missingNapiChecked = true;
+            warnSafe(ctx, `[gjsify-napi-addon] a native .node addon was found but '${NAPI_BARE_SPECIFIER}' is not ` +
+                `resolvable — leaving it to normal resolution. Install it to route the addon through ` +
+                `N-API on GJS: gjsify install ${NAPI_BARE_SPECIFIER}`);
+        }
+        return found;
     }
     return {
         name: 'gjsify-napi-node-addon',
         resolveId: {
             order: 'pre',
             filter: { id: ADDON_FILTER_RE },
-            async handler(source, importer) {
+            async handler(source, rawImporter) {
                 const ctx = this;
+                // The two engines disagree on "no importer": npm `rolldown`
+                // passes `undefined`, `@gjsify/rolldown-native` passes `null`
+                // (its hook payload round-trips through JSON, which has no
+                // `undefined`). Every guard below is written `=== undefined`,
+                // and `null` passes all of them — `dirname(null)` then threw
+                // `The "path" argument must be of type string. Received type
+                // object` and took the whole GJS build down as an
+                // UNHANDLEABLE_ERROR. Normalise once, at the boundary.
+                const importer = typeof rawImporter === 'string' ? rawImporter : undefined;
                 const cls = classifySpecifier(source);
                 if (cls !== null) {
                     // Direct `.node` — resolve the file path itself.
@@ -584,7 +828,8 @@ export function napiNodeAddonPlugin(options = {}) {
                         const abs = await resolveNodeFile(ctx, source, importer);
                         if (abs === null)
                             return null; // unresolvable — let the default chain error
-                        await warnIfNapiMissing(ctx, importer);
+                        if (!(await ensureNapiAvailable(ctx, importer)))
+                            return null;
                         return { id: encodeVirtual('direct', abs) };
                     }
                     // napi-rs platform sibling — confirm it resolves to a `.node`.
@@ -592,7 +837,8 @@ export function napiNodeAddonPlugin(options = {}) {
                         const resolved = await ctx.resolve(source, importer, { skipSelf: true });
                         if (!resolved || !resolved.id.endsWith('.node'))
                             return null; // not a native sibling
-                        await warnIfNapiMissing(ctx, importer);
+                        if (!(await ensureNapiAvailable(ctx, importer)))
+                            return null;
                         return { id: encodeVirtual('napi-rs', resolved.id) };
                     }
                     // node-gyp-build / bindings — probe the importer's package root.
@@ -601,8 +847,9 @@ export function napiNodeAddonPlugin(options = {}) {
                     const pkgRoot = nearestPackageRoot(importer);
                     if (pkgRoot === null)
                         return null;
+                    if (!(await ensureNapiAvailable(ctx, importer)))
+                        return null;
                     const addonPath = resolveAddonPath(pkgRoot, { warn: (m) => warnSafe(ctx, m) }); // throws → build error
-                    await warnIfNapiMissing(ctx, importer);
                     return { id: encodeVirtual(cls.kind, addonPath) };
                 }
                 // napi-rs GENERATED-LOADER ENTRY (`index.*` filter). Replace the
@@ -610,11 +857,21 @@ export function napiNodeAddonPlugin(options = {}) {
                 // of a napi-rs package (package.json signal) AND a current-platform
                 // `.node` resolves. Otherwise fall through (never a shim over a
                 // missing file, never an unrelated package's entry rewritten).
-                const entry = detectNapiRsEntryCached(source);
+                // The specifier may be the entry PATH (an internal import, or a
+                // caller that already aliased it) or the package's BARE name —
+                // the ordinary `import { transform } from 'lightningcss'`. For
+                // the bare form the entry file is only known after resolution,
+                // so resolve first and test the resolved id. `entryFileFor`
+                // memoizes both the resolve and the rejection.
+                const entryFile = await entryFileFor(ctx, source, importer);
+                if (entryFile === null)
+                    return null;
+                const entry = detectNapiRsEntryCached(entryFile);
                 if (entry !== null) {
-                    const addonPath = await resolveNapiRsEntryAddon(ctx, entry.pkgRoot, entry.pkg, source);
+                    const addonPath = await resolveNapiRsEntryAddon(ctx, entry.pkgRoot, entry.pkg, entryFile);
                     if (addonPath !== null) {
-                        await warnIfNapiMissing(ctx, importer);
+                        if (!(await ensureNapiAvailable(ctx, importer)))
+                            return null;
                         return { id: encodeVirtual('napi-rs-entry', addonPath) };
                     }
                 }

package/lib/plugins/unresolved-workspace-import.d.ts

@@ -0,0 +1,105 @@
+import type { Plugin } from 'rolldown';
+/** Build targets that compose this guard. Used only for the error message. */
+export type WorkspaceImportGuardTarget = 'gjs' | 'node' | 'browser' | 'nativescript';
+export interface WorkspaceImportGuardOptions {
+    /** `--app <target>` this build is for; named verbatim in the error. */
+    target: WorkspaceImportGuardTarget;
+    /**
+     * The substitution table this target promised (specifier → target), already
+     * merged across tiers exactly as `aliasPlugin` received it. A miss here is
+     * fine — case (b) still covers a direct `@gjsify/*` import.
+     */
+    aliases?: Record<string, string>;
+    /**
+     * The target's own externals policy. Anything it claims is a DELIBERATE
+     * external and is ignored. Pass the same predicate `externalsPlugin` gets
+     * (plus exact-name membership) so the two cannot drift.
+     */
+    isExternal?: (id: string) => boolean;
+}
+/**
+ * Is `id` a bare `@gjsify/*` package specifier (root or subpath)?
+ *
+ * Deliberately excludes disk paths and synthetic ids: a resolved
+ * `/…/node_modules/@gjsify/fs/lib/esm/index.js` is already resolved, and a
+ * `\0gjsify-*` virtual id belongs to the plugin that emitted it.
+ */
+export declare function isWorkspaceSpecifier(id: string): boolean;
+/** What the guard decided about one specifier. */
+export type ImportVerdict = {
+    verdict: 'ignore';
+    reason: 'entry' | 'not-bare' | 'declared-external' | 'out-of-scope';
+} | {
+    verdict: 'check';
+    candidate: string;
+    aliasTarget?: string;
+};
+export interface ClassifyImportInput {
+    source: string;
+    importer: string | undefined;
+    aliases?: Record<string, string>;
+    isExternal?: (id: string) => boolean;
+}
+/**
+ * Pure decision: does this import edge have to resolve, and to what?
+ *
+ * Split out from the plugin so the legitimate-vs-broken line is unit-testable
+ * without a bundler (`packages/infra/cli/src/unresolved-workspace-import.spec.ts`).
+ */
+export declare function classifyImport(input: ClassifyImportInput): ImportVerdict;
+export interface UnresolvedWorkspaceImportDetails {
+    target: WorkspaceImportGuardTarget;
+    /** The specifier as written in the importing module. */
+    source: string;
+    /** What actually had to resolve (the alias target, or `source` itself). */
+    candidate: string;
+    /** Set when `source` was rewritten by the substitution table. */
+    aliasTarget?: string;
+    /**
+     * Specifiers whose substitution-table entry names `candidate`, discovered by
+     * REVERSE lookup — the half of the story `source` alone cannot tell.
+     *
+     * `aliasPlugin` resolves its target through `this.resolve(target, importer)`,
+     * so when `node:fs` → `@gjsify/fs` fails, the id that reaches THIS hook is
+     * `@gjsify/fs` with no alias entry of its own: the message would name the
+     * missing package but not the `node:fs` the user actually wrote, which is
+     * the specifier that survives into the bundle and the one they will grep
+     * for. Reversing the table recovers it (`['fs', 'node:fs']` — both forms
+     * route to the same target, and naming both is accurate).
+     */
+    aliasedFrom?: readonly string[];
+    importer: string;
+}
+/** A `@gjsify/*` edge the build promised to substitute could not be resolved. */
+export declare class UnresolvedWorkspaceImportError extends Error {
+    readonly details: UnresolvedWorkspaceImportDetails;
+    constructor(details: UnresolvedWorkspaceImportDetails);
+}
+/**
+ * The actionable message. Names the specifier, the importer and the likely
+ * cause — the three things `UNRESOLVED_IMPORT` (and the post-hoc `node:` guard)
+ * cannot tell you.
+ */
+export declare function formatUnresolvedWorkspaceImport(details: UnresolvedWorkspaceImportDetails): string;
+/**
+ * Reverse the substitution table: alias TARGET → the specifiers that route to it.
+ *
+ * Built once per plugin instance (the tables run to ~150 entries per target, and
+ * the guard only consults this on the failure path).
+ */
+export declare function buildReverseAliasIndex(aliases: Record<string, string> | undefined): Map<string, string[]>;
+/**
+ * Refuse a build whose `@gjsify/*` substitution could not be resolved.
+ *
+ * `order: 'post'` so every deliberate claim — `aliasPlugin` (`pre`),
+ * `napiNodeAddonPlugin` (`pre`), `gjsGiNodePlugin` (`pre`),
+ * `gjsImportsEmptyPlugin`, `externalsPlugin` — gets first refusal. Only ids that
+ * NOTHING claimed reach this hook, i.e. exactly the ones headed for the
+ * unresolved-import fallback.
+ *
+ * The hook re-runs the full resolution chain via `this.resolve(…, { skipSelf })`
+ * — which is what Rolldown's builtin resolver would have done next — and returns
+ * its result when it succeeds, so a healthy build resolves the specifier exactly
+ * once and behaves identically. Only a genuine `null` throws.
+ */
+export declare function unresolvedWorkspaceImportPlugin(options: WorkspaceImportGuardOptions): Plugin;