blogger-hbs 0.0.4 → 0.0.6

package/README.md

@@ -8,7 +8,8 @@ Build Blogger themes from Handlebars templates, with bundled scripts and styles.
 - Split a theme into templates with `{{import "./header.hbs"}}`, data with `{{import "./data.json"}}`.
 - Import scripts and styles, bundled with [Rsbuild](https://rsbuild.rs) and inlined: `{{import "./main.ts"}}`.
 - Every template is validated as XML, and the rendered theme is validated and formatted as Blogger saves it.
-- Compile plugins provide partials and data, runtime plugins provide helpers.
+- Plugins provide partials, data and helpers, bundled into the theme.
+- The compiled theme renders in any JavaScript runtime, a Cloudflare Worker too, with `blogger-hbs/runtime`.
 
 ## Usage
 
@@ -18,139 +19,32 @@ pnpm add -D blogger-hbs
 
 ```ts
 // blogger-hbs.config.ts
-import { defineConfig } from 'blogger-hbs';
+import { defineConfig } from "blogger-hbs";
 
 export default defineConfig({
-	entry: 'src/index.hbs',
-	alias: { '~': 'src' },
-	context: {},
+  entry: "src/index.hbs",
+  alias: { "~": "src" },
+  context: {},
 });
 ```
 
 ```sh
-blogger-hbs          # build to dist/theme.xml
-blogger-hbs --watch  # build again on changes
-blogger-hbs --help   # all the options
+blogger-hbs                              # build to dist/theme.xml
+blogger-hbs --watch                      # build again on changes
+blogger-hbs validate theme.xml           # validate a theme
+blogger-hbs format theme.xml -o out.xml  # format it
+blogger-hbs --help                       # all the options
 ```
 
 The same is available from JavaScript with `compileTemplate`, `watchTemplate` and `renderTemplate`.
 
-## Rendering anywhere
+## Documentation
 
-The build writes `dist/compiled.js`, an ES module that imports nothing: the templates, scripts, styles and the runtimes of the plugins are all in it. `blogger-hbs/runtime` renders it in any JavaScript runtime (Node.js, Deno, Bun, Cloudflare Workers, a browser) without the compiler or Node.js.
-
-```ts
-// a Cloudflare Worker
-import { createRenderer } from 'blogger-hbs/runtime';
-import * as theme from './dist/compiled.js';
-
-// set up once, render many times, each render on its own
-const renderer = createRenderer(theme);
-
-export default {
-	async fetch() {
-		const html = await renderer.render({ title: 'Blog' });
-		return new Response(html, { headers: { 'content-type': 'text/html' } });
-	},
-};
-```
-
-`createRenderer(theme, { plugins })` takes runtime plugins of the host rendering the theme, for example with data of the request in `prepare`. The helpers of the theme itself are in `compiled.js`, see [Helpers of the theme](#helpers-of-the-theme). `formatXml` and `validateXml` are in `blogger-hbs/runtime` as well. A compiled module is rendered by the version of `blogger-hbs` it is compiled with, `createRenderer` checks it.
-
-## Helpers of the theme
-
-Helpers are given by the runtime of a plugin, which is bundled into `compiled.js`: the theme renders with them wherever it is rendered. A plugin of the theme itself only needs a name and its runtime.
-
-```ts
-// blogger-hbs.config.ts
-export default defineConfig({
-	plugins: [{ name: 'theme', runtime: { entry: './src/runtime.ts' } }],
-});
-```
-
-```ts
-// src/runtime.ts
-import { defineRuntimePlugin } from 'blogger-hbs/runtime';
-
-export default defineRuntimePlugin((api) => ({
-	helpers: {
-		upper: (text: string) => text.toUpperCase(),
-	},
-}));
-```
-
-## Plugins
-
-A compile plugin provides partials (`{{> name.partial}}`) and data (`{{@name.value}}`) when compiling, and can come with a runtime half for rendering.
-
-```ts
-import { fileURLToPath } from 'node:url';
-import type { CompilePlugin } from 'blogger-hbs';
-
-export function myPlugin(options: { prefix: string }): CompilePlugin {
-	return {
-		name: 'my',
-		provide({ requests }, plugin) {
-			// every partial used, with where and how: `{{> my.badge size=16}}`
-			for (const { name, usages } of requests) {
-				for (const usage of usages) {
-					if ('color' in usage.hash) {
-						plugin.error(`'color' is not a prop of ${name}`, usage);
-					}
-				}
-			}
-			return Object.fromEntries(
-				requests.map(({ name }) => [name, `<span class='${name}'/>`]),
-			);
-		},
-		// bundled into compiled.js, it can not use Node.js modules
-		runtime: {
-			entry: fileURLToPath(new URL('./runtime.js', import.meta.url)),
-			options: { prefix: options.prefix },
-		},
-	};
-}
-```
-
-```ts
-// runtime.ts, published as runtime.js
-import { defineRuntimePlugin } from 'blogger-hbs/runtime';
-
-export default defineRuntimePlugin((api, options: { prefix: string }) => ({
-	helpers: {
-		greet: (name: string) =>
-			new api.SafeString(`${options.prefix} ${api.escapeExpression(name)}`),
-	},
-	// before every render, can be async, read as `{{@my.posts}}`
-	async prepare(context) {
-		return { posts: [] };
-	},
-	// after every render
-	transform: (html) => html,
-}));
-```
-
-| Hook | When |
-| --- | --- |
-| `buildStart(plugin)` | first, in every compilation, also each time when watching |
-| `preprocess(templates, plugin)` | with every template, their ASTs can be changed |
-| `provide({ partials, requests, templates }, plugin)` | with the partials used, again for those the provided ones use |
-| `finalize({ provided, missing, requests, available }, plugin)` | once, for partials that need all the others |
-| `data({ provided, available, templates }, plugin)` | once, the values are JSON |
-| `buildEnd(plugin, error?)` | last, when the templates are compiled |
-
-### Partials of a plugin
-
-A plugin `my` provides its main partial and any names separated by single dots:
-
-| In a template | Key provided |
-| --- | --- |
-| `{{> my}}`, `{{#> my}}...{{/my}}` | `.` |
-| `{{> my.badge}}` | `badge` |
-| `{{> my.badge.small}}` | `badge.small` |
-
-A name is checked as it is written, `{{> my.}}`, `{{> my..badge}}`, `{{> my.badge.}}` and `{{> my/badge}}` are errors where they are, and a theme can not define an inline partial with a name of a plugin, `{{#*inline "my.badge"}}`. Partials of no plugin are left to Handlebars.
-
-Every hook gets the plugin context: `root`, `entry`, `mode`, `watch`, `resolve(specifier, importer?)` with the aliases, `addWatchFile(file)`, `warn(message, loc?)` and `error(message, loc?)`. `enforce: 'pre'` or `'post'` runs a plugin before or after the others.
-
-The runtime halves of all the plugins are bundled together, a module they share (a dependency of two plugins) is in `compiled.js` once and is the same instance for both. The runtime half is set up with `api` (`SafeString`, `escapeExpression`, `createFrame`, `HelperError`) and the options, which are JSON. Its helpers also work with `renderTemplate`, `prepare` and `transform` need `createRenderer`.
+- [Configuration](./docs/configuration.md): the options of the config and of the CLI.
+- [Templates](./docs/templates.md): importing templates, data, scripts and styles.
+- [Helpers](./docs/helpers.md): the built-in helpers and those of a theme.
+- [Plugins](./docs/plugins.md): partials, data, hooks and runtimes of plugins.
+- [Validation and formatting](./docs/validation.md): what is checked, and how the theme is written.
+- [Rendering anywhere](./docs/rendering.md): `blogger-hbs/runtime` and `createRenderer`.
+- [JavaScript API](./docs/api.md): `compileTemplate`, `watchTemplate` and the others.
+- [Errors](./docs/errors.md): what errors say and how to throw them.

package/dist/cli/index.js

@@ -1,27 +1,34 @@
 import { CompileError } from "../compiler/errors.js";
+import { withLocation } from "../plugins/index.js";
 import { didYouMean } from "../utils/suggest.js";
 import { COMPILE_OPTION_KEYS, assertCompileOptions, assertDirectories, assertEntry, resolvePaths } from "../compiler/options.js";
-import { formatXml, validateXml } from "../xml/format.js";
+import { XmlError, processXml } from "../xml/process.js";
 import { compileTemplate } from "../compiler/compile.js";
 import { watchTemplate } from "../compiler/watch.js";
 import { loadConfig } from "../config.js";
 import { createRenderer } from "../runtime/render.js";
+import { collectStats, formatStats } from "./stats.js";
 import * as path from "node:path";
 import * as fs from "node:fs/promises";
-import { createRequire } from "node:module";
 import { watch } from "node:fs";
 import { styleText } from "node:util";
 import { cac } from "cac";
 //#region src/cli/index.ts
-const { version } = createRequire(import.meta.url)("../../package.json");
-const log = {
-	success: (message) => console.log(`${styleText("green", "✓")} ${message}`),
-	info: (message) => console.log(`${styleText("cyan", "●")} ${message}`),
-	warn: (message) => console.warn(`${styleText("yellow", "⚠")} ${message}`),
-	error: (error) => console.error(`${styleText("red", "✗")} ${formatError(error)}`)
-};
+const { version, license, repository } = JSON.parse(await fs.readFile(new URL("../../package.json", import.meta.url), "utf-8"));
+/** What the CLI prints, with `write`, warnings and errors on stderr. */
+function logTo(write) {
+	return {
+		write,
+		success: (message) => write(`${styleText("green", "✓")} ${message}`),
+		info: (message) => write(`${styleText("cyan", "●")} ${message}`),
+		warn: (message) => console.warn(`${styleText("yellow", "⚠")} ${message}`),
+		error: (error) => console.error(`${styleText("red", "✗")} ${formatError(error)}`)
+	};
+}
+const log = logTo(console.log);
 const cli = cac("blogger-hbs");
 cli.command("[root]", "Compile the template and render it").alias("build").option("-c, --config <file>", "Path of the config file").option("--entry <file>", "Entry template, relative to the root").option("-o, --out-dir <dir>", "Output directory, relative to the root").option("--context <file>", "JSON file with the context to render with").option("-w, --watch", "Build again when a file changes").option("--no-clean", "Keep the files in the output directory").option("--no-validate", "Do not validate the rendered template as XML, nor format it (templates are always validated when compiling)").option("--no-format", "Do not format the rendered template").example("blogger-hbs").example("blogger-hbs --watch").example("blogger-hbs ./theme --entry src/index.hbs --context context.json").action(async (rootArg, rawFlags) => {
+	printHeader();
 	const text = (value) => value === void 0 ? void 0 : String(value);
 	const root = text(rootArg);
 	const flags = {
@@ -34,22 +41,45 @@ cli.command("[root]", "Compile the template and render it").alias("build").optio
 	if (flags.watch) await watchBuild(root, flags);
 	else await build(root, flags);
 });
+cli.command("validate <file>", "Validate a theme as Blogger reads it").option("--json", "Print the result as JSON").example("blogger-hbs validate dist/theme.xml").example("blogger-hbs validate dist/theme.xml --json").action(async (file, flags) => {
+	await processFile(String(file), {
+		format: false,
+		json: flags.json
+	});
+});
+cli.command("format <file>", "Format a theme as Blogger saves it, written to stdout, or to --out").option("-o, --out <file>", "Write it to this file instead of stdout").option("--json", "Print the result as JSON, the theme in it without --out").example("blogger-hbs format theme.xml").example("blogger-hbs format theme.xml -o theme.formatted.xml").action(async (file, flags) => {
+	const out = flags.out === void 0 ? void 0 : String(flags.out);
+	await processFile(String(file), {
+		format: true,
+		out,
+		json: flags.json
+	});
+});
 cli.help();
-cli.version(version);
+cli.globalCommand.versionNumber = version;
+cli.option("-v, --version", "Display the version, the copyright and the license");
+/** Whether the header is printed, so that an error before a command runs prints it too. */
+let headerPrinted = false;
 try {
 	cli.parse(process.argv, { run: false });
-	await cli.runMatchedCommand();
+	if (cli.options.version) await printVersion();
+	else await cli.runMatchedCommand();
 } catch (error) {
+	if (!headerPrinted && !cli.options.json) printHeader(formatsToStdout() ? console.error : console.log);
 	log.error(describeCliError(error));
 	process.exitCode = 1;
 }
+/** Whether the command formats a theme to stdout, which has nothing else on it. */
+function formatsToStdout() {
+	return cli.matchedCommandName === "format" && cli.options.out === void 0;
+}
 /** Adds a suggestion and a pointer to `--help` to the errors of the arguments. */
 function describeCliError(error) {
 	if (!(error instanceof Error) || error.name !== "CACError") return error;
 	const flags = [...cli.commands, cli.globalCommand].flatMap((command) => command.options.flatMap((option) => option.rawName.match(/--[\w-]+/g) ?? []));
 	const unknown = /^Unknown option `(.+)`$/.exec(error.message)?.[1];
 	const hint = unknown ? didYouMean(unknown, flags, "`") : "";
-	return /* @__PURE__ */ new Error(`${error.message}${hint}\n  Run 'blogger-hbs --help' to see the available options`);
+	return /* @__PURE__ */ new Error(`${error.message}${hint}\nRun 'blogger-hbs ${cli.matchedCommandName ? `${cli.matchedCommandName} ` : ""}--help' to see the available options`);
 }
 async function setup(root, flags) {
 	const cwd = process.cwd();
@@ -83,7 +113,8 @@ async function setup(root, flags) {
 		format: flags.format === false ? false : output.format ?? true,
 		clean,
 		context: flags.context ? await readContext(path.resolve(cwd, flags.context), flags.context) : config.context ?? {},
-		publicDir: await resolvePublicDir(resolvedRoot, config.publicDir, outDir)
+		publicDir: await resolvePublicDir(resolvedRoot, config.publicDir, outDir),
+		sizes: /* @__PURE__ */ new Map()
 	};
 }
 /** The public directory, `public` when it exists unless set otherwise. */
@@ -155,7 +186,7 @@ async function build(root, flags) {
 	const start = performance.now();
 	const compiled = await compileTemplate(current.options);
 	log.success(`Compiled in ${elapsed(start)}`);
-	await write(current, compiled);
+	await write(current, compiled, start);
 }
 /** Watches the template and restarts when the config file changes. */
 async function watchBuild(root, flags) {
@@ -167,6 +198,15 @@ async function watchBuild(root, flags) {
 	const start = async () => {
 		let begin = performance.now();
 		let first = true;
+		/** Shown before what a rebuild prints, after the first build. */
+		let divider = "";
+		/** Once, before the first thing a rebuild prints, its output can be the same. */
+		const printDivider = () => {
+			if (divider) {
+				console.log(divider);
+				divider = "";
+			}
+		};
 		try {
 			await copyPublic(current);
 		} catch (error) {
@@ -174,15 +214,20 @@ async function watchBuild(root, flags) {
 		}
 		watcher = await watchTemplate({
 			...current.options,
-			onStart() {
+			onStart({ files }) {
 				begin = performance.now();
+				divider = first ? "" : formatDivider(files);
 			},
 			async onCompile(compiled) {
+				printDivider();
 				log.success(`${first ? "Compiled" : "Rebuilt"} in ${elapsed(begin)}`);
+				await write(current, compiled, begin);
 				first = false;
-				await write(current, compiled);
 			},
-			onError: log.error
+			onError(error) {
+				printDivider();
+				log.error(error);
+			}
 		});
 		for (const file of current.loaded.dependencies) try {
 			const configWatcher = watch(file, () => {
@@ -262,45 +307,225 @@ async function prepareOutDir({ outDir, clean }) {
 * Writes the compiled module and the rendered template, validated and
 * formatted after rendering when enabled.
 */
-async function write(current, compiled) {
-	const { outDir, moduleFile, templateFile, context } = current;
-	if (moduleFile) await fs.writeFile(path.join(outDir, moduleFile), compiled.source);
-	if (!templateFile) return;
+async function write(current, compiled, begin) {
+	const { outDir, moduleFile, templateFile } = current;
+	const written = [];
+	let theme;
+	if (moduleFile) {
+		const file = path.join(outDir, moduleFile);
+		await fs.writeFile(file, compiled.source);
+		written.push({
+			path: path.relative(process.cwd(), file),
+			content: compiled.source
+		});
+	}
+	if (templateFile) {
+		theme = await writeTheme(current, compiled, templateFile);
+		written.unshift(theme.file);
+	}
+	const stats = await collectStats(compiled, written, theme?.info && {
+		...theme.file,
+		info: theme.info
+	});
+	console.log(formatStats(stats, current.sizes, { previousTheme: current.theme }));
+	current.sizes = new Map(stats.files.map(({ path, size }) => [path, size]));
+	current.theme = stats.theme;
+	log.success(`Built in ${elapsed(begin)}`);
+}
+/** `─── 14:32:05 · src/header.hbs +2 ───────`, dim. */
+function formatDivider(files) {
+	const time = (/* @__PURE__ */ new Date()).toLocaleTimeString("en-GB", { hour12: false });
+	const [file, ...others] = files.map((item) => path.relative(process.cwd(), item));
+	const text = `─── ${time}${file ? ` · ${file}${others.length > 0 ? ` +${others.length}` : ""}` : ""} `;
+	return `\n${styleText("dim", text + "─".repeat(Math.max(3, 50 - text.length)))}`;
+}
+/** Renders, validates and formats the theme, as enabled, and writes it. */
+async function writeTheme(current, compiled, templateFile) {
+	const { outDir, context } = current;
 	const file = path.join(outDir, templateFile);
 	const shown = path.relative(process.cwd(), file);
 	let start = performance.now();
 	const rendered = await createRenderer(compiled).render(context);
 	log.success(`Rendered in ${elapsed(start)}`);
+	if (!current.validate) {
+		await fs.writeFile(file, rendered);
+		return { file: {
+			path: shown,
+			content: rendered
+		} };
+	}
 	start = performance.now();
-	let output;
+	let result;
 	try {
-		output = finalizeXml(current, rendered);
+		result = processXml(rendered, {
+			path: shown,
+			format: current.format
+		});
 	} catch (error) {
 		await fs.writeFile(file, rendered);
-		throw new CompileError(`The rendered template ${shown} is not valid XML: ${error.message}`);
+		throw new CompileError("The rendered template is not valid XML", {
+			cause: error,
+			loc: error.loc
+		});
 	}
-	if (current.validate) log.success(`${current.format ? "Formatted" : "Validated"} in ${elapsed(start)}`);
-	await fs.writeFile(file, output);
-	log.success(`Written ${styleText("dim", shown)}`);
+	for (const { message, loc } of result.warnings) log.warn(withLocation(message, loc));
+	log.success(`${current.format ? "Formatted" : "Validated"} in ${elapsed(start)}`);
+	await fs.writeFile(file, result.xml);
+	return {
+		file: {
+			path: shown,
+			content: result.xml
+		},
+		info: result.info
+	};
 }
-/** Validates and formats the rendered template, as enabled. */
-function finalizeXml({ validate, format }, xml) {
-	if (!validate) return xml;
-	if (!format) {
-		validateXml(xml);
-		return xml;
+/**
+* Validates the theme in `file`, and with `format` formats it, written to
+* `out` or to stdout. Warnings are placed in what is written, errors in
+* `file`, and nothing is written when it is not valid.
+*/
+async function processFile(file, { format, out, json }) {
+	if (json) {
+		const report = await reportOf(file, {
+			format,
+			out
+		});
+		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		if (!report.valid) process.exitCode = 1;
+		return;
 	}
-	return formatXml(xml);
+	const toStdout = format && out === void 0;
+	const print = toStdout ? logTo(console.error) : log;
+	if (!toStdout) printHeader(print.write);
+	const start = performance.now();
+	const { result, written } = await processTheme(file, {
+		format,
+		out
+	});
+	for (const { message, loc } of result.warnings) print.warn(withLocation(message, loc));
+	if (!format) print.success(`Validated in ${elapsed(start)}`);
+	else if (out === void 0) process.stdout.write(result.xml);
+	else print.success(`Formatted in ${elapsed(start)}, written to ${written}`);
+}
+/**
+* Reads, processes and, with `out`, writes the theme in `file`. Its
+* warnings and info are placed in what is written, and an error throws.
+*/
+async function processTheme(file, { format, out }) {
+	const shown = path.relative(process.cwd(), path.resolve(file));
+	const xml = await readTheme(file, shown);
+	let result;
+	try {
+		result = processXml(xml, {
+			path: shown,
+			format
+		});
+	} catch (error) {
+		throw new Error(`${shown} is not valid XML`, { cause: error });
+	}
+	const written = !format ? shown : out === void 0 ? "<stdout>" : path.relative(process.cwd(), path.resolve(out));
+	const at = (item) => ({
+		...item,
+		loc: {
+			...item.loc,
+			path: written
+		}
+	});
+	result = {
+		...result,
+		warnings: result.warnings.map(at),
+		info: {
+			...result.info,
+			sections: result.info.sections.map(at),
+			widgets: result.info.widgets.map(at)
+		}
+	};
+	if (format && out !== void 0) {
+		await fs.mkdir(path.dirname(path.resolve(out)), { recursive: true });
+		await fs.writeFile(out, result.xml);
+	}
+	return {
+		result,
+		written
+	};
+}
+async function reportOf(file, { format, out }) {
+	try {
+		const { result, written } = await processTheme(file, {
+			format,
+			out
+		});
+		return {
+			valid: true,
+			warnings: result.warnings,
+			info: result.info,
+			...format && out === void 0 && { xml: result.xml },
+			...format && out !== void 0 && { written }
+		};
+	} catch (error) {
+		const cause = error instanceof Error ? error.cause : void 0;
+		return {
+			valid: false,
+			errors: cause instanceof XmlError ? [...cause.errors] : [{ message: messageOf(error) }]
+		};
+	}
+}
+/** The message of an error and of what caused it, on one line. */
+function messageOf(error) {
+	const messages = [];
+	for (let current = error; current !== void 0;) {
+		messages.push(current instanceof Error ? current.message : String(current));
+		current = current instanceof Error ? current.cause : void 0;
+	}
+	return messages.join(": ");
+}
+/** The text of the theme in `file`, an error saying so when it can not be read. */
+async function readTheme(file, shown) {
+	try {
+		return await fs.readFile(file, "utf-8");
+	} catch (error) {
+		throw new Error(`Can not read ${shown}`, { cause: error });
+	}
+}
+/** The version, the copyright and the license, where the project is, and the runtime. */
+async function printVersion() {
+	printHeader();
+	const notice = await fs.readFile(new URL("../../LICENSE.md", import.meta.url), "utf-8").catch(() => "");
+	const copyright = /^Copyright .*$/m.exec(notice)?.[0];
+	console.log([
+		copyright,
+		`Released under the ${license} License, provided as is, without warranty.`,
+		repository.url,
+		"",
+		`Node.js ${process.version} on ${process.platform}-${process.arch}`
+	].filter((line) => line !== void 0).join("\n"));
+}
+/**
+* A blank line, `blogger-hbs v0.0.4` right-aligned on a cyan line under it,
+* before what a command prints, with `write`.
+*/
+function printHeader(write = console.log) {
+	headerPrinted = true;
+	const text = `blogger-hbs v${version}`;
+	const width = text.length + 2;
+	write(`\n${" ".repeat(width - text.length)}${styleText("bold", "blogger-hbs")} ${styleText("dim", `v${version}`)}\n${styleText("cyan", "─".repeat(width))}`);
 }
 function elapsed(start) {
 	return styleText("yellow", `${Math.round(performance.now() - start)}ms`);
 }
-/** The message of the error and of everything that caused it. */
+/**
+* The message of the error and of everything that caused it, a cause whose
+* message is already in the one before is not repeated. The lines of a
+* message are indented under its first.
+*/
 function formatError(error) {
 	const lines = [];
+	let previous = "";
 	let current = error;
 	while (current !== void 0) {
-		lines.push(current instanceof Error ? `${lines.length === 0 ? "" : "Caused by: "}${current.message}` : String(current));
+		const message = current instanceof Error ? current.message : String(current);
+		if (lines.length === 0 || !previous.includes(message)) lines.push(`${lines.length === 0 ? "" : "Caused by: "}${message.replaceAll("\n", "\n  ")}`);
+		previous = message;
 		current = current instanceof Error ? current.cause : void 0;
 	}
 	return lines.join("\n  ");