diff --git a/.husky/pre-commit b/.husky/pre-commit index 9b26ff2a841..44b7198c1fa 100755 --- a/.husky/pre-commit +++ b/.husky/pre-commit @@ -13,7 +13,8 @@ sh scripts/check/check-git-identity.sh # session's changes, and never download a missing tool during a commit. npx --no-install lint-staged --no-stash node scripts/quality/gate-manifest.mjs -node scripts/check/check-docs-sync.mjs +# --mode=pr: judge what this commit does; mirrors the base left stale are the translation wave's job +node scripts/check/check-docs-sync.mjs --mode=pr npm run check:any-budget:t11 # kit type scale (#19066 block 7): sizes under 12 px and font-bold may only go down node scripts/check/check-type-scale-ratchet.mjs --ratchet --quiet diff --git a/scripts/check/check-docs-sync.mjs b/scripts/check/check-docs-sync.mjs index cebf4566a24..bc519e4a0f4 100644 --- a/scripts/check/check-docs-sync.mjs +++ b/scripts/check/check-docs-sync.mjs @@ -8,7 +8,14 @@ // translation-mirror checks (docs/i18n//llm.txt copies and the translated // CHANGELOG.md sections) are skipped with a reason: feature PRs never write // docs/i18n/**; the translation wave (scripts/i18n/sync-llm-mirrors.mjs) and the -// release (npm run release:sync-changelog-i18n) do. +// release (npm run release:sync-changelog-i18n) do. Two exceptions keep a mirror +// edit visible: a change that writes the mirrors (writer branch, or its own diff +// when the base resolves) is judged strictly, and the llm.txt mirrors must always +// agree with each other or with the root (a hand edit to one of them fails even +// in a depth-1 checkout). +// +// The pre-commit hook passes --mode=pr: a commit is judged on what it does, not on mirrors the +// base left stale. import fs from "node:fs"; import path from "node:path"; @@ -182,6 +189,74 @@ function checkI18nMirrorFile(fileName, sourcePath) { } } +/** + * PR mode, when the change is not judged strictly on the exact-copy mirrors (it does not write + * them, or its diff base is unresolvable — the depth-1 checkout of docs-sync-strict). A base that + * moved leaves every mirror equally stale; a hand edit leaves one mirror that matches neither the + * root nor the body most mirrors share. So each mirror must exist, keep its separator, and carry + * either the root body or that most common body — a check that needs no base. + * @returns {boolean} true when every mirror already matches the root body + */ +function checkI18nMirrorConsistency(fileName, sourcePath) { + if (!fs.existsSync(i18nDocsPath)) { + fail("docs/i18n directory is missing"); + return false; + } + + const sourceBody = normalizeMirrorBody(stripTopHeading(readText(sourcePath))); + const locales = fs + .readdirSync(i18nDocsPath, { withFileTypes: true }) + .filter((entry) => entry.isDirectory()) + .map((entry) => entry.name) + .sort(); + + const bodies = new Map(); + for (const locale of locales) { + const targetPath = path.join(i18nDocsPath, locale, fileName); + if (!fs.existsSync(targetPath)) { + fail(`docs/i18n/${locale}/${fileName} is missing`); + continue; + } + const body = extractI18nMirrorBody(readText(targetPath)); + if (body === null) { + fail(`docs/i18n/${locale}/${fileName} is missing the i18n mirror separator`); + continue; + } + bodies.set(locale, normalizeMirrorBody(body)); + } + + const counts = new Map(); + for (const body of bodies.values()) counts.set(body, (counts.get(body) ?? 0) + 1); + let shared = null; + let sharedCount = 0; + for (const [body, count] of counts) { + if (count > sharedCount) [shared, sharedCount] = [body, count]; + } + + let agreeing = 0; + let current = 0; + for (const [locale, body] of bodies) { + if (body === sourceBody) current += 1; + if (body === sourceBody || body === shared) { + agreeing += 1; + continue; + } + fail( + `docs/i18n/${locale}/${fileName} differs from root ${fileName} and from the other locales' mirrors (hand edit? run node scripts/i18n/sync-llm-mirrors.mjs)` + ); + } + + const allCurrent = current > 0 && current === locales.length; + if (allCurrent) { + console.log(`[docs-sync] ${fileName} i18n mirrors match root content: ${current} locales`); + } else if (agreeing > 0) { + console.log( + `[docs-sync] pr mode: ${fileName} mirrors agree with each other: ${agreeing} locales (${current} already match the root)` + ); + } + return allCurrent; +} + /** * Check i18n CHANGELOG mirrors by verifying that all version sections from the * root CHANGELOG exist in each translation. Unlike strict mirror files (llm.txt), @@ -312,7 +387,7 @@ try { if (scope.llm) { console.log(`[docs-sync] pr mode: ${scope.llm} — checking the llm.txt mirrors strictly`); checkI18nMirrorFile("llm.txt", llmPath); - } else { + } else if (!checkI18nMirrorConsistency("llm.txt", llmPath)) { console.log( `[docs-sync] SKIP reason=pr-mode — docs/i18n//llm.txt mirrors are refreshed by the translation wave (scripts/i18n/sync-llm-mirrors.mjs), not by feature PRs; ${STRICT_ELSEWHERE}` ); diff --git a/tests/unit/check-docs-sync-mode.test.ts b/tests/unit/check-docs-sync-mode.test.ts index fdb19c2d005..feaf06606d3 100644 --- a/tests/unit/check-docs-sync-mode.test.ts +++ b/tests/unit/check-docs-sync-mode.test.ts @@ -255,3 +255,92 @@ test("PR mode judges the mirror a change itself edits, whatever the branch name" // The CHANGELOG mirrors were not touched: that check stays skipped. assert.match(edited.out, /SKIP reason=pr-mode — translated CHANGELOG\.md mirrors/); }); + +// A shallow CI checkout (the docs-sync-strict job checks out at depth 1) cannot resolve the diff +// base, so "did the change edit a mirror?" is unanswerable there. One check needs no base: the +// llm.txt mirrors are exact copies, so a base that moved leaves them all equally stale, while a +// hand edit leaves one mirror differing from the root AND from the others. +const MIRROR_HEADER = (locale: string) => `# OmniRoute (${locale})\n\n🌐 bar\n\n---\n\n`; +const LLM_BODY = LLM.replace(/^# .+\n+/, ""); + +function addLocales(root: string, locales: string[], body = LLM_BODY) { + for (const locale of locales) + write(root, `docs/i18n/${locale}/llm.txt`, MIRROR_HEADER(locale) + body); +} + +const PR_NO_BASE = { GITHUB_EVENT_NAME: "pull_request", GITHUB_HEAD_REF: "fix/fr-typo" }; + +test("PR mode without a diff base fails a hand-edited llm.txt mirror (it agrees with nothing)", () => { + const root = fixture(); + addLocales(root, ["de", "es"]); + write( + root, + "docs/i18n/fr/llm.txt", + `${MIRROR_HEADER("fr")}> A proxy.\n\n## Section\n\nmauvais\n` + ); + const { status, out } = run(root, [], PR_NO_BASE); + assert.equal(status, 1, out); + assert.match(out, /mode=pr \(auto: pull_request\)/); + assert.match( + out, + /FAIL - docs\/i18n\/fr\/llm\.txt differs from root llm\.txt and from the other locales' mirrors/ + ); + assert.doesNotMatch(out, /FAIL - docs\/i18n\/(de|es)\//); +}); + +test("PR mode without a diff base passes mirrors that are all stale the same way", () => { + const root = fixture(); + addLocales(root, ["de", "es"]); + staleMirrors(root); + const { status, out } = run(root, [], PR_NO_BASE); + assert.equal(status, 0, out); + assert.match(out, /llm\.txt mirrors agree with each other: 3 locales/); + assert.match(out, /SKIP reason=pr-mode — docs\/i18n\/\/llm\.txt mirrors are refreshed/); +}); + +test("PR mode accepts a mirror already synced to the root while the others are still stale", () => { + const root = fixture(); + addLocales(root, ["de", "es"]); + staleMirrors(root); + // e.g. a locale added by add-locale after the root moved: it copies the current root. + write( + root, + "docs/i18n/es/llm.txt", + MIRROR_HEADER("es") + + fs.readFileSync(path.join(root, "llm.txt"), "utf8").replace(/^# .+\n+/, "") + ); + const { status, out } = run(root, ["--mode=pr"]); + assert.equal(status, 0, out); +}); + +test("PR mode reports the release line when every llm.txt mirror already matches the root", () => { + const root = fixture(); + addLocales(root, ["de", "es"]); + const { status, out } = run(root, ["--mode=pr"]); + assert.equal(status, 0, out); + assert.match(out, /\[docs-sync\] llm\.txt i18n mirrors match root content: 3 locales/); + assert.doesNotMatch(out, /SKIP reason=pr-mode — docs\/i18n\/\/llm\.txt/); +}); + +test("PR mode still fails a missing llm.txt mirror or a mirror without its separator", () => { + const root = fixture(); + addLocales(root, ["de"]); + write(root, "docs/i18n/es/README.md", "x\n"); + write(root, "docs/i18n/de/llm.txt", "no separator here\n"); + const { status, out } = run(root, ["--mode=pr"]); + assert.equal(status, 1, out); + assert.match(out, /FAIL - docs\/i18n\/es\/llm\.txt is missing/); + assert.match(out, /FAIL - docs\/i18n\/de\/llm\.txt is missing the i18n mirror separator/); +}); + +// The pre-commit hook judges what the commit does, not what the base did: a local run defaults +// to release mode, so without the flag one merged feature PR that edits llm.txt (allowed — the +// wave syncs the mirrors) would block every later commit on that base until the wave runs. +test("the pre-commit hook runs check-docs-sync in PR mode", () => { + const hook = fs.readFileSync( + path.resolve(path.dirname(SCRIPT), "../../.husky/pre-commit"), + "utf8" + ); + const lines = hook.split("\n").filter((line) => line.includes("check-docs-sync.mjs")); + assert.deepEqual(lines, ["node scripts/check/check-docs-sync.mjs --mode=pr"]); +});