@gjsify/vite-plugin-blueprint 0.40.0 → 0.41.0

package/README.md

@@ -14,7 +14,10 @@ npm install @gjsify/vite-plugin-blueprint
 yarn add @gjsify/vite-plugin-blueprint
 ```
 
-Requires `blueprint-compiler` to be installed on the system (e.g. `sudo dnf install blueprint-compiler`).
+Requires `blueprint-compiler` on the system (e.g. `sudo dnf install blueprint-compiler`). It is found on
+`PATH`, and on Windows also in an MSYS2 install that is not on `PATH`; set `BLUEPRINT_COMPILER` to point at
+one the plugin does not find. When there is none, the build error names the install command for the host it
+ran on rather than leaving you to guess — so this README does not repeat one per platform.
 
 ## Usage
 

package/lib/index.d.ts

@@ -3,5 +3,5 @@ export interface BlueprintPluginOptions {
     minify?: boolean;
     verbose?: boolean;
 }
-export { resolveBlueprintCompiler, formatMissingBlueprintCompiler } from './resolve-compiler.js';
+export { BlueprintCompileError, BlueprintCompilerNotFoundError, type BlueprintHost, currentBlueprintHost, formatMissingBlueprintCompiler, type ResolvedBlueprintCompiler, resolveBlueprintCompiler, } from './resolve-compiler.js';
 export default function blueprintPlugin(options?: BlueprintPluginOptions): Plugin;

package/lib/index.js

@@ -1,29 +1,34 @@
 import { execa } from 'execa';
 import minifyXML from 'minify-xml';
-import { formatMissingBlueprintCompiler, resolveBlueprintCompiler } from './resolve-compiler.js';
-export { resolveBlueprintCompiler, formatMissingBlueprintCompiler } from './resolve-compiler.js';
+import { BlueprintCompileError, BlueprintCompilerNotFoundError, resolveBlueprintCompiler, } from './resolve-compiler.js';
+export { BlueprintCompileError, BlueprintCompilerNotFoundError, currentBlueprintHost, formatMissingBlueprintCompiler, resolveBlueprintCompiler, } from './resolve-compiler.js';
 export default function blueprintPlugin(options = {}) {
     const { minify = false, verbose = false } = options;
+    // Cached only on SUCCESS, so the PATH walk costs one probe per plugin
+    // instance instead of one per `.blp`. A MISS is deliberately re-probed:
+    // installing the compiler and saving the file is how a watch session is
+    // meant to recover, and caching "absent" would make that need a restart.
+    let compiler = null;
     return {
         name: 'vite-plugin-blueprint',
         async load(id) {
             if (id.endsWith('.blp')) {
-                // Resolved per load rather than once at plugin construction, so a
-                // compiler installed mid-watch is picked up without a restart —
-                // and so the "missing" diagnostic names the .blp that wanted it.
-                const compiler = resolveBlueprintCompiler();
+                compiler ??= resolveBlueprintCompiler();
                 if (!compiler) {
-                    throw new Error(`${id}: ${formatMissingBlueprintCompiler()}`);
+                    // Names the `.blp` that wanted it, so the diagnostic points at
+                    // a file the reader recognises rather than at the plugin.
+                    throw new BlueprintCompilerNotFoundError(id);
                 }
+                const resolved = compiler;
                 try {
                     // Compile .blp file and get XML output directly
-                    const { stdout } = await execa(compiler.file, [...compiler.prefixArgs, 'compile', id], {
+                    const { stdout } = await execa(resolved.file, [...resolved.prefixArgs, 'compile', id], {
                         // Only ever an overlay (an MSYS2 PATH prepend); undefined
                         // inherits the environment unchanged.
-                        env: compiler.env,
+                        env: resolved.env,
                     });
                     if (verbose)
-                        console.log(`Compiled ${id} (blueprint-compiler via ${compiler.source})`);
+                        console.log(`Compiled ${id} (blueprint-compiler via ${resolved.source})`);
                     let xmlContent = stdout;
                     // Minify XML if option is enabled
                     if (minify) {
@@ -35,12 +40,8 @@ export default function blueprintPlugin(options = {}) {
                     return `export default ${JSON.stringify(xmlContent)};`;
                 }
                 catch (error) {
-                    // The compiler EXISTS and refused the file, so this is a
-                    // blueprint syntax/type error and its own stderr is the
-                    // useful part — surface that, not an install hint the reader
-                    // has already satisfied.
                     const detail = error instanceof Error ? error.stderr || error.message : String(error);
-                    throw new Error(`${id}: blueprint-compiler failed (${compiler.file})\n${detail}`);
+                    throw new BlueprintCompileError(id, resolved.file, detail);
                 }
             }
         },

package/lib/resolve-compiler.d.ts

@@ -8,20 +8,77 @@ export interface ResolvedBlueprintCompiler {
     env?: Record<string, string>;
     source: 'env' | 'path' | 'msys2';
 }
+/**
+ * The host facts this module decides on, taken as a PARAMETER rather than read
+ * from ambient `process.*`.
+ *
+ * Every unit-test leg in this repo runs on Linux, so an ambient
+ * `process.platform` puts the darwin and win32 branches — which are most of this
+ * module and the only ones anybody gets wrong — out of reach of any test. This
+ * is the purity `packages/infra/cli/src/utils/platform-check.ts` documents,
+ * applied to the module whose entire job is a per-OS answer.
+ */
+export interface BlueprintHost {
+    /** `process.platform` of the host being answered for. */
+    platform: NodeJS.Platform;
+    /** That host's environment. */
+    env: Record<string, string | undefined>;
+    /** Does this path exist? `existsSync` in production, a map in a test. */
+    exists: (path: string) => boolean;
+}
+/** The running process as a {@link BlueprintHost}. */
+export declare function currentBlueprintHost(): BlueprintHost;
 /**
  * Locate a usable blueprint-compiler, or null when there is none.
  *
  * Order: `BLUEPRINT_COMPILER` (an explicit answer always wins, and is the escape
  * hatch for an install none of the probes below know about) → `PATH` → an MSYS2
  * install on win32.
+ *
+ * A set-but-unusable override resolves to null rather than falling through to
+ * the probes. Handing back a path that is not there sent its `ENOENT` into the
+ * "the compiler EXISTS and refused the file" branch, which then blamed the
+ * `.blp` for a typo in an environment variable; and quietly ignoring an explicit
+ * instruction to run a second guess is not better. Null is what lets
+ * {@link formatMissingBlueprintCompiler} say which of the two actually happened.
  */
-export declare function resolveBlueprintCompiler(): ResolvedBlueprintCompiler | null;
+export declare function resolveBlueprintCompiler(host?: BlueprintHost): ResolvedBlueprintCompiler | null;
 /**
  * What to tell someone who has no blueprint-compiler.
  *
  * Names the install command for THIS platform rather than listing every one:
  * the reader is on one host and the other two lines are noise they have to
- * filter. `BLUEPRINT_COMPILER` is mentioned everywhere because it is the answer
- * for any install the probes miss.
+ * filter. The Linux arm is the exception that proves it — every Linux row of
+ * `PM_PACKAGES` in `@gjsify/cli`'s `check-system-deps.ts` spells the package
+ * identically, so splitting it per distro would be four lines carrying one word.
+ *
+ * `BLUEPRINT_COMPILER` is mentioned everywhere because it is the answer for any
+ * install the probes miss — except when it is itself the problem, which gets its
+ * own sentence: repeating "or set BLUEPRINT_COMPILER" at someone who just set it
+ * is how a diagnostic loses their trust.
  */
-export declare function formatMissingBlueprintCompiler(): string;
+export declare function formatMissingBlueprintCompiler(host?: BlueprintHost): string;
+/**
+ * No usable compiler on this host.
+ *
+ * Carries the whole user-facing sentence so the wording has exactly one home and
+ * the plugin composes nothing: what this replaces was an `ExecaError` naming the
+ * COMMAND, in the guest's own language, from inside a rolldown plugin stack
+ * (#1098).
+ */
+export declare class BlueprintCompilerNotFoundError extends Error {
+    readonly blueprintPath: string;
+    readonly name = "BlueprintCompilerNotFoundError";
+    constructor(blueprintPath: string, host?: BlueprintHost);
+}
+/**
+ * The compiler exists and refused the file, so this is a blueprint syntax or
+ * type error and its own stderr is the useful part — never an install hint the
+ * reader has already satisfied.
+ */
+export declare class BlueprintCompileError extends Error {
+    readonly blueprintPath: string;
+    readonly compilerFile: string;
+    readonly name = "BlueprintCompileError";
+    constructor(blueprintPath: string, compilerFile: string, detail: string);
+}

package/lib/resolve-compiler.js

@@ -12,6 +12,24 @@
 // available; nothing said how to get it.
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+/**
+ * `existsSync` throws rather than answering `false` when the argument is not a
+ * usable path at all (an embedded NUL, for one) — and an unreadable or malformed
+ * PATH entry is not an answer about the command we are looking for. Same catch,
+ * and same reason, as `isOnPath()` in `@gjsify/cli`'s `check-system-deps.ts`.
+ */
+function existsSafe(path) {
+    try {
+        return existsSync(path);
+    }
+    catch {
+        return false;
+    }
+}
+/** The running process as a {@link BlueprintHost}. */
+export function currentBlueprintHost() {
+    return { platform: process.platform, env: process.env, exists: existsSafe };
+}
 /**
  * MSYS2 install roots to probe on win32, in order.
  *
@@ -26,13 +44,15 @@ import { join } from 'node:path';
  * extracted-archive install, which is what a host without admin rights gets;
  * `C:\tools\msys64` is Chocolatey's.
  */
-const MSYS2_ROOTS = [
-    process.env.MSYS2_ROOT,
-    'C:\\msys64',
-    process.env.USERPROFILE && join(process.env.USERPROFILE, 'msys64'),
-    process.env.USERPROFILE && join(process.env.USERPROFILE, 'Tools', 'msys64'),
-    'C:\\tools\\msys64',
-].filter((root) => typeof root === 'string' && root.length > 0);
+function msys2Roots(env) {
+    return [
+        env.MSYS2_ROOT,
+        'C:\\msys64',
+        env.USERPROFILE && join(env.USERPROFILE, 'msys64'),
+        env.USERPROFILE && join(env.USERPROFILE, 'Tools', 'msys64'),
+        'C:\\tools\\msys64',
+    ].filter((root) => typeof root === 'string' && root.length > 0);
+}
 /**
  * MSYS2 environments, most-preferred first. `ucrt64` is MSYS2's own default for
  * new installs and links the modern Universal CRT; the others are probed so an
@@ -40,25 +60,22 @@ const MSYS2_ROOTS = [
  */
 const MSYS2_ENVS = ['ucrt64', 'mingw64', 'clang64'];
 /** Executable suffixes to try for a bare command name. Windows needs them; POSIX does not. */
-const EXE_SUFFIXES = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+function exeSuffixes(platform) {
+    return platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+}
 /** First existing `<dir>/<cmd><suffix>`, or null. */
-function findOnPath(cmd) {
-    const pathVar = process.env.PATH;
+function findOnPath(cmd, host) {
+    const pathVar = host.env.PATH;
     if (!pathVar)
         return null;
-    const sep = process.platform === 'win32' ? ';' : ':';
+    const sep = host.platform === 'win32' ? ';' : ':';
     for (const dir of pathVar.split(sep)) {
         if (!dir)
             continue;
-        for (const suffix of EXE_SUFFIXES) {
+        for (const suffix of exeSuffixes(host.platform)) {
             const candidate = join(dir, cmd + suffix);
-            try {
-                if (existsSync(candidate))
-                    return candidate;
-            }
-            catch {
-                // An unreadable PATH entry is not an answer about `cmd`.
-            }
+            if (host.exists(candidate))
+                return candidate;
         }
     }
     return null;
@@ -79,67 +96,124 @@ function findOnPath(cmd) {
  * on PATH) would load two GLib builds into one process, which is a worse problem
  * than the one it solves.
  */
-function findInMsys2() {
-    if (process.platform !== 'win32')
+function findInMsys2(host) {
+    if (host.platform !== 'win32')
         return null;
-    for (const root of MSYS2_ROOTS) {
+    for (const root of msys2Roots(host.env)) {
         for (const env of MSYS2_ENVS) {
             const bin = join(root, env, 'bin');
             const script = join(bin, 'blueprint-compiler');
             const python = join(bin, 'python.exe');
-            try {
-                if (!existsSync(script) || !existsSync(python))
-                    continue;
-            }
-            catch {
+            if (!host.exists(script) || !host.exists(python))
                 continue;
-            }
             return {
                 file: python,
                 prefixArgs: [script],
-                env: { PATH: `${bin};${process.env.PATH ?? ''}` },
+                // `;` is a win32 fact, not a host fact — this branch only runs there.
+                env: { PATH: `${bin};${host.env.PATH ?? ''}` },
                 source: 'msys2',
             };
         }
     }
     return null;
 }
+/** Does this override name a location, as opposed to a bare command to look up? */
+function looksLikePath(override) {
+    return override.includes('/') || override.includes('\\');
+}
 /**
  * Locate a usable blueprint-compiler, or null when there is none.
  *
  * Order: `BLUEPRINT_COMPILER` (an explicit answer always wins, and is the escape
  * hatch for an install none of the probes below know about) → `PATH` → an MSYS2
  * install on win32.
+ *
+ * A set-but-unusable override resolves to null rather than falling through to
+ * the probes. Handing back a path that is not there sent its `ENOENT` into the
+ * "the compiler EXISTS and refused the file" branch, which then blamed the
+ * `.blp` for a typo in an environment variable; and quietly ignoring an explicit
+ * instruction to run a second guess is not better. Null is what lets
+ * {@link formatMissingBlueprintCompiler} say which of the two actually happened.
  */
-export function resolveBlueprintCompiler() {
-    const override = process.env.BLUEPRINT_COMPILER;
+export function resolveBlueprintCompiler(host = currentBlueprintHost()) {
+    const override = host.env.BLUEPRINT_COMPILER;
     if (override) {
-        return { file: override, prefixArgs: [], source: 'env' };
+        if (looksLikePath(override)) {
+            return host.exists(override) ? { file: override, prefixArgs: [], source: 'env' } : null;
+        }
+        // A bare command name is a legitimate override, and must still reach the
+        // child through the same PATH walk any other command name gets.
+        const onPath = findOnPath(override, host);
+        return onPath ? { file: onPath, prefixArgs: [], source: 'env' } : null;
     }
-    const onPath = findOnPath('blueprint-compiler');
+    const onPath = findOnPath('blueprint-compiler', host);
     if (onPath) {
         return { file: onPath, prefixArgs: [], source: 'path' };
     }
-    return findInMsys2();
+    return findInMsys2(host);
 }
 /**
  * What to tell someone who has no blueprint-compiler.
  *
  * Names the install command for THIS platform rather than listing every one:
  * the reader is on one host and the other two lines are noise they have to
- * filter. `BLUEPRINT_COMPILER` is mentioned everywhere because it is the answer
- * for any install the probes miss.
+ * filter. The Linux arm is the exception that proves it — every Linux row of
+ * `PM_PACKAGES` in `@gjsify/cli`'s `check-system-deps.ts` spells the package
+ * identically, so splitting it per distro would be four lines carrying one word.
+ *
+ * `BLUEPRINT_COMPILER` is mentioned everywhere because it is the answer for any
+ * install the probes miss — except when it is itself the problem, which gets its
+ * own sentence: repeating "or set BLUEPRINT_COMPILER" at someone who just set it
+ * is how a diagnostic loses their trust.
  */
-export function formatMissingBlueprintCompiler() {
-    const install = process.platform === 'win32'
+export function formatMissingBlueprintCompiler(host = currentBlueprintHost()) {
+    const override = host.env.BLUEPRINT_COMPILER;
+    if (override) {
+        return (`BLUEPRINT_COMPILER is set to "${override}", which is not ${looksLikePath(override) ? 'a file that exists' : 'on PATH'}.\n` +
+            '  Point it at a blueprint-compiler executable, or unset it to search PATH\n' +
+            '  (and, on Windows, the usual MSYS2 install locations).');
+    }
+    const install = host.platform === 'win32'
         ? 'MSYS2 packages it prebuilt (it needs PyGObject, which has no Windows wheel, so pip cannot):\n' +
             '    pacman -S mingw-w64-ucrt-x86_64-blueprint-compiler mingw-w64-ucrt-x86_64-gtk4 mingw-w64-ucrt-x86_64-libadwaita\n' +
             '  An MSYS2 install under C:\\msys64, %USERPROFILE%\\msys64, %USERPROFILE%\\Tools\\msys64 or\n' +
             '  C:\\tools\\msys64 is found automatically — it does NOT need to be on PATH.'
-        : process.platform === 'darwin'
+        : host.platform === 'darwin'
             ? 'brew install blueprint-compiler'
-            : 'sudo dnf install blueprint-compiler   (Debian/Ubuntu: sudo apt install blueprint-compiler)';
-    return ('blueprint-compiler was not found, so a .blp template cannot be compiled.\n' +
+            : 'sudo dnf install blueprint-compiler   (apt, pacman, zypper and apk package it under the same name)';
+    return ('blueprint-compiler was not found — @gjsify/vite-plugin-blueprint needs it to\n' +
+        '  compile .blp templates to GtkBuilder XML.\n' +
         `  ${install}\n` +
         '  Or set BLUEPRINT_COMPILER to its full path.');
 }
+/**
+ * No usable compiler on this host.
+ *
+ * Carries the whole user-facing sentence so the wording has exactly one home and
+ * the plugin composes nothing: what this replaces was an `ExecaError` naming the
+ * COMMAND, in the guest's own language, from inside a rolldown plugin stack
+ * (#1098).
+ */
+export class BlueprintCompilerNotFoundError extends Error {
+    blueprintPath;
+    name = 'BlueprintCompilerNotFoundError';
+    constructor(blueprintPath, host = currentBlueprintHost()) {
+        super(`${blueprintPath}: ${formatMissingBlueprintCompiler(host)}`);
+        this.blueprintPath = blueprintPath;
+    }
+}
+/**
+ * The compiler exists and refused the file, so this is a blueprint syntax or
+ * type error and its own stderr is the useful part — never an install hint the
+ * reader has already satisfied.
+ */
+export class BlueprintCompileError extends Error {
+    blueprintPath;
+    compilerFile;
+    name = 'BlueprintCompileError';
+    constructor(blueprintPath, compilerFile, detail) {
+        super(`${blueprintPath}: blueprint-compiler failed (${compilerFile})\n${detail}`);
+        this.blueprintPath = blueprintPath;
+        this.compilerFile = compilerFile;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/vite-plugin-blueprint",
-    "version": "0.40.0",
+    "version": "0.41.0",
     "description": "Compile GNOME Blueprint .blp templates to XML strings via blueprint-compiler. Vite / Rollup / Rolldown compatible.",
     "type": "module",
     "main": "lib/index.js",
@@ -24,9 +24,12 @@
         "types"
     ],
     "scripts": {
-        "clear": "gjsify clear lib tsconfig.tsbuildinfo",
+        "clear": "gjsify clear lib tsconfig.tsbuildinfo test.node.mjs",
         "check": "gjsify tsc --noEmit",
-        "build": "gjsify tsc"
+        "build": "gjsify tsc -p tsconfig.build.json",
+        "build:test:node": "gjsify build src/test.mts --app node --outfile test.node.mjs",
+        "test": "gjsify run build:test:node && gjsify run test:node",
+        "test:node": "node test.node.mjs"
     },
     "repository": {
         "type": "git",
@@ -63,6 +66,8 @@
         }
     },
     "devDependencies": {
+        "@gjsify/cli": "^0.41.0",
+        "@gjsify/unit": "^0.41.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3",
         "vite": "^8.1.3"