@waveso/docs 0.1.0 → 0.3.0

package/dist/source.js

@@ -1,17 +1,12 @@
+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 { encodeSegments, toAliasRoute } from "./route-path.js";
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
 import path from "node:path";
-import matter from "gray-matter";
+import { VFile } from "vfile";
+import { matter } from "vfile-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. */
@@ -26,7 +21,11 @@ const INDEX_NAME = "index";
 */
 function resolveDocsConfig(config) {
 	return {
-		contentDir: path.resolve(process.cwd(), config.contentDir),
+		contentDir: path.resolve(
+			/*turbopackIgnore: true*/
+			process.cwd(),
+			config.contentDir
+		),
 		basePath: normalizeBasePath(config.basePath ?? "/docs"),
 		includeDrafts: config.includeDrafts ?? false,
 		assertLinks: config.assertLinks ?? true,
@@ -83,10 +82,43 @@ 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,
+		/**
+		* Throw the scan away. The next query reads the disk again.
+		*
+		* ⚠️ A STAT-WALK DIRTY CHECK WAS BUILT HERE AND MEASURED AND REMOVED. The
+		* idea is obvious and the roadmap called for it: mark dirty, then compare
+		* a stat-only fingerprint of the tree against the cached one and skip the
+		* re-read when nothing changed. It rests on stat being much cheaper than
+		* read, and on this corpus it is not — the fingerprint has to `readdir`
+		* every directory and `stat` every file, which is nearly everything the
+		* scan does apart from the read and the parse.
+		*
+		* Measured over 501 pages, median of six, against a full rescan:
+		*
+		*   ~1.4 KB pages   28.3 ms vs 26.8 ms   0.95x  (slower)
+		*   ~20 KB pages    28.8 ms vs 27.4 ms   0.95x  (slower)
+		*   ~120 KB pages   39.1 ms vs 45.1 ms   1.15x  (faster)
+		*
+		* Documentation pages are the first two rows. So it is a small regression
+		* plus a new class of invalidation bug, in exchange for a win on a corpus
+		* nobody has. There is no cheaper correct fingerprint either: statting
+		* only directories catches an added or renamed file but not an edited one,
+		* which is the common case in a dev server.
+		*
+		* If this is ever revisited, the thing to change is the *scan*, not the
+		* check — patch only the files whose mtime moved and re-derive the nav in
+		* memory, which is a different item with a much harder correctness story.
+		*/
 		invalidate() {
 			cached = null;
 		},
@@ -94,6 +126,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 +145,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 +159,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,36 +185,83 @@ 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;
 	let content;
 	try {
-		const parsed = matter(raw, { language: "yaml" });
-		data = parsed.data;
-		content = parsed.content;
+		const file = new VFile({ value: raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw });
+		matter(file, { strip: true });
+		data = file.data.matter;
+		content = String(file);
 	} 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 +282,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 +295,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,22 +371,16 @@ function isVisibleIn(file, config) {
 	return config.includeDrafts || file.frontmatter.draft !== true;
 }
 /**
-* A former URL from `aliases` frontmatter, as a route.
-*
-* `'quickstart'` on a site mounted at `/docs` becomes `/docs/quickstart`.
-* Leading and trailing slashes are tolerated because authors write them, but
-* the value is always relative to the base path — an alias of `'/docs/old'` on
-* a `/docs` site would produce `/docs/docs/old`.
+* ⚠️ CHARACTERS `path-to-regexp` READS AS PATTERN SYNTAX.
 *
-* 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.
+* 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.
 */
-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}`;
-}
 /**
 * ⚠️ `_` AND `.` BOTH, MATCHING `isIgnoredDir` BELOW — which is what this did
 * NOT do. A leading dot was skipped and a leading underscore was not, so
@@ -302,18 +394,19 @@ 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);
 }
 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(/\/+$/, "");
@@ -329,4 +422,4 @@ function humanize(name) {
 	return name.split(/[-_\s]+/).filter((word) => word !== "").map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`).join(" ");
 }
 //#endregion
-export { createDocsSource, resolveDocsConfig, toAliasRoute };
+export { createDocsSource, resolveDocsConfig };