From 5a07ada8f04bb19f49b982b0210e7c082ed3d339 Mon Sep 17 00:00:00 2001 From: Vivswan Shah <58091053+Vivswan@users.noreply.github.com> Date: Mon, 26 Oct 2026 16:22:40 -0400 Subject: [PATCH 1/2] refactor(docs): read guide link targets from the rendered page The guides' three link tests (orphan pages, every relative link resolves to a file, every #fragment names a heading) scanned the markdown source with a regex over the lines outside fences and dropped targets matching a scheme with `//` or `mailto:`. They now read the rendered page through linkDestinations, which the file already had: Bun.markdown.html renders, HTMLRewriter reads every href and src, and `entities` decodes character references. The hand-rolled regex scan is deleted and the orphan test shares the same helper. linkTargets returns a record per link: the destination as rendered, and the path and the fragment split on the rendered destination and percent-decoded apart through node:querystring's unescape, which decodes every valid escape and leaves a bare % as written, as a server does. An encoded %23 so stays part of the path, and a destination holding both a bare % and a valid escape decodes, where a whole-string decodeURIComponent threw and fell back to the raw text. Differential, old scan against new, over every page the tests read (42 docs/ pages plus README.md, CONTRIBUTING.md, and .github/SECURITY.md): 424 targets each, identical on all 45 files, so no test's verdict changes. Over 3000 generated documents composed from 33 link forms, the new scan equals the browser's answer in all 3000 and the old scan in 631. The forms they differ on: a titled destination, an angle-bracketed one, a nested-parenthesis title, the three reference-style forms, a raw HTML anchor and img, a tel: scheme, a link-shaped code span, an escaped bracket, and percent-, entity-, and backslash-encoded paths. The new test pins each of those with the record it expects, plus the encoded # and the mixed bare-and-escaped percent. The old scan's unclosed-fence throw has its successor in the heading test, which still runs linesOutsideFences over the same files. --- test/docs/guides.test.ts | 133 ++++++++++++++++++++++++++++----------- 1 file changed, 96 insertions(+), 37 deletions(-) diff --git a/test/docs/guides.test.ts b/test/docs/guides.test.ts index 627ca4be9..416237bf7 100644 --- a/test/docs/guides.test.ts +++ b/test/docs/guides.test.ts @@ -10,6 +10,7 @@ import { describe, expect, test } from "bun:test"; import { existsSync, readdirSync, readFileSync } from "node:fs"; import { join, posix } from "node:path"; +import { unescape as percentDecoded } from "node:querystring"; import { DecodingMode, decodeHTML } from "entities"; import { ok } from "neverthrow"; import { parse as parseYaml } from "yaml"; @@ -208,6 +209,42 @@ async function linkDestinations( return destinations; } +/** One local link as a browser resolves it: the path it requests and the fragment it looks up, each decoded on its own. */ +interface LinkTarget { + /** The destination as the renderer wrote it, for a failure message. */ + readonly destination: string; + + /** The file the link requests, relative to its page, percent-decoded as a server does (a valid escape decodes, a bare % stays); "" for a fragment-only link. */ + readonly path: string; + + /** The heading the link looks up, percent-decoded; null for a destination with no #. */ + readonly fragment: string | null; +} + +/** + * The links in `markdown` a reader can follow locally; a destination with a scheme (https:, mailto:, tel:) is skipped. + * The split on # comes before the decoding, so an encoded %23 stays part of the path, as a browser requests it. + */ +async function linkTargets( + markdown: string, + attributes?: readonly string[], +): Promise { + const targets: LinkTarget[] = []; + for (const destination of await linkDestinations(markdown, attributes)) { + const hash = destination.indexOf("#"); + const path = hash === -1 ? destination : destination.slice(0, hash); + if (/^[a-z]+:/.test(path)) { + continue; + } + targets.push({ + destination, + path: percentDecoded(path), + fragment: hash === -1 ? null : percentDecoded(destination.slice(hash + 1)), + }); + } + return targets; +} + /** An origin no real link names, under which docs/ is served for the resolution below. */ const SITE_ORIGIN = "https://docs-site.invalid"; @@ -224,14 +261,7 @@ async function linksLeavingDocs(markdown: string, page: string): Promise { const name = posix.basename(target.split("#")[0] ?? ""); - const decoded = (text: string): string => { - try { - return decodeURIComponent(text); - } catch { - return text; - } - }; - const needles = [target, decoded(target), name, decoded(name)]; + const needles = [target, percentDecoded(target), name, percentDecoded(name)]; const index = needles .map((needle) => lines.findIndex((line) => line.includes(needle))) .find((found) => found !== -1); @@ -411,12 +441,11 @@ describe("docs/ guide pages", () => { const linked = new Set(); for (const file of linkScanFiles()) { // href only: an image or embed shows the file but takes the reader nowhere. - for (const destination of await linkDestinations(readFileSync(file.path, "utf8"), ["href"])) { - const path = destination.split("#")[0] ?? ""; - if (path === "" || /^[a-z]+:/.test(path)) { + for (const target of await linkTargets(readFileSync(file.path, "utf8"), ["href"])) { + if (target.path === "") { continue; } - const resolved = join(file.path, "..", decodeURIComponent(path)); + const resolved = join(file.path, "..", target.path); if (resolved !== file.path) { linked.add(resolved); } @@ -426,49 +455,37 @@ describe("docs/ guide pages", () => { expect(orphans, "no README, guide, or root page links these docs/ pages").toEqual([]); }); - /** Every link target in `file` outside its fences, the external ones (a scheme, mailto:) skipped. */ - function linkTargets(file: { label: string; path: string }): string[] { - const markdown = linesOutsideFences(readFileSync(file.path, "utf8"), file.label).join("\n"); - return [...markdown.matchAll(/\]\(([^)]+)\)/g)] - .map((match) => match[1] ?? "") - .filter((target) => !/^[a-z]+:\/\//.test(target) && !target.startsWith("mailto:")); - } - /** Why a target's #fragment matches no heading of the markdown file it names; null for a target with no fragment to check, or a good one. */ function fragmentProblem( file: { label: string; path: string }, - target: string, + target: LinkTarget, slugsOf: (path: string) => Set, ): string | null { - const hash = target.indexOf("#"); - if (hash === -1) { + if (target.fragment === null) { return null; } - const fragment = target.slice(hash + 1); - const path = target.slice(0, hash); - const resolved = path === "" ? file.path : join(file.path, "..", path); + const resolved = target.path === "" ? file.path : join(file.path, "..", target.path); if (!resolved.endsWith(".md")) { return null; // only markdown targets have slugified headings } if (!existsSync(resolved)) { - return `${file.label}: (${target}) target file does not exist`; + return `${file.label}: (${target.destination}) target file does not exist`; } - if (!slugsOf(resolved).has(fragment)) { - return `${file.label}: (${target}) fragment matches no heading`; + if (!slugsOf(resolved).has(target.fragment)) { + return `${file.label}: (${target.destination}) fragment matches no heading`; } return null; } - test("every relative link in the guides, README, and CONTRIBUTING resolves to a real file", () => { + test("every relative link in the guides, README, and CONTRIBUTING resolves to a real file", async () => { const broken: string[] = []; for (const file of linkScanFiles()) { - for (const target of linkTargets(file)) { - const path = target.split("#")[0] ?? ""; - if (path === "") { + for (const target of await linkTargets(readFileSync(file.path, "utf8"))) { + if (target.path === "") { continue; } - if (!existsSync(join(file.path, "..", path))) { - broken.push(`${file.label}: (${target})`); + if (!existsSync(join(file.path, "..", target.path))) { + broken.push(`${file.label}: (${target.destination})`); } } } @@ -483,7 +500,7 @@ describe("docs/ guide pages", () => { expect(leaving).toEqual([]); }); - test("every relative link with a #fragment points at a real heading", () => { + test("every relative link with a #fragment points at a real heading", async () => { const files = linkScanFiles(); const slugCache = new Map>(); const slugsOf = (path: string): Set => { @@ -496,7 +513,7 @@ describe("docs/ guide pages", () => { }; const broken: string[] = []; for (const file of files) { - for (const target of linkTargets(file)) { + for (const target of await linkTargets(readFileSync(file.path, "utf8"))) { const problem = fragmentProblem(file, target, slugsOf); if (problem !== null) { broken.push(problem); @@ -990,6 +1007,48 @@ describe("links-leaving-docs guard (mutation checks)", () => { }); }); +describe("link target scan (mutation checks)", () => { + test("reads each destination as a browser does, where a regex over the source read it differently", async () => { + // A regex over the source read the first three lines, the tel: link, and the encoded forms differently; the other + // schemes pin the skip, the two bare percents pin the tolerant decode, and %23 pins the split before the decode. + const link = (destination: string, path: string, fragment: string | null): LinkTarget => ({ + destination, + path, + fragment, + }); + const page = [ + '[titled](a.md "Title") [bracketed]() [nested](p.md (title))', + "[reference][ref] [collapsed][] [shortcut]", + 'anchor ', + "[phone](tel:+15550100) [mail](mailto:x@example.com) [site](https://example.com/)", + "Not links: `[span](code.md)` and \\[escaped](escaped.md).", + "[encoded](a%20b.md#frag%20x) [entity](../ent.md) [escaped](\\.\\./esc.md)", + "[bare percent](50%.md) [bare and escape](<50% done.md>) [encoded hash](README.md%23library) [fragment](#top)", + "", + "[ref]: ref.md", + "[collapsed]: collapsed.md", + "[shortcut]: shortcut.md", + ].join("\n"); + expect(await linkTargets(page)).toEqual([ + link("a.md", "a.md", null), + link("a%20b.md", "a b.md", null), + link("p.md", "p.md", null), + link("ref.md", "ref.md", null), + link("collapsed.md", "collapsed.md", null), + link("shortcut.md", "shortcut.md", null), + link("raw.md", "raw.md", null), + link("raw.png", "raw.png", null), + link("a%20b.md#frag%20x", "a b.md", "frag x"), + link("../ent.md", "../ent.md", null), + link("../esc.md", "../esc.md", null), + link("50%.md", "50%.md", null), + link("50%%20done.md", "50% done.md", null), + link("README.md%23library", "README.md#library", null), + link("#top", "", "top"), + ]); + }); +}); + describe("refusal table parser (mutation checks)", () => { const header = ["| The layer has | The fold says |", "|---|---|"]; const row = (has: string, says = "`the message`"): string => `| ${has} | ${says} |`; From a5bca1b2bcc1f7425fa20e381a3d0cfedc9b88c5 Mon Sep 17 00:00:00 2001 From: Vivswan Shah <58091053+Vivswan@users.noreply.github.com> Date: Mon, 26 Oct 2026 17:07:48 -0400 Subject: [PATCH 2/2] fix(docs): resolve each guide link with the URL parser against its page Two destination forms the first-# split read wrong: a network path (``) or a scheme outside `[a-z]` (`git+ssh://...`) passed the `^[a-z]+:` test and was reported as a missing file, and a padded raw-HTML href (``) or a destination with a query (`guide.md?view=1`) kept the padding or the query in the path and was reported missing although the file exists. linkTargets now takes the page's path from the repository root and resolves every rendered destination with URL.parse against a base on SITE_ORIGIN, the origin no real link names that linksLeavingDocs already uses. A destination the parser rejects or that lands on another origin (an absolute URL, a `//host/` network path, a non-special scheme) is external; otherwise the path is the pathname from the repository root, percent-decoded as before, and the fragment the decoded hash. The parser trims padding and splits the query before anything is decoded, so an encoded %23 still stays in the path. LinkTarget.path is repository-relative now, so the three link tests resolve with join(ROOT, path) and the fragment-only special case is gone: such a link resolves to its page. Differential over the 45 pages the tests read (42 docs/ pages, README.md, CONTRIBUTING.md, .github/SECURITY.md), each link normalized to the file it names plus its fragment: the regex scan, the first-# split, and the URL-parser resolution give 424 links each and no page differs between any two. The fixture gained the four forms, with repository-relative expectations; a mutation back to the first-# split fails exactly those four entries. --- test/docs/guides.test.ts | 89 ++++++++++++++++++++-------------------- 1 file changed, 45 insertions(+), 44 deletions(-) diff --git a/test/docs/guides.test.ts b/test/docs/guides.test.ts index 416237bf7..304efdb95 100644 --- a/test/docs/guides.test.ts +++ b/test/docs/guides.test.ts @@ -209,12 +209,18 @@ async function linkDestinations( return destinations; } -/** One local link as a browser resolves it: the path it requests and the fragment it looks up, each decoded on its own. */ +/** An origin no real link names, under which the repository is served for linkTargets, and docs/ alone, at SITE_ROOT, for linksLeavingDocs. */ +const SITE_ORIGIN = "https://docs-site.invalid"; + +/** The path docs/ is served under, which no real link names either, so a destination that climbs out (even back into a literal "docs/") lands outside it. */ +const SITE_ROOT = "/docs-root-7c1e/"; + +/** One link within the repository, as a browser resolves it against its page: the file it requests and the heading it looks up, each decoded on its own. */ interface LinkTarget { /** The destination as the renderer wrote it, for a failure message. */ readonly destination: string; - /** The file the link requests, relative to its page, percent-decoded as a server does (a valid escape decodes, a bare % stays); "" for a fragment-only link. */ + /** The file the link requests, from the repository root, percent-decoded as a server does (a valid escape decodes, a bare % stays); the page itself for a fragment-only link. */ readonly path: string; /** The heading the link looks up, percent-decoded; null for a destination with no #. */ @@ -222,35 +228,31 @@ interface LinkTarget { } /** - * The links in `markdown` a reader can follow locally; a destination with a scheme (https:, mailto:, tel:) is skipped. - * The split on # comes before the decoding, so an encoded %23 stays part of the path, as a browser requests it. + * The links in `markdown`, the page at `page` from the repository root, that lead within the repository, resolved as a + * browser does: padding trimmed, query and #fragment split off before the path is decoded (an encoded %23 stays in + * the path), and a destination on another origin (a scheme, a network path `//host/`) or one no parser accepts skipped. */ async function linkTargets( markdown: string, + page: string, attributes?: readonly string[], ): Promise { + const base = `${SITE_ORIGIN}/${page}`; const targets: LinkTarget[] = []; for (const destination of await linkDestinations(markdown, attributes)) { - const hash = destination.indexOf("#"); - const path = hash === -1 ? destination : destination.slice(0, hash); - if (/^[a-z]+:/.test(path)) { + const url = URL.parse(destination, base); + if (url === null || url.origin !== SITE_ORIGIN) { continue; } targets.push({ destination, - path: percentDecoded(path), - fragment: hash === -1 ? null : percentDecoded(destination.slice(hash + 1)), + path: percentDecoded(url.pathname.slice(1)), + fragment: url.hash === "" ? null : percentDecoded(url.hash.slice(1)), }); } return targets; } -/** An origin no real link names, under which docs/ is served for the resolution below. */ -const SITE_ORIGIN = "https://docs-site.invalid"; - -/** The path docs/ is served under, which no real link names either, so a destination that climbs out (even back into a literal "docs/") lands outside it. */ -const SITE_ROOT = "/docs-root-7c1e/"; - /** * Relative links in the docs/ page at `page` that resolve outside docs/. * Resolution is the WHATWG URL parser's, as a browser does it; the published site is built from docs/ alone, so a link @@ -441,11 +443,9 @@ describe("docs/ guide pages", () => { const linked = new Set(); for (const file of linkScanFiles()) { // href only: an image or embed shows the file but takes the reader nowhere. - for (const target of await linkTargets(readFileSync(file.path, "utf8"), ["href"])) { - if (target.path === "") { - continue; - } - const resolved = join(file.path, "..", target.path); + const links = await linkTargets(readFileSync(file.path, "utf8"), file.label, ["href"]); + for (const target of links) { + const resolved = join(ROOT, target.path); if (resolved !== file.path) { linked.add(resolved); } @@ -464,7 +464,7 @@ describe("docs/ guide pages", () => { if (target.fragment === null) { return null; } - const resolved = target.path === "" ? file.path : join(file.path, "..", target.path); + const resolved = join(ROOT, target.path); if (!resolved.endsWith(".md")) { return null; // only markdown targets have slugified headings } @@ -480,11 +480,8 @@ describe("docs/ guide pages", () => { test("every relative link in the guides, README, and CONTRIBUTING resolves to a real file", async () => { const broken: string[] = []; for (const file of linkScanFiles()) { - for (const target of await linkTargets(readFileSync(file.path, "utf8"))) { - if (target.path === "") { - continue; - } - if (!existsSync(join(file.path, "..", target.path))) { + for (const target of await linkTargets(readFileSync(file.path, "utf8"), file.label)) { + if (!existsSync(join(ROOT, target.path))) { broken.push(`${file.label}: (${target.destination})`); } } @@ -513,7 +510,7 @@ describe("docs/ guide pages", () => { }; const broken: string[] = []; for (const file of files) { - for (const target of await linkTargets(readFileSync(file.path, "utf8"))) { + for (const target of await linkTargets(readFileSync(file.path, "utf8"), file.label)) { const problem = fragmentProblem(file, target, slugsOf); if (problem !== null) { broken.push(problem); @@ -1010,7 +1007,8 @@ describe("links-leaving-docs guard (mutation checks)", () => { describe("link target scan (mutation checks)", () => { test("reads each destination as a browser does, where a regex over the source read it differently", async () => { // A regex over the source read the first three lines, the tel: link, and the encoded forms differently; the other - // schemes pin the skip, the two bare percents pin the tolerant decode, and %23 pins the split before the decode. + // schemes pin the skip, the two bare percents the tolerant decode, %23 the split before the decode, and the last + // line the URL parser's own trimming, query split, and origin test (a network path and a non-URL scheme are external). const link = (destination: string, path: string, fragment: string | null): LinkTarget => ({ destination, path, @@ -1024,27 +1022,30 @@ describe("link target scan (mutation checks)", () => { "Not links: `[span](code.md)` and \\[escaped](escaped.md).", "[encoded](a%20b.md#frag%20x) [entity](../ent.md) [escaped](\\.\\./esc.md)", "[bare percent](50%.md) [bare and escape](<50% done.md>) [encoded hash](README.md%23library) [fragment](#top)", + ' [clone](git+ssh://git@example.com/r.git) padded [query](guide.md?view=1)', "", "[ref]: ref.md", "[collapsed]: collapsed.md", "[shortcut]: shortcut.md", ].join("\n"); - expect(await linkTargets(page)).toEqual([ - link("a.md", "a.md", null), - link("a%20b.md", "a b.md", null), - link("p.md", "p.md", null), - link("ref.md", "ref.md", null), - link("collapsed.md", "collapsed.md", null), - link("shortcut.md", "shortcut.md", null), - link("raw.md", "raw.md", null), - link("raw.png", "raw.png", null), - link("a%20b.md#frag%20x", "a b.md", "frag x"), - link("../ent.md", "../ent.md", null), - link("../esc.md", "../esc.md", null), - link("50%.md", "50%.md", null), - link("50%%20done.md", "50% done.md", null), - link("README.md%23library", "README.md#library", null), - link("#top", "", "top"), + expect(await linkTargets(page, "docs/start/page.md")).toEqual([ + link("a.md", "docs/start/a.md", null), + link("a%20b.md", "docs/start/a b.md", null), + link("p.md", "docs/start/p.md", null), + link("ref.md", "docs/start/ref.md", null), + link("collapsed.md", "docs/start/collapsed.md", null), + link("shortcut.md", "docs/start/shortcut.md", null), + link("raw.md", "docs/start/raw.md", null), + link("raw.png", "docs/start/raw.png", null), + link("a%20b.md#frag%20x", "docs/start/a b.md", "frag x"), + link("../ent.md", "docs/ent.md", null), + link("../esc.md", "docs/esc.md", null), + link("50%.md", "docs/start/50%.md", null), + link("50%%20done.md", "docs/start/50% done.md", null), + link("README.md%23library", "docs/start/README.md#library", null), + link("#top", "docs/start/page.md", "top"), + link(" guide.md ", "docs/start/guide.md", null), + link("guide.md?view=1", "docs/start/guide.md", null), ]); }); });