mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-11-16 17:09:09 +00:00
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:
@@ -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
|
||||
|
||||
@@ -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}`
|
||||
);
|
||||
|
||||
@@ -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"]);
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user