Files
novalon-website/scripts/accessibility/axe-node-count.mjs
T
zhangxiang 0157b1c9f5 fix(gates): axe 底色哨兵改从令牌取值(它抄的那份字面量早已过期),并补终局验证读数
`check:axe` 首跑 EXIT=1,其中 `bgMismatch=36` 的红因写着
「底色不等于令牌值 ⇒ 样式未加载」—— 两句**都是错的**:
样式加载得好好的(light 侧逐页相等、对比度节点 0),
错的是哨兵自己抄了一份令牌值。

副本漂移的证据链:
- `axe-node-count.mjs:52` 硬编码 `EXPECTED_BG = { light:'rgb(255, 255, 255)',
  dark:'rgb(10, 14, 20)' }`;
- 暗色底在 P1 暖色迁移(**本分支基线 `da9a5cb6` 之前**)就是 `--color-bg-primary: #141210`
  / `-rgb: 20 18 16`;
- `git diff da9a5cb6..HEAD -- src/app/globals.css` 里**没有任何** `color-bg-primary` 改动
  ⇒ 不是本轮引入;`git log -S "rgb(10, 14, 20)"` 定位到字面量入库那一笔。
  归因先于修闸:少了这一步,很容易把它读成「本批改坏了」。

修法是把**副本换成真源**,而不是把副本改成新值(那只是再抄一遍,下次换色板还会红):
现读 `--color-bg-primary-rgb` 三元组当场拼期望色。
实测读到了错诊断的代价:一个失效的哨兵会**顺带伪造一句错的诊断**。

改完重做负对照,证明没把闸调瞎(§5.34 那类"全站 CSS 404 仍 exit 0"的反面):
- 临时移走 `dist/standalone/dist/static` 起服务 ⇒ `expected=""`、
  `actual="rgba(0, 0, 0, 0)"` ⇒ 判红(`probe-bg-negative.mjs` 以 EXIT=0 表达
  「负对照成立」);
- 装配完好 ⇒ `expected="rgb(20, 18, 16)"` 与 `actual` 相等 ⇒ 判绿。

另记一条同轮事实:本次改造漏改一处 `pageBg` 引用,闸以
`FATAL: 扫描中断(uncaughtException):pageBg is not defined` 崩掉而不是静默通过 ——
这正是退出码分档(0 通过 / 1 判红 / 2 未能度量 + FATAL 独立路径)兑现价值的地方;
而 `scripts/**/*.mjs` 不在 `tsconfig` 覆盖内,只有真跑才暴露(§5.43 同族)。

终局验证补跑读数(装配后的 standalone 产物,详见台账 §11.6):
- `check:axe:routes` 清单 **35 条** → `check:axe` **EXIT=0**:
  `bgMismatch=0`、`contrastNodes=0`、`violationNodes=0`、`extraRuleNodes=0`、
  `extraRuleCoveragePairs=105`、`non2xxResponses=1`(期望内的 `/_not-found`)、
  `unexpectedStatus=0`。
- `test:visual:all -- --update-snapshots=none` 复跑 **104 failed / 21 passed**
  (五 project 均匀 21/21/20/21/21),**0 例 element-not-found、0 例超时**。
  与首跑 109/16 的差值全部归因到那 5 条 `founder-quote-section` 死选择器
  (区块按裁定已删除 ⇒ 区域截图永不可能命中),已在上笔改写为反向守卫并变异验证。
  ⇒ 剩下的 104 条**都是像素不符**,即本批语法改动的预期外溢:
  **AUTH-VISUAL 的重采量是这 104 张**,不是"基线全坏"。
- `test:e2e:prod`:`UJ-01/02/03/08/10` × chromium + chromium-mobile ⇒ **14 passed**。
  ⚠ GA4 那 16 例在本 worktree **仍 skipped**:worktree 没有 `.env.production`,
  而 `NEXT_PUBLIC_GA_MEASUREMENT_ID` 是 **build 期烘焙**进客户端产物的 ⇒
  「prod 目标下 GA4 才真断言」这条口径在缺该文件的树上不成立,
  须记为**未取证**而不是通过。

ISR 冻结产物的最终闭环:删自造 `uj03-test-news-*` 行(连带 `AuditLog.targetId`
与 `ContentZone.items` 的 JSON 引用)→ `npm run build`(`news.html` 里 uj03 命中 0)
→ 重跑 routes + axe。纪律不变:**重置 ISR 只能靠重建或 revalidate,不许手删 `dist/**`**。

文档:台账 §11.6、`docs/lessons-learned.md` §5.44 + 更新记录一行、
探针 `probe-bg.mjs` / `probe-bg-sentinel.mjs` / `probe-bg-negative.mjs` / `probe-drawer.mjs`。

复跑:`type-check` EXIT=0、`lint` EXIT=0(0 error / 81 warning)、
`check:visual` EXIT=0(grammar 11/11 + accents 成立,两条自证先跑)、
`jest` 1747 例、`build` EXIT=0。
2026-10-17 02:17:39 +08:00

310 lines
17 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// 全站 axe 节点计数门禁(验收 §8-⑤ 的永久化版本)。
//
// 来源:本文件由 `docs/acceptance/2026-09-21-axe/axe-contrast-evidence.mjs` 平移而来(2026-09-23),
// 行为口径不变:同一份路由清单在 **chromium + firefox** × **light + dark** 四个组合下逐页跑两遍 axe-core
// 1) tag 通道 `runOnly:{type:'tag',values:['wcag2a','wcag2aa','wcag21a','wcag21aa']}`
// 2) 规则级通道 `runOnly:{type:'rules',values:EXTRA_RULES}`
// 第 2 遍是 `presentation-role-conflict` 的**唯一真实覆盖**(该规则属 `best-practice` tag,不在 tag 通道内),
// 也是 Lighthouse 那三条死断言删除后 `autocomplete-valid` / `svg-img-alt` 的兜底。
// 证据链:docs/acceptance/2026-09-21-gates/final-tree-results.md §⑤ 与「Lighthouse 的 3 条死断言」。
//
// 与一次性版本的关键差异:**门禁判定从「打印 PASSED」升级为「exit code」**,并新增分母自证断言,
// 使「悄悄不再覆盖」无法以绿灯形式通过(CI 见 Jenkinsfile 的 ♿♿ 阶段)。
//
// 用法:
// npm run check:axe:routes # 生成路由清单(默认 /tmp/axe-routes.xml)
// npm run check:axe # 用该清单扫描并判定
// 环境变量:BASE(默认 http://localhost:3100,须是 `node dist/standalone/server.js` 起的生产服务,
// 非 dev server)、SITEMAP(路由清单 XML)、OUT(证据 JSON 输出目录,默认 docs/acceptance/2026-09-21-axe,
// 历史证据仍留在这里)。
//
// 退出码:0 通过 / 1 门禁判红(violation 节点 > 0、主题或底色不匹配、规则级通道分母不闭合)/
// 2 输入不可用(路由清单缺失或解析出 0 条)。
import { chromium, firefox } from 'playwright';
import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'fs';
import { fileURLToPath } from 'url';
import { dirname, isAbsolute, join, resolve } from 'path';
// 本脚本从证据目录 docs/acceptance/2026-09-21-axe/ 搬到 scripts/accessibility/,cwd 相对路径一律改为
// 仓库根相对,这样无论从哪个目录调用都指向同一份 axe-core 与同一处证据目录(行为等价,只是不再依赖 cwd)。
const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
const repoPath = (p) => (isAbsolute(p) ? p : resolve(REPO_ROOT, p));
const BASE = process.env.BASE || 'http://localhost:3100';
const OUT = repoPath(process.env.OUT || 'docs/acceptance/2026-09-21-axe');
const SITEMAP = repoPath(process.env.SITEMAP || '/tmp/axe-routes.xml');
const AXE_SCRIPT = repoPath('node_modules/axe-core/axe.min.js');
const TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'];
// Lighthouse 12.6.1 不包装这三条 axe 规则,且 presentation-role-conflict 属 best-practice tag(不在 TAGS 内)
// ⇒ 只有这里的规则级 runOnly 才真正测到它们;证据链见 docs/acceptance/2026-09-21-gates/final-tree-results.md
//
// 两条数组刻意分开:
// CANONICAL_EXTRA_RULES = 门禁**要求被判定**的三条规则(绝对下限,写死在此)
// EXTRA_RULES = 实际传给 axe 的 runOnly 列表(默认等于下限)
// 只删 EXTRA_RULES 会立即判红(分母不再等于 路由 × 组合 × 3 条下限),删 CANONICAL 则需要改动带注释的门禁契约本身。
const CANONICAL_EXTRA_RULES = ['autocomplete-valid', 'presentation-role-conflict', 'svg-img-alt'];
const EXTRA_RULES = [...CANONICAL_EXTRA_RULES];
const ENGINES = [['chromium', chromium], ['firefox', firefox]];
const THEMES = ['light', 'dark'];
const COMBOS = ENGINES.length * THEMES.length; // 4 个「引擎 × 主题」组合
/**
* 底色哨兵:页面的 body 底色必须等于**令牌自己声明的值**。
* 为什么要有这条:样式没加载时所有元素都落在默认黑白底上,对比度会「意外通过」,
* 于是 axe 给出一个漂亮的 0 违规 —— 这条哨兵就是用来把那种「意外达标」判红的。
*
* ⚠ 原实现把期望值**硬编码成两条字面量**(light #FFF、dark `rgb(10, 14, 20)`),
* 而 P1 暖色迁移早在本分支基线 `da9a5cb6` 之前就把暗色底改成了暖墨
* (`--color-bg-primary-rgb: 20 18 16`)⇒ 闸的哨兵从此**恒红**,
* 本轮实测 `bgMismatch=36`(chromium/dark 与 firefox/dark 各 36 页)。
* 归因核过:`git diff da9a5cb6..HEAD -- src/app/globals.css` 里**没有**任何
* `color-bg-primary` 改动 ⇒ 不是本轮引入,是「令牌改了、闸里的抄本没跟」,
* 与本仓 `check:token-twins` 守的是同一类病(一个语义有多条表示通道)。
*
* 修法不是把字面量改成新值 —— 那只是把抄本再抄一遍,下次换色板还会红。
* 现改成**从令牌自己取值**:读 `--color-bg-primary-rgb` 三元组拼成期望色,
* 哨兵的失败模式不变(CSS 没加载时该自定义属性解析为空 ⇒ 期望串拼不出来 ⇒ 判红),
* 但对色板变更免疫。
*/
const BG_TRIPLET_VAR = '--color-bg-primary-rgb';
// 逐页状态码期望:清单里绝大多数路由必须 2xx/3xx,`/_not-found` 是本站 404 页、**期望** 404。
// 为什么必须逐页判:404/500 页几乎没有可比对节点,`violationNodes` 仍为 0,而 `s.pages` 计数照加;
// 聚合保险丝 `okResponses > 0` 只在**全部**响应都非 2xx 时才炸 ⇒ 单个路由退化成 404 会被当「干净」计过。
// 证据:docs/acceptance/2026-09-21-axe/axe-evidence.json 实测 136 行 = 132×200 + 4×404(全部来自 /_not-found)。
const EXPECTED_404 = ['/_not-found'];
const statusOffenders = [];
function fatal(message, code = 2) {
console.error(`FATAL: ${message}`);
process.exit(code);
}
// 扫描中途抛错(浏览器启动失败、服务不可达、axe 注入失败)会以非 0 退出,这里只是把原因说清楚。
for (const ev of ['unhandledRejection', 'uncaughtException']) {
process.on(ev, (err) => fatal(`扫描中断(${ev}):${err instanceof Error ? err.message : String(err)}`, 1));
}
if (!existsSync(AXE_SCRIPT)) {
fatal(`缺少 ${AXE_SCRIPT}(axe-core 未安装?先 npm ci)`, 2);
}
if (!existsSync(SITEMAP)) {
fatal(`路由清单 ${SITEMAP} 不存在。先跑 npm run check:axe:routes 生成清单`, 2);
}
const urls = [...new Set(
readFileSync(SITEMAP, 'utf8')
.split('<url>')
.slice(1)
.map((b) => (b.match(/<loc>([^<]+)<\/loc>/) || [])[1])
.map((loc) => {
try {
return new URL(loc).pathname;
} catch {
return null;
}
})
.filter(Boolean)
)];
// 空清单时下面的循环零次执行、计数器全为 0,「PASSED = true」是假绿,必须拒绝出证据。
if (urls.length === 0) {
fatal(`从 ${SITEMAP} 解析出 0 条路由,扫描等于没测,退出 2`, 2);
}
async function settle(page) {
await page.waitForTimeout(1200);
await page.evaluate(async () => {
let last = -1;
for (let i = 0; i < 12; i += 1) {
window.scrollTo(0, document.body.scrollHeight);
await new Promise((r) => setTimeout(r, 180));
if (Math.round(window.scrollY) === last) break;
last = Math.round(window.scrollY);
}
window.scrollTo(0, 0);
});
await page.waitForTimeout(400);
}
const rows = [];
for (const [engineName, launcher] of ENGINES) {
const browser = await launcher.launch();
for (const theme of THEMES) {
const ctx = await browser.newContext({ colorScheme: theme });
await ctx.addInitScript((t) => {
localStorage.setItem('novalon-theme', t);
localStorage.setItem('novalon-cookie-preferences',
JSON.stringify({ necessary: true, analytics: false, functional: false, timestamp: '2026-09-21T00:00:00.000Z' }));
}, theme);
const page = await ctx.newPage();
for (const url of urls) {
const res = await page.goto(`${BASE}${url}`, { waitUntil: 'domcontentloaded', timeout: 45000 });
const statusCode = res ? res.status() : 0;
await settle(page);
const observedTheme = await page.evaluate(() =>
document.documentElement.getAttribute('data-theme'));
await page.addScriptTag({ path: AXE_SCRIPT });
const tagRun = await page.evaluate((tags) => window.axe.run(document, {
runOnly: { type: 'tag', values: tags },
resultTypes: ['violations'],
}), TAGS);
const violations = tagRun.violations.map((v) => ({
id: v.id, impact: v.impact, nodes: v.nodes.length,
sample: v.nodes.slice(0, 3).map((n) => (n.target || []).join(' ')),
}));
// 规则级复跑:axe 遇到未知 rule id 会直接抛错;extraRulesChecked 断言三条规则确实参与了本页运行。
const ruleRes = await page.evaluate((rules) => window.axe.run(document, {
runOnly: { type: 'rules', values: rules },
}), EXTRA_RULES);
const ruleViolations = ruleRes.violations.map((v) => ({
id: v.id, impact: v.impact, nodes: v.nodes.length,
sample: v.nodes.slice(0, 3).map((n) => (n.target || []).join(' ')),
}));
const ruleIds = new Set([
...ruleRes.violations, ...ruleRes.passes, ...ruleRes.incomplete, ...ruleRes.inapplicable,
].map((r) => r.id));
const covered = CANONICAL_EXTRA_RULES.filter((id) => ruleIds.has(id));
// 一次 evaluate 同时取「实际底色」与「令牌声明的底色」,避免两次读之间主题被切换
const bgRead = await page.evaluate((varName) => {
const root = getComputedStyle(document.documentElement);
const triplet = (root.getPropertyValue(varName) || '').trim();
const parts = triplet.split(/\s+/).filter(Boolean);
const expected = parts.length >= 3 ? `rgb(${parts.slice(0, 3).join(', ')})` : '';
return { actual: getComputedStyle(document.body).backgroundColor, expected };
}, BG_TRIPLET_VAR);
rows.push({
engine: engineName, theme, url, observedTheme, statusCode,
pageBg: bgRead.actual,
expectedBg: bgRead.expected,
bgMatchesToken: bgRead.expected !== '' && bgRead.actual === bgRead.expected,
violationRules: violations.length,
violationNodes: violations.reduce((a, v) => a + v.nodes, 0),
contrastNodes: violations.filter((v) => v.id === 'color-contrast').reduce((a, v) => a + v.nodes, 0),
extraRuleNodes: ruleViolations.reduce((a, v) => a + v.nodes, 0),
extraRulesChecked: ruleIds.size,
extraRulesCovered: covered,
extraRulesMissing: CANONICAL_EXTRA_RULES.filter((id) => !ruleIds.has(id)),
violations,
extraRuleViolations: ruleViolations,
});
console.log(`${engineName}/${theme} ${url} status=${statusCode} theme=${observedTheme} bg=${bgRead.actual}|期望 ${bgRead.expected} rules=${violations.length} nodes=${rows.at(-1).violationNodes} contrast=${rows.at(-1).contrastNodes} extra=${rows.at(-1).extraRuleNodes}/${covered.length}/${rows.at(-1).extraRulesChecked}`);
}
await ctx.close();
}
await browser.close();
}
const summary = {};
for (const r of rows) {
const k = `${r.engine}/${r.theme}`;
summary[k] = summary[k] || {
pages: 0, themeMismatch: 0, bgMismatch: 0, contrastNodes: 0, violationNodes: 0,
extraRuleNodes: 0, extraRulePagesUnderCovered: 0, extraRuleCoveragePairs: 0,
non2xxResponses: 0, okResponses: 0, unexpectedStatus: 0,
};
summary[k].pages += 1;
summary[k].contrastNodes += r.contrastNodes;
summary[k].violationNodes += r.violationNodes;
summary[k].extraRuleNodes += r.extraRuleNodes;
summary[k].extraRuleCoveragePairs += r.extraRulesCovered.length;
// 两条都要满足:三条下限规则逐条判定过(缺一条即覆盖腐化),且通道本身没跑出预期之外的形状。
if (r.extraRulesMissing.length > 0 || r.extraRulesChecked !== EXTRA_RULES.length) {
summary[k].extraRulePagesUnderCovered += 1;
}
if (r.observedTheme !== r.theme) summary[k].themeMismatch += 1;
if (!r.bgMatchesToken) summary[k].bgMismatch += 1;
if (r.statusCode >= 200 && r.statusCode < 400) summary[k].okResponses += 1;
else summary[k].non2xxResponses += 1;
// 逐页状态码判据(独立于上面两条聚合计数)
const expects404 = EXPECTED_404.includes(r.url);
const statusMatches = expects404
? r.statusCode === 404
: r.statusCode >= 200 && r.statusCode < 400;
if (!statusMatches) {
summary[k].unexpectedStatus += 1;
statusOffenders.push(
`${k} ${r.url} status=${r.statusCode} expected=${expects404 ? '404' : '2xx/3xx'}`,
);
}
}
const expectedCombos = ENGINES.flatMap(([e]) => THEMES.map((t) => `${e}/${t}`));
const totalRuleChecks = rows.reduce((a, r) => a + r.extraRulesChecked, 0);
const totalCanonicalCoverage = rows.reduce((a, r) => a + r.extraRulesCovered.length, 0);
const expectedCanonicalCoverage = urls.length * COMBOS * CANONICAL_EXTRA_RULES.length;
const missingRuleUnion = [...new Set(rows.flatMap((r) => r.extraRulesMissing))];
// ---- 门禁断言(exit code 由此决定,不再只是打印) ----
const failures = [];
const push = (cond, msg) => { if (!cond) failures.push(msg); };
// 分母自证:缺了它,「少扫了几个组合」与「扫了且全绿」在证据上无法区分。
push(rows.length === urls.length * COMBOS,
`分母不闭合:rows=${rows.length},应为 ${urls.length} 路由 × ${COMBOS} 组合 = ${urls.length * COMBOS}`);
for (const combo of expectedCombos) {
const s = summary[combo];
if (!s) { push(false, `${combo} 组合完全缺失(浏览器未启动或中途中断)`); continue; }
push(s.pages === urls.length, `${combo} 只扫了 ${s.pages} 页,清单有 ${urls.length} 页`);
push(s.violationNodes === 0, `${combo} violationNodes=${s.violationNodes}(阈值 0)`);
push(s.contrastNodes === 0, `${combo} contrastNodes=${s.contrastNodes}(阈值 0)`);
push(s.extraRuleNodes === 0, `${combo} extraRuleNodes=${s.extraRuleNodes}(三条规则级判据,阈值 0)`);
push(s.extraRulePagesUnderCovered === 0,
`${combo} 有 ${s.extraRulePagesUnderCovered} 页的规则级通道未覆盖满 ${CANONICAL_EXTRA_RULES.length} 条下限规则(缺:${missingRuleUnion.join(', ') || '形状异常'})`);
push(s.extraRuleCoveragePairs === urls.length * CANONICAL_EXTRA_RULES.length,
`${combo} 规则级覆盖 ${s.extraRuleCoveragePairs} ≠ ${urls.length} 路由 × ${CANONICAL_EXTRA_RULES.length} 规则`);
push(s.themeMismatch === 0, `${combo} themeMismatch=${s.themeMismatch}(以为在量深色其实还是浅色)`);
push(s.bgMismatch === 0, `${combo} bgMismatch=${s.bgMismatch}(底色不等于令牌值 ⇒ 样式未加载 ⇒ 对比度「意外达标」)`);
// 保险丝:整组全非 2xx ⇒ 服务或清单不对,扫的是 404 页而不是本站页面。
push(s.okResponses > 0, `${combo} 所有响应都非 2xx(BASE=${BASE} 不是可用的生产服务,或清单已过期)`);
push(s.unexpectedStatus === 0,
`${combo} 有 ${s.unexpectedStatus} 页状态码不符期望(404/500 页会被 axe 判为「无违规」且仍计入 pages 分母;期望见 EXPECTED_404)`);
}
// offenders 明细直接进判据文本(而非只打 stdout):本仓曾因 line reporter 不带 stdout
// 而在并发失败时「查不到规则名」,同理这里若不落进 failures 就查不到是哪一条路由 404。
if (statusOffenders.length > 0) {
push(false, `逐页状态码断言失败 ${statusOffenders.length} 处:\n ${statusOffenders.join('\n ')}`);
}
push(totalRuleChecks === urls.length * COMBOS * EXTRA_RULES.length,
`规则级通道总量 ${totalRuleChecks} ≠ ${urls.length}×${COMBOS}×${EXTRA_RULES.length} = ${urls.length * COMBOS * EXTRA_RULES.length}`);
// 绝对下限的分母闭合:三条规则 × 每一页 × 每一个组合,一个都不能少(0 违规 ≠ 没测到)。
push(totalCanonicalCoverage === expectedCanonicalCoverage,
`规则级覆盖 ${totalCanonicalCoverage} ≠ ${expectedCanonicalCoverage}` +
`(= ${urls.length} 路由 × ${COMBOS} 组合 × ${CANONICAL_EXTRA_RULES.length} 条下限规则 ${CANONICAL_EXTRA_RULES.join(', ')})`);
const artifact = {
generatedAt: new Date().toISOString(),
base: BASE,
axeCore: JSON.parse(readFileSync(repoPath('node_modules/axe-core/package.json'), 'utf8')).version,
routeSource: `${SITEMAP} → ${urls.length} 条路由(sitemap ∪ 预渲染产物 ∪ 站内链接 BFS)`,
routeCount: urls.length,
routes: urls,
combinations: expectedCombos,
tags: TAGS,
extraRules: EXTRA_RULES,
requiredRuleCoverage: CANONICAL_EXTRA_RULES,
thresholds: {
colorContrastNodes: 0, violationNodes: 0, themeMismatch: 0, bgMismatch: 0,
extraRuleNodes: 0, extraRulePagesUnderCovered: 0,
rows: urls.length * COMBOS,
totalExtraRuleChecks: urls.length * COMBOS * EXTRA_RULES.length,
requiredRuleCoverageTotal: expectedCanonicalCoverage,
},
totalExtraRuleChecks: totalRuleChecks,
expectedExtraRuleChecks: urls.length * COMBOS * EXTRA_RULES.length,
totalRequiredRuleCoverage: totalCanonicalCoverage,
expectedRequiredRuleCoverage: expectedCanonicalCoverage,
passed: failures.length === 0,
failures,
summary,
rows,
};
mkdirSync(OUT, { recursive: true });
writeFileSync(`${OUT}/axe-evidence.json`, JSON.stringify(artifact, null, 2));
console.log('\nSUMMARY', JSON.stringify(summary, null, 2));
console.log('PASSED =', artifact.passed);
if (!artifact.passed) {
console.error(`\nFAIL: axe 节点计数门禁 ${failures.length} 条判据未通过(证据已写入 ${OUT}/axe-evidence.json)`);
for (const f of failures) console.error(` ✗ ${f}`);
process.exit(1);
}