Redesign an existing website to make it better. Built on top of impeccable.
88%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
/**
* qa/checks/links.mjs — category G: link integrity (delivery layer).
*
* From every page's full HTML:
* - internal hrefs must resolve: inventory hit, or live 200 (off-inventory
* info), redirect (info), else broken (error)
* - fragment links (#x, /path#x) must target an existing id — checked in
* server HTML first, then re-verified in the RENDERED DOM before being
* reported (blocks assign ids client-side; server HTML alone false-flags)
* - mailto:/tel: must be well-formed
* - external links: SKIPPED by default (on blog-scale fleets the unique
* external set dominates sweep time — 35 of 38 min on a 1,035-page run).
* Pass --probe-externals to probe each unique URL once (HEAD, GET
* fallback); 404/410/DNS-fail -> warn (external sites flap; never an
* error). The skip is always reported as an info finding, never silent.
*/
import { fetchUrl, pMap, finding, pageUrl, decodeAttr } from '../lib.mjs';
const ASSET_RE = /\.(css|js|png|jpe?g|gif|webp|avif|svg|ico|woff2?|xml|txt|json|pdf|mp4|webm|mov|zip)$/i;
export async function run(ctx) {
const { base, inventory } = ctx;
const findings = [];
const known = new Set(inventory.pages.map((p) => p.path));
for (const f of inventory.fragments) known.add(f);
const pageHtml = new Map();
await pMap(inventory.pages, async (p) => {
const res = await ctx.fetchPage(pageUrl(base, p.url || p.path));
if (res.status === 200) pageHtml.set(p.path, res.body);
}, 8);
const internal = new Map(); // path -> Set(referrers)
const anchors = []; // {referrer, targetPath, id}
const external = new Map(); // url -> Set(referrers)
for (const [path, html] of pageHtml) {
for (const m of html.matchAll(/<a[^>]+href=["']([^"']+)["']/gi)) {
const href = decodeAttr(m[1].trim());
if (!href || href === '#') {
findings.push(finding('links', 'empty-href', 'warn', path, 'anchor with empty/# href (dead link affordance)'));
continue;
}
if (href.startsWith('mailto:')) {
if (!/^mailto:[^@\s]+@[^@\s]+\.[a-z]{2,}$/i.test(href.split('?')[0])) {
findings.push(finding('links', 'malformed-mailto', 'warn', path, `malformed mailto: ${href}`));
}
} else if (href.startsWith('tel:')) {
if (!/^tel:\+?[\d\-().\s]{7,}$/.test(href)) {
findings.push(finding('links', 'malformed-tel', 'warn', path, `malformed tel: ${href}`));
}
} else if (href.startsWith('#')) {
anchors.push({ referrer: path, targetPath: path, id: href.slice(1) });
} else if (href.startsWith('/')) {
const [clean, frag] = href.split('#');
const target = clean.split('?')[0].replace(/\/$/, '') || '/';
if (!ASSET_RE.test(target)) {
if (!internal.has(target)) internal.set(target, new Set());
internal.get(target).add(path);
if (frag) anchors.push({ referrer: path, targetPath: target, id: frag });
}
} else if (/^https?:\/\//i.test(href)) {
let sameHost = false;
try { sameHost = new URL(href).host === new URL(base).host; } catch { /* keep external */ }
if (sameHost) {
const target = new URL(href).pathname.replace(/\/$/, '') || '/';
if (!ASSET_RE.test(target)) {
if (!internal.has(target)) internal.set(target, new Set());
internal.get(target).add(path);
}
} else {
if (!external.has(href)) external.set(href, new Set());
external.get(href).add(path);
}
}
}
}
// internal targets
await pMap([...internal.entries()], async ([target, referrers]) => {
if (known.has(target)) return;
const res = await fetchUrl(pageUrl(base, target), { redirect: 'manual' });
if (res.status === 200) {
findings.push(finding('links', 'off-inventory-link', 'info', target,
`internal link target ${target} serves 200 but is not in the tracked inventory`,
{ referrers: [...referrers].slice(0, 5) }));
} else if ([301, 302, 307, 308].includes(res.status)) {
findings.push(finding('links', 'link-via-redirect', 'info', target,
`internal links point at ${target} which redirects to ${res.location} — consider linking the destination`,
{ referrers: [...referrers].slice(0, 5) }));
} else {
findings.push(finding('links', 'broken-internal-link', 'error', target,
`internal link target ${target} returns ${res.status || res.error}`,
{ referrers: [...referrers].slice(0, 10) }));
}
}, 8);
// anchor targets: pass 1 against server HTML; survivors re-verified in the
// rendered DOM (block JS assigns ids at decoration time — e.g. TOC/term ids)
const suspects = [];
for (const a of anchors) {
const html = pageHtml.get(a.targetPath);
if (!html) continue; // off-inventory target already reported
if (!new RegExp(`id=["']${a.id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']`).test(html)) {
suspects.push(a);
}
}
if (suspects.length) {
let renderedIds = null; // targetPath -> Set(ids), null = browser unavailable
try {
const { openBrowser, newPage, goto } = await import('../lib.mjs');
const browser = await openBrowser({ mode: 'plain' });
const page = await newPage(browser);
renderedIds = new Map();
for (const target of [...new Set(suspects.map((a) => a.targetPath))]) {
try {
await goto(page, pageUrl(base, target), { waitUntil: 'domcontentloaded', timeout: 30000 });
await page.waitForTimeout(3500); // let block decoration assign ids
renderedIds.set(target, new Set(await page.evaluate(
() => [...document.querySelectorAll('[id]')].map((e) => e.id),
)));
} catch { renderedIds.set(target, null); }
}
await browser.close();
} catch { /* no playwright — report unverified */ }
for (const a of suspects) {
const ids = renderedIds?.get(a.targetPath);
if (ids === undefined || ids === null) {
findings.push(finding('links', 'anchor-unverified', 'info', a.referrer,
`anchor #${a.id} on ${a.targetPath} not in server HTML; rendered DOM not checkable here — verify manually`));
} else if (!ids.has(a.id)) {
findings.push(finding('links', 'broken-anchor', 'warn', a.referrer,
`anchor #${a.id} on ${a.targetPath} has no matching id (verified in rendered DOM)`));
}
}
}
// externals: probe each unique URL once (opt-in — see header)
if (!ctx.opts.probeExternals) {
if (external.size) {
findings.push(finding('links', 'externals-skipped', 'info', '',
`${external.size} unique external link(s) not probed — pass --probe-externals to check them`));
}
return findings;
}
await pMap([...external.entries()], async ([url, referrers]) => {
let res = await fetchUrl(url, { method: 'HEAD', timeoutMs: 8000, retries: 0 });
if (res.status === 0 || res.status >= 400) {
// many hosts reject HEAD but serve GET (e.g. maps.google.com HEAD=404, GET=200)
res = await fetchUrl(url, { timeoutMs: 8000, retries: 0 });
}
if (res.status === 404 || res.status === 410 || res.status === 0) {
findings.push(finding('links', 'broken-external-link', 'warn', [...referrers][0],
`external link ${url} returns ${res.status || `network error: ${res.error}`}`,
{ referrers: [...referrers].slice(0, 10) }));
}
}, 6);
return findings;
}.tessl-plugin
skills
audit
reference
deploy
reference
scripts
test
diff
direct
dynamics
extract
migrate
prepare-migration
prototype
assets
motion
fixtures
reference
qa
replica
reference
scripts
test
reskin
rollout
spec
stardust
uplift
reference