diff --git a/.github/workflows/build-verify.yml b/.github/workflows/build-verify.yml index c30d26ba..f6eaa5d5 100644 --- a/.github/workflows/build-verify.yml +++ b/.github/workflows/build-verify.yml @@ -23,6 +23,8 @@ jobs: run: npm ci - name: Test tutorial release tooling run: npm run test:tutorials + - name: Test link verification + run: npm run test:links - name: Package tutorial projects run: npm run package:tutorials - name: Build website diff --git a/.github/workflows/gh-pages-deploy.yml b/.github/workflows/gh-pages-deploy.yml index a0b2a0cd..dabb5293 100644 --- a/.github/workflows/gh-pages-deploy.yml +++ b/.github/workflows/gh-pages-deploy.yml @@ -31,6 +31,8 @@ jobs: run: npm ci - name: Test tutorial release tooling run: npm run test:tutorials + - name: Test link verification + run: npm run test:links - name: Package tutorial projects run: npm run package:tutorials - name: Restore original video publication dates diff --git a/README.md b/README.md index 7aaa6fd6..c3394c61 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,19 @@ $ npm run build This command generates static content into the `build` directory and can be served using any static contents hosting service. +Both `npm run build` and `npm run buildLocal` finish with `npm run verify:links`. +This JavaScript check scans the generated HTML for links to missing pages, +downloads, images, scripts, video files, captions, canonical pages, and redirect +destinations. It includes full `https://docs.phcode.dev/...` URLs and prints the +source HTML file and broken link before failing the build. Both CI workflows +run it through the build command, so a failure stops deployment. + +The check uses the build files without contacting the live site. It checks +destination paths; Docusaurus and the tutorial checks handle section anchors. +External site availability and temporary server errors still need live monitoring. +Run `npm run test:links` to test the checker. After a direct +`npm run docusaurus -- build`, run `npm run verify:links` separately. + ### Tutorial release checks Run these checks before releasing tutorial changes. They use JavaScript and diff --git a/blog/2024-04-27-Release-3.6/index.md b/blog/2024-04-27-Release-3.6/index.md index 06c865e9..f32bee33 100644 --- a/blog/2024-04-27-Release-3.6/index.md +++ b/blog/2024-04-27-Release-3.6/index.md @@ -44,7 +44,7 @@ source CSS file editor. #### Editor Rulers Add multiple, color-customizable rulers in the editor to better visualize line -lengths. [Read more...](https://docs.phcode.dev/docs/Features/editor-rulers/) +lengths. [Read more...](/docs/customizing-editor#editor-rulers) ![image](https://github.com/phcode-dev/phoenix/assets/5336369/71b8b04c-d2ca-47b8-84bb-53cd0fb4593c) diff --git a/docusaurus.config.js b/docusaurus.config.js index ec843626..64474b2f 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -165,6 +165,7 @@ const config = { redirects: [ ...appLinks, { from: '/docs/Features/recent-files', to: '/docs/file-management#recent-files' }, + { from: '/docs/Features/editor-rulers', to: '/docs/customizing-editor#editor-rulers' }, { from: '/docs/Features/live-preview-settings', to: '/docs/Features/Live Preview/live-preview-settings' }, { from: '/docs/Linux', to: '/docs/intro#linux' }, { from: '/docs/Features/Live Preview/markdown-live-preview', to: '/docs/Pro Features/markdown-editor' }, diff --git a/package.json b/package.json index f38cb817..e28731a1 100644 --- a/package.json +++ b/package.json @@ -5,11 +5,13 @@ "scripts": { "docusaurus": "docusaurus", "test:tutorials": "node --test --test-reporter=tap scripts/tutorial-release.test.cjs", + "test:links": "node --test --test-reporter=tap scripts/verify-links.test.cjs", "package:tutorials": "node scripts/package-tutorials.cjs", "verify:tutorials": "node scripts/verify-tutorials.cjs", + "verify:links": "node scripts/verify-links.cjs", "start": "docusaurus start", - "build": "npm run buildAPIDocsDev && docusaurus build", - "buildLocal": "npm run buildAPIDocsLocal && docusaurus build", + "build": "npm run buildAPIDocsDev && docusaurus build && npm run verify:links", + "buildLocal": "npm run buildAPIDocsLocal && docusaurus build && npm run verify:links", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", "clear": "docusaurus clear", diff --git a/scripts/verify-links.cjs b/scripts/verify-links.cjs new file mode 100644 index 00000000..837e0883 --- /dev/null +++ b/scripts/verify-links.cjs @@ -0,0 +1,112 @@ +const fs = require('node:fs'); +const path = require('node:path'); +const {parseArgs} = require('node:util'); +const {load} = require('cheerio'); + +const SITE = path.join(__dirname, '..'); +const SITE_URL = 'https://docs.phcode.dev'; +const REFERENCES = [ + ['a[href], area[href], link[href]', 'href'], + ['img[src], script[src], iframe[src], audio[src], video[src], source[src], track[src], embed[src]', 'src'], + ['video[poster]', 'poster'], + ['object[data]', 'data'], +]; + +function listFiles(directory, root = directory) { + return fs.readdirSync(directory, {withFileTypes: true}).flatMap(entry => { + const file = path.join(directory, entry.name); + if (entry.isDirectory()) return listFiles(file, root); + return entry.isFile() ? [path.relative(root, file).split(path.sep).join('/')] : []; + }); +} + +// Check the finished artifact, including the absolute production URLs that +// Docusaurus treats as external links. Never request the live website: new pages +// do not exist there yet, and an outage must not make a valid build fail. +function verify(buildDir, siteUrl = SITE_URL) { + const build = path.resolve(buildDir); + const origin = new URL(siteUrl); + const files = new Set(listFiles(build)); + if (!files.has('index.html')) throw new Error('Missing index.html in ' + build + '; build the website first.'); + const htmlFiles = [...files].filter(file => file.endsWith('.html')).sort(); + const missing = new Set(); + const targets = new Map(); + let checked = 0; + + function check(href, base, source) { + if (!href?.trim()) return; + let url; + try { + url = new URL(href, base); + } catch { + missing.add(source + ' -> ' + href + ' (invalid URL)'); + return; + } + if (!['http:', 'https:'].includes(url.protocol) || url.host !== origin.host) return; + checked++; + if (!targets.has(url.pathname)) { + let exists = false; + try { + const name = decodeURIComponent(url.pathname).slice(1); + // GitHub Pages serves clean URLs from .html files, or directory indexes. + // A trailing slash needs its own index (including client redirects). + const candidates = name === '' ? ['index.html'] : name.endsWith('/') + ? [name + 'index.html'] + : [name, name + '.html', name + '/index.html']; + exists = candidates.some(candidate => files.has(candidate)); + } catch { + // Malformed percent escapes must fail instead of skipping validation. + } + targets.set(url.pathname, exists); + } + if (!targets.get(url.pathname)) missing.add(source + ' -> ' + href); + } + + for (const file of htmlFiles) { + const document = load(fs.readFileSync(path.join(build, file), 'utf8')); + const pageUrl = new URL('/' + file.split('/').map(encodeURIComponent).join('/'), origin); + const baseHref = document('base[href]').first().attr('href'); + let base = pageUrl; + if (baseHref) { + try { + base = new URL(baseHref, pageUrl); + } catch { + missing.add(file + ' -> ' + baseHref + ' (invalid base URL)'); + } + } + for (const [selector, attribute] of REFERENCES) { + document(selector).each((_, element) => check(document(element).attr(attribute), base, file)); + } + // Client redirects also need a real destination, even without an tag. + document('meta[http-equiv]').each((_, element) => { + if (document(element).attr('http-equiv').toLowerCase() !== 'refresh') return; + const content = document(element).attr('content') || ''; + const match = /^\s*[\d.]+\s*;\s*url\s*=\s*(.*?)\s*$/i.exec(content); + if (match) check(match[1].replace(/^(['"])(.*)\1$/, '$2'), base, file); + }); + } + + if (missing.size) { + throw new Error('Found ' + missing.size + ' broken local reference(s):\n' + + [...missing].sort().map(item => ' ' + item).join('\n') + + '\nFix the source link or add a redirect to an existing page, then rebuild.'); + } + return 'PASS: ' + htmlFiles.length + ' HTML files and ' + checked + ' local references; all destinations exist.'; +} + +if (require.main === module) { + try { + const {values} = parseArgs({options: { + 'build-dir': {type: 'string', default: path.join(SITE, 'build')}, + 'site-url': {type: 'string', default: SITE_URL}, + help: {type: 'boolean', short: 'h'}, + }}); + console.log(values.help ? 'Usage: npm run verify:links -- [--build-dir PATH] [--site-url URL]' : + verify(values['build-dir'], values['site-url'])); + } catch (error) { + console.error('FAIL: ' + error.message); + process.exitCode = 1; + } +} + +module.exports = {verify}; diff --git a/scripts/verify-links.test.cjs b/scripts/verify-links.test.cjs new file mode 100644 index 00000000..131d00e4 --- /dev/null +++ b/scripts/verify-links.test.cjs @@ -0,0 +1,94 @@ +const {test} = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); +const {spawnSync} = require('node:child_process'); +const {verify} = require('./verify-links.cjs'); + +function fixture(t, files) { + const build = fs.mkdtempSync(path.join(os.tmpdir(), 'phcode-links-')); + t.after(() => fs.rmSync(build, {recursive: true, force: true})); + for (const [name, content] of Object.entries(files)) { + const file = path.join(build, name); + fs.mkdirSync(path.dirname(file), {recursive: true}); + fs.writeFileSync(file, content); + } + return build; +} + +test('accepts clean URLs, encoded paths, relative downloads, queries and redirect aliases', t => { + const build = fixture(t, { + 'index.html': 'Guide' + + 'Old addressOld address without slash' + + 'Guide', + 'docs/A Guide.html': 'Download' + + 'Steps

Steps

', + 'docs/legacy/index.html': '' + + '', + 'downloads/project.zip': 'fixture', + }); + assert.match(verify(build), /^PASS: 3 HTML files/); +}); + +test('catches the absolute Editor Rulers URL in a rendered blog post', t => { + const build = fixture(t, { + 'index.html': 'Release', + 'blog/release-3.6.html': 'Read more', + }); + assert.throws(() => verify(build), + /blog\/release-3\.6\.html -> https:\/\/docs\.phcode\.dev\/docs\/Features\/editor-rulers\//); +}); + +test('reports missing media, canonical pages and redirect destinations together', t => { + const build = fixture(t, { + 'index.html': '' + + '' + + '', + }); + assert.throws(() => verify(build), error => { + for (const target of ['missing-page', 'missing-poster.png', 'missing-video.mp4', + 'missing-captions.vtt', 'missing-redirect']) assert(error.message.includes(target)); + return true; + }); +}); + +test('does not contact external sites or reject non-HTTP links', t => { + const build = fixture(t, { + 'index.html': 'External' + + 'EmailCall' + + 'Top', + }); + assert.match(verify(build), /^PASS:/); +}); + +test('rejects malformed paths and does not confuse a file with its trailing-slash URL', t => { + const build = fixture(t, { + 'index.html': 'Missing directory indexInvalid escape', + 'guide.html': '

Guide

', + }); + assert.throws(() => verify(build), error => + error.message.includes('/guide/') && error.message.includes('/bad%ZZ')); +}); + +test('resolves relative references against an HTML base URL', t => { + const build = fixture(t, { + 'index.html': 'Guide', + 'docs/guide.html': '

Guide

', + }); + assert.match(verify(build), /^PASS:/); +}); + +test('CLI fails the build for broken references or an incomplete build directory', t => { + const build = fixture(t, {'index.html': 'Broken'}); + const script = path.join(__dirname, 'verify-links.cjs'); + const env = {...process.env}; + delete env.NODE_TEST_CONTEXT; + const result = spawnSync(process.execPath, [script, '--build-dir', build], {encoding: 'utf8', env}); + assert.ifError(result.error); + assert.equal(result.status, 1); + assert.match(result.stderr, /index\.html -> \/missing/); + fs.unlinkSync(path.join(build, 'index.html')); + assert.throws(() => verify(build), /build the website first/); +});