@gjsify/vite-plugin-blueprint 0.53.0 → 0.55.0

package/lib/index.d.ts

@@ -2,8 +2,17 @@ import { type Plugin } from 'vite';
 export interface BlueprintPluginOptions {
     minify?: boolean;
     verbose?: boolean;
+    /**
+     * Write each `.blp`'s `x.d.blp.ts` sidecar beside it during `load` (ADR 0088 § 4). On by
+     * default: the types are what the named exports are FOR, and a build that emits `build()`
+     * without them leaves every consumer on the ambient `*.blp` wildcard.
+     *
+     * A `.blp` under `node_modules` is never written, whatever this says — see `writeSidecar`.
+     */
+    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,5 +1,8 @@
-import { readFile } from 'node:fs/promises';
-import { accessibilityElement, accessibilityValue, emitGtkBuilderXml, enumOrFlagsTypeOf, gtypeName, parseBlueprint, projectToSharedNode, resolveIdent, } from '@gjsify/blueprint';
+import { readFile, writeFile } from 'node:fs/promises';
+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` /
@@ -13,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.
@@ -63,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}`;
 /**
@@ -84,10 +93,91 @@ 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.
+ *
+ * ONLY ON A DIFFERENCE, for two reasons that both bite in watch mode: a write with identical
+ * bytes still moves the mtime, which the watcher sees as a change and turns into a rebuild
+ * loop; and a `.blp` whose sidecar is already correct should leave the working tree untouched,
+ * so `git status` after a build stays a statement about what the author changed.
+ *
+ * NEVER UNDER `node_modules`. A `.blp` shipped inside a dependency is not this project's to
+ * edit, and the tree may be read-only or a store symlink. A failure to write anywhere else is
+ * reported and not thrown: the sidecar is the developer's convenience and
+ * `scripts/check-blueprint-sidecars.mjs` is the enforcement, so a read-only checkout should
+ * still build.
+ */
+async function writeSidecar(file, text, verbose) {
+    if (file.includes('node_modules'))
+        return;
+    const path = sidecarPathFor(file);
+    try {
+        if ((await readFile(path, 'utf8').catch(() => undefined)) === text)
+            return;
+        await writeFile(path, text, 'utf8');
+        if (verbose)
+            console.log(`Wrote ${path} (@gjsify/vite-plugin-blueprint)`);
+    }
+    catch (error) {
+        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 } = options;
+    const { minify = false, verbose = false, sidecars = true } = options;
     return {
         name: 'vite-plugin-blueprint',
         // The query has to be resolved by hand: the default resolver stats the specifier, and
@@ -136,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)};`;
@@ -152,8 +244,29 @@ export default function blueprintPlugin(options = {}) {
                 if (verbose)
                     console.log(`Minified XML for ${asked.file}`);
             }
-            // Return the XML content as a string
-            return `export default ${JSON.stringify(xmlContent)};`;
+            // ADR 0088's named exports, beside the `default` that does not move. The module text
+            // is `@gjsify/blueprint`'s, not this file's, because the sidecar DECLARES what this
+            // 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, 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), 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.53.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.53.0",
+        "@gjsify/blueprint": "^0.55.0",
         "minify-xml": "^4.5.2"
     },
     "peerDependencies": {
@@ -63,8 +63,8 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.53.0",
-        "@gjsify/unit": "^0.53.0",
+        "@gjsify/cli": "^0.55.0",
+        "@gjsify/unit": "^0.55.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3",
         "vite": "^8.1.3"

package/types/blueprint.d.ts

@@ -1,3 +1,16 @@
+/**
+ * The FALLBACK, and only the fallback, since ADR 0088.
+ *
+ * A `.blp` with an `x.d.blp.ts` sidecar beside it is typed by that sidecar instead — measured on
+ * TypeScript 6.0.3, a sidecar read under `allowArbitraryExtensions` wins over this wildcard. This
+ * stays because the migration is per-file and must be: a `.blp` with no sidecar keeps typing as
+ * the XML string it has always been, so nothing had to move when the named exports landed.
+ *
+ * It is also what makes the missing-sidecar case LOUD rather than silent. A consumer writing
+ * `import { build } from './x.blp'` against a file with no sidecar lands here, where only
+ * `default` exists, and `tsc` reports TS2614 naming each missing member — which is why
+ * `scripts/check-blueprint-sidecars.mjs` does not check for that case itself.
+ */
 declare module '*.blp' {
     const content: string;
     export default content;