@kirana-style/webpack 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @kirana-style/webpack
 
-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 webpack 5 adapter for Kirana, which Rspack runs unchanged
+([11-integrations](../../../../spec/11-integrations.md)).
+
+```js
+// webpack.config.js
+import { KiranaPlugin } from "@kirana-style/webpack"
+
+export default {
+  experiments: { css: true }, // or css-loader with mini-css-extract-plugin
+  plugins: [new KiranaPlugin()],
+}
+```
+
+```js
+// next.config.js — Next.js with webpack (`next build --webpack`)
+import { withKirana } from "@kirana-style/webpack/next"
+
+export default withKirana({})
+```
+
+- **Loader.** The plugin registers a `pre` loader for scripts, so `sx` is read before `swc-loader`,
+  `babel-loader` or Next.js compile JSX away.
+- **Stylesheet.** `@kirana-style/core/stylesheet.css` is ordinary CSS to webpack. The plugin writes the
+  finished stylesheet into the emitted asset at `processAssets`' optimize stage — after every module,
+  before the CSS minimizer and before `realContentHash` renames the file by its content.
+- **Several compilers.** Every compiler of a project (Next.js's server, edge and client) shares one
+  compiler session, so atoms from server components reach the client's stylesheet.
+
+Options: `root` (default: the compiler's context), `config`, `reportInfo`. Watch builds rewrite the
+stylesheet; CSS hot updates on the dev server are not implemented yet.

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@kirana-style/webpack",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Kirana for webpack 5 and Rspack: a loader that compiles modules and a plugin that finishes the stylesheet.",
+  "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/webpack"
+  },
+  "bugs": {
+    "url": "https://github.com/kirana-style/kirana/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./loader": {
+      "types": "./src/loader.d.ts",
+      "default": "./src/loader.js"
+    },
+    "./next": {
+      "types": "./src/next.d.ts",
+      "default": "./src/next.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@kirana-style/compiler": "0.1.0",
+    "@kirana-style/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "webpack": "^5.90.0",
+    "@rspack/core": "^2.2.8"
+  },
+  "peerDependenciesMeta": {
+    "webpack": {
+      "optional": true
+    },
+    "@rspack/core": {
+      "optional": true
+    }
+  },
+  "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,64 @@
+import type { KiranaWebpackOptions } from "./session.ts";
+export type { KiranaWebpackOptions } from "./session.ts";
+type Asset = {
+    name: string;
+    source: {
+        source: () => string | Buffer;
+    };
+};
+type Compilation = {
+    warnings: Error[];
+    errors: Error[];
+    getAssets: () => readonly Asset[];
+    updateAsset: (name: string, source: unknown) => void;
+    hooks: {
+        finishModules: {
+            tapPromise: (name: string, hook: (modules: Iterable<unknown>) => Promise<void>) => void;
+        };
+        processAssets: {
+            tapPromise: (options: {
+                name: string;
+                stage: number;
+            }, hook: () => Promise<void>) => void;
+        };
+    };
+};
+/** The part of webpack's and Rspack's compiler the plugin uses. */
+export type Compiler = {
+    context: string;
+    options: {
+        mode?: string;
+        module: {
+            rules: unknown[];
+        };
+    };
+    webpack: {
+        WebpackError: new (message: string) => Error;
+        Compilation: {
+            PROCESS_ASSETS_STAGE_OPTIMIZE: number;
+        };
+        sources: {
+            RawSource: new (source: string) => unknown;
+        };
+    };
+    hooks: {
+        thisCompilation: {
+            tap: (name: string, hook: (compilation: Compilation) => void) => void;
+        };
+        invalid: {
+            tap: (name: string, hook: (file: string | null) => void) => void;
+        };
+        watchRun: {
+            tapPromise: (name: string, hook: () => Promise<void>) => void;
+        };
+        done: {
+            tapPromise: (name: string, hook: () => Promise<void>) => void;
+        };
+    };
+};
+export declare class KiranaPlugin {
+    readonly options: KiranaWebpackOptions;
+    constructor(options?: KiranaWebpackOptions);
+    apply(compiler: Compiler): void;
+}
+export default KiranaPlugin;

package/src/index.js

@@ -0,0 +1,114 @@
+/**
+ * The webpack 5 and Rspack host adapter (KRN-INT-001, KRN-INT-003): a `pre` loader compiles modules,
+ * and the plugin finishes the stylesheet entry. Rspack implements webpack's plugin and loader API,
+ * so one adapter serves both. It never interprets styles (D-028).
+ *
+ * The stylesheet entry is ordinary CSS to the host — native CSS, `css-loader` with
+ * `mini-css-extract-plugin`, Rsbuild's or Next.js's pipeline — so the host names and links it as it
+ * does any stylesheet. The loader answers it with the placeholder rule, and the plugin writes the
+ * finished stylesheet into the emitted asset at `processAssets`' optimize stage: after every module
+ * is built, before the CSS minimizer, and before `realContentHash` renames the file by its real
+ * content (on by default in production in both bundlers).
+ *
+ * Not `rebuildModule` at `finishModules`, which would let the host hash the right content from the
+ * start: Rspack 2 panics ("should have event sender") rebuilding a module under Rsbuild's CSS
+ * extraction.
+ */
+import { fillStylesheet, shouldCompile, stylesheetPath, } from "@kirana-style/compiler/host";
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createSession, sessions } from "./session.js";
+/** The loader, next to this file with the same extension (TypeScript source in the workspace, JavaScript when packed). */
+const LOADER = fileURLToPath(new URL(`./loader${import.meta.url.slice(import.meta.url.lastIndexOf("."))}`, import.meta.url));
+const NAME = "kirana";
+const SCRIPT_FILE = /\.[cm]?[jt]sx?$/;
+export class KiranaPlugin {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    apply(compiler) {
+        const root = this.options.root ?? compiler.context;
+        const stylesheetFile = stylesheetPath(root);
+        const id = createSession(this.options, root, stylesheetFile, compiler.options.mode !== "development");
+        const session = sessions.get(id);
+        const loader = {
+            loader: this.options.loader ?? LOADER,
+            options: { session: id },
+        };
+        compiler.options.module.rules.unshift({
+            enforce: "pre",
+            test: SCRIPT_FILE,
+            // Installed packages pass through the loader untouched unless they are in `libraries`.
+            use: [loader],
+        }, {
+            enforce: "pre",
+            test: (file) => file === stylesheetFile,
+            use: [loader],
+        });
+        // A watch rebuild: modules that read the changed file's tokens or relations compile again.
+        compiler.hooks.invalid.tap(NAME, (file) => {
+            if (file)
+                void session.driver().then((driver) => driver.invalidate(file));
+        });
+        // Watching: the stylesheet entry follows a file the plugin rewrites whenever the stylesheet
+        // changes, outside `node_modules`, which bundlers treat as immutable and do not watch.
+        compiler.hooks.watchRun.tapPromise(NAME, async () => {
+            if (session.live)
+                return;
+            session.live = path.join(tmpdir(), `kirana-${createHash("sha256").update(root).digest("hex").slice(0, 12)}.css`);
+            await writeFile(session.live, "");
+        });
+        compiler.hooks.done.tapPromise(NAME, async () => {
+            if (!session.live)
+                return;
+            const css = (await session.driver()).stylesheet(false);
+            if ((await readFile(session.live, "utf8")) !== css)
+                await writeFile(session.live, css);
+        });
+        compiler.hooks.thisCompilation.tap(NAME, (compilation) => {
+            const { Compilation, sources, WebpackError } = compiler.webpack;
+            compilation.hooks.finishModules.tapPromise(NAME, async (modules) => {
+                const driver = await session.driver();
+                // Modules a persistent cache restored never reached the loader: compile them from disk, so
+                // their atoms are in the stylesheet. Their cached code already names the same classes.
+                for (const module of modules) {
+                    // A module without a file (webpack's runtime) has no `resource`, and is no script.
+                    const file = String(module.resource).split("?")[0];
+                    if (!SCRIPT_FILE.test(file) || session.compiled.has(file))
+                        continue;
+                    const source = await readFile(file, "utf8");
+                    if (!shouldCompile(file, source, driver.libraries))
+                        continue;
+                    driver.transform(file, source);
+                    session.compiled.add(file);
+                }
+                try {
+                    session.reporter.project({
+                        warn: (message) => compilation.warnings.push(new WebpackError(message)),
+                        error: (message) => {
+                            throw new WebpackError(message);
+                        },
+                    }, root, driver.diagnostics());
+                }
+                catch (error) {
+                    compilation.errors.push(error);
+                }
+            });
+            compilation.hooks.processAssets.tapPromise({ name: NAME, stage: Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE }, async () => {
+                const css = (await session.driver()).stylesheet(session.minify);
+                for (const asset of compilation.getAssets()) {
+                    if (!asset.name.endsWith(".css"))
+                        continue;
+                    const source = fillStylesheet(String(asset.source.source()), css);
+                    if (source !== undefined)
+                        compilation.updateAsset(asset.name, new sources.RawSource(source));
+                }
+            });
+        });
+    }
+}
+export default KiranaPlugin;

package/src/loader.d.ts

@@ -0,0 +1,12 @@
+/** The part of webpack's and Rspack's loader context the loader uses. */
+export type LoaderContext = {
+    resourcePath: string;
+    resourceQuery: string;
+    getOptions: () => {
+        session: string;
+    };
+    async: () => (error: Error | null, code?: string, map?: unknown) => void;
+    addDependency: (file: string) => void;
+    emitWarning: (warning: Error) => void;
+};
+export default function kiranaLoader(this: LoaderContext, source: string, map?: unknown): void;

package/src/loader.js

@@ -0,0 +1,51 @@
+/**
+ * The loader half of the webpack and Rspack adapter (KRN-INT-001): it compiles one module, or
+ * answers the stylesheet entry with the placeholder rule the plugin later replaces. The plugin
+ * registers it as a `pre` loader, so it sees the source before any other loader strips types or JSX.
+ */
+import { PLACEHOLDER, shouldCompile } from "@kirana-style/compiler/host";
+import { sessions } from "./session.js";
+export default function kiranaLoader(source, map) {
+    const callback = this.async();
+    const session = sessions.get(this.getOptions().session);
+    if (!session) {
+        callback(new Error("@kirana-style/webpack/loader runs only through the Kirana plugin: add `new KiranaPlugin()` to `plugins`"));
+        return;
+    }
+    const file = this.resourcePath;
+    session
+        .driver()
+        .then((driver) => {
+        // In a build the plugin writes the finished stylesheet into the emitted asset; while watching,
+        // the entry is the live stylesheet (see index.ts).
+        if (file === session.stylesheetFile) {
+            if (session.live) {
+                this.addDependency(session.live);
+                callback(null, driver.stylesheet(false));
+            }
+            else
+                callback(null, PLACEHOLDER);
+            return;
+        }
+        if (!shouldCompile(file + this.resourceQuery, source, driver.libraries)) {
+            callback(null, source, map);
+            return;
+        }
+        const result = driver.transform(file, source);
+        session.compiled.add(file);
+        for (const dependency of result.dependencies)
+            this.addDependency(dependency);
+        session.reporter.module({
+            warn: (message) => this.emitWarning(new Error(message)),
+            error: (message) => {
+                throw new Error(message);
+            },
+        }, file, source, result.diagnostics);
+        if (result.code === undefined)
+            callback(null, source, map);
+        // An object, as loaders pass maps to each other: Next.js's SWC loader encodes a string again.
+        else
+            callback(null, result.code, result.map && JSON.parse(result.map));
+    })
+        .catch((error) => callback(error));
+}

package/src/next.d.ts

@@ -0,0 +1,13 @@
+import type { KiranaWebpackOptions } from "./session.ts";
+type WebpackConfig = {
+    plugins?: unknown[];
+};
+type NextContext = {
+    dir: string;
+};
+type NextConfig = {
+    webpack?: (config: WebpackConfig, context: NextContext) => WebpackConfig;
+    [key: string]: unknown;
+};
+export declare function withKirana<Config extends NextConfig>(nextConfig?: Config, options?: KiranaWebpackOptions): Omit<Config, "webpack"> & Required<Pick<NextConfig, "webpack">>;
+export {};

package/src/next.js

@@ -0,0 +1,16 @@
+/**
+ * Next.js with webpack (`next build --webpack`, KRN-INT-003): `withKirana` adds the plugin to every
+ * compiler Next creates — server, client and edge — at the project directory, and keeps any
+ * `webpack` function the configuration already has. For Turbopack, `@kirana-style/next` configures both.
+ */
+import { KiranaPlugin } from "./index.js";
+export function withKirana(nextConfig = {}, options = {}) {
+    return {
+        ...nextConfig,
+        webpack(config, context) {
+            ;
+            (config.plugins ??= []).push(new KiranaPlugin({ root: context.dir, ...options }));
+            return nextConfig.webpack ? nextConfig.webpack(config, context) : config;
+        },
+    };
+}

package/src/session.d.ts

@@ -0,0 +1,48 @@
+/**
+ * What the plugin and the loader share: one Driver per compiler, found by an id the plugin puts in
+ * the loader's options. An id rather than the object, because Rspack hands loader options across its
+ * JavaScript–Rust boundary as data.
+ */
+import { Driver } from "@kirana-style/compiler";
+import type { DriverOptions } from "@kirana-style/compiler";
+import { createReporter } from "@kirana-style/compiler/host";
+import type { KiranaConfig } from "@kirana-style/core/config";
+export type KiranaWebpackOptions = {
+    /** The project root: where `kirana.config.*` and `@kirana-style/core` are found. Default: the compiler's context. */
+    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">;
+    /** The loader's path, in place of this package's (tests: one instance of the loader to measure). */
+    loader?: string;
+};
+export type Session = {
+    root: string;
+    /** `@kirana-style/core/stylesheet.css` as the compiler resolves it. */
+    stylesheetFile: string;
+    minify: boolean;
+    driver: () => Promise<Driver>;
+    reporter: ReturnType<typeof createReporter>;
+    /**
+     * The scripts this process's loader compiled. A persistent cache (`cache: { type: "filesystem" }`,
+     * which Meteor turns on) hands back a module without running loaders, so the plugin compiles the
+     * rest from disk before it writes the stylesheet.
+     */
+    compiled: Set<string>;
+    /**
+     * Set while the compiler watches (a dev server, `--watch`): the stylesheet entry then holds the
+     * live stylesheet and depends on this file, which the plugin rewrites when the stylesheet changes
+     * so the bundler rebuilds the entry and sends its own CSS hot update (KRN-INT-009).
+     */
+    live?: string;
+};
+/**
+ * Registries live on `globalThis` under registered symbols, because the loader is loaded by the
+ * bundler's own module loader and may be a second instance of this module (a test runner's, or a
+ * duplicated install); every instance must find the same entries.
+ */
+export declare const sessions: Map<string, Session>;
+export declare function createSession(options: KiranaWebpackOptions, root: string, stylesheetFile: string, minify: boolean): string;

package/src/session.js

@@ -0,0 +1,51 @@
+/**
+ * What the plugin and the loader share: one Driver per compiler, found by an id the plugin puts in
+ * the loader's options. An id rather than the object, because Rspack hands loader options across its
+ * JavaScript–Rust boundary as data.
+ */
+import { Driver } from "@kirana-style/compiler";
+import { createReporter } from "@kirana-style/compiler/host";
+/**
+ * Registries live on `globalThis` under registered symbols, because the loader is loaded by the
+ * bundler's own module loader and may be a second instance of this module (a test runner's, or a
+ * duplicated install); every instance must find the same entries.
+ */
+export const sessions = registry("sessions");
+/**
+ * One Driver and one reporter per project — root and configuration — shared by every compiler that
+ * builds it. Next.js runs a server, an edge and a client compiler over one app: a server component is
+ * compiled only by the server compiler while the stylesheet is emitted by the client one, so a Driver
+ * per compiler would leave the client's stylesheet without the server components' atoms. Next.js builds
+ * the server first, so the client's stylesheet, filled at the end of its own build, holds them all.
+ * Sharing also reports a module's warnings once rather than once per compiler.
+ */
+const projects = registry("projects");
+function registry(name) {
+    return (globalThis[Symbol.for(`kirana.webpack.${name}`)] ??= new Map());
+}
+export function createSession(options, root, stylesheetFile, minify) {
+    const id = `kirana-${sessions.size}`;
+    const key = JSON.stringify([
+        root,
+        options.config ?? null,
+        options.reportInfo ?? false,
+    ]);
+    // Injected engines (tests) are never shared, in either direction.
+    let project = options.driver ? undefined : projects.get(key);
+    if (!project) {
+        let driver;
+        project = {
+            driver: () => (driver ??= Driver.create({
+                root,
+                config: options.config,
+                ...options.driver,
+            })),
+            reporter: createReporter(options),
+            compiled: new Set(),
+        };
+        if (!options.driver)
+            projects.set(key, project);
+    }
+    sessions.set(id, { root, stylesheetFile, minify, ...project });
+    return id;
+}