hdoc-tools 0.62.1 → 0.62.2

package/hdoc-validate-interbook.js

@@ -10,7 +10,8 @@
 //      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.
+//      A path matched by the target book's redirects[] also passes, unless
+//      the redirect code is 410 (content deliberately removed) — error.
 //   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.
@@ -32,12 +33,22 @@
 
 	const LIBRARY_URL = "https://docs.hornbill.com/_books/library.json";
 	const GITHUB_ORG_FALLBACK = "https://github.com/Hornbill-Docs";
+	const PUBLISHED_SITE = "https://docs.hornbill.com";
+
+	// Books generated outside GitHub (built in Hornbill Projects, published
+	// straight to docs.hornbill.com) have no repo to inspect, so they are keyed
+	// off the docId suffix instead:
+	//   -api / -db  → not verifiable at all, skip
+	//   -packages   → verify the page exists on the published site
+	const UNVERIFIABLE_SUFFIXES = ["-api", "-db"];
+	const PUBLISHED_ONLY_SUFFIXES = ["-packages"];
 
 	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 published_cache = {}; // published url -> promise of { ok, status }
 
 	const gh_headers = () => {
 		const headers = {
@@ -139,8 +150,10 @@
 		};
 	};
 
-	// 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).
+	// The redirect urls declared in the target book's hdocbook-project.json,
+	// mapped to their redirect code. A link to a 301/308-redirected path is
+	// valid (the published site forwards it); a 410 means the content was
+	// deliberately removed, so a link to it is broken.
 	const get_redirect_urls = (repo) => {
 		if (!redirects_cache[repo]) {
 			redirects_cache[repo] = (async () => {
@@ -150,7 +163,7 @@
 					if (file.status === 200) {
 						const project = JSON.parse(file.content);
 						for (const redirect of project.redirects || []) {
-							if (redirect.url) urls[redirect.url] = true;
+							if (redirect.url) urls[redirect.url] = redirect.code || 301;
 						}
 					}
 				} catch {
@@ -196,8 +209,9 @@
 
 	// 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).
+	// { found, redirected, gone, unverifiable, anchors } — anchors null when
+	// the article was matched via redirect (content not fetched); gone true
+	// when the path matched a 410 redirect (content removed).
 	const resolve_article = (repo, doc_id, article_path) => {
 		const cache_key = `${doc_id}|${article_path}`;
 		if (!article_cache[cache_key]) {
@@ -227,7 +241,9 @@
 					}
 				}
 				const redirect_urls = await get_redirect_urls(repo);
-				if (redirect_urls[`/${base}`]) {
+				const redirect_code = redirect_urls[`/${base}`];
+				if (redirect_code) {
+					if (redirect_code === 410) return { found: false, gone: true };
 					return { found: true, redirected: true, anchors: null };
 				}
 				return { found: false };
@@ -236,6 +252,29 @@
 		return article_cache[cache_key];
 	};
 
+	const has_suffix = (doc_id, suffixes) =>
+		suffixes.some((suffix) => doc_id.endsWith(suffix));
+
+	// GET the published site to confirm a generated book page exists. HEAD is
+	// NOT usable here — docs.hornbill.com answers 404 to HEAD on pages that
+	// GET serves 200.
+	const check_published = (url) => {
+		if (!published_cache[url]) {
+			published_cache[url] = (async () => {
+				const resp = await hdoc.fetchWithRetry(
+					url,
+					{
+						headers: { "User-Agent": "HornbillDocsBuild" },
+						timeoutMs: 10000,
+					},
+					2,
+				);
+				return { ok: resp.ok, status: resp.status };
+			})();
+		}
+		return published_cache[url];
+	};
+
 	exports.init = (token) => {
 		git_token = token || "";
 	};
@@ -251,6 +290,48 @@
 		const doc_id = segments.shift();
 		const article_path = segments.length > 0 ? segments.join("/") : "index";
 
+		// Books not sourced from GitHub — resolved by docId suffix, no repo
+		if (has_suffix(doc_id, UNVERIFIABLE_SUFFIXES)) {
+			return {
+				level: "skip",
+				message: `Inter-book link target book [${doc_id}] is generated - link not verified: ${link}`,
+			};
+		}
+		if (has_suffix(doc_id, PUBLISHED_ONLY_SUFFIXES)) {
+			const url = `${PUBLISHED_SITE}${link_path}`;
+			let published;
+			try {
+				published = await check_published(url);
+			} catch (e) {
+				return {
+					level: "warning",
+					message: `Unable to verify inter-book link [${link}]: ${e}`,
+				};
+			}
+			if (published.status === 404) {
+				return {
+					level: "error",
+					message: `Inter-book link target page does not exist on ${PUBLISHED_SITE} [${doc_id}]: ${link}`,
+				};
+			}
+			if (!published.ok) {
+				return {
+					level: "warning",
+					message: `Unable to verify inter-book link [${link}]: ${url} returned HTTP ${published.status}`,
+				};
+			}
+			if (hash_anchor) {
+				return {
+					level: "skip",
+					message: `Inter-book link page verified on ${PUBLISHED_SITE} - hash anchor not verified: ${link}`,
+				};
+			}
+			return {
+				level: "ok",
+				message: `Inter-book link verified on ${PUBLISHED_SITE}: ${link}`,
+			};
+		}
+
 		let book;
 		try {
 			book = await resolve_book(doc_id);
@@ -296,6 +377,12 @@
 			};
 		}
 		if (!article.found) {
+			if (article.gone) {
+				return {
+					level: "error",
+					message: `Inter-book link target article was removed (410 gone) from book [${doc_id}]: ${link}`,
+				};
+			}
 			return {
 				level: "error",
 				message: `Inter-book link target article does not exist in book [${doc_id}]: ${link}`,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "hdoc-tools",
-	"version": "0.62.1",
+	"version": "0.62.2",
 	"description": "Hornbill HDocBook Development Support Tool",
 	"main": "hdoc.js",
 	"bin": {