@waveso/docs 0.1.0

package/dist/source.d.ts

@@ -0,0 +1,67 @@
+import { DocFile, DocFrontmatter, DocNavNode, DocsConfig, ResolvedDocsConfig } from "./types.js";
+//#region src/source.d.ts
+/**
+ * A content directory, scanned once and queried many times.
+ *
+ * Every method is async because the first one to be called performs the scan;
+ * subsequent calls resolve from the same in-flight promise.
+ */
+interface DocsSource<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
+  /** Every page, drafts excluded unless `includeDrafts`. */
+  all(): Promise<Array<DocFile<TFrontmatter>>>;
+  /**
+   * One page by route segments. Returns drafts regardless of config, so a
+   * preview route can opt into them without a second source.
+   */
+  find(segments: string[]): Promise<DocFile<TFrontmatter> | undefined>;
+  /** The navigation tree for the content root. */
+  nav(): Promise<DocNavNode[]>;
+  /** Route segments for `generateStaticParams`, drafts excluded. */
+  slugs(): Promise<string[][]>;
+  /**
+   * Discard the cached scan, so the next query reads the disk again.
+   *
+   * A one-shot `next build` never needs this — the tree cannot change while it
+   * runs, and caching is the whole point. A long-lived Vite dev server does:
+   * without it, a markdown file created after startup could never appear, and
+   * the source would be permanently wrong for the rest of the session.
+   */
+  invalidate(): void;
+  config: ResolvedDocsConfig<TFrontmatter>;
+}
+/**
+ * Apply {@link DocsConfig} defaults and resolve `contentDir` against
+ * `process.cwd()` — the project root under both `next build` and `vite build`.
+ *
+ * `basePath` is normalised to have a leading slash and no trailing one, so
+ * href construction is a plain concatenation everywhere else. Mounting docs at
+ * the site root (`'/'`) normalises to `''`, matching the Next.js convention.
+ */
+declare function resolveDocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatter>(config: DocsConfig<TFrontmatter>): ResolvedDocsConfig<TFrontmatter>;
+/**
+ * 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.
+ */
+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 };

package/dist/source.js

@@ -0,0 +1,332 @@
+import { parseFrontmatter } from "./frontmatter.js";
+import { orderNavEntries, readDocsMeta } from "./meta.js";
+import { readFile, readdir, 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. */
+const INDEX_NAME = "index";
+/**
+* Apply {@link DocsConfig} defaults and resolve `contentDir` against
+* `process.cwd()` — the project root under both `next build` and `vite build`.
+*
+* `basePath` is normalised to have a leading slash and no trailing one, so
+* href construction is a plain concatenation everywhere else. Mounting docs at
+* the site root (`'/'`) normalises to `''`, matching the Next.js convention.
+*/
+function resolveDocsConfig(config) {
+	return {
+		contentDir: path.resolve(process.cwd(), config.contentDir),
+		basePath: normalizeBasePath(config.basePath ?? "/docs"),
+		includeDrafts: config.includeDrafts ?? false,
+		assertLinks: config.assertLinks ?? true,
+		...config.frontmatterSchema === void 0 ? {} : { frontmatterSchema: config.frontmatterSchema }
+	};
+}
+/**
+* Sources are memoised by resolved config so that the twenty route files of a
+* docs site share one filesystem scan instead of each starting their own.
+*
+* The values are heterogeneous in `TFrontmatter`, which no `Map` type can
+* express; the read in {@link createDocsSource} is a cast justified by
+* {@link schemaKey} — a key only matches an entry built from the very same
+* schema object, and therefore from the very same `TFrontmatter`.
+*/
+const sources = /* @__PURE__ */ new Map();
+/** Schema identities, assigned on first sight. */
+const schemaIds = /* @__PURE__ */ new WeakMap();
+let schemaIdCount = 0;
+/**
+* A key fragment identifying a `frontmatterSchema`, by reference.
+*
+* Two configs that differ only by schema must not share a source: the cached
+* `DocFile.frontmatter` was parsed by whichever schema arrived first, so
+* sharing would hand one caller the other's fields — silently, and only for the
+* fields the two schemas disagree about. Identity is the only comparison a
+* Standard Schema supports; a validator has no stable serialisation.
+*/
+function schemaKey(schema) {
+	if (schema === void 0) return "default-schema";
+	const existing = schemaIds.get(schema);
+	if (existing !== void 0) return `schema-${existing}`;
+	schemaIdCount += 1;
+	schemaIds.set(schema, schemaIdCount);
+	return `schema-${schemaIdCount}`;
+}
+/**
+* Create (or reuse) the source for a content directory.
+*/
+function createDocsSource(config) {
+	const resolved = resolveDocsConfig(config);
+	const key = [
+		resolved.contentDir,
+		resolved.basePath,
+		resolved.includeDrafts,
+		resolved.assertLinks,
+		schemaKey(resolved.frontmatterSchema)
+	].join("\0");
+	const existing = sources.get(key);
+	if (existing) return existing;
+	const created = buildSource(resolved);
+	sources.set(key, created);
+	return created;
+}
+function buildSource(config) {
+	let cached = null;
+	const load = () => cached ??= scan(config);
+	const isVisible = (file) => config.includeDrafts || file.frontmatter.draft !== true;
+	return {
+		config,
+		invalidate() {
+			cached = null;
+		},
+		async all() {
+			const { files } = await load();
+			return files.filter(isVisible);
+		},
+		async find(segments) {
+			const { bySlug } = await load();
+			return bySlug.get(segments.join("/"));
+		},
+		async nav() {
+			return (await load()).nav;
+		},
+		async slugs() {
+			const { files } = await load();
+			return files.filter(isVisible).map((file) => file.segments);
+		}
+	};
+}
+async function scan(config) {
+	await assertContentDir(config.contentDir);
+	const root = await scanDir(config.contentDir, [], "", config);
+	const files = [];
+	const bySlug = /* @__PURE__ */ new Map();
+	collect(root, files, bySlug);
+	return {
+		files,
+		bySlug,
+		nav: buildNav(root, config)
+	};
+}
+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()}).`);
+}
+async function scanDir(absPath, segments, name, config) {
+	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);
+	return {
+		name,
+		absPath,
+		segments,
+		meta,
+		metaPath: path.join(absPath, "meta.json"),
+		index,
+		pages: pages.filter((page) => page !== index),
+		dirs
+	};
+}
+async function readPage(filePath, 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;
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		throw new Error(`Could not parse the frontmatter block in ${relativePath}: ${reason}`);
+	}
+	const name = baseName(filePath);
+	const segments = name === INDEX_NAME ? [...dirSegments] : [...dirSegments, name];
+	return {
+		segments,
+		slug: segments.join("/"),
+		href: toHref(config.basePath, segments),
+		filePath,
+		relativePath,
+		frontmatter: await parseFrontmatter(data, relativePath, config.frontmatterSchema),
+		content
+	};
+}
+function collect(dir, files, bySlug) {
+	const own = dir.index ? [dir.index, ...dir.pages] : dir.pages;
+	for (const 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.`);
+		bySlug.set(file.slug, file);
+		files.push(file);
+	}
+	for (const child of dir.dirs) collect(child, files, bySlug);
+}
+function buildNav(dir, config) {
+	const entries = [];
+	/**
+	* `guides.md` beside a `guides/` that has no `index.md` is that directory's
+	* own page: both answer to the name `meta.json` addresses them by, and both
+	* contribute a nav entry. Merged into one group whose heading links to the
+	* page, rather than left to collide — an ambiguous name is how a published
+	* route ends up reachable from no link in the sidebar.
+	*
+	* When the directory *does* have an `index.md`, the two claim the same route
+	* and `collect` has already failed the build.
+	*/
+	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);
+			continue;
+		}
+		entries.push(toPageEntry(page, config));
+	}
+	if (dir.index) entries.push({
+		...toPageEntry(dir.index, config),
+		isIndex: true
+	});
+	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;
+		const group = {
+			type: "group",
+			title,
+			children,
+			...href !== void 0 ? { href } : {}
+		};
+		const node = children.length === 0 && index !== void 0 && href !== void 0 ? {
+			type: "page",
+			title,
+			href,
+			slug: index.slug
+		} : group;
+		const order = index?.frontmatter.order;
+		entries.push({
+			name: child.name,
+			title,
+			node,
+			inlineChildren: children,
+			...index !== void 0 && href !== void 0 ? { indexNode: {
+				type: "page",
+				title: navTitle(index),
+				href,
+				slug: index.slug
+			} } : {},
+			...order !== void 0 ? { order } : {}
+		});
+	}
+	return orderNavEntries(entries, dir.meta, dir.metaPath);
+}
+function toPageEntry(page, config) {
+	const title = navTitle(page);
+	const { order } = page.frontmatter;
+	return {
+		name: baseName(page.filePath),
+		title,
+		node: {
+			type: "page",
+			title,
+			href: page.href,
+			slug: page.slug
+		},
+		...order !== void 0 ? { order } : {},
+		...isVisibleIn(page, config) ? {} : { hidden: true }
+	};
+}
+/** Sidebars are narrow: `label` wins over `title` when the author set one. */
+function navTitle(page) {
+	return page.frontmatter.label ?? page.frontmatter.title;
+}
+/**
+* A group heading: its own `meta.json` title, else the title of the page that
+* *is* the directory (`index.md`, or a merged same-named sibling), else the
+* directory name humanised.
+*/
+function groupTitle(dir, index) {
+	const fromMeta = dir.meta?.title;
+	if (fromMeta !== void 0) return fromMeta;
+	if (index) return navTitle(index);
+	return humanize(dir.name);
+}
+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`.
+*
+* 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.
+*/
+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
+* `_drafts/` was excluded while `_notes.md` beside it was published: routed,
+* listed in the sidebar, written into the sitemap, indexed for search.
+*
+* The asymmetry cannot have been intentional. There is no `ignore` option in
+* `DocsConfig`, and `draft: true` still demands a valid `title`, so the
+* underscore is the ONLY way to keep a markdown file in the tree without
+* publishing it — and it silently did not work for the half people reach for
+* first. Docusaurus and Nextra skip both forms.
+*/
+function isPageFile(name) {
+	return !name.startsWith(".") && !name.startsWith("_") && name.endsWith(PAGE_EXTENSION) && name.length > 3;
+}
+/** `_drafts/` and `.git/` are not content. */
+function isIgnoredDir(name) {
+	return name.startsWith(".") || name.startsWith("_");
+}
+function baseName(filePath) {
+	return path.basename(filePath, PAGE_EXTENSION);
+}
+function toHref(basePath, segments) {
+	if (segments.length === 0) return basePath === "" ? "/" : basePath;
+	return `${basePath}/${segments.join("/")}`;
+}
+function normalizeBasePath(basePath) {
+	const trimmed = basePath.trim().replace(/\/+$/, "");
+	if (trimmed === "") return "";
+	return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+/** Windows separators never reach a URL or a `relativePath`. */
+function toPosix(value) {
+	return value.split(path.sep).join("/");
+}
+/** `getting-started` -> `Getting Started`. */
+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 };