@tenphi/docs 0.17.0 → 0.18.0

package/dist/{content-XLQlJDnf.js → content-6Xp1J4Jh.js}

@@ -1,4 +1,4 @@
-import { i as normalizeDocsConfig } from "./config-Ci9Nv0wQ.js";
+import { i as normalizeDocsConfig, m as validateTableOfContents, p as validateSeo, u as pagePublishing } from "./config-CD77r6rT.js";
 import { cloneAst, parseMarkdown, removeRenderedTitle, serializeMarkdown, stripLeadingBadgeBlock } from "./markdown/index.js";
 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";
@@ -150,17 +150,20 @@ function openApiPages(source, routeBase, text) {
 		];
 		if (string(operation.description)) body.push(operation.description, "");
 		if (Array.isArray(operation.tags) && operation.tags.length) body.push(`**Tags:** ${operation.tags.filter((tag) => typeof tag === "string").map(escapeText).join(", ")}`, "");
-		const pathItem = resolveReference(document.paths[path], document);
-		const parameters = [...Array.isArray(pathItem.parameters) ? pathItem.parameters : [], ...Array.isArray(operation.parameters) ? operation.parameters : []];
+		const parameters = mergeParameters(resolveReference(document.paths[path], document).parameters, operation.parameters, document);
+		renderSecurity(body, operation.security !== void 0 ? operation.security : document.security, document);
 		if (parameters.length) {
 			body.push("## Parameters", "", "| Name | In | Required | Description |", "| --- | --- | --- | --- |");
-			for (const parameter of parameters) {
-				const item = resolveReference(parameter, document);
-				if (!record(item)) continue;
+			for (const item of parameters) {
 				const schema = record(item.schema) ? ` (${schemaLabel(item.schema)})` : "";
 				body.push(`| ${tableCell(string(item.name) ?? "—")} | ${tableCell(string(item.in) ?? "—")} | ${item.required === true ? "Yes" : "No"} | ${tableCell(`${string(item.description) ?? ""}${schema}`)} |`);
 			}
 			body.push("");
+			for (const item of parameters) if ("example" in item || "examples" in item || "content" in item) {
+				body.push(`### ${escapeText(String(item.name))} (${escapeText(String(item.in))})`, "");
+				renderExamples(body, item, document);
+				renderContent(body, item.content, document);
+			}
 		}
 		if (operation.requestBody !== void 0) {
 			const request = resolveReference(operation.requestBody, document);
@@ -168,7 +171,7 @@ function openApiPages(source, routeBase, text) {
 				body.push("## Request body", "");
 				if (string(request.description)) body.push(request.description, "");
 				body.push(`**Required:** ${request.required === true ? "Yes" : "No"}`, "");
-				renderContent(body, request.content);
+				renderContent(body, request.content, document);
 			}
 		}
 		if (record(operation.responses)) {
@@ -177,12 +180,12 @@ function openApiPages(source, routeBase, text) {
 				const response = resolveReference(value, document);
 				if (!record(response)) continue;
 				body.push(`### ${escapeText(status)}${string(response.description) ? ` — ${escapeText(response.description)}` : ""}`, "");
-				renderContent(body, response.content);
+				renderContent(body, response.content, document);
 			}
 		}
 		pages.push({
 			route,
-			sourcePath: `${source}#${route.slice(routeBase.length + 1)}.md`,
+			sourcePath: `${source}#${route.split("/").at(-1)}.md`,
 			title: operationTitle,
 			...string(operation.description) ? { description: operation.description } : {},
 			body: body.join("\n")
@@ -190,15 +193,85 @@ function openApiPages(source, routeBase, text) {
 	}
 	return pages;
 }
-function renderContent(lines, content) {
+function mergeParameters(path, operation, document) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const list of [path, operation]) {
+		if (list === void 0) continue;
+		if (!Array.isArray(list)) throw new Error("OpenAPI parameters must be an array.");
+		const seen = /* @__PURE__ */ new Set();
+		for (const value of list) {
+			const item = resolveReference(value, document);
+			if (!record(item) || !string(item.name) || ![
+				"query",
+				"header",
+				"path",
+				"cookie"
+			].includes(String(item.in))) throw new Error("OpenAPI parameters need a name and a valid in location.");
+			const identity = JSON.stringify([item.name, item.in]);
+			if (seen.has(identity)) throw new Error(`Duplicate OpenAPI parameter ${item.name} in ${item.in}.`);
+			seen.add(identity);
+			merged.set(identity, item);
+		}
+	}
+	return [...merged.values()];
+}
+function renderContent(lines, content, document) {
 	if (!record(content)) return;
 	for (const [mediaType, media] of Object.entries(content)) {
 		lines.push(`#### ${escapeText(mediaType)}`, "");
 		if (record(media) && media.schema !== void 0) lines.push(jsonBlock(media.schema), "");
-		if (record(media) && record(media.examples)) for (const [name, example] of Object.entries(media.examples)) {
-			const value = record(example) && "value" in example ? example.value : example;
-			lines.push(`**Example: ${escapeText(name)}**`, "", jsonBlock(value), "");
+		if (record(media)) renderExamples(lines, media, document);
+	}
+}
+function renderExamples(lines, owner, document) {
+	if ("example" in owner) lines.push("**Example**", "", jsonBlock(owner.example), "");
+	if (!record(owner.examples)) return;
+	for (const [name, raw] of Object.entries(owner.examples)) {
+		const example = resolveReference(raw, document);
+		if (!record(example)) throw new Error(`OpenAPI example ${name} must be an Example Object.`);
+		lines.push(`**Example: ${escapeText(name)}**`, "");
+		if (string(example.summary)) lines.push(escapeText(example.summary), "");
+		if (string(example.description)) lines.push(example.description, "");
+		if ("value" in example) lines.push(jsonBlock(example.value), "");
+		if (string(example.externalValue)) {
+			const url = example.externalValue;
+			lines.push(/^https?:\/\/[^\s<>]+$/i.test(url) ? `[External example](<${url}>)` : `External example: ${escapeText(url)}`, "");
+		}
+	}
+}
+function renderSecurity(lines, security, document) {
+	lines.push("## Authentication", "");
+	if (security === void 0 || Array.isArray(security) && !security.length) {
+		lines.push("No authentication required.", "");
+		return;
+	}
+	if (!Array.isArray(security)) throw new Error("OpenAPI security must be an array.");
+	const schemes = record(document.components) && record(document.components.securitySchemes) ? document.components.securitySchemes : {};
+	if (security.length > 1) lines.push("Use any one of these alternatives:", "");
+	for (const [index, requirement] of security.entries()) {
+		if (!record(requirement)) throw new Error("OpenAPI security requirements must be objects.");
+		if (security.length > 1) lines.push(`### Alternative ${index + 1}`, "");
+		const names = Object.keys(requirement);
+		if (!names.length) {
+			lines.push("No authentication required (anonymous access).", "");
+			continue;
+		}
+		if (names.length > 1) lines.push("All of the following are required together:", "");
+		for (const name of names) {
+			const scheme = resolveReference(schemes[name], document);
+			if (!record(scheme)) throw new Error(`Unknown OpenAPI security scheme: ${name}.`);
+			const scopes = requirement[name];
+			if (!Array.isArray(scopes) || scopes.some((scope) => typeof scope !== "string")) throw new Error(`OpenAPI security scopes for ${name} must be strings.`);
+			let detail = string(scheme.type) ?? "security scheme";
+			if (scheme.type === "http") detail = `HTTP ${string(scheme.scheme) ?? "authentication"}${string(scheme.bearerFormat) ? ` (${scheme.bearerFormat})` : ""}`;
+			else if (scheme.type === "apiKey") detail = `API key ${string(scheme.name) ?? name} in ${string(scheme.in) ?? "request"}`;
+			else if (scheme.type === "oauth2") detail = "OAuth 2.0";
+			else if (scheme.type === "openIdConnect") detail = "OpenID Connect";
+			else if (scheme.type === "mutualTLS") detail = "Mutual TLS";
+			lines.push(`- **${escapeText(name)}:** ${escapeText(detail)}${scopes.length ? `. Required scopes: ${scopes.map((scope) => escapeText(String(scope))).join(", ")}` : ""}`);
+			if (string(scheme.description)) lines.push("", scheme.description, "");
 		}
+		lines.push("");
 	}
 }
 function assertLocalReferences(value, document, source, seen = /* @__PURE__ */ new Set()) {
@@ -208,22 +281,46 @@ function assertLocalReferences(value, document, source, seen = /* @__PURE__ */ n
 	else for (const [key, item] of Object.entries(value)) {
 		if (key === "$ref" && (typeof item !== "string" || !item.startsWith("#/"))) throw new Error(`OpenAPI source ${source} has an external or invalid $ref; bundle references into the document first.`);
 		if (key === "$ref" && typeof item === "string" && lookupReference(item, document) === void 0) throw new Error(`OpenAPI source ${source} has an unresolved reference: ${item}.`);
+		if ([
+			"example",
+			"default",
+			"const",
+			"enum"
+		].includes(key)) continue;
+		if (key === "examples") {
+			if (record(item)) {
+				for (const example of Object.values(item)) if (record(example)) {
+					const { value: _payload, ...metadata } = example;
+					assertLocalReferences(metadata, document, source, seen);
+				}
+			}
+			continue;
+		}
+		if (key === "properties" && record(item)) {
+			for (const schema of Object.values(item)) assertLocalReferences(schema, document, source, seen);
+			continue;
+		}
 		assertLocalReferences(item, document, source, seen);
 	}
 }
 function resolveReference(value, document) {
 	const visited = /* @__PURE__ */ new Set();
+	const overrides = {};
 	while (record(value) && typeof value.$ref === "string") {
+		for (const key of ["summary", "description"]) if (!(key in overrides) && typeof value[key] === "string") overrides[key] = value[key];
 		const ref = value.$ref;
 		if (visited.has(ref)) throw new Error(`Circular OpenAPI reference: ${ref}.`);
 		visited.add(ref);
 		value = lookupReference(ref, document);
 		if (value === void 0) throw new Error(`Unresolved OpenAPI reference: ${ref}.`);
 	}
-	return value;
+	return record(value) ? {
+		...value,
+		...overrides
+	} : value;
 }
 function lookupReference(ref, document) {
-	return ref.slice(2).split("/").reduce((current, part) => record(current) ? current[part.replace(/~1/g, "/").replace(/~0/g, "~")] : void 0, document);
+	return decodeURIComponent(ref.slice(2)).split("/").reduce((current, part) => record(current) || Array.isArray(current) ? current[part.replace(/~1/g, "/").replace(/~0/g, "~")] : void 0, document);
 }
 function record(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -247,7 +344,7 @@ function schemaLabel(schema) {
 	return typeof schema.$ref === "string" ? schema.$ref.split("/").at(-1) ?? "schema" : string(schema.type) ?? "schema";
 }
 function jsonBlock(value) {
-	const body = JSON.stringify(value, null, 2);
+	const body = JSON.stringify(value, null, 2) ?? "null";
 	let longest = 0;
 	for (const [run] of body.matchAll(/`+/g)) longest = Math.max(longest, run.length);
 	const fence = "`".repeat(Math.max(3, longest + 1));
@@ -495,7 +592,8 @@ function inside$1(root, path) {
 //#region src/graph/index.ts
 const MARKDOWN_EXTENSIONS = [".md", ".mdx"];
 const execFileAsync = promisify(execFile);
-const FRONTMATTER_KEYS = /* @__PURE__ */ new Set([
+const DOCS_FRONTMATTER_KEYS = /* @__PURE__ */ new Set([
+	"seo",
 	"aliases",
 	"title",
 	"description",
@@ -576,10 +674,10 @@ async function createDocsGraph(options = {}) {
 		}], routeMap, diagnostics);
 		validateNavigation(tab.items ?? [], routeMap, diagnostics);
 	}
-	for (const version of config.site.versions ?? []) if (!routeMap.has(version.routeBase)) diagnostics.push({
+	for (const version of config.site.versions ?? []) if (![version.routeBase, ...Object.keys(config.locales ?? {}).filter((locale) => locale !== "root").map((locale) => `/${locale}${version.routeBase === "/" ? "" : version.routeBase}`)].some((route) => routeMap.has(route) && !routeMap.get(route).frontmatter.draft)) diagnostics.push({
 		code: "DOCS_VERSION_ROOT_MISSING",
 		severity: "error",
-		message: `Version ${version.label} needs a page at ${version.routeBase}.`
+		message: `Version ${version.label} needs a non-draft page at ${version.routeBase} or a localized equivalent.`
 	});
 	entries.sort((left, right) => left.route.localeCompare(right.route));
 	return {
@@ -592,6 +690,10 @@ async function createDocsGraph(options = {}) {
 			entryId: entry.id,
 			sourcePath: entry.sourcePath,
 			title: entry.title,
+			discoverable: !entry.frontmatter.draft,
+			indexable: pagePublishing(entry, config).index,
+			sitemap: pagePublishing(entry, config).sitemap,
+			canonical: pagePublishing(entry, config).canonical,
 			...entry.frontmatter.sidebar !== void 0 ? { sidebar: entry.frontmatter.sidebar } : {}
 		})),
 		assets: Array.from(new Map(entries.flatMap((entry) => entry.assets).map((asset) => [asset.publicPath ?? `${asset.original}:${asset.line ?? ""}`, asset])).values()),
@@ -817,7 +919,7 @@ async function readEntry(source, config, diagnostics) {
 	if (frontmatter.sidebar === void 0 && source.navigation !== void 0) frontmatter.sidebar = source.navigation;
 	const diagnosticCount = diagnostics.length;
 	const metadata = {};
-	for (const key of Object.keys(frontmatter)) if (!FRONTMATTER_KEYS.has(key)) {
+	for (const key of Object.keys(frontmatter)) if (!DOCS_FRONTMATTER_KEYS.has(key)) {
 		if (config.content.frontmatter !== "reject") {
 			metadata[key] = frontmatter[key];
 			delete frontmatter[key];
@@ -1381,6 +1483,7 @@ function validateFrontmatter(value, file, diagnostics) {
 		message,
 		file
 	});
+	if (value.seo !== void 0) for (const message of validateSeo(value.seo, "page")) error(message);
 	if (value.aliases !== void 0 && (!Array.isArray(value.aliases) || value.aliases.some((alias) => typeof alias !== "string"))) error("aliases must be an array of route strings.");
 	for (const key of [
 		"title",
@@ -1397,10 +1500,7 @@ function validateFrontmatter(value, file, diagnostics) {
 		validateOptionalStrings(record.sidebar, ["label", "group"], "sidebar", error);
 		if (record.sidebar.order !== void 0 && typeof record.sidebar.order !== "number") error("sidebar.order must be a number.");
 	}
-	if (isPlainRecord(record.tableOfContents)) for (const key of ["minHeadingLevel", "maxHeadingLevel"]) {
-		const level = record.tableOfContents[key];
-		if (level !== void 0 && (!Number.isInteger(level) || Number(level) < 1 || Number(level) > 6)) error(`tableOfContents.${key} must be an integer from 1 to 6.`);
-	}
+	if (record.tableOfContents !== void 0) for (const message of validateTableOfContents(record.tableOfContents)) error(message);
 	if (record.editUrl !== void 0 && record.editUrl !== false && typeof record.editUrl !== "string") error("editUrl must be false or a string.");
 	if (record.lastUpdated !== void 0 && typeof record.lastUpdated !== "boolean" && !(record.lastUpdated instanceof Date)) error("lastUpdated must be a date or boolean.");
 	if (record.hero !== void 0) {
@@ -1424,6 +1524,8 @@ function validateHero(hero, error) {
 		if (!isPlainRecord(hero.image)) error("hero.image must be an object.");
 		else {
 			const image = hero.image;
+			for (const key of ["width", "height"]) if (image[key] !== void 0 && (!Number.isInteger(image[key]) || Number(image[key]) <= 0)) error(`hero.image.${key} must be a positive integer.`);
+			if (image.width === void 0 !== (image.height === void 0)) error("hero.image needs both width and height when dimensions are specified.");
 			if ([
 				"html",
 				"file",
@@ -1549,6 +1651,6 @@ function toLoaderEntry(entry) {
 	};
 }
 //#endregion
-export { resolvePackageLock as _, validateDocs as a, routeForPath as c, discoverPackage as d, lockForSource as f, reconcileDocsLock as g, readDocsLock as h, formatDiagnostics as i, assertSafePackagePath as l, packageNameFromSpecifier as m, DocsValidationError as n, createDocsGraph as o, materializePackage as p, assertValidDocs as r, normalizeRoute as s, createDocsLoader as t, defaultLock as u, validateLock as v, writeDocsLock as y };
+export { reconcileDocsLock as _, validateDocs as a, writeDocsLock as b, normalizeRoute as c, defaultLock as d, discoverPackage as f, readDocsLock as g, packageNameFromSpecifier as h, formatDiagnostics as i, routeForPath as l, materializePackage as m, DocsValidationError as n, DOCS_FRONTMATTER_KEYS as o, lockForSource as p, assertValidDocs as r, createDocsGraph as s, createDocsLoader as t, assertSafePackagePath as u, resolvePackageLock as v, validateLock as y };
 
-//# sourceMappingURL=content-XLQlJDnf.js.map
+//# sourceMappingURL=content-6Xp1J4Jh.js.map