@waveso/docs 0.2.0 → 0.3.0

package/dist/sitemap-limit.d.ts

@@ -0,0 +1,34 @@
+//#region src/sitemap-limit.d.ts
+/**
+ * Google's per-sitemap URL cap, and the warning for crossing it.
+ *
+ * Private — deliberately not an entry point in `package.json`. It lives in its
+ * own module for one reason: the branch is otherwise untestable. `next.ts` held
+ * the limit and the `console.warn` inline, and reaching them from a test meant
+ * writing 50,001 markdown files to a temporary directory, so the test that
+ * claimed to cover it ("warns rather than silently emitting an oversized
+ * sitemap") built a one-page site and asserted the warning did *not* fire. It
+ * could only ever fail if the comparison were inverted.
+ *
+ * A count is the whole input. Split out, the arithmetic and the wording are
+ * checkable in microseconds, and `createDocsSitemap`'s own test keeps covering
+ * the case that matters at the integration level: an ordinary sitemap stays
+ * quiet.
+ */
+/**
+ * The cap.
+ *
+ * 50,000 URLs or 50 MB uncompressed, whichever comes first; a crawler rejects
+ * the file whole rather than truncating it.
+ */
+declare const SITEMAP_URL_LIMIT = 50000;
+/**
+ * The warning for a sitemap of `count` URLs, or `undefined` when it fits.
+ *
+ * Splitting belongs to the caller — Next's `generateSitemaps` plus a slice of
+ * the returned array is three lines — but silently emitting a file no crawler
+ * will read is not something to discover from Search Console six weeks later.
+ */
+declare function sitemapLimitWarning(count: number): string | undefined;
+//#endregion
+export { SITEMAP_URL_LIMIT, sitemapLimitWarning };

package/dist/sitemap-limit.js

@@ -0,0 +1,37 @@
+//#region src/sitemap-limit.ts
+/**
+* Google's per-sitemap URL cap, and the warning for crossing it.
+*
+* Private — deliberately not an entry point in `package.json`. It lives in its
+* own module for one reason: the branch is otherwise untestable. `next.ts` held
+* the limit and the `console.warn` inline, and reaching them from a test meant
+* writing 50,001 markdown files to a temporary directory, so the test that
+* claimed to cover it ("warns rather than silently emitting an oversized
+* sitemap") built a one-page site and asserted the warning did *not* fire. It
+* could only ever fail if the comparison were inverted.
+*
+* A count is the whole input. Split out, the arithmetic and the wording are
+* checkable in microseconds, and `createDocsSitemap`'s own test keeps covering
+* the case that matters at the integration level: an ordinary sitemap stays
+* quiet.
+*/
+/**
+* The cap.
+*
+* 50,000 URLs or 50 MB uncompressed, whichever comes first; a crawler rejects
+* the file whole rather than truncating it.
+*/
+const SITEMAP_URL_LIMIT = 5e4;
+/**
+* The warning for a sitemap of `count` URLs, or `undefined` when it fits.
+*
+* Splitting belongs to the caller — Next's `generateSitemaps` plus a slice of
+* the returned array is three lines — but silently emitting a file no crawler
+* will read is not something to discover from Search Console six weeks later.
+*/
+function sitemapLimitWarning(count) {
+	if (count <= 5e4) return void 0;
+	return `@waveso/docs: this sitemap has ${count} URLs, above Google's limit of ${SITEMAP_URL_LIMIT}. Split it with Next's \`generateSitemaps\` and slice the array this returns.`;
+}
+//#endregion
+export { SITEMAP_URL_LIMIT, sitemapLimitWarning };

package/dist/source.d.ts

@@ -53,27 +53,5 @@ declare function resolveDocsConfig<TFrontmatter extends DocFrontmatter = DocFron
  * Create (or reuse) the source for a content directory.
  */
 declare function createDocsSource<TFrontmatter extends DocFrontmatter = DocFrontmatter>(config: DocsConfig<TFrontmatter>): DocsSource<TFrontmatter>;
-/**
- * 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`.
- *
- * 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. The source scan calls it too, so
- * every rejection below names the markdown file at the moment it is read.
- */
-declare function toAliasRoute(alias: string, basePath: string,
-/**
- * The source path, for the error. A STRING rather than the whole `DocFile`
- * it used to take: this function dereferenced exactly one property of it, and
- * demanding the object meant a cache reader or a manifest-driven redirect
- * table had to fabricate a `DocFile` to agree with the package about which
- * routes exist. That is the reason it is exported at all.
- */
-sourceLabel: string): string;
 //#endregion
-export { DocsSource, createDocsSource, resolveDocsConfig, toAliasRoute };
+export { DocsSource, createDocsSource, resolveDocsConfig };

package/dist/source.js

@@ -1,10 +1,11 @@
 import { docsError } from "./docs-error.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import { orderNavEntries, readDocsMeta } from "./meta.js";
-import { foldSegments } from "./plugins/remark-doc-links.js";
+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
 /** Markdown only. MDX is deliberately out of scope for this package. */
 const PAGE_EXTENSION = ".md";
@@ -20,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,
@@ -87,6 +92,33 @@ function buildSource(config) {
 	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;
 		},
@@ -201,9 +233,10 @@ async function readPage(filePath, name, dirSegments, config) {
 	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 docsError("invalid-frontmatter", `Could not parse the frontmatter block in ${relativePath}: ${reason}`, { cause: err });
@@ -348,29 +381,6 @@ function isVisibleIn(file, config) {
 * 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`.
-* 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`.
-*
-* 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. 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();
-	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
 * NOT do. A leading dot was skipped and a leading underscore was not, so
@@ -394,19 +404,6 @@ function isIgnoredDir(name) {
 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}/${encodeSegments(segments)}`;
@@ -425,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 };