fix(ci): check-docs-sync PR mode keeps llm.txt mirrors consistent; pre-commit runs in PR mode

Two review findings on the PR-mode split of check-docs-sync:

- The docs-sync-strict job checks out at depth 1, so the diff base never
  resolves there and a hand edit to one docs/i18n/<locale>/llm.txt passed
  as SKIP. PR mode now runs a check that needs no base: every llm.txt
  mirror must exist, keep its separator and carry either the root body or
  the body most mirrors share. A base that moved leaves them all equally
  stale and passes; a single hand-edited mirror fails. Release mode is
  unchanged (same lines and exit code as the script before the split).

- The pre-commit hook ran the script without a mode, i.e. release mode
  locally. After a feature PR that edits only the root llm.txt merged,
  every later commit on that base would be blocked until the wave synced
  the mirrors. The hook now passes --mode=pr: a commit is judged on what
  it does; mirrors it writes are still judged strictly.
This commit is contained in:
diegosouzapw
2026-11-13 14:35:37 -03:00
parent 1acf72d3dc
commit b2cf3b68c7
3 changed files with 168 additions and 3 deletions

View File

@@ -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

View File

@@ -8,7 +8,14 @@
// translation-mirror checks (docs/i18n/<locale>/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/<locale>/llm.txt mirrors are refreshed by the translation wave (scripts/i18n/sync-llm-mirrors.mjs), not by feature PRs; ${STRICT_ELSEWHERE}`
);

View File

@@ -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\/<locale>\/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\/<locale>\/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"]);
});