@gjsify/rolldown-plugin-gjsify 0.22.0 → 0.24.1

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

@@ -0,0 +1,120 @@
+import type { Plugin } from 'rolldown';
+/**
+ * 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 declare const ADDON_FILTER_RE: RegExp;
+/** Options for {@link napiNodeAddonPlugin}. */
+export interface NapiNodeAddonPluginOptions {
+    /**
+     * Emit a one-line warning when a native addon is intercepted but
+     * `@gjsify/napi` is not resolvable in the consumer graph. Default `true`.
+     */
+    warnOnMissingNapi?: boolean;
+}
+/** A native addon package root has no resolvable compiled `.node`. */
+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).
+ */
+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).
+ */
+export declare function nearestPackageRoot(importerFile: string): string | null;
+/** Direct `.node` import → the addon's exports (ESM default). */
+export declare function directNodeShim(addonPath: string): string;
+/** `node-gyp-build` replacement — a callable `load(dir)` carrying `.path()`. */
+export declare function nodeGypBuildShim(addonPath: string): string;
+/** `bindings` replacement — a callable `bindings(name)` returning the addon. */
+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.
+ */
+export declare function classifySpecifier(source: string): {
+    kind: 'node-gyp-build' | 'bindings';
+} | {
+    kind: 'direct-node';
+} | {
+    kind: 'napi-rs-candidate';
+} | null;
+/** Minimal package.json shape read for napi-rs detection. */
+export interface AddonPackageJson {
+    name?: string;
+    main?: string;
+    module?: string;
+    exports?: unknown;
+    browser?: string;
+    napi?: unknown;
+    optionalDependencies?: Record<string, string>;
+}
+/**
+ * A package.json describes a napi-rs generated-loader package when EITHER
+ * signal holds — both are package.json-level (not source sniffing):
+ *
+ *   (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.
+ *
+ * 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.
+ */
+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.
+ */
+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.
+ */
+export declare function isNapiRsSibling(pkg: AddonPackageJson, dep: string): boolean;
+/**
+ * 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.
+ */
+export declare function napiNodeAddonPlugin(options?: NapiNodeAddonPluginOptions): Plugin;