@medicomind/rolldown-compression 2.3.6 → 2.4.0

package/dist/index.mjs

@@ -1,7 +1,6 @@
 import { createRequire } from "node:module";
 import { createHash } from "node:crypto";
 import path from "node:path";
-import { createFilter } from "@rollup/pluginutils";
 import { mkdir, readFile, readdir, stat, unlink, writeFile } from "node:fs/promises";
 //#region ts/options.ts
 /**
@@ -41,6 +40,25 @@ const LOG_LEVELS = [
 	"warn",
 	"info"
 ];
+function toArray(patterns) {
+	if (patterns === void 0) return [];
+	return Array.isArray(patterns) ? patterns : [patterns];
+}
+function createFilter(include, exclude) {
+	const includes = toArray(include);
+	const excludes = toArray(exclude);
+	const matches = (fileName, pattern) => {
+		if (typeof pattern === "string") return path.matchesGlob(fileName, pattern);
+		pattern.lastIndex = 0;
+		return pattern.test(fileName);
+	};
+	return (fileName) => {
+		if (typeof fileName !== "string" || fileName.includes("\0")) return false;
+		const normalizedFileName = fileName.replaceAll("\\", "/");
+		if (excludes.some((pattern) => matches(normalizedFileName, pattern))) return false;
+		return includes.length === 0 || includes.some((pattern) => matches(normalizedFileName, pattern));
+	};
+}
 /** File extensions produced by this plugin; used by the re-compression guard. */
 const COMPRESSED_EXTENSION_RE = /\.(gz|br|zst)$/i;
 var OptionValidationError = class extends Error {
@@ -114,7 +132,7 @@ function resolveOptions(options = {}) {
 	if (filename !== void 0 && typeof filename !== "string" && typeof filename !== "function") throw new OptionValidationError("invalid filename: expected a string pattern or a function");
 	if (!Array.isArray(algorithms) || algorithms.length === 0) throw new OptionValidationError("invalid algorithms: expected a non-empty array");
 	return {
-		filter: createFilter(include, exclude, { resolve: false }),
+		filter: createFilter(include, exclude),
 		threshold,
 		algorithms: algorithms.map(resolveAlgorithm),
 		filename,
@@ -128,9 +146,46 @@ function resolveOptions(options = {}) {
 	};
 }
 /**
+* Validate a resolved artifact name before anything is emitted or written.
+*
+* A `filename` function is arbitrary user code, so its result is checked the
+* same way a path from outside would be: it has to stay inside the output
+* directory and must not claim the name of the asset it was derived from.
+* Returns the normalized name to use, or the reason it was rejected.
+*/
+function checkArtifactName(outputFileName, sourceFileName, algorithm) {
+	const context = `the filename option resolved "${sourceFileName}" (${algorithm})`;
+	if (typeof outputFileName !== "string" || outputFileName.length === 0) return {
+		ok: false,
+		message: `${context} to ${JSON.stringify(outputFileName)}; expected a non-empty file name relative to the output directory`
+	};
+	if (outputFileName.includes("\0")) return {
+		ok: false,
+		message: `${context} to a name containing a NUL byte`
+	};
+	const normalized = path.posix.normalize(outputFileName.replaceAll("\\", "/"));
+	if (path.posix.isAbsolute(normalized) || /^[a-zA-Z]:/.test(normalized)) return {
+		ok: false,
+		message: `${context} to the absolute path "${outputFileName}"; expected a path relative to the output directory`
+	};
+	if (normalized === ".." || normalized.startsWith("../") || normalized.endsWith("/")) return {
+		ok: false,
+		message: `${context} to "${outputFileName}", which does not name a file inside the output directory`
+	};
+	if (normalized === sourceFileName) return {
+		ok: false,
+		message: `${context} to the same name as the source asset; refusing to overwrite it`
+	};
+	return {
+		ok: true,
+		fileName: normalized
+	};
+}
+/**
 * Resolve the emitted file name for a compressed artifact.
 *
-* Supported tokens: `[path]`, `[base]`, `[name]`, `[ext]`, `[hash]`.
+* Supported tokens: `[path]`, `[base]`, `[name]`, `[ext]`, `[hash]`. The
+* result is not validated here — see {@link checkArtifactName}.
 */
 function resolveOutputFileName(filename, fileName, algorithm, source) {
 	if (typeof filename === "function") return filename(fileName, algorithm.algorithm);
@@ -165,49 +220,69 @@ const compressBuffers = createRequire(import.meta.url)("../index.js").compressBu
 * {@link STREAM_DEFAULT_CHUNK_SIZE} when `chunkSize` is 0 — so the whole
 * build is never held in memory and assets written to disk by other
 * plugins' `writeBundle` hooks are compressed as well.
+*
+* Rolldown runs the output hooks once per output, so the per-output state
+* below is reset in `renderStart` rather than shared across a whole build.
 */
-const PLUGIN_NAME = "rolldown-compression";
+/**
+* Rolldown asks plugins to be named with a `rolldown-plugin-` prefix so they
+* are recognizable in logs, errors and hook traces.
+*/
+const PLUGIN_NAME = "rolldown-plugin-compression";
+const PACKAGE_NAME = "@medicomind/rolldown-compression";
 /** Source bytes per batch in stream mode when `chunkSize` is 0. */
 const STREAM_DEFAULT_CHUNK_SIZE = 4194304;
-const LOG_PRIORITY = {
-	silent: 0,
-	error: 1,
-	warn: 2,
-	info: 3
-};
-function createLogger(level) {
-	const priority = LOG_PRIORITY[level];
-	const prefix = `[${PLUGIN_NAME}]`;
-	return {
-		info: (message) => {
-			if (priority >= LOG_PRIORITY.info) console.info(`${prefix} ${message}`);
-		},
-		warn: (message) => {
-			if (priority >= LOG_PRIORITY.warn) console.warn(`${prefix} ${message}`);
-		},
-		error: (message) => {
-			if (priority >= LOG_PRIORITY.error) console.error(`${prefix} ${message}`);
-		}
-	};
+/**
+* Slack applied when deciding whether a file on disk was written by the
+* current output. Some filesystems store mtimes at one-second granularity,
+* and the wall clock can drift against them, so a strict comparison would
+* occasionally misread a file the build had just produced as a leftover.
+*/
+const MTIME_SLACK_MS = 2e3;
+/** Concurrent `stat` calls while scanning the output directory. */
+const STAT_CONCURRENCY = 32;
+/** Version of the shipping package, surfaced through `plugin.version`. */
+const PACKAGE_VERSION = readPackageVersion();
+function readPackageVersion() {
+	try {
+		const { version } = createRequire(import.meta.url)("../package.json");
+		return typeof version === "string" ? version : void 0;
+	} catch {
+		return;
+	}
 }
 function toBuffer(source) {
-	return typeof source === "string" ? Buffer.from(source, "utf8") : Buffer.from(source);
+	if (typeof source === "string") return Buffer.from(source, "utf8");
+	if (Buffer.isBuffer(source)) return source;
+	return Buffer.from(source.buffer, source.byteOffset, source.byteLength);
 }
 function formatBytes(bytes) {
 	if (bytes < 1024) return `${bytes} B`;
 	if (bytes < 1048576) return `${(bytes / 1024).toFixed(1)} kB`;
 	return `${(bytes / 1048576).toFixed(2)} MB`;
 }
+function createLogger(context, logLevel) {
+	const verbose = logLevel === "info";
+	const warns = logLevel === "info" || logLevel === "warn";
+	const noop = () => {};
+	return {
+		debug: verbose ? (message) => context.debug?.(message) : noop,
+		info: verbose ? (message) => context.info?.(message) : noop,
+		warn: warns ? (message) => context.warn?.(message) : noop
+	};
+}
 /**
 * Shared batching core: queues per-algorithm tasks, flushes them to the
 * native module and hands successful results to `emit`. Only one batch of
 * source buffers is referenced at a time once a flush trigger is set.
 */
-function createBatchRunner(options, logger, emittedNames, emit, fail) {
+function createBatchRunner({ options, log, emittedNames, isReserved, emit, fail }) {
 	const processedSources = /* @__PURE__ */ new Set();
 	const emittedBySource = /* @__PURE__ */ new Map();
 	const failures = [];
 	const stats = /* @__PURE__ */ new Map();
+	/** Artifact name -> the `source (algorithm)` that claimed it, for collision reporting. */
+	const claimed = /* @__PURE__ */ new Map();
 	const chunkSize = options.chunkSize > 0 ? options.chunkSize : options.stream ? STREAM_DEFAULT_CHUNK_SIZE : 0;
 	let pending = [];
 	let pendingSourceBytes = 0;
@@ -228,7 +303,7 @@ function createBatchRunner(options, logger, emittedNames, emit, fail) {
 				continue;
 			}
 			if (result.skipped) {
-				logger.info(`skipped ${artifact.outputFileName}: ${result.algorithm} output would not be smaller than the original`);
+				log.debug(`skipped ${artifact.outputFileName}: ${result.algorithm} output would not be smaller than the original`);
 				continue;
 			}
 			await emit(artifact, result.data);
@@ -247,8 +322,13 @@ function createBatchRunner(options, logger, emittedNames, emit, fail) {
 	};
 	const addFile = async (fileName, buffer) => {
 		for (const algorithm of options.algorithms) {
-			const outputFileName = resolveOutputFileName(options.filename, fileName, algorithm, buffer);
-			if (outputFileName === fileName) fail(`the filename option resolved "${fileName}" (${algorithm.algorithm}) to the same name as the source asset; refusing to overwrite it`);
+			const check = checkArtifactName(resolveOutputFileName(options.filename, fileName, algorithm, buffer), fileName, algorithm.algorithm);
+			if (!check.ok) return fail(check.message);
+			const outputFileName = check.fileName;
+			const owner = claimed.get(outputFileName);
+			if (owner !== void 0) fail(`both ${owner} and ${fileName} (${algorithm.algorithm}) resolve to the artifact "${outputFileName}"; make the filename option depend on the algorithm`);
+			if (isReserved(outputFileName)) fail(`the artifact "${outputFileName}" for ${fileName} (${algorithm.algorithm}) would overwrite a file this build already owns`);
+			claimed.set(outputFileName, `${fileName} (${algorithm.algorithm})`);
 			pending.push({
 				task: {
 					fileName,
@@ -275,12 +355,12 @@ function createBatchRunner(options, logger, emittedNames, emit, fail) {
 		stats
 	};
 }
-function logSummary(logger, stats, startedAt) {
+function formatSummary(stats, startedAt) {
 	const summary = [...stats.entries()].map(([algorithm, stat]) => `${algorithm}: ${stat.count} file(s), ${formatBytes(stat.originalBytes)} -> ${formatBytes(stat.outputBytes)}`).join("; ");
-	if (summary.length === 0) return;
+	if (summary.length === 0) return void 0;
 	const totalSaved = [...stats.values()].reduce((sum, stat) => sum + (stat.originalBytes - stat.outputBytes), 0);
 	const elapsedMs = performance.now() - startedAt;
-	logger.info(`${summary}; saved ${formatBytes(totalSaved)} in ${(elapsedMs / 1e3).toFixed(2)}s`);
+	return `${summary}; saved ${formatBytes(totalSaved)} in ${(elapsedMs / 1e3).toFixed(2)}s`;
 }
 /** Recursively list every file under `root`, in a deterministic order. */
 async function walkFiles(root) {
@@ -297,26 +377,133 @@ async function walkFiles(root) {
 	await visit(root);
 	return files;
 }
+/** Run `task` over `items` with at most `limit` in flight, preserving order. */
+async function mapConcurrent(items, limit, task) {
+	const results = new Array(items.length);
+	let next = 0;
+	const worker = async () => {
+		for (let index = next++; index < items.length; index = next++) results[index] = await task(items[index]);
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+	return results;
+}
+/**
+* Every file under `outDir` eligible for compression, each tagged with whether
+* this build produced it.
+*
+* Compression stays deliberately broad — whatever is in the output directory
+* and matches the filter gets compressed, which is the point of stream mode.
+* Deletion does not: removing a file is not undoable, so it is restricted to
+* files the build owns and never reaches leftovers from an earlier build in a
+* directory that was not emptied.
+*/
+async function collectStreamSources(outDir, bundleNames, writtenSinceMs, options, emittedNames) {
+	const absolutePaths = await walkFiles(outDir);
+	const infos = await mapConcurrent(absolutePaths, STAT_CONCURRENCY, async (absolute) => {
+		try {
+			return await stat(absolute);
+		} catch {
+			return;
+		}
+	});
+	const sources = [];
+	for (const [index, absolute] of absolutePaths.entries()) {
+		const info = infos[index];
+		if (info === void 0) continue;
+		const fileName = path.relative(outDir, absolute).split(path.sep).join("/");
+		if (!options.filter(fileName)) continue;
+		if (COMPRESSED_EXTENSION_RE.test(fileName) || emittedNames.has(fileName)) continue;
+		if (info.size < options.threshold) continue;
+		sources.push({
+			fileName,
+			absolute,
+			size: info.size,
+			ownedByBuild: bundleNames.has(fileName) || info.mtimeMs >= writtenSinceMs
+		});
+	}
+	return sources;
+}
+/**
+* Split sources into read groups that mirror the batch boundaries
+* {@link createBatchRunner} would pick, so a group can be read concurrently
+* without ever holding more than one batch of file contents in memory.
+*/
+function* groupBySize(sources, maxBytes) {
+	let group = [];
+	let bytes = 0;
+	for (const source of sources) {
+		group.push(source);
+		bytes += source.size;
+		if (bytes >= maxBytes) {
+			yield group;
+			group = [];
+			bytes = 0;
+		}
+	}
+	if (group.length > 0) yield group;
+}
 function createCompressionPlugin(options) {
-	const logger = createLogger(options.logLevel);
 	const emittedNames = /* @__PURE__ */ new Set();
-	return Object.assign({
+	/**
+	* Wall-clock start of the current output. Stream mode compares file mtimes
+	* against it to tell what this build wrote from what it merely found in the
+	* output directory, which is what `deleteOriginalAssets` is allowed to touch.
+	*/
+	let outputStartedAtMs;
+	/** `deleteOriginalAssets` removing a chunk is worth saying once, not every build. */
+	let chunkDeletionWarned = false;
+	const warnDeletedChunks = (names, log) => {
+		if (names.length === 0 || chunkDeletionWarned) return;
+		chunkDeletionWarned = true;
+		const sample = names.slice(0, 3).join(", ");
+		log.warn(`deleteOriginalAssets removed ${names.length} chunk(s) (${sample}${names.length > 3 ? ", …" : ""}); requests for those paths only resolve if the server rewrites them to the compressed variant, and dynamic imports and source map links still reference the original names`);
+	};
+	const skipsWatchMode = (watchMode, log) => {
+		if (!watchMode || options.enableInWatchMode) return false;
+		log.info("watch mode detected, skipping compression (set enableInWatchMode to opt in)");
+		return true;
+	};
+	const plugin = {
 		name: PLUGIN_NAME,
+		...PACKAGE_VERSION === void 0 ? {} : { version: PACKAGE_VERSION },
+		meta: {
+			packageName: PACKAGE_NAME,
+			...PACKAGE_VERSION === void 0 ? {} : { version: PACKAGE_VERSION },
+			description: "Compresses emitted assets with gzip, brotli and zstd through a native Rust core"
+		},
+		api: {
+			packageName: PACKAGE_NAME,
+			algorithms: options.algorithms.map((algorithm) => algorithm.algorithm),
+			extensions: options.algorithms.map((algorithm) => algorithm.extension),
+			emittedFileNames: () => [...emittedNames]
+		},
+		renderStart() {
+			emittedNames.clear();
+			outputStartedAtMs = Date.now();
+		},
 		async generateBundle(_outputOptions, bundle) {
-			if (options.stream) return;
-			if (this.meta?.watchMode && !options.enableInWatchMode) {
-				logger.info("watch mode detected, skipping compression (set enableInWatchMode to opt in)");
+			if (options.stream) {
+				outputStartedAtMs ??= Date.now();
 				return;
 			}
+			const log = createLogger(this, options.logLevel);
+			if (skipsWatchMode(this.meta?.watchMode, log)) return;
 			const startedAt = performance.now();
 			const fail = (message) => this.error(/* @__PURE__ */ new Error(`[${PLUGIN_NAME}] ${message}`));
-			const runner = createBatchRunner(options, logger, emittedNames, (artifact, data) => {
-				this.emitFile({
-					type: "asset",
-					fileName: artifact.outputFileName,
-					source: data
-				});
-			}, fail);
+			const runner = createBatchRunner({
+				options,
+				log,
+				emittedNames,
+				isReserved: (fileName) => Object.hasOwn(bundle, fileName),
+				emit: (artifact, data) => {
+					this.emitFile({
+						type: "asset",
+						fileName: artifact.outputFileName,
+						source: data
+					});
+				},
+				fail
+			});
 			for (const [fileName, output] of Object.entries(bundle)) {
 				if (!options.filter(fileName)) continue;
 				if (COMPRESSED_EXTENSION_RE.test(fileName) || emittedNames.has(fileName)) continue;
@@ -327,54 +514,90 @@ function createCompressionPlugin(options) {
 			await runner.flush();
 			if (runner.processedSources.size === 0) return;
 			if (runner.failures.length > 0) fail(`${runner.failures.length} compression task(s) failed:\n${runner.failures.join("\n")}`);
-			if (options.deleteOriginalAssets) for (const fileName of runner.processedSources) {
-				if ((runner.emittedBySource.get(fileName) ?? 0) === 0) logger.warn(`deleteOriginalAssets removed "${fileName}" even though no compressed variant was emitted for it`);
-				delete bundle[fileName];
+			if (options.deleteOriginalAssets) {
+				const deletedChunks = [];
+				for (const fileName of runner.processedSources) {
+					if ((runner.emittedBySource.get(fileName) ?? 0) === 0) {
+						log.warn(`kept "${fileName}": deleteOriginalAssets only removes an asset once a compressed variant of it exists`);
+						continue;
+					}
+					if (bundle[fileName]?.type === "chunk") deletedChunks.push(fileName);
+					delete bundle[fileName];
+				}
+				warnDeletedChunks(deletedChunks, log);
 			}
-			logSummary(logger, runner.stats, startedAt);
+			const summary = formatSummary(runner.stats, startedAt);
+			if (summary !== void 0) log.info(summary);
 		},
 		writeBundle: {
 			order: "post",
-			async handler(outputOptions) {
+			async handler(outputOptions, bundle) {
 				if (!options.stream) return;
-				if (this.meta?.watchMode && !options.enableInWatchMode) {
-					logger.info("watch mode detected, skipping compression (set enableInWatchMode to opt in)");
-					return;
-				}
+				const log = createLogger(this, options.logLevel);
+				if (skipsWatchMode(this.meta?.watchMode, log)) return;
 				const outDir = outputOptions.dir !== void 0 ? path.resolve(outputOptions.dir) : outputOptions.file !== void 0 ? path.resolve(path.dirname(outputOptions.file)) : void 0;
 				if (outDir === void 0) {
-					logger.warn("stream mode could not determine the output directory, skipping compression");
+					log.warn("stream mode could not determine the output directory, skipping compression");
 					return;
 				}
 				const startedAt = performance.now();
 				const fail = (message) => this.error(/* @__PURE__ */ new Error(`[${PLUGIN_NAME}] ${message}`));
-				const runner = createBatchRunner(options, logger, emittedNames, async (artifact, data) => {
-					const target = path.join(outDir, artifact.outputFileName);
-					await mkdir(path.dirname(target), { recursive: true });
-					await writeFile(target, data);
-				}, fail);
-				for (const absolute of await walkFiles(outDir)) {
-					const fileName = path.relative(outDir, absolute).split(path.sep).join("/");
-					if (!options.filter(fileName)) continue;
-					if (COMPRESSED_EXTENSION_RE.test(fileName) || emittedNames.has(fileName)) continue;
-					if ((await stat(absolute)).size < options.threshold) continue;
-					await runner.addFile(fileName, await readFile(absolute));
+				const sources = await collectStreamSources(outDir, new Set(Object.keys(bundle ?? {})), outputStartedAtMs === void 0 ? -Infinity : outputStartedAtMs - MTIME_SLACK_MS, options, emittedNames);
+				const sourceNames = new Set(sources.map((source) => source.fileName));
+				const ownedNames = new Set(sources.filter((source) => source.ownedByBuild).map((source) => source.fileName));
+				const runner = createBatchRunner({
+					options,
+					log,
+					emittedNames,
+					isReserved: (fileName) => sourceNames.has(fileName),
+					emit: async (artifact, data) => {
+						const target = path.join(outDir, artifact.outputFileName);
+						await mkdir(path.dirname(target), { recursive: true });
+						await writeFile(target, data);
+					},
+					fail
+				});
+				const batchBytes = options.chunkSize > 0 ? options.chunkSize : STREAM_DEFAULT_CHUNK_SIZE;
+				for (const group of groupBySize(sources, batchBytes)) {
+					const buffers = await mapConcurrent(group, group.length, (source) => readFile(source.absolute));
+					for (const [index, source] of group.entries()) await runner.addFile(source.fileName, buffers[index]);
 				}
 				await runner.flush();
 				if (runner.processedSources.size === 0) return;
 				if (runner.failures.length > 0) fail(`${runner.failures.length} compression task(s) failed:\n${runner.failures.join("\n")}`);
-				if (options.deleteOriginalAssets) for (const fileName of runner.processedSources) {
-					if ((runner.emittedBySource.get(fileName) ?? 0) === 0) logger.warn(`deleteOriginalAssets removed "${fileName}" even though no compressed variant was emitted for it`);
-					await unlink(path.join(outDir, fileName));
+				if (options.deleteOriginalAssets) {
+					const deletedChunks = [];
+					for (const fileName of runner.processedSources) {
+						if ((runner.emittedBySource.get(fileName) ?? 0) === 0) {
+							log.warn(`kept "${fileName}": deleteOriginalAssets only removes an asset once a compressed variant of it exists`);
+							continue;
+						}
+						if (!ownedNames.has(fileName)) {
+							log.warn(`kept "${fileName}": deleteOriginalAssets only removes files this build wrote to the output directory`);
+							continue;
+						}
+						if (bundle?.[fileName]?.type === "chunk") deletedChunks.push(fileName);
+						await unlink(path.join(outDir, fileName));
+					}
+					warnDeletedChunks(deletedChunks, log);
 				}
-				logSummary(logger, runner.stats, startedAt);
+				const summary = formatSummary(runner.stats, startedAt);
+				if (summary !== void 0) log.info(summary);
 			}
 		}
-	}, { apply: "build" });
+	};
+	plugin.apply = "build";
+	return plugin;
 }
 //#endregion
 //#region ts/index.ts
 /**
+* @medicomind/rolldown-compression
+*
+* Rolldown plugin that compresses emitted assets with gzip, brotli and zstd
+* using a native Rust core (napi-rs + rayon).
+*/
+/**
 * Create the compression plugin.
 *
 * Options are validated eagerly: invalid levels, algorithm names, thresholds