// Docs link audit tests cover documentation link validation behavior. import { spawnSync } from "node:child_process"; import fs from "node:fs"; import os from "node:os"; import path from "node:path"; import { fileURLToPath } from "node:url"; import { describe, expect, it } from "vitest"; import { createDocsMarkdown, parseDocsDocument } from "../../scripts/lib/docs-markdown.mjs"; import { normalizeRoute } from "../../scripts/lib/docs-published-routes.mts"; import { cleanupTempDirs, makeTempDir } from "../../test/helpers/temp-dir.js"; const { auditDocsLinks, prepareExternalLinkAuditTree, prepareMirroredDocsDir, resolveRoute } = await import("../../scripts/docs-link-audit.mts"); type AuditCliCase = { name: string; source: string[]; broken: number; anchors?: boolean; diagnostics?: string[]; files?: Record; navigation?: string[]; redirects?: Array<{ source: string; destination: string }>; }; describe("docs-link-audit", () => { function tempEntries(prefix: string): Set { return new Set(fs.readdirSync(os.tmpdir()).filter((entry) => entry.startsWith(prefix))); } it.each(["\n", "\r\n"])("preserves code literals with line ending %j", (newline) => { const source = [ "Intro", "", "```md", '', "```", "", "[live](/same)", ].join(newline); const md = createDocsMarkdown(); const document = parseDocsDocument(source, md, { mapLink: (href: string, line: number | undefined) => ({ href, line }), }); expect(document.links).toEqual([{ href: "/same", line: 7 }]); expect(md.renderer.render(document.tokens, md.options, document.env)).toContain( "<Card href="/same" title="Literal" />", ); }); it.each([ { name: "published possessive links", source: "## Request today's summary\n\n## The vendor's harness, as a plugin", headings: [ ["request-today's-summary", "request-todays-summary"], ["the-vendor's-harness%2C-as-a-plugin", "the-vendors-harness-as-a-plugin"], ], collisions: [], }, { name: "normalized duplicates and numbered suffixes before alias reservation", source: "## A-s\n\n## As\n\n## A-s\n\n## A-s-2\n\n## A-s", headings: [ ["a-s", null], ["as", "as-2"], ["a-s-1", "as-3"], ["a-s-2", "as-2-1"], ["a-s-3", "as-4"], ], collisions: [{ id: "as", reason: "compatibility alias collision" }], }, { name: "percent bytes, underscores and numbered title prefixes", source: "## café 中文 _Über\n\n## café 中文 _Über\n\n## 1. Today\n\n## 1. Today\n\n## 100% ready", headings: [ ["caf%C3%A9-%E4%B8%AD%E6%96%87-_%C3%BCber", "café-中文-_über"], ["caf%C3%A9-%E4%B8%AD%E6%96%87-_%C3%BCber-1", "café-中文-_über-2"], ["1.-today", "1-today"], ["1.-today-1", "1-today-2"], ["100%25-ready", "100%-ready"], ], collisions: [], }, ])("preserves Mint heading targets for $name", ({ source, headings, collisions }) => { const document = parseDocsDocument(source); expect( document.tokens .filter((token) => token.type === "heading_open") .map((token) => [token.attrGet("id"), token.meta?.anchorAlias ?? null]), ).toEqual(headings); expect(document.collisions).toEqual(collisions); expect(new Set(document.ids).size).toBe(document.ids.length); }); it.each([ { name: "shared heading/Step TOC with an independent Tab counter", source: [ "## Today's summary", '', 'one', 'two', "", "", 'one', 'two', 'three', "", 'one', 'two', 'one', 'two', ], ids: [ "today's-summary", "todays-summary", "todays-summary-2", "todays-summary-3", "todays-summary-1", "todays-summary-2-1", "todays-summary-3-1", "as", "as-1", "param-as", "param-as-1", ], collisions: [], }, { name: "authored IDs reserved before heading aliases and component IDs", source: [ "## Today's summary", '', 'one', 'two', 'three', 'four', '', ], ids: ["today's-summary", "todays-summary", "as", "param-as", "as-1", "as-2", "param-as-1"], collisions: [{ id: "todays-summary", reason: "compatibility alias collision" }], }, { name: "raw component apostrophes normalized after separators", source: [ 'one', 'two', ], ids: ["as-s-guide", "param-as-s-guide"], collisions: [], }, ])("preserves Mint component targets for $name", ({ source, ids, collisions }) => { const document = parseDocsDocument(source.join("\n\n")); expect(document.ids).toEqual(ids); expect(document.collisions).toEqual(collisions); expect(new Set(document.ids).size).toBe(document.ids.length); }); it.each([ { name: "component and list fences", source: [ "", " ~~~md", " [example](/hidden-tilde)", " ~~~not-a-closing-fence", " [example](/hidden-after-false-close)", " ~~~", "", "", "- Example", "", " ````md", " ```text", " [example](/hidden-nested)", " ```", " ````", "", "[real](/missing-page)", "[valid](/page)", ], broken: 1, }, { name: "legacy malformed MDX", source: [ "", "~~~md", "[example](/hidden-fallback)", "~~~", "[real](/missing-page)", "[valid](/page)", ], broken: 1, }, { name: "indented component prose", source: ["", " [real](/missing-page)", "", "[valid](/page)"], broken: 1, }, { name: "valid prose", source: ["[valid](/page)"], broken: 0 }, ...[false, true].map((anchors) => ({ name: `fenced raw HTML boundaries (anchors=${anchors})`, anchors, source: [ "```html", "", "

",
        "```",
        "",
        '',
        "[Visible](/missing-page)",
        "",
        "",
        "```html",
        "

", "```", "", "[valid](/page)", ], broken: 1, diagnostics: ["page.mdx:7 :: /missing-page :: route/file not found"], })), { name: "repeated occurrences beside protected literals", source: [ "---", "title: Positions", "---", "```md", "[hidden](/missing-page)", "```", "[first](/missing-page)", "[second](/missing-page)", "", "`[hidden](/missing-page)` [third](/missing-page)", "[valid](/page)", ], broken: 3, diagnostics: [7, 8, 10].map( (line) => `page.mdx:${line} :: /missing-page :: route/file not found`, ), }, { name: "reference, HTML, component and normalized relative occurrences", source: [ "[reference][missing]", "", "[missing]: /missing-page", "", 'HTML', "", '', "", "[relative](./missing-page.md)", "[valid](/page)", ], broken: 4, diagnostics: [1, 5, 7, 9].map( (line) => `page.mdx:${line} :: /missing-page :: route/file not found`, ), }, { name: "unmapped expansions", source: [ '', "", '

', "[embedded](/missing-page)", "

", "", "[valid](/page)", ], files: { "docs/part.txt": "[included](/missing-page)\n" }, broken: 2, diagnostics: ["page.mdx:unknown :: /missing-page :: route/file not found"], }, { name: "decoded direct paths and HTML-alias targets", anchors: true, source: [ "[direct](/caf%C3%A9#known)", "[literal percent](/100%25#known)", "[asset](/image%20space.svg)", "[redirect](/via)", "[bad redirect](/invalid)", "[raw Markdown redirect](/raw)", "[after](/missing-page)", "[external](/outside)", ], files: { "docs/café.md": "## Known\n", "docs/100%.md": "## Known\n", "docs/image space.svg": "", }, redirects: [ { source: "/via", destination: "https://docs.openclaw.ai/caf%C3%A9#known" }, { source: "/invalid", destination: "https://docs.openclaw.ai/bad%" }, { source: "/raw", destination: "/café.md#known" }, { source: "/outside", destination: "https://example.test/page#external-section" }, ], broken: 4, diagnostics: [ "docs.json:unknown :: /invalid :: malformed URL path", "page.mdx:5 :: /invalid :: malformed URL path", "page.mdx:6 :: /raw :: fragment requires an HTML page, not raw Markdown", "page.mdx:7 :: /missing-page :: route/file not found", ], }, ...[false, true].map((anchors) => ({ name: `malformed emitted paths (anchors=${anchors})`, anchors, source: [ '', "", 'HTML', "", '