From 674bb4afe892c8ddc1123cc46e3e8c50aa6f95a5 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 3 Sep 2026 02:23:29 +0000 Subject: [PATCH] docs(i18n): name the measurement-widening race in check-i18n-coverage's header MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The DOWN-direction remedy read as "your diff improved something" when the usual cause was "main moved under you" — a PR that widens what this ratchet measures races every in-flight PR that changes what is measured, invisibly, because the instrument does not exist on main. Append one sentence to the remedy pointing the reader at merging main first, and name the class generally in the file's own header, alongside the campaign observation and the forward-looking exposure (app-crm, app-todo, bulkActions, datasets). Fixes #14729 Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01WLJQhde67SeTccsmnBVarV --- scripts/check-i18n-coverage.mjs | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/scripts/check-i18n-coverage.mjs b/scripts/check-i18n-coverage.mjs index 696bcf65df..7957f769c8 100644 --- a/scripts/check-i18n-coverage.mjs +++ b/scripts/check-i18n-coverage.mjs @@ -142,6 +142,30 @@ // addressing only `fix` would have left it splitting; readings belong in // `evidence`, which is not keyed. The classified branches (`WORKSPACE_BUILD_FIX` / // `INSTALL_THEN_BUILD_FIX`) group byte-for-byte as they did before. +// +// #14729 named a class the ratchet itself produces, not a defect in it: PR #14651 +// (#14376) taught this gate to walk three new families, one of them +// `objects.OBJECT._validations.RULE.message`, and its committed baseline therefore +// held counts only that branch could compute — on `main` the walk did not exist, so +// other PRs moved those counts without being able to see that they did. Two PRs did +// exactly that while it waited to land, each costing a patch round: merge `main`, +// re-derive, rebuild every number in the PR body. Stated generally, because it is +// not i18n-specific — type-check debt counts, token ratchets and liveness state +// counts have the same shape: a PR that widens what a committed ratchet MEASURES +// races every PR that changes what is MEASURED, for its whole review-and-queue +// latency — and the race is invisible on `main`, because there the instrument does +// not exist. The two collisions were not independent draws, either: both were steps +// of one in-flight campaign moving the examples' authored `validations[].message` +// onto a shared translation channel, and a campaign that systematically touches +// exactly the family a PR makes measurable collides on every step it lands. As of +// `224f8ea`, `app-showcase` has zero untranslated rule messages left — that leg is +// finished — but the exposure is forward-looking, not closed: `app-crm` (5) and +// `app-todo` (4) rule messages, plus `bulkActions` (18) and `datasets` (62), are +// untranslated populations nobody is currently working, and a PR that starts +// walking any of them will race this gate the same way. It fails safe either +// direction — the DOWN-direction remedy below is what caught both collisions — so +// the cost is latency and re-derive rounds, not correctness; that is why the fix +// here is one sentence in that remedy, not a mechanism. import { execFileSync } from 'node:child_process'; import { readdirSync, readFileSync, writeFileSync, existsSync, openSync, closeSync, unlinkSync } from 'node:fs'; import { dirname, join, resolve } from 'node:path'; @@ -1338,7 +1362,8 @@ for (const [file, allowed] of Object.entries(baseline)) { } else if (now < allowed) { errors.push( `${file}: untranslated declared strings improved ${allowed} → ${now} — ratchet DOWN: ` + - `run \`node scripts/check-i18n-coverage.mjs --update\` and commit the baseline.`, + `run \`node scripts/check-i18n-coverage.mjs --update\` and commit the baseline. ` + + `If you did not touch this population, merge \`origin/main\` first — the movement is probably not yours.`, ); } }