@dirwell/core 0.0.1-alpha.1 → 0.0.2

package/dist/index.mjs

@@ -1,9 +1,313 @@
 import { t as copyJsonObject } from "./json-Bvj6xQLq.mjs";
-import { cp, lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { cp, lstat, mkdir, mkdtemp, open, opendir, readFile, readdir, readlink, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { createHash } from "node:crypto";
 import picomatch from "picomatch";
+import ignore from "ignore";
+import { createHash, randomUUID } from "node:crypto";
 import { constants } from "node:fs";
+//#region src/filters.ts
+/** Resolve configuration paths once, before a host changes working directories. */
+function resolveIgnoreFiles(value = [], cwd = process.cwd()) {
+	if (!Array.isArray(value)) throw new TypeError("ignoreFiles must be an array");
+	return value.map((input) => {
+		const file = typeof input === "string" ? { path: input } : input;
+		if (typeof file !== "object" || file === null || Array.isArray(file)) throw new TypeError("ignoreFiles entries must be paths or objects");
+		for (const key of Object.keys(file)) if (![
+			"path",
+			"baseDir",
+			"optional"
+		].includes(key)) throw new TypeError(`Unsupported ignoreFiles key "${key}"`);
+		for (const key of ["path", "baseDir"]) if ((key === "path" || file[key] !== void 0) && (typeof file[key] !== "string" || file[key].length === 0)) throw new TypeError(`ignoreFiles.${key} must be a non-empty string`);
+		if (file.optional !== void 0 && typeof file.optional !== "boolean") throw new TypeError("ignoreFiles.optional must be a boolean");
+		const filename = path.resolve(cwd, file.path);
+		return {
+			path: filename,
+			baseDir: path.resolve(cwd, file.baseDir ?? path.dirname(filename)),
+			optional: file.optional ?? false
+		};
+	});
+}
+async function createIgnoreMatcher(files) {
+	const rules = [];
+	const scopes = /* @__PURE__ */ new Map();
+	let hasRules = false;
+	for (const file of resolveIgnoreFiles(files)) {
+		let contents;
+		try {
+			contents = await readFile(file.path, "utf8");
+		} catch (error) {
+			if (file.optional && error instanceof Error && "code" in error && error.code === "ENOENT") continue;
+			throw error;
+		}
+		const base = await realpath(file.baseDir);
+		if (contents.split(/\r?\n/).some((line) => line.trim() !== "" && !line.startsWith("#"))) hasRules = true;
+		let matcher = scopes.get(base);
+		if (matcher === void 0) {
+			matcher = ignore();
+			scopes.set(base, matcher);
+			rules.push({
+				base,
+				matcher
+			});
+		}
+		matcher.add(contents);
+	}
+	rules.sort((left, right) => left.base.split(path.sep).length - right.base.split(path.sep).length);
+	const matches = (filename, directory) => {
+		let ignored = false;
+		for (const rule of rules) {
+			if (!isWithin(rule.base, filename)) continue;
+			const relative = path.relative(rule.base, filename).split(path.sep).join("/");
+			if (relative === "") continue;
+			const result = rule.matcher.test(relative + (directory ? "/" : ""));
+			if (result.ignored) ignored = true;
+			else if (result.unignored) ignored = false;
+		}
+		return ignored;
+	};
+	return Object.assign(matches, { hasRules });
+}
+function normalizePathPatterns(value, name) {
+	if (value === void 0) return [];
+	const patterns = typeof value === "string" ? [value] : value;
+	if (!Array.isArray(patterns) || patterns.some((pattern) => typeof pattern !== "string" || pattern.length === 0 || pattern.startsWith("/") || /^[A-Za-z]:/.test(pattern) || pattern.startsWith("!") || pattern.includes("\\") || pattern.split("/").some((segment) => segment === "." || segment === ".."))) throw new TypeError(`${name} must contain root-relative glob patterns using forward slashes`);
+	return patterns;
+}
+function isWithin(parent, candidate) {
+	const relative = path.relative(parent, candidate);
+	return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+var SelectionBudgetError = class extends Error {
+	name = "SelectionBudgetError";
+};
+/** Select physical source paths; parent directories remain when a descendant matches. */
+async function selectSourcePaths(sourceDir, outputDir, include, exclude, ignoredPaths = [], ignoreFiles = [], preparedIgnore, budget) {
+	const isIgnored = preparedIgnore ?? await createIgnoreMatcher(ignoreFiles);
+	const canonicalRoot = await realpath(sourceDir);
+	const ignored = ignoredPaths.map((value) => path.resolve(value));
+	const included = normalizePathPatterns(include, "include").map((pattern) => picomatch(pattern, {
+		dot: true,
+		nonegate: true
+	}));
+	const excluded = normalizePathPatterns(exclude, "exclude").map((pattern) => picomatch(pattern, {
+		dot: true,
+		nonegate: true
+	}));
+	const selected = /* @__PURE__ */ new Set([""]);
+	const symlinks = /* @__PURE__ */ new Map();
+	let entries = 0;
+	let directories = 0;
+	async function visit(directory, relativeDir, inheritedInclude) {
+		budget?.signal.throwIfAborted();
+		if (budget) {
+			const physical = await realpath(directory);
+			if (!isWithin(canonicalRoot, physical)) return false;
+			if (path.relative(canonicalRoot, physical).split(path.sep).join("/") !== relativeDir) return false;
+		}
+		if (budget && !await budget.allowPath(relativeDir)) return false;
+		if (budget && ++directories > budget.maxDirectories) throw new SelectionBudgetError("Directory scan budget exceeded");
+		let hasSelected = false;
+		for await (const entry of await opendir(directory)) {
+			budget?.signal.throwIfAborted();
+			if (budget && ++entries > budget.maxEntries) throw new SelectionBudgetError("Entry scan budget exceeded");
+			const absolutePath = path.join(directory, entry.name);
+			if (isWithin(outputDir, absolutePath) || ignored.some((value) => isWithin(value, absolutePath))) continue;
+			const relativePath = path.posix.join(relativeDir, entry.name);
+			if (budget && !await budget.allowPath(relativePath)) continue;
+			const directoryLike = entry.isDirectory();
+			const matches = (matcher) => matcher(relativePath) || directoryLike && matcher(`${relativePath}/`);
+			if (excluded.some(matches) || isIgnored(path.join(canonicalRoot, relativePath), directoryLike)) continue;
+			const includedHere = inheritedInclude || included.some(matches);
+			if (directoryLike) {
+				const hasSelectedChild = await visit(absolutePath, relativePath, includedHere);
+				if (included.length === 0 || includedHere || hasSelectedChild) {
+					selected.add(relativePath);
+					hasSelected = true;
+				}
+			} else if (included.length === 0 || includedHere) {
+				selected.add(relativePath);
+				hasSelected = true;
+				if (entry.isSymbolicLink()) symlinks.set(relativePath, await readlink(absolutePath));
+			}
+		}
+		return hasSelected;
+	}
+	if (!isIgnored(canonicalRoot, true)) await visit(sourceDir, "", false);
+	const mirroredSymlinks = /* @__PURE__ */ new Set();
+	for (const [relativePath, target] of symlinks) {
+		if (path.isAbsolute(target)) continue;
+		const targetPath = path.resolve(sourceDir, path.dirname(relativePath), target);
+		if (!isWithin(sourceDir, targetPath)) continue;
+		const targetRelativePath = path.relative(sourceDir, targetPath).split(path.sep).join("/");
+		if (selected.has(targetRelativePath)) mirroredSymlinks.add(relativePath);
+	}
+	return {
+		selected,
+		symlinks: new Set(symlinks.keys()),
+		mirroredSymlinks
+	};
+}
+//#endregion
+//#region src/validation.ts
+function optionObject(value, name) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+	return value;
+}
+function distance(left, right) {
+	let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+	for (let i = 1; i <= left.length; i++) {
+		const current = [i];
+		for (let j = 1; j <= right.length; j++) current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, previous[j - 1] + (left[i - 1] === right[j - 1] ? 0 : 1));
+		previous = current;
+	}
+	return previous[right.length];
+}
+function optionKeys(value, allowed, name) {
+	for (const key of Object.keys(value)) {
+		if (allowed.includes(key)) continue;
+		const suggestion = allowed.map((candidate) => ({
+			candidate,
+			distance: distance(key, candidate)
+		})).sort((left, right) => left.distance - right.distance).find((item) => item.distance <= 2)?.candidate;
+		throw new TypeError(`Unsupported option "${name}.${key}".${suggestion ? ` Did you mean "${name}.${suggestion}"?` : ` Supported keys: ${allowed.join(", ")}.`}`);
+	}
+}
+function scalar(value, type, name) {
+	if (value !== void 0 && typeof value !== type) throw new TypeError(`${name} must be a ${type}`);
+}
+function choice(value, allowed, name) {
+	if (value !== void 0 && !allowed.includes(value)) throw new TypeError(`${name} must be one of ${allowed.join(", ")}`);
+}
+function positiveInteger(value, name) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) throw new TypeError(`${name} must be a positive safe integer`);
+}
+function validateListingPlan(value) {
+	const plan = optionObject(value, "listing");
+	optionKeys(plan, ["html", "data"], "listing");
+	for (const [key, strategy, size] of [[
+		"html",
+		"paged",
+		"pageSize"
+	], [
+		"data",
+		"blocks",
+		"blockSize"
+	]]) {
+		const section = optionObject(plan[key], `listing.${key}`);
+		optionKeys(section, section.strategy === strategy ? ["strategy", size] : ["strategy"], `listing.${key}`);
+		if (section.strategy !== "all" && section.strategy !== strategy) throw new TypeError(`listing.${key}.strategy must be all or ${strategy}`);
+		if (section.strategy === strategy) positiveInteger(section[size], `listing.${key}.${size}`);
+	}
+}
+function selection(value, name) {
+	for (const key of ["include", "exclude"]) if (value[key] !== void 0 && typeof value[key] !== "string" && (!Array.isArray(value[key]) || value[key].some((item) => typeof item !== "string"))) throw new TypeError(`${name}.${key} must be a string or array of strings`);
+	resolveIgnoreFiles(value.ignoreFiles);
+	scalar(value.entryData, "function", `${name}.entryData`);
+	if (value.sort !== void 0) {
+		const sort = optionObject(value.sort, `${name}.sort`);
+		optionKeys(sort, [
+			"field",
+			"direction",
+			"directoriesFirst",
+			"nameMode"
+		], `${name}.sort`);
+		scalar(sort.directoriesFirst, "boolean", `${name}.sort.directoriesFirst`);
+		choice(sort.field, [
+			"name",
+			"size",
+			"modified"
+		], `${name}.sort.field`);
+		choice(sort.direction, ["asc", "desc"], `${name}.sort.direction`);
+		choice(sort.nameMode, [
+			"natural",
+			"locale",
+			"unicode"
+		], `${name}.sort.nameMode`);
+	}
+}
+function requiredString(value, name) {
+	if (typeof value !== "string" || !value.length) throw new TypeError(`${name} must be a non-empty string`);
+}
+function validateTheme(value, name = "options.theme") {
+	if (value === void 0) throw new TypeError("Core requires an explicit theme");
+	const theme = optionObject(value, name);
+	requiredString(theme.name, `${name}.name`);
+	if (typeof theme.render !== "function") throw new TypeError(`${name}.render must be a function`);
+	scalar(theme.entryData, "function", `${name}.entryData`);
+	scalar(theme.searchIndex, "boolean", `${name}.searchIndex`);
+	if (theme.listing !== void 0) {
+		const listing = optionObject(theme.listing, `${name}.listing`);
+		optionKeys(listing, ["pagination"], `${name}.listing`);
+		if (typeof listing.pagination !== "boolean") throw new TypeError(`${name}.listing.pagination must be a boolean`);
+	}
+}
+const generateKeys = {
+	sourceDir: true,
+	outputDir: true,
+	theme: true,
+	include: true,
+	exclude: true,
+	ignoreFiles: true,
+	sort: true,
+	entryData: true,
+	fileHref: true,
+	dryRun: true,
+	outputPolicy: true,
+	listing: true,
+	metadata: true,
+	base: true,
+	mode: true,
+	mirror: true,
+	outputName: true,
+	urlStrategy: true,
+	symlinks: true
+};
+function validateGenerateOptions(value) {
+	const options = optionObject(value, "options");
+	optionKeys(options, Object.keys(generateKeys), "options");
+	requiredString(options.sourceDir, "options.sourceDir");
+	requiredString(options.outputDir, "options.outputDir");
+	validateTheme(options.theme);
+	selection(options, "options");
+	for (const key of ["fileHref", "metadata"]) scalar(options[key], "function", `options.${key}`);
+	for (const key of ["dryRun", "mirror"]) scalar(options[key], "boolean", `options.${key}`);
+	scalar(options.base, "string", "options.base");
+	choice(options.mode, ["ssg", "mpa"], "options.mode");
+	choice(options.urlStrategy, Object.keys({
+		base: true,
+		"html-base": true,
+		relative: true
+	}), "options.urlStrategy");
+	choice(options.outputPolicy, ["owned", "replace"], "options.outputPolicy");
+	if (options.outputName !== void 0 && typeof options.outputName !== "string" && typeof options.outputName !== "function") throw new TypeError("options.outputName must be a string or function");
+	if (options.listing !== void 0 && typeof options.listing !== "function") validateListingPlan(options.listing);
+	if (options.symlinks !== void 0) {
+		const links = optionObject(options.symlinks, "options.symlinks");
+		optionKeys(links, [
+			"follow",
+			"boundary",
+			"onCycle"
+		], "options.symlinks");
+		scalar(links.follow, "boolean", "options.symlinks.follow");
+		choice(links.boundary, ["root", "anywhere"], "options.symlinks.boundary");
+		choice(links.onCycle, ["error", "skip"], "options.symlinks.onCycle");
+	}
+}
+const serviceKeys = {
+	root: true,
+	include: true,
+	exclude: true,
+	ignoreFiles: true,
+	sort: true,
+	entryData: true
+};
+function validateDirectoryOptions(value) {
+	const options = optionObject(value, "options");
+	optionKeys(options, Object.keys(serviceKeys), "options");
+	requiredString(options.root, "options.root");
+	selection(options, "options");
+}
+//#endregion
 //#region src/filesystem.ts
 function entryKind(stats) {
 	if (stats.isDirectory()) return "directory";
@@ -78,6 +382,7 @@ async function describeEntry({ absolutePath, relativePath, rootRealPath, ancesto
 function projectListingEntry(entry, context) {
 	const link = entry.symlink;
 	return {
+		...entry.publicData === void 0 ? {} : { data: copyJsonObject(entry.publicData) },
 		id: entry.relativePath,
 		name: entry.name,
 		kind: entry.kind,
@@ -94,18 +399,13 @@ function projectListingEntry(entry, context) {
 		}
 	};
 }
-function record(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function positiveInteger(value, key) {
-	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) throw new TypeError(`${key} must be a positive safe integer`);
-}
-function validateListingPlan(value) {
-	if (!record(value) || !record(value.html) || !record(value.data)) throw new TypeError("listing must contain html and data plans");
-	if (value.html.strategy === "paged") positiveInteger(value.html.pageSize, "listing.html.pageSize");
-	else if (value.html.strategy !== "all") throw new TypeError("listing.html.strategy must be \"all\" or \"paged\"");
-	if (value.data.strategy === "blocks") positiveInteger(value.data.blockSize, "listing.data.blockSize");
-	else if (value.data.strategy !== "all") throw new TypeError("listing.data.strategy must be \"all\" or \"blocks\"");
+/** Annotation providers receive public facts, not transport URLs or raw stat objects. */
+function entryDataFacts(entry) {
+	const { href: _href, exitsExplorer: _exits, data: _data, ...facts } = projectListingEntry(entry, {
+		hrefFor: () => null,
+		exitsExplorerFor: () => false
+	});
+	return facts;
 }
 function listingRevision(entries, sort, hrefBase, blockSize) {
 	return createHash("sha256").update(JSON.stringify({
@@ -117,69 +417,87 @@ function listingRevision(entries, sort, hrefBase, blockSize) {
 	})).digest("hex");
 }
 //#endregion
-//#region src/filters.ts
-function normalizePathPatterns(value, name) {
-	if (value === void 0) return [];
-	const patterns = typeof value === "string" ? [value] : value;
-	if (!Array.isArray(patterns) || patterns.some((pattern) => typeof pattern !== "string" || pattern.length === 0 || pattern.startsWith("/") || /^[A-Za-z]:/.test(pattern) || pattern.startsWith("!") || pattern.includes("\\") || pattern.split("/").some((segment) => segment === "." || segment === ".."))) throw new TypeError(`${name} must contain root-relative glob patterns using forward slashes`);
-	return patterns;
-}
-function isWithin(parent, candidate) {
-	const relative = path.relative(parent, candidate);
-	return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
-}
-/** Select physical source paths; parent directories remain when a descendant matches. */
-async function selectSourcePaths(sourceDir, outputDir, include, exclude, ignoredPaths = []) {
-	const ignored = ignoredPaths.map((value) => path.resolve(value));
-	const included = normalizePathPatterns(include, "include").map((pattern) => picomatch(pattern, {
-		dot: true,
-		nonegate: true
-	}));
-	const excluded = normalizePathPatterns(exclude, "exclude").map((pattern) => picomatch(pattern, {
-		dot: true,
-		nonegate: true
-	}));
-	const selected = /* @__PURE__ */ new Set([""]);
-	const symlinks = /* @__PURE__ */ new Map();
-	async function visit(directory, relativeDir, inheritedInclude) {
-		let hasSelected = false;
-		for (const entry of await readdir(directory, { withFileTypes: true })) {
-			const absolutePath = path.join(directory, entry.name);
-			if (isWithin(outputDir, absolutePath) || ignored.some((value) => isWithin(value, absolutePath))) continue;
-			const relativePath = path.posix.join(relativeDir, entry.name);
-			const directoryLike = entry.isDirectory();
-			const matches = (matcher) => matcher(relativePath) || directoryLike && matcher(`${relativePath}/`);
-			if (excluded.some(matches)) continue;
-			const includedHere = inheritedInclude || included.some(matches);
-			if (directoryLike) {
-				const hasSelectedChild = await visit(absolutePath, relativePath, includedHere);
-				if (included.length === 0 || includedHere || hasSelectedChild) {
-					selected.add(relativePath);
-					hasSelected = true;
-				}
-			} else if (included.length === 0 || includedHere) {
-				selected.add(relativePath);
-				hasSelected = true;
-				if (entry.isSymbolicLink()) symlinks.set(relativePath, await readlink(absolutePath));
-			}
-		}
-		return hasSelected;
+//#region src/publication.ts
+const outputMarker = "__dirwell/ownership.json";
+const outputMarkerContents = "{\"type\":\"dirwell-output\",\"version\":1}\n";
+async function lockOutput(output) {
+	const canonical = await canonicalPath(output);
+	const lockPath = path.join(path.dirname(canonical), `.${path.basename(canonical)}-dirwell.lock`);
+	await mkdir(path.dirname(lockPath), { recursive: true });
+	let handle;
+	try {
+		handle = await open(lockPath, "wx");
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "EEXIST") throw new Error(`Output is locked by another build: ${lockPath}. Wait for it to finish. Remove a stale lock only after confirming its owner has stopped; --force does not bypass locks.`);
+		throw error;
 	}
-	await visit(sourceDir, "", false);
-	const mirroredSymlinks = /* @__PURE__ */ new Set();
-	for (const [relativePath, target] of symlinks) {
-		if (path.isAbsolute(target)) continue;
-		const targetPath = path.resolve(sourceDir, path.dirname(relativePath), target);
-		if (!isWithin(sourceDir, targetPath)) continue;
-		const targetRelativePath = path.relative(sourceDir, targetPath).split(path.sep).join("/");
-		if (selected.has(targetRelativePath)) mirroredSymlinks.add(relativePath);
+	try {
+		await handle.writeFile(JSON.stringify({ pid: process.pid }));
+	} catch (error) {
+		await handle.close();
+		await rm(lockPath);
+		throw error;
 	}
 	return {
-		selected,
-		symlinks: new Set(symlinks.keys()),
-		mirroredSymlinks
+		lockPath,
+		async release() {
+			await handle.close();
+			await rm(lockPath);
+		}
 	};
 }
+async function canonicalPath(filename) {
+	try {
+		return await realpath(filename);
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+		const parent = path.dirname(filename);
+		if (parent === filename) throw error;
+		return path.join(await canonicalPath(parent), path.basename(filename));
+	}
+}
+/** Force permits output ownership replacement, never source containment violations. */
+async function checkOutput(source, output, policy = "owned") {
+	if (policy !== "owned" && policy !== "replace") throw new TypeError("outputPolicy must be owned or replace");
+	if (isInsideRoot(await canonicalPath(output), await realpath(source))) throw new Error("outputDir must not contain the sourceDir");
+	let stat;
+	try {
+		stat = await lstat(output);
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+		throw error;
+	}
+	if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("outputDir must be a directory, not a file or symlink");
+	if ((await readdir(output)).length === 0 || policy === "replace") return true;
+	try {
+		const marker = path.join(output, outputMarker);
+		if (!(await lstat(path.dirname(marker))).isSymbolicLink() && !(await lstat(marker)).isSymbolicLink() && await readFile(marker, "utf8") === "{\"type\":\"dirwell-output\",\"version\":1}\n") return true;
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+	}
+	throw new Error("Output is nonempty and not owned by Dirwell. Choose another directory or explicitly replace it with --force (-f) / outputPolicy: 'replace'.");
+}
+/** Keep a recoverable previous tree until the new tree is installed. */
+async function publishOutput(staged, output, source, policy = "owned") {
+	const exists = await checkOutput(source, output, policy);
+	await mkdir(path.dirname(output), { recursive: true });
+	const backup = path.join(path.dirname(output), `.${path.basename(output)}-previous-${randomUUID()}`);
+	if (exists) await rename(output, backup);
+	try {
+		await rename(staged, output);
+	} catch (error) {
+		if (exists) try {
+			await rename(backup, output);
+		} catch (restoreError) {
+			throw new AggregateError([error, restoreError], `Publication failed; previous output is retained at ${backup}`);
+		}
+		throw error;
+	}
+	if (exists) await rm(backup, {
+		recursive: true,
+		force: true
+	});
+}
 //#endregion
 //#region src/generator.ts
 const indexPattern = /^index\.html?$/i;
@@ -250,10 +568,28 @@ async function generateExplorer(options) {
 }
 /** Internal entry point for hosts that stage previews outside their published output. */
 async function generateExplorerSkippingPaths(options, ignoredPaths) {
-	const sourceDir = path.resolve(options.sourceDir);
-	const outputDir = path.resolve(options.outputDir);
+	validateGenerateOptions(options);
+	const source = path.resolve(options.sourceDir), output = path.resolve(options.outputDir);
+	await checkOutput(source, output, options.outputPolicy);
+	if (options.dryRun) return generateExplorerUnlocked(options, ignoredPaths);
+	const lock = await lockOutput(output);
+	const lexicalLock = path.join(path.dirname(output), path.basename(lock.lockPath));
+	try {
+		return await generateExplorerUnlocked(options, [
+			...ignoredPaths,
+			lock.lockPath,
+			lexicalLock
+		]);
+	} finally {
+		await lock.release();
+	}
+}
+async function generateExplorerUnlocked(options, ignoredPaths) {
+	const sourceDir = await realpath(path.resolve(options.sourceDir));
+	const outputDir = await canonicalPath(path.resolve(options.outputDir));
 	const ignoredSourcePaths = ignoredPaths.map((value) => path.resolve(value));
 	const rootRealPath = await realpath(sourceDir);
+	const replacesOutput = await checkOutput(sourceDir, outputDir, options.outputPolicy);
 	const outputName = options.outputName ?? defaultOutputName;
 	const resolveOutputName = typeof outputName === "string" ? () => outputName : outputName;
 	const theme = options.theme;
@@ -264,7 +600,7 @@ async function generateExplorerSkippingPaths(options, ignoredPaths) {
 	const followSymlinks = options.symlinks?.follow ?? false;
 	const boundary = options.symlinks?.boundary ?? "root";
 	const onCycle = options.symlinks?.onCycle ?? "skip";
-	const filtersActive = options.include !== void 0 || options.exclude !== void 0 || ignoredSourcePaths.length > 0;
+	const filtersActive = options.include !== void 0 || options.exclude !== void 0 || (options.ignoreFiles?.length ?? 0) > 0 || ignoredSourcePaths.length > 0;
 	const plans = [];
 	if (isInsideRoot(outputDir, sourceDir)) throw new Error("outputDir must not contain the sourceDir");
 	try {
@@ -274,13 +610,13 @@ async function generateExplorerSkippingPaths(options, ignoredPaths) {
 		if (error instanceof Error && "code" in error && error.code === "ENOENT") {} else throw error;
 	}
 	const outputIsWithinSource = isInsideRoot(sourceDir, outputDir);
-	const selection = await selectSourcePaths(sourceDir, outputDir, options.include, options.exclude, ignoredSourcePaths);
+	const selection = await selectSourcePaths(sourceDir, outputDir, options.include, options.exclude, ignoredSourcePaths, options.ignoreFiles);
 	const stageParent = outputIsWithinSource ? path.dirname(sourceDir) : path.dirname(outputDir);
-	await mkdir(stageParent, { recursive: true });
-	const stagedOutputDir = await mkdtemp(path.join(stageParent, `.${path.basename(outputDir)}-dirwell-`));
+	if (!options.dryRun) await mkdir(stageParent, { recursive: true });
+	const stagedOutputDir = options.dryRun ? null : await mkdtemp(path.join(stageParent, `.${path.basename(outputDir)}-dirwell-`));
 	const buildOutputDir = stagedOutputDir;
 	try {
-		if (options.mirror ?? true) {
+		if (!options.dryRun && (options.mirror ?? true)) {
 			await rm(buildOutputDir, {
 				recursive: true,
 				force: true
@@ -297,7 +633,7 @@ async function generateExplorerSkippingPaths(options, ignoredPaths) {
 			});
 		}
 	} catch (error) {
-		await rm(stagedOutputDir, {
+		if (stagedOutputDir !== null) await rm(stagedOutputDir, {
 			recursive: true,
 			force: true
 		});
@@ -317,14 +653,23 @@ async function generateExplorerSkippingPaths(options, ignoredPaths) {
 			const relativePath = path.relative(rootRealPath, path.join(physicalRealPath, name));
 			return selection.selected.has(relativePath.split(path.sep).join("/"));
 		});
-		const entries = await Promise.all(names.map((name) => describeEntry({
-			absolutePath: path.join(physicalDir, name),
-			relativePath: path.posix.join(logicalDir, name),
-			rootRealPath,
-			ancestors: nextAncestors,
-			followSymlinks,
-			selectedPaths: filtersActive ? selection.selected : null
-		})));
+		const entries = await Promise.all(names.map(async (name) => {
+			const entry = await describeEntry({
+				absolutePath: path.join(physicalDir, name),
+				relativePath: path.posix.join(logicalDir, name),
+				rootRealPath,
+				ancestors: nextAncestors,
+				followSymlinks,
+				selectedPaths: filtersActive ? selection.selected : null
+			});
+			return options.entryData === void 0 ? entry : {
+				...entry,
+				publicData: copyJsonObject(await options.entryData(entryDataFacts(entry), {
+					operation: "build",
+					directoryPath: logicalDir
+				}))
+			};
+		}));
 		entries.sort((left, right) => compareEntries(left, right, options.sort) || (options.listing === void 0 ? 0 : compareUnicode(left.relativePath, right.relativePath)));
 		const describedCurrent = await describeEntry({
 			absolutePath: physicalDir,
@@ -388,6 +733,20 @@ async function generateExplorerSkippingPaths(options, ignoredPaths) {
 	}
 	try {
 		await visit("", sourceDir, /* @__PURE__ */ new Set());
+		const report = {
+			sourceDir,
+			outputDir,
+			theme: theme.name,
+			dryRun: options.dryRun ?? false,
+			mirror: options.mirror ?? true,
+			replacesOutput,
+			selectedPaths: [...selection.selected].filter(Boolean).sort(),
+			pages: plans.map((plan) => ({
+				directory: plan.logicalDir,
+				outputName: plan.outputName
+			}))
+		};
+		if (options.dryRun) return report;
 		const generatedPages = new Map(plans.filter((plan) => plan.outputName !== null).map((plan) => [plan.logicalDir, plan.outputName]));
 		const generatedDirectories = new Set(generatedPages.keys());
 		const pagePathForDirectory = (logicalPath) => {
@@ -406,6 +765,15 @@ async function generateExplorerSkippingPaths(options, ignoredPaths) {
 		const sharedAssets = /* @__PURE__ */ new Map();
 		const rawLinkFiles = /* @__PURE__ */ new Map();
 		const searchEntries = /* @__PURE__ */ new Map();
+		const fileHrefs = /* @__PURE__ */ new Map();
+		const mappedFileHref = (logicalPath) => {
+			if (!fileHrefs.has(logicalPath)) {
+				const href = options.fileHref(logicalPath);
+				if (href !== null && (typeof href !== "string" || href.length === 0 || href.includes("\\") || Array.from(href).some((character) => character.charCodeAt(0) < 32) || !["http:", "https:"].includes(new URL(href, "https://dirwell.invalid/").protocol))) throw new TypeError("fileHref must return a synchronous HTTP(S), root-relative or relative URL, or null");
+				fileHrefs.set(logicalPath, href);
+			}
+			return fileHrefs.get(logicalPath);
+		};
 		for (const { directory, logicalDir } of theme.searchIndex === false ? [] : plans) for (const entry of directory.entries) {
 			if (searchEntries.has(entry.relativePath)) continue;
 			const targetLogicalPath = isUnavailableSymlink(entry) ? null : entry.symlink?.targetRelativePath !== null && entry.symlink !== null ? entry.symlink.targetRelativePath : path.posix.join(logicalDir, entry.name);
@@ -416,7 +784,10 @@ async function generateExplorerSkippingPaths(options, ignoredPaths) {
 				const filename = rawLinkFilename(entry);
 				rawLinkFiles.set(filename, entry.symlink.target);
 				href = `raw-links/${filename}`;
-			} else if (linkedPath !== null) href = linkedPath === "" ? "../" : `../${encodeLogicalPath(linkedPath)}${directoryLike && linkedPath === targetLogicalPath ? "/" : ""}`;
+			} else if (linkedPath !== null) {
+				href = linkedPath === "" ? "../" : `../${encodeLogicalPath(linkedPath)}${directoryLike && linkedPath === targetLogicalPath ? "/" : ""}`;
+				if (!directoryLike && options.fileHref !== void 0) href = mappedFileHref(linkedPath);
+			}
 			searchEntries.set(entry.relativePath, {
 				exitsExplorer: isUnavailableSymlink(entry) || targetLogicalPath !== null && (!directoryLike || !generatedDirectories.has(targetLogicalPath)),
 				href,
@@ -460,6 +831,7 @@ async function generateExplorerSkippingPaths(options, ignoredPaths) {
 				const targetLogicalPath = targetLogicalPathFor(entry);
 				if (targetLogicalPath === null) return null;
 				const directoryLike = entry.kind === "directory" || entry.symlink?.targetKind === "directory";
+				if (!directoryLike && options.fileHref !== void 0) return mappedFileHref(targetLogicalPath);
 				return hrefForLogicalPath(targetLogicalPath, directoryLike);
 			};
 			const baseContext = {
@@ -652,14 +1024,12 @@ async function generateExplorerSkippingPaths(options, ignoredPaths) {
 				version: 3
 			}));
 		}
-		await rm(outputDir, {
-			recursive: true,
-			force: true
-		});
-		await mkdir(path.dirname(outputDir), { recursive: true });
-		await rename(stagedOutputDir, outputDir);
+		await mkdir(path.join(buildOutputDir, "__dirwell"), { recursive: true });
+		await writeFile(path.join(buildOutputDir, outputMarker), outputMarkerContents);
+		await publishOutput(buildOutputDir, outputDir, sourceDir, options.outputPolicy);
+		return report;
 	} finally {
-		await rm(stagedOutputDir, {
+		if (stagedOutputDir !== null) await rm(stagedOutputDir, {
 			recursive: true,
 			force: true
 		});
@@ -692,8 +1062,17 @@ function assertLogicalPath(value) {
 }
 /** Live reads; no watcher, recursive stat snapshot, output tree or implicit cache. */
 async function createDirectoryService(options) {
+	validateDirectoryOptions(options);
 	const root = await realpath(options.root);
-	const selected = async () => options.include === void 0 && options.exclude === void 0 ? null : (await selectSourcePaths(root, path.join(root, "__dirwell"), options.include, options.exclude)).selected;
+	const ignoreFiles = resolveIgnoreFiles(options.ignoreFiles);
+	await createIgnoreMatcher(ignoreFiles);
+	normalizePathPatterns(options.include, "include");
+	normalizePathPatterns(options.exclude, "exclude");
+	const selected = async () => {
+		const matcher = await createIgnoreMatcher(ignoreFiles);
+		if (normalizePathPatterns(options.include, "include").length === 0 && normalizePathPatterns(options.exclude, "exclude").length === 0 && !matcher.hasRules) return null;
+		return (await selectSourcePaths(root, path.join(root, "__dirwell"), options.include, options.exclude, [], ignoreFiles, matcher)).selected;
+	};
 	async function describe(logicalPath, selection) {
 		assertLogicalPath(logicalPath);
 		if (selection !== null && !selection.has(logicalPath)) throw new DirectoryAccessError("Unavailable path");
@@ -715,6 +1094,23 @@ async function createDirectoryService(options) {
 		});
 	}
 	return {
+		async scan(budget) {
+			if (!budget || !Number.isSafeInteger(budget.maxEntries) || budget.maxEntries < 1 || !Number.isSafeInteger(budget.maxDirectories) || budget.maxDirectories < 1 || !(budget.signal instanceof AbortSignal) || typeof budget.allowPath !== "function") throw new TypeError("scan requires positive entry/directory limits, an AbortSignal and allowPath");
+			const selection = (await selectSourcePaths(root, path.join(root, "__dirwell"), options.include, options.exclude, [], ignoreFiles, void 0, budget)).selected;
+			const entries = [];
+			for (const logical of [...selection].sort()) {
+				budget.signal.throwIfAborted();
+				if (!logical) continue;
+				try {
+					const entry = await describe(logical, selection);
+					if (entry.kind === "file" || entry.kind === "directory") entries.push(entry);
+				} catch (error) {
+					if (error instanceof Error && "code" in error && error.code === "ENOENT") continue;
+					throw error;
+				}
+			}
+			return entries;
+		},
 		async resolvePath(logicalPath) {
 			const selection = await selected();
 			const entry = await describe(logicalPath, selection);
@@ -762,12 +1158,20 @@ async function createDirectoryService(options) {
 			if (!isInsideRoot(root, physical)) throw new DirectoryAccessError("Unavailable directory");
 			const names = (await readdir(physical)).filter((name) => logicalPath !== "" || name !== "__dirwell");
 			const entries = (await Promise.all(names.filter((name) => selection === null || selection.has(path.posix.join(logicalPath, name))).map(async (name) => {
+				let entry;
 				try {
-					return await describe(path.posix.join(logicalPath, name), selection);
+					entry = await describe(path.posix.join(logicalPath, name), selection);
 				} catch (error) {
 					if (error instanceof Error && "code" in error && error.code === "ENOENT") return null;
 					throw error;
 				}
+				return options.entryData === void 0 ? entry : {
+					...entry,
+					publicData: copyJsonObject(await options.entryData(entryDataFacts(entry), {
+						operation: "server",
+						directoryPath: logicalPath
+					}))
+				};
 			}))).filter((entry) => entry !== null);
 			entries.sort((left, right) => compareEntries(left, right, options.sort) || (left.relativePath < right.relativePath ? -1 : left.relativePath > right.relativePath ? 1 : 0));
 			return {
@@ -784,6 +1188,6 @@ async function createDirectoryService(options) {
 	};
 }
 //#endregion
-export { DirectoryAccessError, compareEntries, copyJsonObject, createDirectoryService, defaultOutputName, escapeHtml, generateExplorer, generateExplorerSkippingPaths, listingRevision, projectListingEntry, readGeneratedPage, validateListingPlan };
+export { DirectoryAccessError, SelectionBudgetError, compareEntries, copyJsonObject, createDirectoryService, defaultOutputName, escapeHtml, generateExplorer, generateExplorerSkippingPaths, listingRevision, projectListingEntry, readGeneratedPage, resolveIgnoreFiles, validateListingPlan };
 
 //# sourceMappingURL=index.mjs.map