fix(check-links): one external request per URL, not per occurrence

Third defect in `--external`, and the one that explains why nobody ever ran it:
the fetch sat unmemoised inside the per-page link loop, so every external URL was
re-checked once for each page linking it. `https://github.com/imqueue` appears on
effectively all 1,898 crawled pages — at ~500ms each that is 15 minutes for a single
URL. Because the report buffers to the end, it presented as a hang rather than as
arithmetic: measured twice at 20+ minutes with zero bytes written, killed by hand
both times.

Memoised by URL, plus per-URL progress on stderr so it can never look hung again.
75 unique external links, 1m13s end to end.

Also: localhost is never a link, it is an EXAMPLE. The tutorial tells readers to open
http://localhost:3000/ and :8888/, and --external was connecting to whatever machine
ran the check and reporting ECONNREFUSED as link rot across five pages. Six of the
twelve failures on the first working run were that — precisely the noise that gets a
weekly job muted in a fortnight. Now classified as ignore, next to mailto: and tel:.

The remaining three failures were real responses that need judgement rather than
repair, so they are in the allowlist with their reasons and the date they were
verified: mcp.imqueue.org/mcp 405s because it is POST-only by design (Track B's B6
proposes making that stricter), vscode.dev's MCP install redirect 400s without its
query parameters, and privacy.microsoft.com — cited from both privacy policies as
Clarity's data-processing statement — refuses an unattended HEAD while loading fine
in a browser.

`npm run check:links:external` now exits 0: 75 external links checked, none broken.
That is the first completed run of this check in the repo's history, so it is also
the first evidence that there is no external link rot — the earlier claim of "no rot
today" could not have come from a working checker.

Author: Mikhus

.github/workflows/weekly-maintenance.yml

@@ -113,8 +113,9 @@ jobs:
   link-rot:
     name: External link rot
     runs-on: ubuntu-latest
-    # Belt to check-links.js's per-request timeout braces: 79 external links at a 10s
-    # worst case is ~13 minutes if every single one times out, which never happens.
+    # Measured: 1m13s for the full run (crawl + 75 unique external HEADs). The
+    # per-request timeout and the result memo are what make that true; this is the belt
+    # to their braces, because a scheduled job that hangs burns quota silently.
     timeout-minutes: 25
     permissions:
       # To open/update the tracking issue below.

scripts/check-links.js

@@ -289,6 +289,14 @@ function classify(raw, fromSite, fromPath) {
     return { kind: "ignore" };
   }
   if (url.protocol !== "http:" && url.protocol !== "https:") return { kind: "ignore" };
+  // localhost is never a link, it is an EXAMPLE. The tutorial tells readers to open
+  // http://localhost:3000/ and http://localhost:8888/, and --external was dutifully
+  // connecting to the machine running the check — reporting ECONNREFUSED as broken
+  // link rot on five pages. Six of the twelve failures on the first working run were
+  // this, which on a weekly schedule is exactly the noise that gets a job muted.
+  if (/^(localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0)$/.test(url.hostname)) {
+    return { kind: "ignore" };
+  }
   const host = url.hostname.replace(/^www\./, "");
   const site = siteByHost[host];
   if (site) {
@@ -329,6 +337,34 @@ async function main() {
   const broken = []; // {url, from, reason}
   const brokenSeen = new Set();
   const externals = new Set();
+  // ONE request per unique external URL, not one per OCCURRENCE.
+  //
+  // This memo is load-bearing, not an optimisation, and it is very likely the real
+  // reason nobody ever ran `check:links:external`: the fetch used to sit unmemoised at
+  // the call site below, so a link in the footer or in every mirror's `Source:` line
+  // was re-checked once per page. `https://github.com/imqueue` appears on effectively
+  // all 1,898 crawled pages — at ~500ms each that is 15 minutes for one URL — and the
+  // run buffers its report to the end, so it presented as a hang rather than as
+  // arithmetic. Measured twice at 20+ minutes with zero bytes written, killed by hand.
+  //
+  // 79 unique external links now means at most 79 requests. Progress goes to stderr as
+  // each one resolves, so the run can never look hung again.
+  const externalResults = new Map();
+  const externalVerdict = async (url) => {
+    if (externalResults.has(url)) return externalResults.get(url);
+
+    const r = await request(url, "HEAD").catch(() => ({ status: 0 }));
+    const reason = r.status >= 200 && r.status < 400
+      ? null
+      : `external HTTP ${r.status || r.error || "unreachable"}`;
+
+    externalResults.set(url, reason);
+    if (!QUIET) {
+      process.stderr.write(reason ? `  ext FAIL ${url} - ${reason}\n` : `  ext ok   ${url}\n`);
+    }
+
+    return reason;
+  };
   let pagesCrawled = 0;
 
   function reportBroken(url, from, reason) {
@@ -403,9 +439,9 @@ async function main() {
       if (cls.kind === "external") {
         externals.add(cls.url);
         if (CHECK_EXTERNAL && !externalAllowed(cls.url)) {
-          const r = await request(cls.url, "HEAD").catch(() => ({ status: 0 }));
-          if (!(r.status >= 200 && r.status < 400))
-            reportBroken(cls.url, display, `external HTTP ${r.status || "unreachable"}`);
+          const verdict = await externalVerdict(cls.url);
+
+          if (verdict) reportBroken(cls.url, display, verdict);
         }
         continue;
       }

scripts/external-allowlist.txt

@@ -22,3 +22,19 @@ www.gnu.org
 example.com
 example.org
 cdn.example.com
+
+# Verified by the first working run of `check:links:external` (2026-08-03). Each of
+# these answers a browser and refuses an unattended HEAD, for a reason:
+
+# The hosted MCP endpoint is POST-only by design — a HEAD/GET returning 405 is the
+# server behaving correctly, and Track B's B6 proposes making that stricter still.
+https://mcp.imqueue.org/mcp
+
+# 400 on the bare URL: it is VS Code's MCP install redirect and requires query
+# parameters. The page links it with them; the check strips nothing, but the host
+# rejects a HEAD either way.
+https://vscode.dev/redirect/mcp/install
+
+# Unreachable from an unattended HEAD; loads in a browser. Cited from both privacy
+# policies as Clarity's data-processing statement, so it cannot simply be dropped.
+privacy.microsoft.com