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
2 changes: 2 additions & 0 deletions .github/workflows/build-verify.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/gh-pages-deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
13 changes: 13 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion blog/2024-04-27-Release-3.6/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
1 change: 1 addition & 0 deletions docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -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' },
Expand Down
6 changes: 4 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
112 changes: 112 additions & 0 deletions scripts/verify-links.cjs
Original file line number Diff line number Diff line change
@@ -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 <a> 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};
94 changes: 94 additions & 0 deletions scripts/verify-links.test.cjs
Original file line number Diff line number Diff line change
@@ -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': '<a href="https://docs.phcode.dev/docs/A%20Guide?edition=community#steps">Guide</a>' +
'<a href="/docs/legacy/">Old address</a><a href="/docs/legacy">Old address without slash</a>' +
'<a href="//docs.phcode.dev/docs/A%20Guide">Guide</a>',
'docs/A Guide.html': '<a href="../downloads/project.zip">Download</a>' +
'<a href="#steps">Steps</a><h2 id="steps">Steps</h2>',
'docs/legacy/index.html': '<link rel="canonical" href="/docs/A%20Guide">' +
'<meta http-equiv="refresh" content="0; url=/docs/A%20Guide">',
'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': '<a href="/blog/release-3.6">Release</a>',
'blog/release-3.6.html': '<a href="https://docs.phcode.dev/docs/Features/editor-rulers/">Read more</a>',
});
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': '<link rel="canonical" href="/missing-page">' +
'<video poster="/missing-poster.png"><source src="/missing-video.mp4">' +
'<track src="/missing-captions.vtt"></video>' +
'<meta http-equiv="Refresh" content="0; URL=/missing-redirect">',
});
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': '<a href="https://external.invalid/missing">External</a>' +
'<a href="mailto:help@example.invalid">Email</a><a href="tel:123">Call</a>' +
'<img src="data:image/svg+xml;base64,AAAA"><a href="#">Top</a>',
});
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': '<a href="/guide/">Missing directory index</a><a href="/bad%ZZ">Invalid escape</a>',
'guide.html': '<h1>Guide</h1>',
});
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': '<base href="/docs/"><a href="guide">Guide</a>',
'docs/guide.html': '<h1>Guide</h1>',
});
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': '<a href="/missing">Broken</a>'});
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/);
});
Loading