@waveso/docs 0.1.0 → 0.2.0

package/dist/source.js

@@ -1,17 +1,11 @@
+import { docsError } from "./docs-error.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import { orderNavEntries, readDocsMeta } from "./meta.js";
-import { readFile, readdir, stat } from "node:fs/promises";
+import { foldSegments } from "./plugins/remark-doc-links.js";
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import matter from "gray-matter";
 //#region src/source.ts
-/**
-* The source layer: a content directory on disk becomes `DocFile[]` plus a
-* navigation tree.
-*
-* Node-only, and the only module that touches the filesystem. Everything it
-* produces is plain data, so the result crosses the RSC boundary, a Vite
-* virtual module or a JSON cache file without ceremony.
-*/
 /** Markdown only. MDX is deliberately out of scope for this package. */
 const PAGE_EXTENSION = ".md";
 /** A directory whose `index.md` is the directory's own route. */
@@ -83,7 +77,13 @@ function createDocsSource(config) {
 }
 function buildSource(config) {
 	let cached = null;
-	const load = () => cached ??= scan(config);
+	const load = () => {
+		cached ??= scan(config).catch((err) => {
+			cached = null;
+			throw err;
+		});
+		return cached;
+	};
 	const isVisible = (file) => config.includeDrafts || file.frontmatter.draft !== true;
 	return {
 		config,
@@ -94,6 +94,10 @@ function buildSource(config) {
 			const { files } = await load();
 			return files.filter(isVisible);
 		},
+		async drafts() {
+			const { files } = await load();
+			return files.filter((file) => file.frontmatter.draft === true);
+		},
 		async find(segments) {
 			const { bySlug } = await load();
 			return bySlug.get(segments.join("/"));
@@ -109,7 +113,7 @@ function buildSource(config) {
 }
 async function scan(config) {
 	await assertContentDir(config.contentDir);
-	const root = await scanDir(config.contentDir, [], "", config);
+	const root = await scanDir(config.contentDir, [], "", config, /* @__PURE__ */ new Set([await realpath(config.contentDir)]));
 	const files = [];
 	const bySlug = /* @__PURE__ */ new Map();
 	collect(root, files, bySlug);
@@ -123,15 +127,21 @@ async function assertContentDir(contentDir) {
 	try {
 		if ((await stat(contentDir)).isDirectory()) return;
 	} catch {}
-	throw new Error(`Docs content directory not found: ${contentDir}\nSet \`contentDir\` to a directory of markdown files; relative paths resolve against the working directory (${process.cwd()}).`);
+	throw docsError("missing-content-dir", `Docs content directory not found: ${contentDir}\nSet \`contentDir\` to a directory of markdown files; relative paths resolve against the working directory (${process.cwd()}).`);
 }
-async function scanDir(absPath, segments, name, config) {
+const SKIP = { kind: "skip" };
+async function scanDir(absPath, segments, name, config, ancestors) {
 	const [meta, entries] = await Promise.all([readDocsMeta(absPath), readdir(absPath, { withFileTypes: true })]);
-	const sorted = [...entries].sort((a, b) => a.name.localeCompare(b.name, "en"));
-	const pageEntries = sorted.filter((entry) => entry.isFile() && isPageFile(entry.name));
-	const dirEntries = sorted.filter((entry) => entry.isDirectory() && !isIgnoredDir(entry.name));
-	const [pages, dirs] = await Promise.all([Promise.all(pageEntries.map((entry) => readPage(path.join(absPath, entry.name), segments, config))), Promise.all(dirEntries.map((entry) => scanDir(path.join(absPath, entry.name), [...segments, entry.name], entry.name, config)))]);
-	const index = pages.find((page) => baseName(page.filePath) === INDEX_NAME);
+	const classified = await Promise.all(entries.map((entry) => ({
+		entry,
+		name: entry.name.normalize("NFC")
+	})).sort((a, b) => a.name.localeCompare(b.name, "en")).map((listed) => classifyEntry(absPath, listed.entry, listed.name)));
+	const pageEntries = [];
+	const dirEntries = [];
+	for (const entry of classified) if (entry.kind === "page") pageEntries.push(entry);
+	else if (entry.kind === "dir" && !ancestors.has(entry.realPath)) dirEntries.push(entry);
+	const [pages, dirs] = await Promise.all([Promise.all(pageEntries.map((entry) => readPage(entry.absPath, entry.name, segments, config))), Promise.all(dirEntries.map((entry) => scanDir(entry.absPath, [...segments, entry.name], entry.name, config, new Set(ancestors).add(entry.realPath))))]);
+	const index = pages.find((page) => page.name === INDEX_NAME);
 	return {
 		name,
 		absPath,
@@ -143,7 +153,49 @@ async function scanDir(absPath, segments, name, config) {
 		dirs
 	};
 }
-async function readPage(filePath, dirSegments, config) {
+/**
+* What kind of content is this directory entry?
+*
+* ⚠️ `isFile()` AND `isDirectory()` ARE BOTH FALSE FOR A SYMBOLIC LINK, and
+* `readdir` has no follow option — so a symlinked page, or a whole symlinked
+* section, was absent from `all()`, `nav()`, the sitemap and the search index
+* without a word. The cascade is worse than the omission: the first link to
+* the missing page fails the build with `no such page exists`, which sends the
+* author after a link that is perfectly correct.
+*
+* `stat` follows the link, so the target's kind decides — and the name filters
+* still apply to the link's own name, which is what the URL is built from.
+*/
+async function classifyEntry(dirPath, entry, name) {
+	const absPath = path.join(dirPath, entry.name);
+	let isFile = entry.isFile();
+	let isDir = entry.isDirectory();
+	if (!isFile && !isDir) {
+		if (!entry.isSymbolicLink()) return SKIP;
+		let target;
+		try {
+			target = await stat(absPath);
+		} catch {
+			if (!isPageFile(name)) return SKIP;
+			throw docsError("broken-symlink", `@waveso/docs: ${absPath} is a broken symbolic link, and it names a markdown page — so skipping it would delete a route nobody asked to delete. Point it at an existing file, or remove the link.`);
+		}
+		isFile = target.isFile();
+		isDir = target.isDirectory();
+	}
+	if (isFile) return isPageFile(name) ? {
+		kind: "page",
+		absPath,
+		name: stripExtension(name)
+	} : SKIP;
+	if (isDir && !isIgnoredDir(name)) return {
+		kind: "dir",
+		absPath,
+		name,
+		realPath: await realpath(absPath)
+	};
+	return SKIP;
+}
+async function readPage(filePath, name, dirSegments, config) {
 	const raw = await readFile(filePath, "utf8");
 	const relativePath = toPosix(path.relative(config.contentDir, filePath));
 	let data;
@@ -154,25 +206,29 @@ async function readPage(filePath, dirSegments, config) {
 		content = parsed.content;
 	} catch (err) {
 		const reason = err instanceof Error ? err.message : String(err);
-		throw new Error(`Could not parse the frontmatter block in ${relativePath}: ${reason}`);
+		throw docsError("invalid-frontmatter", `Could not parse the frontmatter block in ${relativePath}: ${reason}`, { cause: err });
 	}
-	const name = baseName(filePath);
 	const segments = name === INDEX_NAME ? [...dirSegments] : [...dirSegments, name];
+	const frontmatter = await parseFrontmatter(data, relativePath, config.frontmatterSchema);
+	for (const alias of frontmatter.aliases ?? []) toAliasRoute(alias, config.basePath, relativePath);
 	return {
-		segments,
-		slug: segments.join("/"),
-		href: toHref(config.basePath, segments),
-		filePath,
-		relativePath,
-		frontmatter: await parseFrontmatter(data, relativePath, config.frontmatterSchema),
-		content
+		name,
+		doc: {
+			segments,
+			slug: segments.join("/"),
+			href: toHref(config.basePath, segments),
+			filePath,
+			relativePath,
+			frontmatter,
+			content
+		}
 	};
 }
 function collect(dir, files, bySlug) {
 	const own = dir.index ? [dir.index, ...dir.pages] : dir.pages;
-	for (const file of own) {
+	for (const { doc: file } of own) {
 		const clash = bySlug.get(file.slug);
-		if (clash) throw new Error(`Two files claim the route "${file.href}": ${clash.relativePath} and ${file.relativePath}. Rename one, or delete the other — a directory index and a same-named sibling file collide.`);
+		if (clash) throw docsError("route-collision", `Two files claim the route "${file.href}": ${clash.relativePath} and ${file.relativePath}. Rename one, or delete the other — a directory index and a same-named sibling file collide.`);
 		bySlug.set(file.slug, file);
 		files.push(file);
 	}
@@ -193,9 +249,8 @@ function buildNav(dir, config) {
 	const mergeable = new Set(dir.dirs.filter((child) => child.index === void 0).map((child) => child.name));
 	const dirPages = /* @__PURE__ */ new Map();
 	for (const page of dir.pages) {
-		const name = baseName(page.filePath);
-		if (mergeable.has(name)) {
-			dirPages.set(name, page);
+		if (mergeable.has(page.name)) {
+			dirPages.set(page.name, page);
 			continue;
 		}
 		entries.push(toPageEntry(page, config));
@@ -207,51 +262,61 @@ function buildNav(dir, config) {
 	for (const child of dir.dirs) {
 		const children = buildNav(child, config);
 		const index = child.index ?? dirPages.get(child.name);
-		const title = groupTitle(child, index);
-		const href = index && isVisibleIn(index, config) ? index.href : void 0;
+		/**
+		* ⚠️ A DRAFT INDEX IS NOT A PUBLIC PAGE, AND ITS TITLE IS NOT EITHER.
+		*
+		* Only `href` used to be gated on visibility, so `secret/index.md` with
+		* `draft: true` still supplied the group heading — an unreleased codename
+		* rendered into the sidebar of a production build, with no link on it, so
+		* no click reveals it and only view-source shows it at all. Its `order`
+		* also still positioned the group among published ones.
+		*/
+		const visible = index && isVisibleIn(index.doc, config) ? index : void 0;
+		const title = groupTitle(child, visible?.doc);
+		const href = visible?.doc.href;
 		const group = {
 			type: "group",
 			title,
 			children,
 			...href !== void 0 ? { href } : {}
 		};
-		const node = children.length === 0 && index !== void 0 && href !== void 0 ? {
+		const node = children.length === 0 && visible !== void 0 && href !== void 0 ? {
 			type: "page",
 			title,
 			href,
-			slug: index.slug
+			slug: visible.doc.slug
 		} : group;
-		const order = index?.frontmatter.order;
+		const order = visible?.doc.frontmatter.order;
 		entries.push({
 			name: child.name,
 			title,
 			node,
 			inlineChildren: children,
-			...index !== void 0 && href !== void 0 ? { indexNode: {
+			...visible !== void 0 && href !== void 0 ? { indexNode: {
 				type: "page",
-				title: navTitle(index),
+				title: navTitle(visible.doc),
 				href,
-				slug: index.slug
+				slug: visible.doc.slug
 			} } : {},
 			...order !== void 0 ? { order } : {}
 		});
 	}
-	return orderNavEntries(entries, dir.meta, dir.metaPath);
+	return orderNavEntries(entries, dir.meta, dir.metaPath, dir.segments.length);
 }
 function toPageEntry(page, config) {
-	const title = navTitle(page);
-	const { order } = page.frontmatter;
+	const title = navTitle(page.doc);
+	const { order } = page.doc.frontmatter;
 	return {
-		name: baseName(page.filePath),
+		name: page.name,
 		title,
 		node: {
 			type: "page",
 			title,
-			href: page.href,
-			slug: page.slug
+			href: page.doc.href,
+			slug: page.doc.slug
 		},
 		...order !== void 0 ? { order } : {},
-		...isVisibleIn(page, config) ? {} : { hidden: true }
+		...isVisibleIn(page.doc, config) ? {} : { hidden: true }
 	};
 }
 /** Sidebars are narrow: `label` wins over `title` when the author set one. */
@@ -273,6 +338,18 @@ function isVisibleIn(file, config) {
 	return config.includeDrafts || file.frontmatter.draft !== true;
 }
 /**
+* ⚠️ CHARACTERS `path-to-regexp` READS AS PATTERN SYNTAX.
+*
+* Next compiles every `redirects()` source with it, so an alias is not the
+* literal URL it looks like. `v1:beta` compiles to `/docs/v1([^/]+?)`, which
+* `next build` accepts without a word and which then 308s the genuinely
+* prerendered `/docs/v1-guide` away — config redirects run before filesystem
+* routes, so the real page is unreachable in production and nothing reports
+* it. `c++` is the loud sibling: the build aborts with `Unexpected MODIFIER at
+* 7`, naming an offset into a string the author never wrote and no file.
+*/
+const ALIAS_PATTERN_CHARS = /[:()+*?{}]/;
+/**
 * A former URL from `aliases` frontmatter, as a route.
 *
 * `'quickstart'` on a site mounted at `/docs` becomes `/docs/quickstart`.
@@ -282,12 +359,17 @@ function isVisibleIn(file, config) {
 *
 * Shared by both adapters so they agree on which routes exist: an alias is a
 * redirect the host installs, so a link to one resolves, and a link that
-* builds under Next must build under Vite.
+* builds under Next must build under Vite. The source scan calls it too, so
+* every rejection below names the markdown file at the moment it is read.
 */
 function toAliasRoute(alias, basePath, sourceLabel) {
-	const trimmed = alias.trim().replace(/^\/+/, "").replace(/\/+$/, "");
-	if (trimmed === "") throw new Error(`@waveso/docs: ${sourceLabel} has an empty entry in its \`aliases\` frontmatter. Each alias is a former URL for this page, relative to the docs base path — e.g. \`aliases: [quickstart]\`.`);
-	return `${basePath}/${trimmed}`;
+	const trimmed = alias.trim();
+	if (trimmed.split("/").some((part) => part === "." || part === "..")) throw docsError("invalid-alias", `@waveso/docs: the alias '${alias}' in ${sourceLabel} has a '.' or '..' segment. An alias is a former URL relative to the docs base path, not a path on disk: write \`aliases: [legacy/old-name]\`.`);
+	const pattern = ALIAS_PATTERN_CHARS.exec(trimmed);
+	if (pattern !== null) throw docsError("invalid-alias", `@waveso/docs: the alias '${alias}' in ${sourceLabel} contains '${pattern[0]}', which Next compiles as redirect pattern syntax rather than as part of the URL — the redirect then swallows every page whose route the pattern happens to match, or fails the build. Remove the character; an alias is a literal former URL.`);
+	const segments = foldSegments([], trimmed);
+	if (segments === void 0 || segments.length === 0) throw docsError("invalid-alias", `@waveso/docs: ${sourceLabel} has an empty entry in its \`aliases\` frontmatter. Each alias is a former URL for this page, relative to the docs base path — e.g. \`aliases: [quickstart]\`.`);
+	return `${basePath}/${encodeSegments(segments)}`;
 }
 /**
 * ⚠️ `_` AND `.` BOTH, MATCHING `isIgnoredDir` BELOW — which is what this did
@@ -302,18 +384,32 @@ function toAliasRoute(alias, basePath, sourceLabel) {
 * first. Docusaurus and Nextra skip both forms.
 */
 function isPageFile(name) {
-	return !name.startsWith(".") && !name.startsWith("_") && name.endsWith(PAGE_EXTENSION) && name.length > 3;
+	return !name.startsWith(".") && !name.startsWith("_") && path.extname(name).toLowerCase() === PAGE_EXTENSION;
 }
 /** `_drafts/` and `.git/` are not content. */
 function isIgnoredDir(name) {
 	return name.startsWith(".") || name.startsWith("_");
 }
-function baseName(filePath) {
-	return path.basename(filePath, PAGE_EXTENSION);
+/** `getting-started.MD` -> `getting-started`. */
+function stripExtension(name) {
+	return name.slice(0, name.length - path.extname(name).length);
+}
+/**
+* Percent-encode the segments, and only here.
+*
+* `segments` and `slug` stay raw on purpose: Next decodes route params before
+* they reach `find()`, so an encoded slug would match nothing. Unencoded, a
+* `#`, `?` or `%` in a filename stops being part of the path — the sitemap
+* emitted `https://example.com/docs/c#%20guide`, and `alternates.canonical`
+* and `og:url` are built by the same call — while a space produced a URL that
+* only works until something re-encodes it.
+*/
+function encodeSegments(segments) {
+	return segments.map(encodeURIComponent).join("/");
 }
 function toHref(basePath, segments) {
 	if (segments.length === 0) return basePath === "" ? "/" : basePath;
-	return `${basePath}/${segments.join("/")}`;
+	return `${basePath}/${encodeSegments(segments)}`;
 }
 function normalizeBasePath(basePath) {
 	const trimmed = basePath.trim().replace(/\/+$/, "");