Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -273,8 +273,11 @@ red PR job against.
to a committed page or lies under a `PROJECT_SITES` prefix of `check-links.sh` (served by a
sibling Pages repo, so probing it is the only way to see it); every canonical page in
`sitemap.xml` and `/404.html` is probed; at
least one redirect shortcut is probed; no duplicates. Fixing a failure means editing the
workflow's probe list. Each rule has a fixture self-test. Zero dependencies.
least one redirect shortcut is probed; no duplicates; and the intro of
`runbooks/availability-failure.md` names exactly the probed paths (the homepage in prose,
every other probe verbatim), so the on-call reader is not sent to pages the job never
requests. Fixing a failure means editing the workflow's probe list or the runbook intro.
Each rule has a fixture self-test. Zero dependencies.
- `node --test scripts/site-origin.test.mjs` — static gate tying the site origin to `CNAME`,
the one file GitHub Pages actually reads for the host: `CNAME` must be a single bare
lowercase DNS host (no scheme, path, port, trailing dot, second line or CRLF); every
Expand Down
83 changes: 83 additions & 0 deletions scripts/availability-probes.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@
// as a failure). Paths under a `PROJECT_SITES` prefix of check-links.sh are
// served on hivecommons.dev by a sibling Pages project repo: they have no
// committed file, so the probe list may name them without resolving to one.
// runbooks/availability-failure.md restates the probed paths for the on-call
// reader; its intro must name exactly the paths the job probes, or the runbook
// sends them looking at the wrong pages (#378 fixed that drift by hand).
// Each rule has a fixture self-test. Zero dependencies.
// Usage: node --test scripts/availability-probes.test.mjs
import { test } from "node:test";
Expand All @@ -21,6 +24,7 @@ const ROOT = join(HERE, "..");
const SITE_ORIGIN = "https://hivecommons.dev";
const WORKFLOW = join(ROOT, ".github", "workflows", "links.yml");
const CHECKER = join(ROOT, "scripts", "check-links.sh");
const RUNBOOK = join(ROOT, "runbooks", "availability-failure.md");

// --- parsing ---------------------------------------------------------------

Expand Down Expand Up @@ -49,6 +53,21 @@ export function isProjectSitePath(path, prefixes) {
return prefixes.some((prefix) => bare.startsWith(prefix));
}

// Site paths the availability runbook's intro (everything before its first
// `## ` heading) says the job probes: each `/...` code span and each bare
// parenthesised (/...) — the latter is how a project-site path served by a
// sibling repo is written, since doc-paths.test.mjs resolves code spans to
// committed files. Returns the distinct paths in order of first mention.
export function runbookProbedPaths(markdown) {
const intro = markdown.split(/^## /m)[0];
const paths = [];
for (const m of intro.matchAll(/`(\/[^`\s]*)`|\((\/[^()\s]*)\)/g)) {
const path = m[1] ?? m[2];
if (!paths.includes(path)) paths.push(path);
}
return paths;
}

export function sitemapLocs(xml) {
return [...xml.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/g)].map((m) => m[1]);
}
Expand Down Expand Up @@ -98,6 +117,24 @@ export function probeListProblems(urls, { sitemap, root = ROOT, projectSites = [
return problems;
}

// The runbook intro and the probe list must name the same paths. The homepage
// is probed as the bare `/`, which the prose calls "the homepage" rather than
// spelling out; every other probe must appear verbatim.
export function runbookProblems(urls, markdown) {
const problems = [];
const probed = (urls ?? []).filter((u) => u.startsWith(SITE_ORIGIN + "/")).map((u) => u.slice(SITE_ORIGIN.length));
const named = runbookProbedPaths(markdown);
const intro = markdown.split(/^## /m)[0];
if (probed.includes("/") && !/\bhomepage\b/i.test(intro)) problems.push("the job probes the homepage but the runbook intro never says so");
for (const path of probed) {
if (path !== "/" && !named.includes(path)) problems.push(`the job probes ${path} but the runbook intro does not name it`);
}
for (const path of named) {
if (!probed.includes(path)) problems.push(`the runbook intro names ${path} but the job does not probe it`);
}
return problems;
}

// --- fixtures --------------------------------------------------------------

const GOOD_YAML = `name: x
Expand Down Expand Up @@ -268,6 +305,43 @@ test("fixture: missing 404.html probe, missing redirect probe, duplicates and fo
assert.ok(query.some((x) => x.includes("query/fragment")), query.join("\n"));
});

const GOOD_RUNBOOK = `# Runbook: probe failing

The job requests the live homepage, \`/stories/\`, the \`/docs/\` shortcut redirect,
\`/llms.txt\`, \`/sitemap.xml\`, \`/robots.txt\`, \`/404.html\` and
the project site (/software-factory/) over HTTPS. See the [rollback runbook](release-rollback.md)
and the workflow (\`.github/workflows/links.yml\`).

## Who is affected

Every visitor to \`https://hivecommons.dev/\` and \`/stories/\`; also \`/never-probed/\`.
`;
const GOOD_RUNBOOK_LIST = [...GOOD_LIST, `${SITE_ORIGIN}/software-factory/`];

test("fixture: runbook probe paths are the intro's /-prefixed code spans and bare (/...) parentheticals, deduplicated, up to the first ## heading", () => {
assert.deepEqual(runbookProbedPaths(GOOD_RUNBOOK), ["/stories/", "/docs/", "/llms.txt", "/sitemap.xml", "/robots.txt", "/404.html", "/software-factory/"]);
assert.deepEqual(runbookProbedPaths("Intro names \`/a/\` twice: \`/a/\` and (/a/), plus \`a/b\`, \`.github/x\`, (b/) and (/sp ace/).\n"), ["/a/"]);
assert.deepEqual(runbookProbedPaths("No headings and no paths.\n"), []);
});

test("fixture: a runbook naming exactly the probed paths (and the homepage in prose) passes", () => {
assert.deepEqual(runbookProblems(GOOD_RUNBOOK_LIST, GOOD_RUNBOOK), []);
// Without a homepage probe the prose need not mention it; foreign URLs are ignored here (probeListProblems reports them).
assert.deepEqual(runbookProblems([...GOOD_RUNBOOK_LIST.filter((u) => u !== SITE_ORIGIN + "/"), "https://example.com/"], GOOD_RUNBOOK.replace("live homepage", "live site")), []);
assert.deepEqual(runbookProblems(null, "Nothing here.\n"), []);
});

test("fixture: a probed path the runbook omits, a runbook path the job dropped, and an unmentioned homepage are each reported", () => {
const omitted = runbookProblems([...GOOD_RUNBOOK_LIST, `${SITE_ORIGIN}/.well-known/security.txt`], GOOD_RUNBOOK);
assert.deepEqual(omitted, ["the job probes /.well-known/security.txt but the runbook intro does not name it"]);
const dropped = runbookProblems(GOOD_RUNBOOK_LIST.filter((u) => !u.endsWith("/robots.txt")), GOOD_RUNBOOK);
assert.deepEqual(dropped, ["the runbook intro names /robots.txt but the job does not probe it"]);
const noHome = runbookProblems(GOOD_RUNBOOK_LIST, GOOD_RUNBOOK.replace("live homepage", "live site"));
assert.deepEqual(noHome, ["the job probes the homepage but the runbook intro never says so"]);
// A path only named after the first ## heading does not count as a probe claim.
assert.ok(!runbookProblems(GOOD_RUNBOOK_LIST, GOOD_RUNBOOK).some((x) => x.includes("/never-probed/")));
});

// --- the real workflow -----------------------------------------------------

test("check-links.sh declares at least one PROJECT_SITES prefix and each is a /-delimited directory path", () => {
Expand All @@ -286,3 +360,12 @@ test("links.yml availability job probes every canonical page, 404.html and a red
"the availability probe list in .github/workflows/links.yml drifted from the committed site (fixing it needs a workflow edit)",
);
});

test("runbooks/availability-failure.md names exactly the paths the links.yml availability job probes", () => {
const urls = probedUrls(readFileSync(WORKFLOW, "utf8"));
assert.deepEqual(
runbookProblems(urls, readFileSync(RUNBOOK, "utf8")),
[],
"the availability runbook's probe list drifted from .github/workflows/links.yml; update the runbook intro (or, if a probe was dropped, the workflow)",
);
});
Loading