Files
rea/scripts/verify-documentation-routes.mjs
T

124 lines
5.0 KiB
JavaScript

import assert from "node:assert/strict";
import { readFile, readdir, stat } from "node:fs/promises";
import { basename, resolve, sep } from "node:path";
import { fileURLToPath } from "node:url";
// Public route baseline before categorization, including upstream signal recordings.
// This fixture is independent of the navigation/rewrite implementation.
const routes = `
adb-device-analysis android-analysis apktool-resource-analysis apple-application-analysis
binary-diagnostics browser-observation browser-scenario-contract cli client-configuration
client-verification electron-observation evm-bytecode firmware-analysis flutter-analysis
frida-instrumentation ghidra-dos ghidra-mips ghidra-nativeaot ghidra-provider ghidra-psp
ghidra-riscv go-binaries harmony-analysis ida-provider installation
javascript-application-graph javascript-application-workflows javascript-artifact-reconstruction
javascript-recovery javascript-runtime-observation javascript-runtime-reconciliation
jeb-analysis managed-code-analysis mcp-contracts mcp-prompts migration-6.2
native-investigation packet-captures pcap-analysis process-capture raw-binary reconstruction-obligation-ledgers
reconstruction-readiness recorded-crashes releasing roadmap signal-recordings sqlite-databases
testing tool-design wasm-artifacts web-network-captures web-runtime web-source-location
website-module-trace website-script-export windows-ghidra-p0
`
.trim()
.split(/\s+/u);
assert.equal(routes.length, 57);
assert.equal(new Set(routes).size, routes.length);
const documentation = resolve(
fileURLToPath(new URL("../docs/", import.meta.url)),
);
const output = resolve(documentation, ".vitepress/dist");
const origin = "https://documentation.invalid";
const checked = new Set();
let internalTargets = 0;
let sourceLinks = 0;
// Legacy public routes remain an independent baseline; all generated pages also
// participate so newly authored directories/specifications cannot escape checks.
for (const route of routes) {
const html = await readFile(resolve(output, route + ".html"), "utf8");
const edit = physicalEditSource(html, route);
assert.equal(basename(edit), route + ".md");
}
const htmlPages = [];
const directories = [output];
while (directories.length > 0) {
const directory = directories.pop();
for (const entry of await readdir(directory, { withFileTypes: true })) {
const path = resolve(directory, entry.name);
if (entry.isDirectory()) directories.push(path);
else if (entry.isFile() && entry.name.endsWith(".html"))
htmlPages.push(path);
}
}
for (const page of htmlPages.sort()) {
const route = page
.slice(output.length + 1)
.split(sep)
.join("/");
const html = await readFile(page, "utf8");
// The configured home layout and generated 404 render no edit action.
// Their outgoing links still participate in the same all-page scan.
if (route !== "404.html" && route !== "index.html") {
const source = physicalEditSource(html, route);
assert.ok(
(await stat(source)).isFile(),
route + ": edit link source is missing",
);
sourceLinks++;
}
for (const match of html.matchAll(
/<(?:a|img)\b[^>]*\b(?:href|src)="([^"]+)"/gu,
)) {
const destination = match[1].replaceAll("&amp;", "&");
const url = new URL(destination, origin + "/rea/" + route);
if (url.origin !== origin || !url.pathname.startsWith("/rea/")) continue;
const key = url.pathname + url.hash;
if (checked.has(key)) continue;
checked.add(key);
let target = decodeURIComponent(url.pathname.slice("/rea/".length));
if (!target || target.endsWith("/")) target += "index.html";
else if (!basename(target).includes(".")) target += ".html";
const physical = resolve(output, target);
assert.ok(
physical.startsWith(output + sep),
destination + ": published path escaped site output",
);
assert.ok(
(await stat(physical)).isFile(),
route + ": broken rendered target " + destination,
);
if (url.hash && target.endsWith(".html")) {
const fragment = decodeURIComponent(url.hash.slice(1));
const page = await readFile(physical, "utf8");
assert.ok(
page.includes('id="' + fragment + '"'),
route + ": missing rendered anchor " + destination,
);
}
internalTargets++;
}
}
function physicalEditSource(html, route) {
const edit = html.match(
/href="https:\/\/github\.com\/morluto\/rea\/edit\/main\/docs\/([^"]+)"/u,
);
assert.ok(edit, route + ": missing physical-source edit link");
const source = resolve(documentation, decodeURIComponent(edit[1]));
assert.ok(
source.startsWith(documentation + sep),
route + ": source escaped documentation root",
);
return source;
}
console.log(
JSON.stringify({
ok: true,
published_routes: routes.length,
html_pages: htmlPages.length,
physical_edit_links: sourceLinks,
distinct_internal_targets_and_anchors: internalTargets,
scope:
"actual generated HTML, local guide routes/edit sources/images and anchors; external network links are not fetched",
}),
);