feat: build steps 7a-10 — the site is complete and reviewable at 22 pages
Steps 7a through 10 as one authorised run. Nothing deployed (D11).
7a Lighthouse returns as `lighthouse@13.4.1` + `chrome-launcher`, NOT
`@lhci/cli`. AGENTS.md §7's advisory attribution was wrong: the carriers
were @lhci/cli's own `tmp` and @puppeteer/browsers' `extract-zip`, not
Lighthouse, which audits clean. A deliberate deviation from R11's literal
trigger, recorded with what it costs. Local gate; CI has no Chrome.
7b OG card generator (satori + sharp) discharges R15 — 20 typed cards plus
per-article cards; the portrait stays on / and /about/ by Q40. Insights
plumbing: ArticleCard, Prose, the index, the article route, articleGraph,
and /'s section 7. Card copy is constrained structurally because text in a
JPEG cannot be grepped by check:claims: every headline IS its page's <h1>,
enforced by `npm run og:proof`.
7c Five drafted launch articles, draft: true / reviewedByPouya: false. An
independent compliance audit returned 76 findings and 57 unsourced
assertions; all blocking and should-fix applied.
8 /contact/, the intake form, and backend/intake/ (undeployed). Plain HTML
POST to a same-origin /api/intake with a 303 redirect, so the form works
with zero JavaScript. docs/05 records three deliberate deviations.
9 /fees/ on Q59's ruling — overtime runs from the session cap, and the
reservation point ships adjacent to the rate. One-page PDF bio discharges
R16; /bio/ is its source, so the circulated artefact stays inside the
review apparatus.
10 /legal/privacy/ and /legal/terms/, written to the backend as built. Three
of the policy's statements are derived and cannot drift.
Also: /about/'s inverse credentials band (approved at step 6); Q59 closed;
R15 and R16 discharged; and a fix to shipped copy — /practice/energy/ asserted
the absence of a regulation the source extract says must not be asserted.
Review: adversarial-reviewer, two rounds (D20/D19). Round 1 returned 16
findings including two blocking — an invisible ghost button on /fees/ at
1.00:1 that Lighthouse scored 100, and a privacy policy that named one data
processor when there are two. All 16 acted on.
Lighthouse, 22 pages, mobile: performance 99-100, accessibility 100,
best practices 100, SEO 100 on every indexable page, CLS 0.000.
AGENTS.md entry (ah) has the detail, including four of my own verification
commands that were wrong and what each of them nearly caused.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Md3GndFqWPzK78xAoebsg5
This commit is contained in:
Pouya Lajevardi
co-authored by
Claude Opus 5
Claude Opus 5
parent
6cfe69033f
commit
210bc25a26
@@ -0,0 +1,377 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* The performance gate. Budget: docs/04-seo-spec.md §Performance —
|
||||
* Lighthouse >= 95 on all four categories, on mobile, for every page.
|
||||
*
|
||||
* WHY THIS IS `lighthouse` AND NOT `@lhci/cli`, WHICH IS WHAT R11 SAID TO PUT
|
||||
* BACK. Measured 2026-08-31 from two probe lockfiles, not recalled:
|
||||
*
|
||||
* @lhci/cli@0.15.1 10 vulnerabilities (7 high) pins lighthouse 12.6.1
|
||||
* high: tmp@0.1.0 <- a DIRECT dependency of @lhci/cli itself
|
||||
* high: extract-zip@2.0.1 <- via @puppeteer/browsers
|
||||
* lighthouse@13.4.1 0 vulnerabilities 109 packages
|
||||
* tmp ABSENT, extract-zip ABSENT
|
||||
*
|
||||
* So the carrier was never Lighthouse. AGENTS.md §7 recorded the advisories as
|
||||
* arriving "via lighthouse -> puppeteer-core -> extract-zip", and on that
|
||||
* attribution the tool looked unusable for as long as the advisories stood.
|
||||
* Standalone `lighthouse` measures the same budget with nothing outstanding.
|
||||
* What is given up is real and is recorded in §7: `lhci autorun`'s assertion
|
||||
* config, its server, and its CI upload.
|
||||
*
|
||||
* THIS IS A LOCAL GATE, NOT A CI CHECK, and the reason is Chrome. Standalone
|
||||
* Lighthouse drives an installed browser; the Gitea runner has none (§7 — the
|
||||
* runner is not registered at all yet, Q23). So this runs from a keyboard and
|
||||
* as a blocking item on docs/06's cutover checklist. It is not wired into
|
||||
* `npm run build` or either deploy path, and saying so is the point: a check
|
||||
* described as running where it cannot is the defect Q22 turned out to be.
|
||||
*
|
||||
* PAGES ARE ENUMERATED FROM `dist/`, NEVER LISTED HERE. A hand-written list
|
||||
* silently stops covering the site the first time a page is added — which is
|
||||
* this project's most expensive recurring shape. Every `index.html` under
|
||||
* `dist/` is a page, so the set cannot go stale.
|
||||
*
|
||||
* Usage: npm run build && npm run lighthouse
|
||||
* npm run lighthouse -- /fees/ /insights/ # a subset, by pathname
|
||||
*/
|
||||
import { createServer } from 'node:http';
|
||||
import { createReadStream } from 'node:fs';
|
||||
import { readdir, readFile, stat } from 'node:fs/promises';
|
||||
import { join, extname, relative, sep } from 'node:path';
|
||||
import lighthouse from 'lighthouse';
|
||||
import * as chromeLauncher from 'chrome-launcher';
|
||||
|
||||
const DIST = new URL('../dist/', import.meta.url).pathname;
|
||||
const THRESHOLD = 95;
|
||||
const CATEGORIES = ['performance', 'accessibility', 'best-practices', 'seo'];
|
||||
|
||||
/** docs/04's own budgets, reported alongside the scores rather than asserted
|
||||
* separately — LCP is the one the spec states in seconds. */
|
||||
const LCP_BUDGET_MS = 2000;
|
||||
const CLS_BUDGET = 0.05;
|
||||
|
||||
const MIME = {
|
||||
'.html': 'text/html; charset=utf-8',
|
||||
'.css': 'text/css; charset=utf-8',
|
||||
'.js': 'text/javascript; charset=utf-8',
|
||||
'.json': 'application/json; charset=utf-8',
|
||||
'.xml': 'application/xml; charset=utf-8',
|
||||
'.txt': 'text/plain; charset=utf-8',
|
||||
'.svg': 'image/svg+xml',
|
||||
'.jpg': 'image/jpeg',
|
||||
'.jpeg': 'image/jpeg',
|
||||
'.png': 'image/png',
|
||||
'.avif': 'image/avif',
|
||||
'.webp': 'image/webp',
|
||||
'.ico': 'image/x-icon',
|
||||
'.woff2': 'font/woff2',
|
||||
'.pdf': 'application/pdf',
|
||||
};
|
||||
|
||||
/**
|
||||
* `trailingSlash: 'always'` + `build.format: 'directory'` (astro.config.mjs),
|
||||
* so `/mediation/` is `dist/mediation/index.html` and an extensionless path
|
||||
* without the slash is a 404 here exactly as it is on CloudFront. Serving it
|
||||
* anyway would measure a URL the site does not have.
|
||||
*/
|
||||
function resolveFile(pathname) {
|
||||
if (pathname.endsWith('/')) return join(DIST, pathname, 'index.html');
|
||||
if (extname(pathname)) return join(DIST, pathname);
|
||||
return null;
|
||||
}
|
||||
|
||||
async function collectPages(dir = DIST) {
|
||||
const out = [];
|
||||
for (const entry of await readdir(dir, { withFileTypes: true })) {
|
||||
const full = join(dir, entry.name);
|
||||
if (entry.isDirectory()) out.push(...(await collectPages(full)));
|
||||
else if (entry.name === 'index.html') {
|
||||
const rel = relative(DIST, dir).split(sep).filter(Boolean).join('/');
|
||||
out.push(rel ? `/${rel}/` : '/');
|
||||
}
|
||||
}
|
||||
return out.sort();
|
||||
}
|
||||
|
||||
function serveDist() {
|
||||
const server = createServer((req, res) => {
|
||||
const pathname = decodeURIComponent(new URL(req.url, 'http://x').pathname);
|
||||
const file = resolveFile(pathname);
|
||||
if (!file) {
|
||||
res.writeHead(404, { 'content-type': 'text/plain' });
|
||||
res.end('404');
|
||||
return;
|
||||
}
|
||||
const stream = createReadStream(file);
|
||||
stream.on('error', () => {
|
||||
res.writeHead(404, { 'content-type': 'text/plain' });
|
||||
res.end('404');
|
||||
});
|
||||
stream.once('open', () => {
|
||||
// NO `cache-control` HEADER, AND THAT IS DELIBERATE — measured
|
||||
// 2026-08-31. `cache-control: no-store` was set here to force a cold
|
||||
// cache, which it did not need to do (Lighthouse resets storage between
|
||||
// runs by default) and which cost the `bf-cache` audit outright:
|
||||
// "Pages whose main resource has cache-control:no-store cannot enter
|
||||
// back/forward cache." The audit failed on every page, in a report whose
|
||||
// whole job is to find defects on the site. Verified by toggling the one
|
||||
// header: bf-cache 0 with it, 1 without, twice each.
|
||||
res.writeHead(200, {
|
||||
'content-type': MIME[extname(file)] ?? 'application/octet-stream',
|
||||
});
|
||||
stream.pipe(res);
|
||||
});
|
||||
});
|
||||
return new Promise((resolve, reject) => {
|
||||
server.once('error', reject);
|
||||
server.listen(0, '127.0.0.1', () =>
|
||||
resolve({ server, port: server.address().port }),
|
||||
);
|
||||
});
|
||||
}
|
||||
|
||||
const pad = (s, n) => String(s).padEnd(n);
|
||||
const scoreOf = (lhr, id) => Math.round((lhr.categories[id]?.score ?? 0) * 100);
|
||||
|
||||
/**
|
||||
* ⚠️ AN INTENTIONALLY `noindex` PAGE CANNOT SCORE 95 ON LIGHTHOUSE'S SEO
|
||||
* CATEGORY, AND THE BUDGET AS WRITTEN DID NOT KNOW THAT.
|
||||
*
|
||||
* Measured 2026-08-31, first full run over 22 pages: five pages scored SEO
|
||||
* **69**, and on every one the ONLY failing audit was `is-crawlable` — *"Page is
|
||||
* blocked from indexing"* — firing on `<meta name="robots" content="noindex,
|
||||
* follow">`. That meta tag is what `docs/04` REQUIRES on `/legal/*`, and it is
|
||||
* deliberate on `/bio/`, `/contact/received/` and `/contact/could-not-send/`.
|
||||
* So the category is measuring the page doing exactly what it was built to do.
|
||||
*
|
||||
* The wrong fix is to drop the SEO threshold, or to except these pages, or to
|
||||
* stop measuring them: each of those hides every OTHER SEO defect on the pages
|
||||
* where a defect is hardest to notice. What is asserted instead is stricter than
|
||||
* a number:
|
||||
*
|
||||
* indexable page -> SEO category >= 95, as before
|
||||
* noindex page -> EVERY SEO audit must pass EXCEPT `is-crawlable`
|
||||
*
|
||||
* A missing canonical, a missing title, an unreadable font size or a bad link on
|
||||
* a noindex page still fails the gate. Only the one audit that is measuring the
|
||||
* intent is set aside, and the page is marked in the table so the number is
|
||||
* never read as unqualified.
|
||||
*
|
||||
* `noindex` is read from the BUILT HTML rather than from a list of paths here —
|
||||
* a list would stop covering the site the first time a page is added.
|
||||
*/
|
||||
const EXPECTED_NOINDEX_FAILURE = 'is-crawlable';
|
||||
|
||||
async function isNoindex(page) {
|
||||
const file = resolveFile(page);
|
||||
const html = await readFile(file, 'utf8');
|
||||
return /<meta[^>]+name="robots"[^>]+content="[^"]*noindex/i.test(html);
|
||||
}
|
||||
|
||||
function failingAudits(lhr, category) {
|
||||
return (lhr.categories[category]?.auditRefs ?? [])
|
||||
.map((ref) => lhr.audits[ref.id])
|
||||
.filter((audit) => audit && audit.score !== null && audit.score < 1)
|
||||
.map((audit) => audit.id);
|
||||
}
|
||||
|
||||
async function main() {
|
||||
try {
|
||||
await stat(join(DIST, 'index.html'));
|
||||
} catch {
|
||||
console.error(
|
||||
'dist/index.html is missing. Run `npm run build` first — this gate ' +
|
||||
'measures the bytes that would ship, not the dev server.',
|
||||
);
|
||||
process.exit(2);
|
||||
}
|
||||
|
||||
const requested = process.argv.slice(2).filter((a) => a.startsWith('/'));
|
||||
const all = await collectPages();
|
||||
const pages = requested.length ? requested : all;
|
||||
const unknown = requested.filter((p) => !all.includes(p));
|
||||
if (unknown.length) {
|
||||
console.error(`Not built: ${unknown.join(', ')}`);
|
||||
process.exit(2);
|
||||
}
|
||||
|
||||
const { server, port } = await serveDist();
|
||||
const baseFlags = ['--headless', '--no-sandbox', '--disable-gpu'];
|
||||
const chrome = await chromeLauncher.launch({ chromeFlags: baseFlags });
|
||||
/**
|
||||
* ⚠️ A SECOND BROWSER, AND THE ACCESSIBILITY CATEGORY IS MEASURED IN IT.
|
||||
*
|
||||
* `--force-prefers-reduced-motion`. This is a deliberate deviation from a
|
||||
* single default run and it must be stated wherever the number is, which is
|
||||
* why the table below labels the column. Measured 2026-08-31, twice per
|
||||
* condition, on `/process/`:
|
||||
*
|
||||
* motion on a11y = 96 color-contrast FAILED, 24 nodes
|
||||
* motion off a11y = 100 color-contrast passed, 0 nodes
|
||||
*
|
||||
* The 24 nodes were the scroll-driven reveal (`animation-timeline: view()`,
|
||||
* global.css) caught mid-flight: axe reported foregrounds like `#d0cbc4` on
|
||||
* `#f8f4ed`, and NEITHER is in this site's palette — they are the real colours
|
||||
* blended toward the background by an in-progress `opacity` keyframe. So the
|
||||
* audit was measuring animation state, not contrast.
|
||||
*
|
||||
* WHY THIS IS THE HONEST RUN RATHER THAN THE CONVENIENT ONE. A category that
|
||||
* reports 24 known-false nodes on ten of fourteen pages cannot surface the
|
||||
* twenty-fifth, real one — it is a control that has stopped controlling, which
|
||||
* is the shape `AGENTS.md` Q22 and the Lighthouse removal both took. The
|
||||
* reduced-motion rendering is not a synthetic one: it is the branch
|
||||
* `global.css` ships for `prefers-reduced-motion: reduce`, a real user setting,
|
||||
* and it is the branch in which every element sits at its FINAL colour, which
|
||||
* is what a contrast audit is asking about. Contrast ratios for the palette
|
||||
* itself are computed and recorded in `docs/02-design-system.md`.
|
||||
*
|
||||
* Performance is NOT measured here — reduced motion would suppress work the
|
||||
* site really does on a default profile.
|
||||
*/
|
||||
const chromeA11y = await chromeLauncher.launch({
|
||||
chromeFlags: [...baseFlags, '--force-prefers-reduced-motion'],
|
||||
});
|
||||
|
||||
const PERF_CATEGORIES = CATEGORIES.filter((id) => id !== 'accessibility');
|
||||
const rows = [];
|
||||
const breaches = [];
|
||||
try {
|
||||
for (const page of pages) {
|
||||
const url = `http://127.0.0.1:${port}${page}`;
|
||||
// Default config otherwise: Lighthouse's mobile preset — mobile form
|
||||
// factor, mobile screen emulation, simulated Slow 4G. That is the
|
||||
// budget's own wording in docs/04, so none of it is overridden.
|
||||
const run = async (chromeInstance, onlyCategories) => {
|
||||
const result = await lighthouse(url, {
|
||||
logLevel: 'error',
|
||||
output: 'json',
|
||||
port: chromeInstance.port,
|
||||
onlyCategories,
|
||||
});
|
||||
if (!result?.lhr) {
|
||||
throw new Error(`Lighthouse returned nothing for ${page}`);
|
||||
}
|
||||
if (result.lhr.runtimeError?.code) {
|
||||
throw new Error(`${page}: ${result.lhr.runtimeError.message}`);
|
||||
}
|
||||
return result.lhr;
|
||||
};
|
||||
|
||||
const lhr = await run(chrome, PERF_CATEGORIES);
|
||||
const lhrA11y = await run(chromeA11y, ['accessibility']);
|
||||
|
||||
const scores = Object.fromEntries([
|
||||
...PERF_CATEGORIES.map((id) => [id, scoreOf(lhr, id)]),
|
||||
['accessibility', scoreOf(lhrA11y, 'accessibility')],
|
||||
]);
|
||||
const lcp = lhr.audits['largest-contentful-paint']?.numericValue ?? NaN;
|
||||
const cls = lhr.audits['cumulative-layout-shift']?.numericValue ?? NaN;
|
||||
const noindex = await isNoindex(page);
|
||||
rows.push({ page, scores, lcp, cls, noindex });
|
||||
|
||||
for (const id of CATEGORIES) {
|
||||
// The SEO category on a noindex page is asserted audit by audit
|
||||
// instead — see the comment on EXPECTED_NOINDEX_FAILURE.
|
||||
if (id === 'seo' && noindex) continue;
|
||||
if (scores[id] < THRESHOLD) {
|
||||
breaches.push(`${page} ${id} = ${scores[id]} (< ${THRESHOLD})`);
|
||||
}
|
||||
}
|
||||
if (noindex) {
|
||||
const unexpected = failingAudits(lhr, 'seo').filter(
|
||||
(id) => id !== EXPECTED_NOINDEX_FAILURE,
|
||||
);
|
||||
if (unexpected.length) {
|
||||
breaches.push(
|
||||
`${page} seo — noindex page, so only \`${EXPECTED_NOINDEX_FAILURE}\` ` +
|
||||
`may fail; these also failed: ${unexpected.join(', ')}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
} finally {
|
||||
// `kill()` is synchronous in chrome-launcher 1.x — `await` on it draws
|
||||
// ts(80007) from `astro check`, which this repo keeps at zero.
|
||||
chrome.kill();
|
||||
chromeA11y.kill();
|
||||
server.close();
|
||||
}
|
||||
|
||||
const w = Math.max(28, ...rows.map((r) => r.page.length + 2));
|
||||
console.log(`\n${pad('page', w)} perf a11y* bestp seo LCP CLS`);
|
||||
console.log('-'.repeat(w + 44));
|
||||
for (const r of rows) {
|
||||
const cells = CATEGORIES.map((id) =>
|
||||
pad(id === 'seo' && r.noindex ? `${r.scores[id]}n` : r.scores[id], 6),
|
||||
).join(' ');
|
||||
const lcpCell = pad(`${(r.lcp / 1000).toFixed(2)}s`, 8);
|
||||
console.log(`${pad(r.page, w)} ${cells} ${lcpCell} ${r.cls.toFixed(3)}`);
|
||||
}
|
||||
|
||||
// The worst-of row excludes noindex pages from the SEO column, because
|
||||
// including them would report 69 as the site's worst SEO score forever and
|
||||
// train a reader to ignore the column — which is how a real regression there
|
||||
// would go unnoticed.
|
||||
const worst = (id) => {
|
||||
const relevant = id === 'seo' ? rows.filter((r) => !r.noindex) : rows;
|
||||
return relevant.length
|
||||
? Math.min(...relevant.map((r) => r.scores[id]))
|
||||
: 100;
|
||||
};
|
||||
console.log('-'.repeat(w + 44));
|
||||
console.log(
|
||||
`${pad(`worst of ${rows.length}`, w)} ` +
|
||||
CATEGORIES.map((id) => pad(worst(id), 6)).join(' ') +
|
||||
` ${pad(`${(Math.max(...rows.map((r) => r.lcp)) / 1000).toFixed(2)}s`, 8)} ` +
|
||||
Math.max(...rows.map((r) => r.cls)).toFixed(3),
|
||||
);
|
||||
console.log(
|
||||
`\nbudgets: all four categories >= ${THRESHOLD} (mobile) · ` +
|
||||
`LCP < ${LCP_BUDGET_MS / 1000}s · CLS < ${CLS_BUDGET} — docs/04-seo-spec.md`,
|
||||
);
|
||||
const noindexCount = rows.filter((r) => r.noindex).length;
|
||||
if (noindexCount) {
|
||||
console.log(
|
||||
`n = deliberately noindex (${noindexCount} page(s)). Lighthouse's SEO\n` +
|
||||
' category cannot exceed ~69 on such a page: `is-crawlable` fails on the\n' +
|
||||
' `noindex` the page is supposed to carry. Those pages are asserted audit\n' +
|
||||
' by audit instead — every SEO audit must pass except that one — and are\n' +
|
||||
' excluded from the SEO worst-of above.',
|
||||
);
|
||||
}
|
||||
console.log(
|
||||
'* a11y is measured with prefers-reduced-motion forced. The scroll-driven\n' +
|
||||
" reveal otherwise puts axe's colour-contrast audit on mid-animation\n" +
|
||||
' opacity rather than on the palette — 24 false nodes, measured. See the\n' +
|
||||
' comment on chromeA11y in this script.',
|
||||
);
|
||||
|
||||
// Reported, not asserted. docs/04 states LCP and CLS as budgets; Lighthouse's
|
||||
// simulated throttling on a loopback server is not the Slow 4G field
|
||||
// measurement they describe, so a hard failure here would be a claim about
|
||||
// the instrument. The category scores ARE the gate.
|
||||
const lcpOver = rows.filter((r) => r.lcp >= LCP_BUDGET_MS);
|
||||
const clsOver = rows.filter((r) => r.cls >= CLS_BUDGET);
|
||||
if (lcpOver.length) {
|
||||
console.log(
|
||||
`note: LCP at or over budget on ${lcpOver.length} page(s): ` +
|
||||
lcpOver.map((r) => r.page).join(', '),
|
||||
);
|
||||
}
|
||||
if (clsOver.length) {
|
||||
console.log(
|
||||
`note: CLS at or over budget on ${clsOver.length} page(s): ` +
|
||||
clsOver.map((r) => r.page).join(', '),
|
||||
);
|
||||
}
|
||||
|
||||
if (breaches.length) {
|
||||
console.error(`\nBUDGET BREACH — ${breaches.length}:`);
|
||||
for (const b of breaches) console.error(` - ${b}`);
|
||||
console.error('\nCLAUDE.md: treat a budget breach as a failing build.');
|
||||
process.exit(1);
|
||||
}
|
||||
console.log(`\nOK — ${rows.length} page(s), no category below ${THRESHOLD}.`);
|
||||
}
|
||||
|
||||
await main();
|
||||
Reference in New Issue
Block a user