hdoc-tools 0.60.1 → 0.62.0

package/hdoc-validate-interbook.js

@@ -0,0 +1,321 @@
+// Inter-book link validation.
+//
+// When a GitHub token is supplied to build/validate, root-relative links that
+// point at OTHER Hornbill Docs books (e.g. /esp-config/some/article#anchor) —
+// and fully-qualified docs.hornbill.com links where those are permitted
+// (_inline content) — are validated instead of being skipped:
+//
+//   1. The target book must exist — either listed in the published library
+//      (https://docs.hornbill.com/_books/library.json) or as a repo under
+//      github.com/Hornbill-Docs/<docId>.
+//   2. The target article must exist in the book's GitHub repo (default
+//      branch): <docId>/<path>.md, <path>/index.md, <path>.html or <path>.htm.
+//      A path matched by the target book's redirects[] also passes.
+//   3. If the source link carries a #hash-anchor, a matching heading anchor
+//      must exist in the target article. Anchor ids are derived from h2/h3
+//      headings with the same hdoc.makeAnchorIdFriendly slug used at build.
+//
+// All lookups are cached as promises (per book, per article, per repo config)
+// so concurrent link checks for the same target collapse into one API call.
+// GitHub API calls go through hdoc.fetchWithRetry which throttles to
+// 1 request/800ms and honours rate-limit headers.
+//
+// Result levels:
+//   ok      - link verified (caller appends to validated-links.txt)
+//   skip    - could not verify by design (book has no public source) — logged
+//   warning - could not verify due to access/infra (401/403, library down)
+//   error   - target book/article/anchor definitively missing
+(() => {
+	const cheerio = require("cheerio");
+	const path = require("node:path");
+	const hdoc = require(path.join(__dirname, "hdoc-module.js"));
+
+	const LIBRARY_URL = "https://docs.hornbill.com/_books/library.json";
+	const GITHUB_ORG_FALLBACK = "https://github.com/Hornbill-Docs";
+
+	let git_token = "";
+	let library_promise = null;
+	const book_cache = {}; // docId -> promise of book resolution
+	const article_cache = {}; // docId|path -> promise of article fetch
+	const redirects_cache = {}; // repo url -> promise of redirect url set
+
+	const gh_headers = () => {
+		const headers = {
+			"User-Agent": "HornbillDocsBuild",
+			"Cache-Control": "no-cache",
+			Accept: "application/vnd.github.raw+json",
+		};
+		if (git_token !== "") headers.authorization = `Bearer ${git_token}`;
+		return headers;
+	};
+
+	// github.com/<owner>/<repo> -> api.github.com/repos/<owner>/<repo>
+	const repo_api_base = (repo_url) => {
+		const clean = repo_url.endsWith("/") ? repo_url.slice(0, -1) : repo_url;
+		return clean.replace(
+			"https://github.com/",
+			"https://api.github.com/repos/",
+		);
+	};
+
+	const get_library = () => {
+		if (library_promise === null) {
+			library_promise = (async () => {
+				const books = {};
+				const resp = await hdoc.fetchWithRetry(LIBRARY_URL, {
+					headers: { "User-Agent": "HornbillDocsBuild" },
+					timeoutMs: 10000,
+				});
+				if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+				const data = await resp.json();
+				for (const book of data.books || []) {
+					books[book.docId] = book;
+				}
+				return books;
+			})().catch((e) => {
+				// Cache the failure — one warning per run, not one per link
+				return { __error: `${e}` };
+			});
+		}
+		return library_promise;
+	};
+
+	// Resolve a docId to { exists, repo|null, unverifiable|undefined }
+	const resolve_book = (doc_id) => {
+		if (!book_cache[doc_id]) {
+			book_cache[doc_id] = (async () => {
+				const library = await get_library();
+				if (!library.__error && library[doc_id]) {
+					return {
+						exists: true,
+						repo: library[doc_id].publicSource || null,
+					};
+				}
+				// Not in the public library (internal book?) or library down —
+				// fall back to the conventional repo location.
+				const fallback_repo = `${GITHUB_ORG_FALLBACK}/${doc_id}`;
+				const details = await hdoc.get_github_repo_details(
+					repo_api_base(fallback_repo),
+					git_token,
+				);
+				if (details.success) return { exists: true, repo: fallback_repo };
+				// get_github_repo_details reports 404 as "Error: HTTP 404" (early
+				// return) or "404 : Not Found" (json branch) depending on path
+				const err = details.error instanceof Error ? details.error.message : `${details.error}`;
+				if (err.includes("404")) {
+					if (library.__error) {
+						// Library unreachable AND no fallback repo — can't be sure
+						return {
+							exists: false,
+							repo: null,
+							unverifiable: `book library unreachable (${library.__error}) and no repo at ${fallback_repo}`,
+						};
+					}
+					return { exists: false, repo: null };
+				}
+				// 401/403/network — repo may exist but we can't see it
+				return {
+					exists: false,
+					repo: null,
+					unverifiable: `GitHub lookup failed for ${fallback_repo}: ${err}`,
+				};
+			})();
+		}
+		return book_cache[doc_id];
+	};
+
+	// Fetch a repo file's raw content via the contents API.
+	// Returns { status, content } — content null unless status 200.
+	const fetch_repo_file = async (repo, file_path) => {
+		const encoded = file_path.split("/").map(encodeURIComponent).join("/");
+		const resp = await hdoc.fetchWithRetry(
+			`${repo_api_base(repo)}/contents/${encoded}`,
+			{ headers: gh_headers(), timeoutMs: 10000 },
+			2,
+		);
+		return {
+			status: resp.status,
+			content: resp.ok ? await resp.text() : null,
+		};
+	};
+
+	// The redirect urls declared in the target book's hdocbook-project.json —
+	// a link to a redirected path is valid (the published site serves 301/308).
+	const get_redirect_urls = (repo) => {
+		if (!redirects_cache[repo]) {
+			redirects_cache[repo] = (async () => {
+				const urls = {};
+				try {
+					const file = await fetch_repo_file(repo, "hdocbook-project.json");
+					if (file.status === 200) {
+						const project = JSON.parse(file.content);
+						for (const redirect of project.redirects || []) {
+							if (redirect.url) urls[redirect.url] = true;
+						}
+					}
+				} catch {
+					// Malformed/missing project file in target repo — no redirects
+				}
+				return urls;
+			})();
+		}
+		return redirects_cache[repo];
+	};
+
+	// Derive the set of hb-doc-anchor-* ids the build would generate for a
+	// target article. Markdown: h2/h3 ATX headings outside code fences, with
+	// [text](url) collapsed to text before slugging (matching rendered text).
+	// HTML: real h2/h3 elements via cheerio.
+	const extract_anchor_ids = (content, is_html) => {
+		const anchors = {};
+		if (is_html) {
+			const $ = cheerio.load(content);
+			$("h2, h3").each(function () {
+				anchors[hdoc.makeAnchorIdFriendly($(this).text().trim())] = true;
+			});
+			return anchors;
+		}
+		let in_fence = false;
+		for (const raw_line of content.split("\n")) {
+			const line = raw_line.trimEnd();
+			if (/^\s*(```|~~~)/.test(line)) {
+				in_fence = !in_fence;
+				continue;
+			}
+			if (in_fence) continue;
+			const match = line.match(/^(##|###)\s+(.*)$/);
+			if (!match) continue;
+			const text = match[2]
+				.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // md links -> link text
+				.replace(/[`*_]/g, "") // inline emphasis/code markers
+				.trim();
+			anchors[hdoc.makeAnchorIdFriendly(text)] = true;
+		}
+		return anchors;
+	};
+
+	// Locate an article inside a book repo, trying the same resolution order
+	// the published site uses. Returns
+	// { found, redirected, unverifiable, anchors } — anchors null when the
+	// article was matched via redirect (content not fetched).
+	const resolve_article = (repo, doc_id, article_path) => {
+		const cache_key = `${doc_id}|${article_path}`;
+		if (!article_cache[cache_key]) {
+			article_cache[cache_key] = (async () => {
+				const base = `${doc_id}/${article_path}`;
+				const candidates = [
+					{ file: `${base}.md`, html: false },
+					{ file: `${base}/index.md`, html: false },
+					{ file: `${base}.html`, html: true },
+					{ file: `${base}.htm`, html: true },
+				];
+				// Book-root link (/other-book) → the book's index page
+				if (article_path === "index") candidates.splice(1, 1);
+				for (const candidate of candidates) {
+					const file = await fetch_repo_file(repo, candidate.file);
+					if (file.status === 200) {
+						return {
+							found: true,
+							anchors: extract_anchor_ids(file.content, candidate.html),
+						};
+					}
+					if (file.status !== 404) {
+						return {
+							found: false,
+							unverifiable: `GitHub returned HTTP ${file.status} for ${candidate.file}`,
+						};
+					}
+				}
+				const redirect_urls = await get_redirect_urls(repo);
+				if (redirect_urls[`/${base}`]) {
+					return { found: true, redirected: true, anchors: null };
+				}
+				return { found: false };
+			})();
+		}
+		return article_cache[cache_key];
+	};
+
+	exports.init = (token) => {
+		git_token = token || "";
+	};
+
+	exports.enabled = () => git_token !== "";
+
+	// link: root-relative inter-book link, e.g. /esp-config/path/article#anchor
+	// Returns { level: 'ok'|'skip'|'warning'|'error', message }
+	exports.check_link = async (link) => {
+		const [link_path, hash_anchor] = link.split("#");
+		const segments = link_path.split("/").filter((s) => s !== "");
+		if (segments[0] === "_books") segments.shift();
+		const doc_id = segments.shift();
+		const article_path = segments.length > 0 ? segments.join("/") : "index";
+
+		let book;
+		try {
+			book = await resolve_book(doc_id);
+		} catch (e) {
+			return {
+				level: "warning",
+				message: `Unable to verify inter-book link [${link}]: ${e}`,
+			};
+		}
+		if (book.unverifiable) {
+			return {
+				level: "warning",
+				message: `Unable to verify inter-book link [${link}]: ${book.unverifiable}`,
+			};
+		}
+		if (!book.exists) {
+			return {
+				level: "error",
+				message: `Inter-book link target book does not exist: ${doc_id} [${link}]`,
+			};
+		}
+		if (!book.repo) {
+			// Generated books (API references) have no public source repo
+			return {
+				level: "skip",
+				message: `Inter-book link target book [${doc_id}] exists but has no source repo - article not verified: ${link}`,
+			};
+		}
+
+		let article;
+		try {
+			article = await resolve_article(book.repo, doc_id, article_path);
+		} catch (e) {
+			return {
+				level: "warning",
+				message: `Unable to verify inter-book link [${link}]: ${e}`,
+			};
+		}
+		if (article.unverifiable) {
+			return {
+				level: "warning",
+				message: `Unable to verify inter-book link [${link}]: ${article.unverifiable}`,
+			};
+		}
+		if (!article.found) {
+			return {
+				level: "error",
+				message: `Inter-book link target article does not exist in book [${doc_id}]: ${link}`,
+			};
+		}
+
+		if (hash_anchor) {
+			if (article.anchors === null) {
+				return {
+					level: "skip",
+					message: `Inter-book link resolves via redirect - hash anchor not verified: ${link}`,
+				};
+			}
+			if (!article.anchors[`hb-doc-anchor-${hash_anchor}`]) {
+				return {
+					level: "error",
+					message: `Inter-book link hash anchor not present in target article: ${link}`,
+				};
+			}
+		}
+		return { level: "ok", message: `Inter-book link verified: ${link}` };
+	};
+})();