@gjsify/vite-plugin-blueprint 0.54.0 → 0.55.0

package/lib/index.d.ts

@@ -11,7 +11,8 @@ export interface BlueprintPluginOptions {
      */
     sidecars?: boolean;
 }
-export { BlueprintProjectionError } from './projection-error.js';
+export { BlueprintProjectionError, RendererRefusalError } from './projection-error.js';
+export type { RefusedUse } from './projection-error.js';
 /** The specifier an import site writes: `./x.blp?shared-tree`. */
 export declare const SHARED_TREE_QUERY = "?shared-tree";
 export default function blueprintPlugin(options?: BlueprintPluginOptions): Plugin;

package/lib/index.js

@@ -1,6 +1,8 @@
 import { readFile, writeFile } from 'node:fs/promises';
-import { basename } from 'node:path';
+import { basename, dirname } from 'node:path';
 import { accessibilityElement, accessibilityValue, emitGtkBuilderXml, emitTypedModule, emitTypedSidecar, enumOrFlagsTypeOf, gtypeName, parseBlueprint, projectToSharedNode, resolveIdent, sidecarPathFor, } from '@gjsify/blueprint';
+import { emitFormatForTree } from '@gjsify/blueprint/oxfmt';
+import { pathToFileURL } from 'node:url';
 import minifyXML from 'minify-xml';
 // Blueprint's OWN two error types are not re-exported here, and that is the shape rather than
 // an omission. What a parse or an emit throws is `@gjsify/blueprint`'s `BlueprintSyntaxError` /
@@ -14,8 +16,8 @@ import minifyXML from 'minify-xml';
 // the file fine and the projection hands back a tree plus the list of what it cost; deciding
 // that such a tree may not reach a renderer is this plugin's decision, taken at the seam where
 // a build target is known. So it is declared where it is thrown.
-export { BlueprintProjectionError } from './projection-error.js';
-import { BlueprintProjectionError } from './projection-error.js';
+export { BlueprintProjectionError, RendererRefusalError } from './projection-error.js';
+import { BlueprintProjectionError, RendererRefusalError } from './projection-error.js';
 /**
  * The five seams `@gjsify/blueprint`'s emitter reaches introspection through, answered by that
  * same package out of the `@girs` vocabulary.
@@ -64,6 +66,12 @@ const SEAMS = Object.freeze({
  *     "NO blueprintPlugin" comment was one half of.
  */
 const SHARED_TREE_PARAM = 'shared-tree';
+/**
+ * `for=<renderer>` names the renderer an import is checked against (ADR 0093 § 2), by the
+ * package name without `@gjsify/`: `./x.blp?shared-tree&for=adwaita-web`. It is chosen at the
+ * import site for ADR 0070 § 1's reason — a target does not determine a renderer.
+ */
+const RENDERER_PARAM = 'for';
 /** The specifier an import site writes: `./x.blp?shared-tree`. */
 export const SHARED_TREE_QUERY = `?${SHARED_TREE_PARAM}`;
 /**
@@ -85,7 +93,9 @@ function readId(id) {
         return undefined;
     if (queryAt === -1)
         return { file, sharedTree: false };
-    return { file, sharedTree: new URLSearchParams(id.slice(queryAt + 1)).has(SHARED_TREE_PARAM) };
+    const params = new URLSearchParams(id.slice(queryAt + 1));
+    const renderer = params.get(RENDERER_PARAM) ?? undefined;
+    return { file, sharedTree: params.has(SHARED_TREE_PARAM), ...(renderer === undefined ? {} : { renderer }) };
 }
 /**
  * Write the sidecar beside its `.blp`, unless nothing would change.
@@ -116,6 +126,56 @@ async function writeSidecar(file, text, verbose) {
         console.warn(`vite-plugin-blueprint: could not write ${path}: ${error.message}`);
     }
 }
+/**
+ * The emitter options for the tree a `.blp` lives in, memoized per directory.
+ *
+ * The walk touches the filesystem, and watch mode re-enters `load` for every changed file in a
+ * tree that may hold hundreds of `.blp` — so one read per distinct directory, not per file. The
+ * walk itself is `emitFormatForTree`'s, shared with the drift gate and `gjsify blueprint types`,
+ * because three answers to "which `.oxfmtrc` does the formatter read" is how the 4-space indent
+ * reached a `tabWidth: 2` consumer in the first place.
+ *
+ * Cached for the life of the PROCESS, which is the declared limit: an `.oxfmtrc` edited while a
+ * dev server is already running is picked up on the next start, not on the next rebuild. That is
+ * the same refresh the formatter itself gets, so a sidecar written after such an edit is the one
+ * the running formatter is no longer using — and `check-blueprint-sidecars.mjs` re-derives from
+ * disk either way, so the committed bytes stay honest.
+ */
+const formatCache = new Map();
+const formatFor = (dir) => {
+    const cached = formatCache.get(dir);
+    if (cached !== undefined)
+        return cached;
+    const format = emitFormatForTree(dir);
+    formatCache.set(dir, format);
+    return format;
+};
+/**
+ * Intersect the constructs a file uses with the table of the renderer it is imported for, and
+ * throw {@link RendererRefusalError} for each one that renderer refuses (ADR 0093 § 2).
+ *
+ * The table is resolved from the `.blp`'s own location, so the renderer found is the one the
+ * project depends on, and read as pure data: `./capabilities` never reaches the renderer's
+ * runtime. A name that resolves to nothing, or a table with no row for a used kind, is an error
+ * and not permission.
+ */
+async function refuseForRenderer(context, file, renderer, uses) {
+    const specifier = `@gjsify/${renderer}/capabilities`;
+    const resolved = await context.resolve(specifier, file, { skipSelf: true });
+    if (resolved === null) {
+        throw new Error(`${file}: \`for=${renderer}\` names no renderer — ${specifier} does not resolve from here.`);
+    }
+    const { capabilities } = (await import(pathToFileURL(resolved.id).href));
+    const refused = uses.flatMap((use) => {
+        const capability = capabilities[use.kind];
+        if (capability === undefined) {
+            throw new Error(`${specifier} declares no row for the construct '${use.kind}'.`);
+        }
+        return capability === 'implemented' ? [] : [{ ...use, reason: capability.refused }];
+    });
+    if (refused.length > 0)
+        throw new RendererRefusalError(file, renderer, refused);
+}
 export default function blueprintPlugin(options = {}) {
     const { minify = false, verbose = false, sidecars = true } = options;
     return {
@@ -166,9 +226,11 @@ export default function blueprintPlugin(options = {}) {
                 // So the build stops here, with the file, the line and the kind of every loss —
                 // a porting task a reader can open, not a warning scrolled past. `minify` does
                 // not apply: it is an XML setting and this exit emits none.
-                const { node, lost } = projectToSharedNode(ast, { gtypeName });
+                const { node, lost, uses } = projectToSharedNode(ast, { gtypeName });
                 if (lost.length > 0)
                     throw new BlueprintProjectionError(asked.file, lost);
+                if (asked.renderer !== undefined)
+                    await refuseForRenderer(this, asked.file, asked.renderer, uses);
                 if (verbose)
                     console.log(`Projected ${asked.file} (@gjsify/blueprint)`);
                 return `export default ${JSON.stringify(node)};`;
@@ -187,15 +249,23 @@ export default function blueprintPlugin(options = {}) {
             // implements and the two have to be written together — `typed-exports.mjs` § the
             // MODULE a bundler gets says why they share a file.
             //
+            // The format is the PROJECT's `.oxfmtrc`, resolved once per directory beside the
+            // `.blp`, and it is what makes this sidecar survive the consumer's own
+            // `gjsify format --check`: the emitter once hardcoded a 4-space indent, which is this
+            // repository's value and nobody else's (ADR 0088 § Consequences). Same walk as the
+            // drift gate and `gjsify blueprint types`, so the three cannot answer differently.
+            const format = formatFor(dirname(asked.file));
+            //
             // The sidecar is written AFTER the module is emitted, so a `.blp` the derivation
             // refuses leaves no sidecar behind claiming exports the module does not have.
-            const moduleText = emitTypedModule(ast, xmlContent);
+            const moduleText = emitTypedModule(ast, xmlContent, format);
             // `basename` from `node:path`, and this plugin is the one caller for which the HOST is
             // the authority: a vite/rolldown plugin only ever runs in the Node process driving the
             // build, on the machine whose paths `asked.file` is a path on. `@gjsify/blueprint`
             // cannot do this itself — see `typed-exports.mjs` § `emitTypedSidecar`.
-            if (sidecars)
-                await writeSidecar(asked.file, emitTypedSidecar(ast, basename(asked.file)), verbose);
+            if (sidecars) {
+                await writeSidecar(asked.file, emitTypedSidecar(ast, basename(asked.file), format), verbose);
+            }
             return moduleText;
         },
     };

package/lib/projection-error.d.ts

@@ -21,3 +21,21 @@ export declare class BlueprintProjectionError extends Error {
     readonly lost: readonly ProjectedLoss[];
     constructor(file: string, lost: readonly ProjectedLoss[]);
 }
+/** One construct a named renderer refuses, with the line it sits on and the table's reason. */
+export interface RefusedUse {
+    kind: string;
+    line: number;
+    reason: string;
+}
+/**
+ * A `.blp` imported with `?shared-tree&for=<renderer>` that uses constructs the renderer's
+ * `./capabilities` table refuses (ADR 0093 § 2).
+ *
+ * A subclass of {@link BlueprintProjectionError} so one `instanceof` catches both refusals; `lost`
+ * is empty, because the projection itself was whole — the renderer is what says no.
+ */
+export declare class RendererRefusalError extends BlueprintProjectionError {
+    readonly renderer: string;
+    readonly refused: readonly RefusedUse[];
+    constructor(file: string, renderer: string, refused: readonly RefusedUse[]);
+}

package/lib/projection-error.js

@@ -32,3 +32,24 @@ export class BlueprintProjectionError extends Error {
         this.lost = lost;
     }
 }
+/**
+ * A `.blp` imported with `?shared-tree&for=<renderer>` that uses constructs the renderer's
+ * `./capabilities` table refuses (ADR 0093 § 2).
+ *
+ * A subclass of {@link BlueprintProjectionError} so one `instanceof` catches both refusals; `lost`
+ * is empty, because the projection itself was whole — the renderer is what says no.
+ */
+export class RendererRefusalError extends BlueprintProjectionError {
+    renderer;
+    refused;
+    constructor(file, renderer, refused) {
+        super(file, []);
+        const listed = refused.map((use) => `  ${use.kind} at ${file}:${use.line} — ${use.reason}`).join('\n');
+        this.message =
+            `${file} cannot be rendered by ${renderer}: ${refused.length} construct(s) it refuses.\n${listed}\n` +
+                'The GtkBuilder-XML exit of the same file is unaffected.';
+        this.name = 'RendererRefusalError';
+        this.renderer = renderer;
+        this.refused = refused;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/vite-plugin-blueprint",
-    "version": "0.54.0",
+    "version": "0.55.0",
     "description": "Compile GNOME Blueprint .blp templates to GtkBuilder-XML strings with the in-repo @gjsify/blueprint parser: no blueprint-compiler, no spawn. Vite / Rollup / Rolldown compatible.",
     "type": "module",
     "main": "lib/index.js",
@@ -47,7 +47,7 @@
     ],
     "license": "MIT",
     "dependencies": {
-        "@gjsify/blueprint": "^0.54.0",
+        "@gjsify/blueprint": "^0.55.0",
         "minify-xml": "^4.5.2"
     },
     "peerDependencies": {
@@ -63,8 +63,8 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.54.0",
-        "@gjsify/unit": "^0.54.0",
+        "@gjsify/cli": "^0.55.0",
+        "@gjsify/unit": "^0.55.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3",
         "vite": "^8.1.3"