@gjsify/vite-plugin-blueprint 0.52.0 → 0.54.0

package/lib/index.d.ts

@@ -2,6 +2,14 @@ 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';
 /** The specifier an import site writes: `./x.blp?shared-tree`. */

package/lib/index.js

@@ -1,5 +1,6 @@
-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 } from 'node:path';
+import { accessibilityElement, accessibilityValue, emitGtkBuilderXml, emitTypedModule, emitTypedSidecar, enumOrFlagsTypeOf, gtypeName, parseBlueprint, projectToSharedNode, resolveIdent, sidecarPathFor, } from '@gjsify/blueprint';
 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` /
@@ -86,8 +87,37 @@ function readId(id) {
         return { file, sharedTree: false };
     return { file, sharedTree: new URLSearchParams(id.slice(queryAt + 1)).has(SHARED_TREE_PARAM) };
 }
+/**
+ * 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}`);
+    }
+}
 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
@@ -152,8 +182,21 @@ 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 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);
+            // `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);
+            return moduleText;
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/vite-plugin-blueprint",
-    "version": "0.52.0",
+    "version": "0.54.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.52.0",
+        "@gjsify/blueprint": "^0.54.0",
         "minify-xml": "^4.5.2"
     },
     "peerDependencies": {
@@ -63,8 +63,8 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.52.0",
-        "@gjsify/unit": "^0.52.0",
+        "@gjsify/cli": "^0.54.0",
+        "@gjsify/unit": "^0.54.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;