@gjsify/rolldown-plugin-gjsify 0.36.0 → 0.38.0

package/lib/plugins/napi-node-addon.d.ts

@@ -1,11 +1,8 @@
 import type { Plugin } from 'rolldown';
 /**
- * Fast-path filter (superset of what `claimSpecifier` claims). Handler re-checks.
- *
+ * Fast-path filter — a superset of what the handler claims; the 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.
+ * {@link BARE_SPECIFIER_RE}).
  */
 export declare const ADDON_FILTER_RE: RegExp;
 /** Options for {@link napiNodeAddonPlugin}. */
@@ -21,22 +18,15 @@ export declare class AddonNotBuiltError extends Error {
     constructor(pkgRoot: string);
 }
 /**
- * Locate the compiled `.node` for an addon package root, matching
- * node-gyp-build's probe order: `build/Release` → `build/Debug` →
- * `prebuilds/<platform>-<arch>/<best tag>`. Throws {@link AddonNotBuiltError}
- * when nothing is found.
- *
- * @param pkgRoot Absolute path to the addon package root (dir with package.json).
- * @param opts.warn Optional sink for a non-fatal warning (ambiguous build dir).
+ * Locate the compiled `.node` for an addon package root, matching node-gyp-build's
+ * probe order: `build/Release` → `build/Debug` →
+ * `prebuilds/<platform>-<arch>/<best tag>`. Throws {@link AddonNotBuiltError} when
+ * nothing is found. `opts.warn` sinks the non-fatal ambiguous-build-dir warning.
  */
 export declare function resolveAddonPath(pkgRoot: string, opts?: {
     warn?: (msg: string) => void;
 }): string;
-/**
- * Walk up from an importer file to the nearest `package.json` directory (the
- * addon package root). Returns null when none is found (should not happen for a
- * real node_modules dep).
- */
+/** Nearest ancestor directory of `importerFile` holding a `package.json`. */
 export declare function nearestPackageRoot(importerFile: string): string | null;
 /** Direct `.node` import → the addon's exports (ESM default). */
 export declare function directNodeShim(addonPath: string): string;
@@ -46,12 +36,7 @@ export declare function nodeGypBuildShim(addonPath: string): string;
 export declare function bindingsShim(addonPath: string): string;
 /** napi-rs sibling → the raw native exports as the module value. */
 export declare function napiRsShim(addonPath: string): string;
-/**
- * Classify a specifier for interception. Pure decision logic (no filesystem
- * probing beyond what `resolveAddonPath` does via the importer) — exported for
- * the unit tests. Returns the shim kind + the package root to probe, or the
- * literal `.node` path for the direct case.
- */
+/** Classify a specifier for interception — pure decision logic, no filesystem. */
 export declare function classifySpecifier(source: string): {
     kind: 'node-gyp-build' | 'bindings';
 } | {
@@ -73,89 +58,67 @@ export interface AddonPackageJson {
 /**
  * Is this manifest a gjsify NATIVE BRIDGE whose prebuilds live in per-target
  * sibling packages (ADR 0017) — `@gjsify/webgl` + `@gjsify/webgl-darwin-x64`, …?
+ * Such a bridge ships a GI typelib plus a `.so`/`.dylib`/`.dll` loaded through
+ * `gi://`, NEVER a Node-API `.node`, so it must never reach `loadAddon()`.
  *
- * Such a bridge ships a GObject-Introspection typelib plus a `.so`/`.dylib`/`.dll`
- * loaded through `gi://`, NEVER a Node-API `.node` addon, so it must never be
- * routed through `loadAddon()`.
- *
- * It has to be excluded EXPLICITLY because the two conventions are
- * indistinguishable by name: ADR 0017 spells a target `<os>-<arch>` and names the
- * package `<self>-<os>-<arch>` in `optionalDependencies` — which is exactly
- * napi-rs' `<self>-<triple>` sibling scheme whenever the target happens to be a
- * name napi-rs also uses. On Linux the two vocabularies differ by the libc token
- * (`linux-x64` vs napi-rs' `linux-x64-gnu`), so `hostNapiRsTriple()` never matched
- * and nothing fired; on macOS napi-rs' triple IS `darwin-x64` / `darwin-arm64`,
- * so every split bridge looked like a napi-rs package to
- * {@link isNapiRsPackageJson} and {@link resolveNapiRsEntryAddon} then probed
- * `ctx.resolve('@gjsify/webgl-darwin-x64')` — an artifact-only package with no JS
- * entry at all. That probe does not return null: the `unresolved-workspace-import`
- * guard (correctly) treats an unresolvable bare `@gjsify/*` as FATAL, so
- * `gjsify build --app gjs` of any consumer of any split bridge died on darwin with
- * "cannot resolve the workspace package" — invisible to every Linux CI job.
+ * The exclusion must be EXPLICIT because the two conventions are indistinguishable
+ * by name: ADR 0017's `<self>-<os>-<arch>` optionalDependency is exactly napi-rs'
+ * `<self>-<triple>` scheme wherever the vocabularies agree. On Linux they differ by
+ * the libc token (`linux-x64` vs `linux-x64-gnu`) so nothing fired, but on macOS
+ * napi-rs' triple IS `darwin-arm64`: every split bridge looked like a napi-rs
+ * package, {@link resolveNapiRsEntryAddon} probed an artifact-only package with no
+ * JS entry, and the `unresolved-workspace-import` guard (correctly) made that
+ * unresolvable bare `@gjsify/*` FATAL — so `--app gjs` of any consumer of any split
+ * bridge died on darwin, invisible to every Linux CI job.
  *
- * `gjsify.platforms` is the right discriminator: it is the OS-axis declaration
- * every native bridge carries (§ Runtime & platform model) and no napi-rs package
- * has any reason to declare it.
- *
- * Exported for the unit tests.
+ * `gjsify.platforms` is the right discriminator: the OS-axis declaration every
+ * native bridge carries (§ Runtime & platform model), which no napi-rs package has
+ * reason to declare.
  */
 export declare function isGjsifyNativeBridge(pkg: AddonPackageJson): boolean;
 /**
- * A package.json describes a napi-rs generated-loader package when EITHER
- * signal holds — both are package.json-level (not source sniffing):
+ * A package.json describes a napi-rs generated-loader package when EITHER signal
+ * holds:
  *
  *   (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 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.
+ *       napi-rs CLI's build block, which no ordinary npm package declares.
+ *   (b) an `optionalDependencies` entry that is a platform SIBLING (see
+ *       {@link isNapiRsSibling}) — 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})
- * makes entry-replacement safe. Exported for the unit tests.
+ * Neither fires on a normal package, so pairing this with the "resolved file IS the
+ * package's own native main entry" check ({@link detectNapiRsEntry}) makes
+ * entry-replacement safe.
  */
 export declare function isNapiRsPackageJson(pkg: AddonPackageJson): boolean;
 /**
- * Decide whether an absolute file path is the NATIVE generated-loader entry of a
- * napi-rs package. Returns the package root + parsed manifest when it is, else
- * null. "Native entry" = the package's `main` (default `index.js`) — NOT its
- * `browser`/wasm fallback and NOT a deep file — so we only ever replace the one
- * generated loader, never an unrelated module. Filesystem-based (reads the
- * nearest package.json); the plugin memoizes calls. Exported for the unit tests.
+ * Is this absolute file path the NATIVE generated-loader entry of a napi-rs package?
+ * Returns the package root + parsed manifest, else null. "Native entry" = a path the
+ * manifest names as its entry — NOT its `browser`/wasm fallback and NOT a deep file
+ * — so only the one generated loader is ever replaced. Reads the nearest
+ * package.json; the plugin memoizes calls.
  */
 export declare function detectNapiRsEntry(entryFile: string): {
     pkgRoot: string;
     pkg: AddonPackageJson;
 } | null;
 /**
- * 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.
+ * 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, a bare triple match an unrelated package's binaries.
  */
 export declare function isNapiRsSibling(pkg: AddonPackageJson, dep: string): boolean;
 /**
  * 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`). 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.
+ * `darwin-arm64`, …) — the tail napi-rs stamps into a sibling package name and a
+ * local binary, and the selector for both. Returns null for a host napi-rs does not
+ * name; the caller then widens rather than guessing.
  */
 export declare function hostNapiRsTriple(): string | null;
 /**
- * Transparent `.node`-addon loader for `gjsify build --app gjs`.
- *
- * resolveId (`order: 'pre'`, importer-aware) intercepts a native-addon
- * acquisition and rewrites it to a virtual module whose value is
- * `loadAddon('<abs .node>')`. Inert unless such a specifier is in the graph —
- * every other id returns null. Register ONLY for `--app gjs` (the C-ABI runs
- * under `@gjsify/napi`); never for node/browser/nativescript.
+ * Transparent `.node`-addon loader for `gjsify build --app gjs`: resolveId
+ * (`order: 'pre'`, importer-aware) rewrites a native-addon acquisition to a virtual
+ * module whose value is `loadAddon('<abs .node>')`, and returns null for everything
+ * else. Register ONLY for `--app gjs` — the C-ABI runs under `@gjsify/napi`.
  */
 export declare function napiNodeAddonPlugin(options?: NapiNodeAddonPluginOptions): Plugin;