@kirana-style/esbuild 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @kirana-style/esbuild
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The esbuild adapter for Kirana ([11-integrations](../../../../spec/11-integrations.md)).
+
+```js
+import kirana from "@kirana-style/esbuild"
+import * as esbuild from "esbuild"
+
+await esbuild.build({
+  entryPoints: ["src/main.tsx"],
+  bundle: true,
+  outdir: "www",
+  plugins: [kirana()],
+})
+```
+
+`onLoad` compiles modules that carry styles; the stylesheet entry loads as a placeholder esbuild
+bundles as CSS, and `onEnd` writes the finished stylesheet into it — on disk, or in `outputFiles`
+with `write: false`. Under `context().watch()` and `serve()` the entry reloads from a file the plugin
+keeps current, so the served stylesheet follows every edit.

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@kirana-style/esbuild",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Kirana for esbuild: compiles modules and finishes the stylesheet esbuild bundles.",
+  "license": "MIT",
+  "author": "The Kirana authors",
+  "homepage": "https://kirana.style",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kirana-style/kirana.git",
+    "directory": "packages/kirana/npm/esbuild"
+  },
+  "bugs": {
+    "url": "https://github.com/kirana-style/kirana/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@kirana-style/compiler": "0.1.0",
+    "@kirana-style/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "esbuild": ">=0.25.0"
+  },
+  "files": [
+    "src",
+    "bin",
+    "*.d.ts",
+    "*.css",
+    "README.md",
+    "builders.json",
+    "schemas",
+    "gatsby-node.mjs",
+    "rules",
+    "recommended.json",
+    "strict.json"
+  ]
+}

package/src/index.d.ts

@@ -0,0 +1,14 @@
+import type { DriverOptions } from "@kirana-style/compiler";
+import type { KiranaConfig } from "@kirana-style/core/config";
+import type { Plugin } from "esbuild";
+export type KiranaEsbuildOptions = {
+    /** The project root: where `kirana.config.*` and `@kirana-style/core` are found. Default: the working directory. */
+    root?: string;
+    /** Options that override `kirana.config.*`. */
+    config?: KiranaConfig;
+    /** Report `info` diagnostics (such as `dynamic-bridged`) as warnings. */
+    reportInfo?: boolean;
+    /** Injected Driver options (tests). */
+    driver?: Pick<DriverOptions, "native" | "importModule">;
+};
+export default function kirana(options?: KiranaEsbuildOptions): Plugin;

package/src/index.js

@@ -0,0 +1,111 @@
+/**
+ * The esbuild host adapter (KRN-INT-001, KRN-INT-003): `onLoad` compiles modules, and `onEnd` writes
+ * the finished stylesheet into the CSS esbuild bundled. It never interprets styles (D-028).
+ *
+ * The stylesheet entry loads as the placeholder rule, which esbuild bundles like any CSS import
+ * (`main.css` beside `main.js`); once every module has loaded, the plugin replaces it — in the written
+ * file, or in `outputFiles` when esbuild keeps them in memory (`write: false`). Watch and serve reload
+ * the entry itself from a file the plugin keeps current, so what `serve` sends follows every edit. A
+ * `naming` pattern that hashes CSS keeps the placeholder's hash.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, writeFileSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { Driver } from "@kirana-style/compiler";
+import { PLACEHOLDER, createReporter, fillStylesheet, shouldCompile, stylesheetPath, } from "@kirana-style/compiler/host";
+const LOADERS = {
+    tsx: "tsx",
+    ts: "ts",
+    mts: "ts",
+    cts: "ts",
+    jsx: "jsx",
+};
+/** An output file with new text, in the shape esbuild gives them. */
+function outputFile(file, text) {
+    return { ...file, contents: new TextEncoder().encode(text), text };
+}
+export default function kirana(options = {}) {
+    return {
+        name: "kirana",
+        setup(build) {
+            const root = options.root ?? process.cwd();
+            const stylesheetFile = stylesheetPath(root);
+            // The written outputs are found through the metafile.
+            build.initialOptions.metafile = true;
+            let driver;
+            const session = () => (driver ??= Driver.create({
+                root,
+                config: options.config,
+                ...options.driver,
+            }));
+            const reporter = createReporter(options);
+            const context = {
+                warn: (message) => console.warn(message),
+                error: (message) => {
+                    throw new Error(message);
+                },
+            };
+            // Watch and serve: the entry follows a file `onEnd` writes whenever the stylesheet changes, so a
+            // rebuild reloads it with the live stylesheet — which is what `serve` sends, from its own
+            // copy of the outputs. The first load, and every load of a one-shot build, is the placeholder.
+            const live = path.join(tmpdir(), `kirana-esbuild-${createHash("sha256").update(root).digest("hex").slice(0, 12)}.css`);
+            let written;
+            writeFileSync(live, "");
+            build.onLoad({ filter: /stylesheet\.css$/ }, async ({ path: file }) => file === stylesheetFile
+                ? {
+                    contents: written === undefined
+                        ? PLACEHOLDER
+                        : (await session()).stylesheet(Boolean(build.initialOptions.minify)),
+                    loader: "css",
+                    watchFiles: [live],
+                }
+                : undefined);
+            build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, async ({ path: file }) => {
+                const compiler = await session();
+                if (!compiler.compiles(file))
+                    return undefined;
+                const code = await readFile(file, "utf8");
+                if (!shouldCompile(file, code, compiler.libraries))
+                    return undefined;
+                const result = compiler.transform(file, code);
+                reporter.module(context, file, code, result.diagnostics);
+                if (result.code === undefined)
+                    return undefined;
+                return {
+                    contents: result.code,
+                    loader: LOADERS[file.slice(file.lastIndexOf(".") + 1)] ?? "js",
+                };
+            });
+            build.onEnd(async (result) => {
+                const compiler = await session();
+                reporter.project(context, root, compiler.diagnostics());
+                const css = compiler.stylesheet(Boolean(build.initialOptions.minify));
+                if (css !== written) {
+                    written = css;
+                    await writeFile(live, css);
+                }
+                if (result.outputFiles) {
+                    result.outputFiles.forEach((file, index) => {
+                        const source = file.path.endsWith(".css")
+                            ? fillStylesheet(file.text, css)
+                            : undefined;
+                        if (source !== undefined)
+                            result.outputFiles[index] = outputFile(file, source);
+                    });
+                    return;
+                }
+                const base = build.initialOptions.absWorkingDir ?? process.cwd();
+                for (const output of Object.keys(result.metafile.outputs)) {
+                    const file = path.resolve(base, output);
+                    if (!file.endsWith(".css") || !existsSync(file))
+                        continue;
+                    const source = fillStylesheet(await readFile(file, "utf8"), css);
+                    if (source !== undefined)
+                        await writeFile(file, source);
+                }
+            });
+        },
+    };
+}