hdoc-tools 0.62.4 → 0.62.5

package/hdoc-validate-interbook.js

@@ -290,6 +290,14 @@
 		const doc_id = segments.shift();
 		const article_path = segments.length > 0 ? segments.join("/") : "index";
 
+		// No book in the path (e.g. a bare "/") - nothing to resolve
+		if (!doc_id) {
+			return {
+				level: "skip",
+				message: `Inter-book link has no target book - link not verified: ${link}`,
+			};
+		}
+
 		// Books not sourced from GitHub — resolved by docId suffix, no repo
 		if (has_suffix(doc_id, UNVERIFIABLE_SUFFIXES)) {
 			return {

package/hdoc-validate.js

@@ -498,10 +498,22 @@
 		return resp.status;
 	};
 
-	// Map an inter-book check result onto errors/warnings/messages and the
-	// validated-links cache. 'ok' and 'skip' outcomes are stable, so they are
-	// appended to validated-links.txt like any other passing link.
-	const handleInterbookResult = (result, link, htmlFile, markdown_paths, markdown_content) => {
+	// Links already written to validated-links.txt this run. A link can appear
+	// on many pages, but only needs writing to the cache file once.
+	const skip_links_written = new Set();
+	const appendSkipLink = (link) => {
+		if (skip_links_written.has(link)) return;
+		skip_links_written.add(link);
+		fs.appendFileSync(skip_link_file, `${link}\n`);
+	};
+
+	// Map a network check result (inter-book or external URL) onto
+	// errors/warnings/messages and the validated-links cache. 'ok' and 'skip'
+	// outcomes are stable, so they are appended to validated-links.txt like any
+	// other passing link. Called once per PAGE carrying the link, so the
+	// message is positioned against the page being reported on.
+	const emitLinkResult = (result, link, htmlFile, markdown_paths, markdown_content) => {
+		if (!result) return;
 		if (result.level === "error") {
 			errors[htmlFile.relativePath].push(
 				processErrorMessage(result.message, markdown_paths.relativePath, markdown_content, link),
@@ -512,10 +524,25 @@
 			);
 		} else {
 			messages[htmlFile.relativePath].push(result.message);
-			fs.appendFileSync(skip_link_file, `${link}\n`);
+			appendSkipLink(link);
 		}
 	};
 
+	// Run a network check for a link at most once per run, but hand the SAME
+	// result back to every page that carries the link. Deduplicating the fetch
+	// is a performance concern; deduplicating the reporting is not - a broken
+	// link on ten pages has to be flagged on all ten, or fixing the first page
+	// just surfaces the second on the next build.
+	// global_links_checked: Map link -> Promise<{ level, message } | null>
+	const checkLinkOnce = (global_links_checked, link, check) => {
+		let pending = global_links_checked.get(link);
+		if (!pending) {
+			pending = check();
+			global_links_checked.set(link, pending);
+		}
+		return pending;
+	};
+
 	const checkLinks = async (source_path, htmlFile, links, hdocbook_config, hdocbook_project, global_links_checked, output_links) => {
 		const markdown_paths = getMDPathFromHtmlPath(htmlFile);
 		const markdown_content = fs.readFileSync(markdown_paths.markdownPath, 'utf8');
@@ -537,11 +564,15 @@
 		// concurrently rather than one-at-a-time.
 		const externalChecks = [];
 
+		// Same link twice on the same page is reported once. Across pages it is
+		// reported every time - see checkLinkOnce.
+		const page_links_checked = new Set();
+
 		for (let i = 0; i < links.length; i++) {
 			if (output_links) console.log(` - ${links[i]}`);
 			if (exclude_links[links[i]]) continue;
-			if (global_links_checked.includes(links[i])) continue;
-			global_links_checked.push(links[i]);
+			if (page_links_checked.has(links[i])) continue;
+			page_links_checked.add(links[i]);
 
 			const valid_url = hdoc.valid_url(links[i]);
 			if (!valid_url) {
@@ -554,6 +585,13 @@
 					if (link_segments[0] === "") link_segments.shift();
 					const link_root = link_segments[0] === "_books" ? link_segments[1] : link_segments[0];
 
+					// A bare "/" is the docs site home page - no book, nothing to
+					// resolve locally or against GitHub.
+					if (link_root === undefined || link_root === "") {
+						appendSkipLink(links[i]);
+						continue;
+					}
+
 					// Check for links with a _books path that have no specific file target
 					// We do need to exclude those with an extension though, for pages that link downloadable resources
 					if (link_segments[0] === "_books" && path.extname(links[i]) === '') {
@@ -567,8 +605,10 @@
 						if (interbook.enabled() && path.extname(links[i].split("#")[0]) === "") {
 							const link = links[i];
 							externalChecks.push(async () =>
-								handleInterbookResult(
-									await interbook.check_link(link),
+								emitLinkResult(
+									await checkLinkOnce(global_links_checked, link, () =>
+										interbook.check_link(link),
+									),
 									link,
 									htmlFile,
 									markdown_paths,
@@ -576,7 +616,7 @@
 								),
 							);
 						} else {
-							fs.appendFileSync(skip_link_file, `${links[i]}\n`);
+							appendSkipLink(links[i]);
 						}
 						continue;
 					}
@@ -603,12 +643,12 @@
 					)
 					.edit_path.replace(path.extname(htmlFile.relativePath), ".md")
 				) {
-					fs.appendFileSync(skip_link_file, `${links[i]}\n`);
+					appendSkipLink(links[i]);
 					continue;
 				}
 
 				if (valid_url.protocol === "mailto:") {
-					fs.appendFileSync(skip_link_file, `${links[i]}\n`);
+					appendSkipLink(links[i]);
 					continue;
 				}
 
@@ -653,8 +693,10 @@
 					const link = links[i];
 					const book_link = valid_url.pathname + valid_url.hash;
 					externalChecks.push(async () =>
-						handleInterbookResult(
-							await interbook.check_link(book_link),
+						emitLinkResult(
+							await checkLinkOnce(global_links_checked, link, () =>
+								interbook.check_link(book_link),
+							),
 							link,
 							htmlFile,
 							markdown_paths,
@@ -668,20 +710,19 @@
 				const url = links[i];
 				const isInternal = url.toLowerCase().includes("internal.hornbill.com");
 
-				externalChecks.push(async () => {
+				// Returns a page-independent { level, message } (or null for "say
+				// nothing") so the outcome can be cached per URL and replayed
+				// against every page that links to it.
+				const checkExternalUrl = async () => {
 					// For internal.hornbill.com links, check network reachability first (result cached)
 					if (isInternal) {
 						const on_int_net = await ensureIntNetCached();
 						if (!on_int_net) {
-							messages[htmlFile.relativePath].push(
-								`Outside of Hornbill network - skipping internal link validation for: ${url}`,
-							);
-							fs.appendFileSync(skip_link_file, `${url}\n`);
-							return;
+							return {
+								level: "skip",
+								message: `Outside of Hornbill network - skipping internal link validation for: ${url}`,
+							};
 						}
-						messages[htmlFile.relativePath].push(
-							`Inside of Hornbill network - performing internal link validation for: ${url}`,
-						);
 					}
 
 					try {
@@ -689,25 +730,39 @@
 						if ((status < 200 || status > 299) && status !== 304) {
 							if (process.env.GITHUB_ACTIONS === 'true' && status === 403 && url.includes(".hornbill.com")) {
 								// Always returns 403 for Hornbill sites through GitHub Actions — not a real error
-							} else {
-								throw `Unexpected Status Returned: ${status}`;
+								return null;
 							}
-						} else {
-							fs.appendFileSync(skip_link_file, `${url}\n`);
+							throw `Unexpected Status Returned: ${status}`;
 						}
+						return {
+							level: "ok",
+							message: `External link is valid: ${url}`,
+						};
 					} catch (e) {
 						let error_message;
 						if (e instanceof AggregateError) {
-							error_message = processErrorMessage(`Issue with external link [${url}]: ${e.message} - ${JSON.stringify(e.errors)}`, markdown_paths.relativePath, markdown_content, url);
+							error_message = `Issue with external link [${url}]: ${e.message} - ${JSON.stringify(e.errors)}`;
 						} else {
-							error_message = processErrorMessage(`Issue with external link [${url}]: ${e}`, markdown_paths.relativePath, markdown_content, url);
+							error_message = `Issue with external link [${url}]: ${e}`;
 						}
-						if (hdocbook_project.validation.external_link_warnings || process.env.GITHUB_ACTIONS === 'true')
-							warnings[htmlFile.relativePath].push(error_message);
-						else
-							errors[htmlFile.relativePath].push(error_message);
+						const level =
+							hdocbook_project.validation.external_link_warnings ||
+							process.env.GITHUB_ACTIONS === 'true'
+								? "warning"
+								: "error";
+						return { level, message: error_message };
 					}
-				});
+				};
+
+				externalChecks.push(async () =>
+					emitLinkResult(
+						await checkLinkOnce(global_links_checked, url, checkExternalUrl),
+						url,
+						htmlFile,
+						markdown_paths,
+						markdown_content,
+					),
+				);
 			}
 		}
 
@@ -1136,7 +1191,9 @@
 		}
 
 		
-		const global_links_checked = [];
+		// link -> Promise<{ level, message } | null> for network checks: fetched
+		// once per run, but reported on every page that carries the link.
+		const global_links_checked = new Map();
 
 		for (const key in html_to_validate) {
 			const file = html_to_validate[key];

package/package.json

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