@tenphi/docs 0.1.0

package/dist/content-DStZeziu.js

@@ -0,0 +1,736 @@
+import { normalizeDocsConfig } from "./config/index.js";
+import { cloneAst, parseMarkdown, removeRenderedTitle, serializeMarkdown, stripLeadingBadgeBlock } from "./markdown/index.js";
+import { createHash } from "node:crypto";
+import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import matter from "gray-matter";
+import { glob } from "tinyglobby";
+import { visit } from "unist-util-visit";
+import { homedir } from "node:os";
+import npa from "npm-package-arg";
+import pacote from "pacote";
+//#region src/npm/index.ts
+const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
+const LOCK_FILE = "tasty-docs.lock.json";
+async function resolvePackageLock(requested, options = {}) {
+	const parsed = npa(requested);
+	if (![
+		"tag",
+		"version",
+		"range"
+	].includes(parsed.type)) throw new Error(`Only npm registry package specifiers are supported (received ${parsed.type}).`);
+	const registry = options.registry ?? DEFAULT_REGISTRY;
+	const manifest = await pacote.manifest(requested, {
+		registry,
+		...options.cacheDir ? { cache: options.cacheDir } : {},
+		fullMetadata: true
+	});
+	if (!manifest.name || !manifest.version || !manifest._integrity) throw new Error(`Registry metadata for ${requested} did not include version and integrity.`);
+	return {
+		requested,
+		resolved: `${manifest.name}@${manifest.version}`,
+		registry,
+		integrity: manifest._integrity
+	};
+}
+async function readDocsLock(root) {
+	try {
+		const value = JSON.parse(await readFile(join(root, LOCK_FILE), "utf8"));
+		validateLock(value);
+		return value;
+	} catch (error) {
+		if (isMissing(error)) return void 0;
+		throw error;
+	}
+}
+async function writeDocsLock(root, lock) {
+	validateLock(lock);
+	await writeFile(join(root, LOCK_FILE), `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+}
+function validateLock(lock) {
+	if (lock.schemaVersion !== 1 || !Array.isArray(lock.sources)) throw new Error("Unsupported or invalid tasty-docs.lock.json.");
+	for (const source of lock.sources) {
+		if (!source.requested || !source.resolved || !source.registry || !source.integrity) throw new Error("Every lock source requires requested, resolved, registry, and integrity.");
+		if (npa(source.resolved).type !== "version") throw new Error(`Locked source must use an exact version: ${source.resolved}.`);
+		if (source.vendored && (source.vendored.startsWith("/") || source.vendored.split(/[\\/]/).includes(".."))) throw new Error(`Vendored package path must stay within the project: ${source.vendored}.`);
+	}
+}
+async function materializePackage(source, config, projectRoot) {
+	if (source.vendored) {
+		if (!projectRoot) throw new Error(`Vendored source ${source.resolved} requires a project root.`);
+		const vendored = resolve(projectRoot, source.vendored);
+		if (!inside$1(projectRoot, vendored)) throw new Error(`Vendored package path escapes the project root: ${source.vendored}.`);
+		if ((await readFile(join(vendored, ".tasty-docs-integrity"), "utf8")).trim() !== source.integrity) throw new Error(`Vendored package integrity marker does not match ${source.resolved}.`);
+		await validateExtractedTree(vendored, config);
+		return vendored;
+	}
+	const cacheRoot = resolve(config.cacheDir || join(homedir(), ".cache", "tasty-docs"), "artifacts");
+	const key = createHash("sha256").update(source.integrity).digest("hex");
+	const destination = join(cacheRoot, key);
+	const marker = join(destination, ".tasty-docs-integrity");
+	try {
+		if ((await readFile(marker, "utf8")).trim() === source.integrity) return destination;
+	} catch (error) {
+		if (!isMissing(error)) throw error;
+	}
+	await mkdir(cacheRoot, { recursive: true });
+	const temporary = await mkdtemp(join(cacheRoot, ".extract-"));
+	try {
+		const tarball = await pacote.tarball(source.resolved, {
+			registry: source.registry,
+			integrity: source.integrity,
+			cache: join(cacheRoot, "_cacache")
+		});
+		if (tarball.byteLength > config.maxArtifactBytes) throw new Error(`Package artifact is ${tarball.byteLength} bytes; limit is ${config.maxArtifactBytes}.`);
+		await pacote.extract(source.resolved, temporary, {
+			registry: source.registry,
+			integrity: source.integrity,
+			cache: join(cacheRoot, "_cacache")
+		});
+		await validateExtractedTree(temporary, config);
+		await writeFile(join(temporary, ".tasty-docs-integrity"), `${source.integrity}\n`);
+		await rm(destination, {
+			recursive: true,
+			force: true
+		});
+		await rename(temporary, destination);
+		return destination;
+	} catch (error) {
+		await rm(temporary, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+}
+async function validateExtractedTree(root, config) {
+	let files = 0;
+	let bytes = 0;
+	const pending = [root];
+	while (pending.length > 0) {
+		const directory = pending.pop();
+		if (!directory) break;
+		for (const name of await readdir(directory)) {
+			if (name === ".tasty-docs-integrity") continue;
+			const path = join(directory, name);
+			const info = await lstat(path);
+			const rel = relative(root, path);
+			if (rel.startsWith(`..${sep}`) || rel === "..") throw new Error(`Package path escapes artifact root: ${rel}.`);
+			if (rel.split(sep).length > config.maxPathDepth) throw new Error(`Package path exceeds maximum depth: ${rel}.`);
+			if (info.isSymbolicLink()) throw new Error(`Package symlinks are not allowed: ${rel}.`);
+			if (info.isDirectory()) pending.push(path);
+			else if (info.isFile()) {
+				files += 1;
+				bytes += info.size;
+				if (info.size > config.maxAssetBytes) throw new Error(`Package file exceeds maximum size: ${rel}.`);
+				if (files > config.maxFiles || bytes > config.maxUnpackedBytes) throw new Error("Package exceeds configured file-count or unpacked-size limit.");
+			} else throw new Error(`Unsupported package entry type: ${rel}.`);
+		}
+	}
+}
+async function discoverPackage(root) {
+	const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+	const hints = manifest.tastyDocs;
+	const homeCandidates = [
+		hints?.index,
+		"README.md",
+		"readme.md"
+	].filter((candidate) => Boolean(candidate));
+	let home;
+	for (const candidate of homeCandidates) try {
+		if ((await stat(join(root, candidate))).isFile()) {
+			home = candidate;
+			break;
+		}
+	} catch (error) {
+		if (!isMissing(error)) throw error;
+	}
+	const patterns = hints?.include?.length ? hints.include : ["docs/**/*.{md,mdx}", "docs/**/*.{png,jpg,jpeg,gif,webp,avif,svg,pdf,txt,zip}"];
+	const discovered = await glob(patterns, {
+		cwd: root,
+		onlyFiles: true,
+		dot: false,
+		ignore: hints?.exclude ?? []
+	});
+	const pages = discovered.filter((path) => /\.mdx?$/i.test(path));
+	if (home && !pages.includes(home)) pages.unshift(home);
+	const assets = discovered.filter((path) => !/\.mdx?$/i.test(path));
+	return {
+		root,
+		manifest,
+		...home ? { home } : {},
+		pages,
+		assets
+	};
+}
+function packageNameFromSpecifier(specifier) {
+	const parsed = npa(specifier);
+	if (!parsed.name) throw new Error(`Invalid npm package specifier: ${specifier}.`);
+	return parsed.name;
+}
+function lockForSource(lock, requested) {
+	const match = lock?.sources.find((source) => source.requested === requested || packageNameFromSpecifier(source.requested) === packageNameFromSpecifier(requested));
+	if (!match) throw new Error(`Package source ${requested} is not locked. Run "tasty-docs update" to create ${LOCK_FILE}.`);
+	return match;
+}
+function defaultLock(sources) {
+	return {
+		schemaVersion: 1,
+		sources
+	};
+}
+function isMissing(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function inside$1(root, path) {
+	const rel = relative(resolve(root), resolve(path));
+	return rel === "" || !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+}
+//#endregion
+//#region src/graph/index.ts
+const MARKDOWN_EXTENSIONS = [".md", ".mdx"];
+const FRONTMATTER_KEYS = /* @__PURE__ */ new Set([
+	"title",
+	"description",
+	"slug",
+	"draft",
+	"sidebar",
+	"toc",
+	"editUrl",
+	"prev",
+	"next",
+	"search",
+	"head"
+]);
+async function createDocsGraph(options = {}) {
+	const root = resolve(options.root ?? process.cwd());
+	const config = normalizeDocsConfig(options.config);
+	const diagnostics = [];
+	const collected = await collectSources(root, config, options.lock ?? await readDocsLock(root), diagnostics);
+	const entries = [];
+	const routeMap = /* @__PURE__ */ new Map();
+	const absoluteMap = /* @__PURE__ */ new Map();
+	const sourceMap = /* @__PURE__ */ new Map();
+	for (const source of collected) {
+		const entry = await readEntry(source, config, diagnostics);
+		if (!entry) continue;
+		const existing = routeMap.get(entry.route);
+		if (existing) {
+			diagnostics.push({
+				code: "DOCS_DUPLICATE_ROUTE",
+				severity: "error",
+				message: `Route ${entry.route} is owned by both ${existing.sourcePath} and ${entry.sourcePath}.`,
+				file: entry.sourcePath,
+				related: [{
+					file: existing.sourcePath,
+					message: "First route owner."
+				}]
+			});
+			continue;
+		}
+		routeMap.set(entry.route, entry);
+		absoluteMap.set(normalizeFs(entry.absolutePath), entry);
+		sourceMap.set(entry.sourcePath, entry);
+		sourceMap.set(entry.id, entry);
+		entries.push(entry);
+	}
+	for (const entry of entries) await transformEntry(entry, absoluteMap, routeMap, config, diagnostics);
+	validateNavigation(config.navigation.items ?? [], routeMap, diagnostics);
+	entries.sort((left, right) => left.route.localeCompare(right.route));
+	return {
+		root,
+		config,
+		entries,
+		routes: entries.map((entry) => ({
+			route: entry.route,
+			entryId: entry.id,
+			sourcePath: entry.sourcePath,
+			title: entry.title
+		})),
+		assets: entries.flatMap((entry) => entry.assets),
+		diagnostics,
+		entryByRoute(route) {
+			return routeMap.get(normalizeRoute(route));
+		},
+		entryBySource(sourcePath) {
+			return sourceMap.get(sourcePath);
+		}
+	};
+}
+async function collectSources(root, config, lock, diagnostics) {
+	const declarations = config.content.sources?.length ? config.content.sources : await conventionSources(root);
+	const results = [];
+	const identities = /* @__PURE__ */ new Set();
+	for (const declaration of declarations) try {
+		const found = await collectDeclaration(root, declaration, config, lock);
+		if (found.length === 0) diagnostics.push({
+			code: "DOCS_SOURCE_NOT_FOUND",
+			severity: "error",
+			message: `Source did not match any files: ${sourceLabel(declaration)}.`
+		});
+		for (const source of found) {
+			const identity = normalizeFs(source.absolutePath);
+			if (identities.has(identity)) continue;
+			identities.add(identity);
+			results.push(source);
+		}
+	} catch (error) {
+		diagnostics.push({
+			code: error instanceof OutsideRootError ? "DOCS_SOURCE_OUTSIDE_ROOT" : "DOCS_SOURCE_NOT_FOUND",
+			severity: "error",
+			message: errorMessage(error)
+		});
+	}
+	return results;
+}
+async function conventionSources(root) {
+	const sources = [];
+	if (await isFile(resolve(root, "README.md"))) sources.push({
+		file: "README.md",
+		route: "/"
+	});
+	if (await isDirectory(resolve(root, "docs"))) sources.push({
+		glob: "docs/**/*.{md,mdx}",
+		base: "docs"
+	});
+	return sources;
+}
+async function collectDeclaration(root, declaration, config, lock) {
+	if ("package" in declaration) {
+		const packageLock = lockForSource(lock, declaration.package);
+		const sourceRoot = await materializePackage(packageLock, config.build, root);
+		const discovery = await discoverPackage(sourceRoot);
+		const patterns = declaration.include?.length ? declaration.include : discovery.pages;
+		const files = declaration.include?.length ? await glob(patterns, {
+			cwd: sourceRoot,
+			onlyFiles: true,
+			ignore: declaration.exclude ?? []
+		}) : discovery.pages.filter((path) => !(declaration.exclude ?? []).includes(path));
+		const index = declaration.index ?? discovery.home;
+		return files.filter((path) => MARKDOWN_EXTENSIONS.includes(extname(path).toLowerCase())).map((path) => ({
+			absolutePath: resolve(sourceRoot, path),
+			sourcePath: path,
+			sourceRoot,
+			route: path === index ? normalizeRoute(declaration.routeBase ?? "/") : routeForPath(path, "docs", declaration.routeBase),
+			trust: declaration.trust ?? "markdown",
+			packageLock
+		}));
+	}
+	if ("file" in declaration) {
+		const absolutePath = resolveSourcePath(root, declaration.file, config.content.allowOutsideRoot);
+		if (!await isFile(absolutePath)) return [];
+		return [{
+			absolutePath,
+			sourcePath: toPosix(relative(root, absolutePath)),
+			sourceRoot: root,
+			...declaration.route ? { route: declaration.route } : {},
+			...declaration.title ? { title: declaration.title } : {},
+			...declaration.description ? { description: declaration.description } : {},
+			trust: "mdx"
+		}];
+	}
+	const patterns = Array.isArray(declaration.glob) ? declaration.glob : [declaration.glob];
+	return (await glob(patterns, {
+		cwd: root,
+		onlyFiles: true,
+		dot: false,
+		ignore: [
+			"**/_*/**",
+			"**/_*",
+			...declaration.exclude ?? []
+		]
+	})).map((path) => {
+		const absolutePath = resolveSourcePath(root, path, config.content.allowOutsideRoot);
+		return {
+			absolutePath,
+			sourcePath: toPosix(relative(root, absolutePath)),
+			sourceRoot: root,
+			route: routeForPath(path, declaration.base, declaration.routeBase),
+			trust: "mdx"
+		};
+	});
+}
+async function readEntry(source, config, diagnostics) {
+	if (extname(source.sourcePath).toLowerCase() === ".mdx" && source.trust !== "mdx") {
+		diagnostics.push({
+			code: "DOCS_UNTRUSTED_MDX",
+			severity: "error",
+			message: `Package MDX requires trust: 'mdx': ${source.sourcePath}.`,
+			file: source.sourcePath,
+			hint: "Keep package sources in Markdown-safe mode or explicitly trust this locked artifact."
+		});
+		return;
+	}
+	const original = await readFile(source.absolutePath, "utf8");
+	const parsedMatter = matter(original);
+	const frontmatter = parsedMatter.data;
+	for (const key of Object.keys(parsedMatter.data)) if (!FRONTMATTER_KEYS.has(key)) diagnostics.push({
+		code: "DOCS_FRONTMATTER_INVALID",
+		severity: "error",
+		message: `Unknown frontmatter key "${key}".`,
+		file: source.sourcePath
+	});
+	const parsed = parseMarkdown(parsedMatter.content);
+	const route = normalizeRoute(frontmatter.slug ?? source.route ?? routeForPath(source.sourcePath));
+	const title = frontmatter.title ?? source.title ?? parsed.firstHeading ?? titleFromFile(source.sourcePath);
+	const description = frontmatter.description ?? source.description ?? parsed.description;
+	const duplicateTitles = /* @__PURE__ */ new Map();
+	for (const heading of parsed.headings) {
+		const count = (duplicateTitles.get(heading.text) ?? 0) + 1;
+		duplicateTitles.set(heading.text, count);
+		if (count > 1) diagnostics.push({
+			code: "DOCS_HEADING_DUPLICATE",
+			severity: "warning",
+			message: `Repeated heading "${heading.text}" receives the generated ID "${heading.slug}".`,
+			file: source.sourcePath,
+			...heading.line ? { line: heading.line } : {}
+		});
+	}
+	return {
+		id: `${source.packageLock?.resolved ?? "local"}:${source.sourcePath}`,
+		sourcePath: source.sourcePath,
+		absolutePath: source.absolutePath,
+		sourceRoot: source.sourceRoot,
+		route,
+		title,
+		...description ? { description } : {},
+		frontmatter,
+		headings: parsed.headings,
+		body: parsedMatter.content,
+		transformedBody: parsedMatter.content,
+		ast: parsed.ast,
+		links: [],
+		assets: [],
+		trust: source.trust,
+		...source.packageLock ? { package: {
+			requested: source.packageLock.requested,
+			resolved: source.packageLock.resolved
+		} } : {}
+	};
+}
+async function transformEntry(entry, absoluteMap, routeMap, config, diagnostics) {
+	const ast = cloneAst(entry.ast);
+	if (config.markdown.stripLeadingBadges) stripLeadingBadgeBlock(ast);
+	removeRenderedTitle(ast, entry.title);
+	visit(ast, (node) => {
+		if (node.type === "html" && entry.trust === "markdown") {
+			if (/<\s*script\b|\son[a-z]+\s*=|javascript:/i.test(node.value)) {
+				diagnostics.push({
+					code: "DOCS_UNSAFE_HTML",
+					severity: "error",
+					message: "Script-capable HTML is not allowed in package Markdown.",
+					file: entry.sourcePath,
+					...node.position?.start.line ? { line: node.position.start.line } : {}
+				});
+				node.value = "";
+			}
+		}
+	});
+	const linkTasks = [];
+	visit(ast, (node) => {
+		if (node.type === "link") linkTasks.push(rewriteLink(node, entry, absoluteMap, routeMap, config, diagnostics));
+		else if (node.type === "image") linkTasks.push(rewriteAsset(node, entry, config, diagnostics));
+	});
+	await Promise.all(linkTasks);
+	entry.ast = ast;
+	entry.transformedBody = serializeMarkdown(ast);
+}
+async function rewriteLink(node, entry, absoluteMap, routeMap, config, diagnostics) {
+	const reference = {
+		original: node.url,
+		...lineData(node)
+	};
+	entry.links.push(reference);
+	if (unsafeProtocol(node.url)) {
+		diagnostic(diagnostics, "DOCS_LINK_UNSAFE", `Unsafe URL protocol: ${node.url}.`, entry, node);
+		return;
+	}
+	if (isExternal(node.url) || node.url.startsWith("#")) return;
+	const { pathname, query, fragment } = splitReference(node.url);
+	if (pathname.startsWith("/")) {
+		const target = routeMap.get(normalizeRoute(pathname));
+		if (!target) missingLink(diagnostics, entry, node, node.url, config);
+		else validateFragment(fragment, target, entry, node, diagnostics, config);
+		return;
+	}
+	const decoded = safeDecode(pathname);
+	const targetPath = resolve(dirname(entry.absolutePath), decoded);
+	if (!inside(entry.sourceRoot, targetPath)) {
+		diagnostic(diagnostics, "DOCS_SOURCE_OUTSIDE_ROOT", `Link escapes its allowed source root: ${node.url}.`, entry, node);
+		return;
+	}
+	const target = findDocument(targetPath, absoluteMap);
+	if (!target) {
+		if (await isFile(targetPath)) return;
+		missingLink(diagnostics, entry, node, node.url, config);
+		return;
+	}
+	node.url = `${withBase(target.route, config.build.base)}${query}${fragment ? `#${fragment}` : ""}`;
+	reference.resolved = node.url;
+	reference.targetSource = target.sourcePath;
+	if (fragment) reference.fragment = fragment;
+	validateFragment(fragment, target, entry, node, diagnostics, config);
+}
+async function rewriteAsset(node, entry, config, diagnostics) {
+	const asset = {
+		original: node.url,
+		...lineData(node)
+	};
+	entry.assets.push(asset);
+	if (isExternal(node.url)) return;
+	if (unsafeProtocol(node.url)) {
+		diagnostic(diagnostics, "DOCS_ASSET_UNSAFE", `Unsafe asset URL: ${node.url}.`, entry, node);
+		return;
+	}
+	const { pathname, query, fragment } = splitReference(node.url);
+	const absolute = resolve(dirname(entry.absolutePath), safeDecode(pathname));
+	if (!inside(entry.sourceRoot, absolute)) {
+		diagnostic(diagnostics, "DOCS_SOURCE_OUTSIDE_ROOT", `Asset escapes its allowed source root: ${node.url}.`, entry, node);
+		return;
+	}
+	try {
+		const info = await stat(absolute);
+		if (!info.isFile()) throw new Error("not a file");
+		if (info.size > config.build.maxAssetBytes) throw new Error(`asset exceeds ${config.build.maxAssetBytes} bytes`);
+		const hash = createHash("sha256").update(await readFile(absolute)).digest("hex").slice(0, 12);
+		const publicPath = withBase(`/_tasty-assets/${hash}-${basename(absolute)}`, config.build.base);
+		node.url = `${publicPath}${query}${fragment ? `#${fragment}` : ""}`;
+		Object.assign(asset, {
+			resolved: node.url,
+			sourcePath: absolute,
+			publicPath,
+			hash,
+			bytes: info.size
+		});
+	} catch (error) {
+		diagnostic(diagnostics, "DOCS_ASSET_NOT_FOUND", `Asset not found or invalid: ${node.url} (${errorMessage(error)}).`, entry, node);
+	}
+}
+function findDocument(path, absoluteMap) {
+	const candidates = [
+		path,
+		...MARKDOWN_EXTENSIONS.map((extension) => `${path}${extension}`),
+		...MARKDOWN_EXTENSIONS.map((extension) => resolve(path, `README${extension}`)),
+		...MARKDOWN_EXTENSIONS.map((extension) => resolve(path, `index${extension}`))
+	];
+	for (const candidate of candidates) {
+		const entry = absoluteMap.get(normalizeFs(candidate));
+		if (entry) return entry;
+	}
+}
+function validateFragment(fragment, target, source, node, diagnostics, config) {
+	if (!fragment) return;
+	const decoded = safeDecode(fragment);
+	if (!target.headings.some((heading) => heading.slug === decoded)) diagnostics.push({
+		code: "DOCS_FRAGMENT_NOT_FOUND",
+		severity: config.build.ci ? "error" : "warning",
+		message: `Heading fragment #${fragment} does not exist on ${target.route}.`,
+		file: source.sourcePath,
+		...lineData(node),
+		hint: `Known headings: ${target.headings.map((heading) => `#${heading.slug}`).join(", ") || "(none)"}.`
+	});
+}
+function missingLink(diagnostics, entry, node, url, config) {
+	diagnostics.push({
+		code: "DOCS_LINK_NOT_FOUND",
+		severity: config.build.strict ? "error" : "warning",
+		message: `Internal link target not found: ${url}.`,
+		file: entry.sourcePath,
+		...lineData(node)
+	});
+}
+function validateNavigation(items, routes, diagnostics) {
+	for (const item of items) if (typeof item === "string") {
+		if (!routes.has(normalizeRoute(item))) diagnostics.push({
+			code: "DOCS_NAV_TARGET_NOT_FOUND",
+			severity: "error",
+			message: `Navigation target does not exist: ${item}.`
+		});
+	} else if ("items" in item) validateNavigation(item.items, routes, diagnostics);
+	else if ("link" in item && item.link.startsWith("/") && !routes.has(normalizeRoute(item.link))) diagnostics.push({
+		code: "DOCS_NAV_TARGET_NOT_FOUND",
+		severity: "error",
+		message: `Navigation target does not exist: ${item.link}.`
+	});
+}
+function normalizeRoute(route) {
+	const segments = (route.split(/[?#]/, 1)[0]?.replace(/\\/g, "/").replace(/\/{2,}/g, "/") ?? "/").split("/").filter(Boolean);
+	if (segments.some((segment) => segment === "..")) throw new Error(`Route may not contain "..": ${route}.`);
+	const normalized = `/${segments.join("/")}`;
+	return normalized === "/" ? "/" : normalized.replace(/\/$/, "");
+}
+function routeForPath(path, base, routeBase) {
+	let relativePath = toPosix(path);
+	if (base) {
+		const normalizedBase = toPosix(base).replace(/^\.\//, "").replace(/\/$/, "");
+		if (relativePath === normalizedBase) relativePath = "";
+		else if (relativePath.startsWith(`${normalizedBase}/`)) relativePath = relativePath.slice(normalizedBase.length + 1);
+	}
+	relativePath = relativePath.replace(/\.(md|mdx)$/i, "");
+	relativePath = relativePath.replace(/(^|\/)README$/i, "$1").replace(/(^|\/)index$/i, "$1");
+	return normalizeRoute(`${routeBase ?? ""}/${relativePath}`);
+}
+function resolveSourcePath(root, path, allowOutsideRoot) {
+	const absolute = isAbsolute(path) ? resolve(path) : resolve(root, path);
+	if (!allowOutsideRoot && !inside(root, absolute)) throw new OutsideRootError(path);
+	return absolute;
+}
+function inside(root, path) {
+	const rel = relative(resolve(root), resolve(path));
+	return rel === "" || !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+}
+function splitReference(url) {
+	const hashIndex = url.indexOf("#");
+	const fragment = hashIndex >= 0 ? url.slice(hashIndex + 1) : "";
+	const withoutHash = hashIndex >= 0 ? url.slice(0, hashIndex) : url;
+	const queryIndex = withoutHash.indexOf("?");
+	return {
+		pathname: queryIndex >= 0 ? withoutHash.slice(0, queryIndex) : withoutHash,
+		query: queryIndex >= 0 ? withoutHash.slice(queryIndex) : "",
+		fragment
+	};
+}
+function isExternal(url) {
+	return /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(url);
+}
+function unsafeProtocol(url) {
+	return /^(?:javascript|vbscript|data):/i.test(url.trim());
+}
+function withBase(route, base) {
+	return `${base === "/" ? "" : `/${base.replace(/^\/+|\/+$/g, "")}`}${normalizeRoute(route)}` || "/";
+}
+function titleFromFile(path) {
+	return basename(path, extname(path)).replace(/^README$/i, basename(dirname(path)) || "Documentation").replace(/[-_]+/g, " ").replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+function diagnostic(diagnostics, code, message, entry, node) {
+	diagnostics.push({
+		code,
+		severity: "error",
+		message,
+		file: entry.sourcePath,
+		...lineData(node)
+	});
+}
+function lineOf(node) {
+	return node.position?.start.line;
+}
+function lineData(node) {
+	const line = lineOf(node);
+	return line === void 0 ? {} : { line };
+}
+function safeDecode(value) {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+function sourceLabel(source) {
+	if ("file" in source) return source.file;
+	if ("glob" in source) return Array.isArray(source.glob) ? source.glob.join(", ") : source.glob;
+	return source.package;
+}
+function normalizeFs(path) {
+	return resolve(path);
+}
+function toPosix(path) {
+	return path.split(sep).join("/");
+}
+async function isFile(path) {
+	try {
+		return (await stat(path)).isFile();
+	} catch {
+		return false;
+	}
+}
+async function isDirectory(path) {
+	try {
+		return (await stat(path)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+var OutsideRootError = class extends Error {
+	constructor(path) {
+		super(`Source path is outside the repository root: ${path}.`);
+		this.name = "OutsideRootError";
+	}
+};
+//#endregion
+//#region src/validation/index.ts
+var DocsValidationError = class extends Error {
+	diagnostics;
+	constructor(diagnostics) {
+		super(formatDiagnostics(diagnostics));
+		this.name = "DocsValidationError";
+		this.diagnostics = diagnostics;
+	}
+};
+function validateDocs(graph) {
+	return [...graph.diagnostics];
+}
+function assertValidDocs(graph) {
+	const errors = graph.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+	if (errors.length > 0) throw new DocsValidationError(errors);
+}
+function formatDiagnostics(diagnostics, json = false) {
+	if (json) return JSON.stringify(diagnostics, null, 2);
+	return diagnostics.map((diagnostic) => {
+		const location = diagnostic.file ? `${diagnostic.file}${diagnostic.line ? `:${diagnostic.line}` : ""}: ` : "";
+		const hint = diagnostic.hint ? `\n  hint: ${diagnostic.hint}` : "";
+		return `${diagnostic.severity.toUpperCase()} ${diagnostic.code} ${location}${diagnostic.message}${hint}`;
+	}).join("\n");
+}
+//#endregion
+//#region src/content/index.ts
+function createDocsLoader(config, options = {}) {
+	return {
+		name: "@tenphi/docs",
+		async load(context) {
+			const graph = await createDocsGraph({
+				...options,
+				...config ? { config } : {}
+			});
+			assertValidDocs(graph);
+			context.store.clear();
+			for (const entry of graph.entries) {
+				const loaderEntry = toLoaderEntry(entry);
+				const data = context.parseData ? await context.parseData({
+					id: loaderEntry.id,
+					data: loaderEntry.data,
+					filePath: entry.sourcePath
+				}) : loaderEntry.data;
+				context.store.set({
+					...loaderEntry,
+					data,
+					filePath: entry.sourcePath
+				});
+			}
+			context.logger?.info(`Loaded ${graph.entries.length} Tasty Docs pages.`);
+		}
+	};
+}
+function toLoaderEntry(entry) {
+	return {
+		id: entry.route === "/" ? "index" : entry.route.slice(1),
+		data: {
+			title: entry.title,
+			draft: entry.frontmatter.draft ?? false,
+			...entry.description ? { description: entry.description } : {},
+			...entry.frontmatter,
+			tastyDocs: {
+				sourcePath: entry.sourcePath,
+				route: entry.route,
+				headings: entry.headings
+			}
+		},
+		body: entry.transformedBody
+	};
+}
+//#endregion
+export { writeDocsLock as _, validateDocs as a, routeForPath as c, lockForSource as d, materializePackage as f, validateLock as g, resolvePackageLock as h, formatDiagnostics as i, defaultLock as l, readDocsLock as m, DocsValidationError as n, createDocsGraph as o, packageNameFromSpecifier as p, assertValidDocs as r, normalizeRoute as s, createDocsLoader as t, discoverPackage as u };
+
+//# sourceMappingURL=content-DStZeziu.js.map