@codenhub/styles 0.7.0 → 0.9.0

package/dist/cli.js

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+// src/cli/purge.ts
+const GROUPS = /* @__PURE__ */ new Set([
+	"@media",
+	"@supports",
+	"@layer",
+	"@container",
+	"@scope",
+	"@starting-style"
+]);
+const IDENT = /^(?:\\[0-9a-fA-F]{1,6}\s?|\\.|[\w-]|\P{ASCII})+/u;
+const ANY_OF = /* @__PURE__ */ new Set([
+	"is",
+	"where",
+	"has"
+]);
+/** Returns the index just past the string or comment that starts at `index`, or `index` when none does. */
+function skipInert(css, index) {
+	const char = css[index];
+	if (char === "\"" || char === "'") {
+		for (let i = index + 1; i < css.length; i++) if (css[i] === "\\") i++;
+		else if (css[i] === char) return i + 1;
+		return css.length;
+	}
+	if (char === "/" && css[index + 1] === "*") {
+		const end = css.indexOf("*/", index + 2);
+		return end === -1 ? css.length : end + 2;
+	}
+	return index;
+}
+/** Returns the index of the first `stop` character at bracket depth zero from `from`, or `end` when there is none. */
+function findTop(css, from, end, stop) {
+	let depth = 0;
+	for (let i = from; i < end; i++) {
+		const next = skipInert(css, i);
+		if (next !== i) {
+			i = next - 1;
+			continue;
+		}
+		const char = css[i];
+		if (char === "\\") i++;
+		else if (depth === 0 && stop.includes(char)) return i;
+		else if (char === "(" || char === "[" || char === "{") depth++;
+		else if (char === ")" || char === "]" || char === "}") depth--;
+	}
+	return end;
+}
+function splitTop(text, separator) {
+	const parts = [];
+	let from = 0;
+	while (from <= text.length) {
+		const at = findTop(text, from, text.length, separator);
+		parts.push(text.slice(from, at));
+		from = at + 1;
+	}
+	return parts;
+}
+function parse(css, start = 0, end = css.length) {
+	const nodes = [];
+	let index = start;
+	while (index < end) {
+		let comment = index;
+		while (comment < end && /\s/.test(css[comment])) comment++;
+		if (css.startsWith("/*", comment)) {
+			const after = skipInert(css, comment);
+			nodes.push({
+				kind: "statement",
+				text: css.slice(index, after)
+			});
+			index = after;
+			continue;
+		}
+		const open = findTop(css, index, end, "{;");
+		if (open >= end || css[open] === ";") {
+			nodes.push({
+				kind: "statement",
+				text: css.slice(index, Math.min(open + 1, end))
+			});
+			index = open + 1;
+			continue;
+		}
+		const close = findTop(css, open + 1, end, "}");
+		const prelude = css.slice(index, open);
+		const atRule = /^\s*(@[\w-]+)/.exec(prelude)?.[1];
+		if (atRule !== void 0 && GROUPS.has(atRule)) nodes.push({
+			kind: "group",
+			prelude,
+			children: parse(css, open + 1, close)
+		});
+		else nodes.push({
+			kind: "block",
+			prelude,
+			body: css.slice(open + 1, close),
+			isRule: atRule === void 0
+		});
+		index = close + 1;
+	}
+	return nodes;
+}
+function serialize(nodes) {
+	let css = "";
+	for (const node of nodes) if (node.kind === "statement") css += node.text;
+	else if (node.kind === "group") css += `${node.prelude}{${serialize(node.children)}}`;
+	else css += `${node.prelude}{${node.body}}`;
+	return css;
+}
+/** Writes the tree one declaration to a line, for `--no-minify`. */
+function format(nodes, indent = "") {
+	let css = "";
+	for (const node of nodes) if (node.kind === "statement") css += `${indent}${node.text.trim()}\n`;
+	else if (node.kind === "group") css += `${indent}${node.prelude.trim()} {\n${format(node.children, `${indent}  `)}${indent}}\n`;
+	else if (node.isRule) {
+		const selectors = splitTop(node.prelude, ",").map((selector) => selector.trim());
+		const declarations = splitTop(node.body, ";").filter((declaration) => declaration.trim() !== "");
+		css += `${indent}${selectors.join(`,\n${indent}`)} {\n`;
+		css += declarations.map((declaration) => `${indent}  ${declaration.trim()};\n`).join("");
+		css += `${indent}}\n`;
+	} else css += `${indent}${node.prelude.trim()} { ${node.body} }\n`;
+	return css;
+}
+function unescapeIdent(raw) {
+	return raw.replace(/\\([0-9a-fA-F]{1,6})\s?|\\(.)/g, (_, hex, char) => {
+		if (hex === void 0) return char;
+		const code = Number.parseInt(hex, 16);
+		return code === 0 || code >= 55296 && code <= 57343 || code > 1114111 ? "�" : String.fromCodePoint(code);
+	});
+}
+/**
+* Says whether a selector can match in markup whose classes are all in `used`.
+* Every class the selector requires has to be there. A class inside `:not()` is
+* never required, and of the selectors inside `:is()`, `:where()`, and `:has()`
+* one is enough. `onClass`, when given, is told every class name it reads.
+*/
+function canMatch(selector, used, onClass) {
+	let isMatch = true;
+	for (let i = 0; i < selector.length; i++) {
+		const next = skipInert(selector, i);
+		if (next !== i) {
+			i = next - 1;
+			continue;
+		}
+		const char = selector[i];
+		if (char === "\\") i++;
+		else if (char === "[") i = findTop(selector, i + 1, selector.length, "]");
+		else if (char === ".") {
+			const raw = IDENT.exec(selector.slice(i + 1))?.[0];
+			if (raw !== void 0) {
+				const name = unescapeIdent(raw);
+				onClass?.(name);
+				isMatch &&= used.has(name);
+				i += raw.length;
+			}
+		} else if (char === ":") {
+			const pseudo = /^::?([\w-]+)\(/.exec(selector.slice(i));
+			if (pseudo !== null) {
+				const open = i + pseudo[0].length;
+				const close = findTop(selector, open, selector.length, ")");
+				const branches = splitTop(selector.slice(open, close), ",");
+				if (ANY_OF.has(pseudo[1])) {
+					const results = branches.map((branch) => canMatch(branch, used, onClass));
+					isMatch &&= results.includes(true);
+				} else if (onClass !== void 0) for (const branch of branches) canMatch(branch, used, onClass);
+				i = close;
+			}
+		}
+		if (!isMatch && onClass === void 0) return false;
+	}
+	return isMatch;
+}
+function isLayer(node) {
+	return node.kind === "group" && /^\s*@layer\b/.test(node.prelude);
+}
+function isEmptyLayer(node) {
+	return node.kind === "group" && isLayer(node) && node.children.every(isEmptyLayer);
+}
+/**
+* Returns the tree without the rules that cannot match `used`. A selector list
+* keeps only its selectors that can. A `@layer` block emptied this way stays,
+* because where it first stands fixes the layer's place in the cascade, unless
+* it is all that is left of a `@media` or `@supports` block: those hold a
+* variant's rules, which come after the layer's first block.
+*/
+function purge(nodes, used) {
+	const kept = [];
+	for (const node of nodes) if (node.kind === "group") {
+		const children = purge(node.children, used);
+		if (isLayer(node) ? true : children.some((child) => !isEmptyLayer(child))) kept.push({
+			...node,
+			children
+		});
+	} else if (node.kind === "block" && node.isRule) {
+		const selectors = splitTop(node.prelude, ",").filter((selector) => canMatch(selector, used));
+		if (selectors.length > 0) kept.push({
+			...node,
+			prelude: selectors.join(",")
+		});
+	} else kept.push(node);
+	return kept;
+}
+// src/cli/run.ts
+const BIN = "chs";
+const MIN_NODE_MAJOR = 24;
+const AESTHETIC_EXPORT = /^\.\/aesthetics\/([^/]+)$/;
+const PURGE_SOURCE = "dist/purge/index.css";
+const PURGE_CLASSES = "dist/purge/classes.json";
+const USAGE = `Usage: ${BIN} build --content <glob> [--content <glob> ...] --output <file> [options]
+
+Builds a StyleKit stylesheet holding only the classes your templates use.
+
+Options:
+  -c, --content <glob>   Files to scan for class names, relative to the current
+                         directory. Repeat for more globs. Quote each glob.
+  -o, --output <file>    Stylesheet to write. Parent directories are created.
+  --aesthetic <name>     Add an aesthetic: {names}. Repeatable.
+  --no-minify            Write readable CSS instead of minified CSS.
+  --help                 Show this help.
+  --version              Show the version.`;
+async function run(argv, io) {
+	try {
+		const parsed = parseCommandLine(argv);
+		if (parsed === "help") io.stdout(USAGE.replace("{names}", readAestheticNames().join(", ")));
+		else if (parsed === "version") io.stdout(readManifest().version);
+		else {
+			const output = await build(parsed, io);
+			const { size } = await fs.stat(output);
+			io.stdout(`${output} ${size} bytes`);
+		}
+		return 0;
+	} catch (error) {
+		io.stderr(`${BIN}: ${error instanceof Error ? error.message : String(error)}`);
+		return 1;
+	}
+}
+function parseCommandLine(argv) {
+	const { values, positionals } = parseFlags(argv);
+	if (values.help) return "help";
+	if (values.version) return "version";
+	const [command, ...extra] = positionals;
+	if (command === void 0) throw new Error(`missing command; run "${BIN} build --content <glob> --output <file>".`);
+	if (command !== "build") throw new Error(`unknown command "${command}"; the only command is "build".`);
+	if (extra.length > 0) throw new Error(`unexpected argument "${extra[0]}"; quote each --content glob so the shell does not expand it, as in --content "app/views/**/*.erb".`);
+	if (!values.content?.length) throw new Error(`missing --content; name the templates to scan, as in --content "app/views/**/*.erb".`);
+	const output = values.output?.trim();
+	if (!output) throw new Error("missing --output; name the stylesheet to write, as in --output public/app.css.");
+	return {
+		contentGlobs: values.content,
+		output,
+		aesthetics: [...new Set(values.aesthetic ?? [])],
+		shouldMinify: !values["no-minify"]
+	};
+}
+function parseFlags(argv) {
+	try {
+		return parseArgs({
+			args: [...argv],
+			allowPositionals: true,
+			options: {
+				content: {
+					type: "string",
+					short: "c",
+					multiple: true
+				},
+				output: {
+					type: "string",
+					short: "o"
+				},
+				aesthetic: {
+					type: "string",
+					multiple: true
+				},
+				"no-minify": { type: "boolean" },
+				help: { type: "boolean" },
+				version: { type: "boolean" }
+			}
+		});
+	} catch (error) {
+		const flag = error instanceof Error ? /'([^']+)'/.exec(error.message)?.[1] : void 0;
+		if (flag === void 0) throw error;
+		const code = error.code;
+		throw new Error(code === "ERR_PARSE_ARGS_UNKNOWN_OPTION" ? `unknown option "${flag}"; run "${BIN} --help" for the options.` : `option "${/--[\w-]+/.exec(flag)?.[0] ?? flag}" is missing its value or does not take one; run "${BIN} --help" for the options.`);
+	}
+}
+async function build(options, io) {
+	assertNodeVersion(io.nodeVersion);
+	const validAesthetics = readAestheticNames();
+	const unknown = options.aesthetics.find((name) => !validAesthetics.includes(name));
+	if (unknown !== void 0) throw new Error(`unknown aesthetic "${unknown}"; choose from ${validAesthetics.join(", ")}.`);
+	const files = new Set((await Promise.all(options.contentGlobs.map((pattern) => findFiles(pattern, io.cwd)))).flat());
+	const contents = [];
+	for (const file of files) contents.push(await fs.readFile(file, "utf8"));
+	const droppable = new Set(JSON.parse(await readPackageFile(PURGE_CLASSES)));
+	const found = new Set(contents.flatMap((content) => findClasses(content, droppable)));
+	const used = { has: (name) => found.has(name) || !droppable.has(name) };
+	const stylesheets = await Promise.all([PURGE_SOURCE, ...options.aesthetics.map((name) => resolveExport(`./aesthetics/${name}`))].map(readPackageFile));
+	const write = options.shouldMinify ? serialize : format;
+	const css = stylesheets.map((stylesheet) => write(purge(parse(stylesheet), used))).join("");
+	const output = path.resolve(io.cwd, options.output);
+	const temporary = `${output}.${process.pid}.tmp`;
+	try {
+		await fs.mkdir(path.dirname(output), { recursive: true });
+		await fs.writeFile(temporary, css);
+		await fs.rename(temporary, output);
+	} catch (error) {
+		await fs.rm(temporary, { force: true }).catch(() => void 0);
+		throw new Error(`cannot write the stylesheet: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return output;
+}
+/** Returns the files a `--content` glob matches, as absolute paths, and fails when there are none. */
+async function findFiles(pattern, cwd) {
+	const files = [];
+	for await (const entry of fs.glob(pattern, {
+		cwd,
+		withFileTypes: true
+	})) if (entry.isFile()) files.push(path.resolve(entry.parentPath, entry.name));
+	if (files.length === 0) throw new Error(`--content "${pattern}" matches no file in ${cwd}; check the path, or run from the project root.`);
+	return files;
+}
+function findClasses(content, known) {
+	return content.split(/[^\w:-]+/).flatMap((word) => known.has(word) ? [word] : word.split(":")).filter((word) => known.has(word));
+}
+function readAestheticNames() {
+	const { exports } = readManifest();
+	return Object.keys(exports).map((subpath) => AESTHETIC_EXPORT.exec(subpath)?.[1]).filter((name) => name !== void 0).sort();
+}
+/** Returns the nearest folder at or above `from` that holds a `package.json`. */
+function findPackageRoot(from) {
+	for (let dir = from;; dir = path.dirname(dir)) {
+		if (existsSync(path.join(dir, "package.json"))) return dir;
+		if (path.dirname(dir) === dir) throw new Error(`cannot find the package.json of @codenhub/styles above ${from}.`);
+	}
+}
+const packageRoot = findPackageRoot(path.dirname(fileURLToPath(import.meta.url)));
+function readManifest() {
+	return JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+}
+function resolveExport(subpath) {
+	return readManifest().exports[subpath].import;
+}
+function readPackageFile(relativePath) {
+	return fs.readFile(path.resolve(packageRoot, relativePath), "utf8");
+}
+function assertNodeVersion(nodeVersion) {
+	if (Number.parseInt(nodeVersion, 10) < MIN_NODE_MAJOR) throw new Error(`this command needs Node.js ${MIN_NODE_MAJOR} or newer; this is Node.js ${nodeVersion}.`);
+}
+// src/cli/cli.ts
+process.exitCode = await run(process.argv.slice(2), {
+	cwd: process.cwd(),
+	nodeVersion: process.versions.node,
+	stdout: (line) => process.stdout.write(`${line}\n`),
+	stderr: (line) => process.stderr.write(`${line}\n`)
+});
+export {};