#!/usr/bin/env node /** * Migration fidelity: every string a change REMOVES from source must reappear * verbatim in a catalog. * * A directory migration replaces literals with `t()` calls. If the English a * user saw is gone from the source and is not a catalog value either, then the * copy silently CHANGED — and nothing else in the toolchain notices: * * live surface : "Create a diagnostic ZIP with frontend and backend logs." * reused key : "Download a bounded diagnostic ZIP containing frontend and backend logs." * * That shape survives `pnpm lint`, all four `i18n:check` gates, the ratchet and * the whole unit suite, because every string IS externalized, the key DOES * exist and the catalogs ARE in sync. It happens when two surfaces render the * same copy, one of them was migrated earlier (often a dead route), and the * later migration adopts the existing, plausible-looking key. The pseudo-locale * cannot see it either: the text is translated, just into different words. * * This check compares the literals present before and after, so it reports at * the point of the edit and covers every route in the change automatically, * rather than relying on whichever one happens to have an e2e assertion * pinning its sentence. * * NOT part of `i18n:check`, and deliberately not in CI: it is diff-based, so it * needs a base ref, and a finding is a prompt to CLASSIFY rather than proof of * a bug. Benign findings are normal and expected — a value extracted into an * interpolation, a placeholder hoisted to a constant, a literal that was never * copy. It narrows the diff for a human; it does not decide. * * COVERAGE IS PARTIAL. Rule 2 is only as tight as the literal text around a * message's placeholders, which is why a message needs two words of prose to * earn one at all (see `canAnchorPattern`). Simulating a rewrite of every * removed string measured 89/96 caught on this migration. The remainder are * messages too thin to distinguish a rewrite from anything else. A clean run is * evidence, not proof — which is why the mutation probe in docs/i18n.md is a * separate step. * * Usage: node scripts/check-removed-literals.mjs [--base ] [--all] * * --all also report literals that look like identifiers/values, not just * the ones that look like prose. */ import fs from "node:fs"; import path from "node:path"; import { git, resolveBase, REPO_ROOT } from "./lib/git-base.mjs"; import { changedFiles, WEB_PREFIX } from "./lib/changed-files.mjs"; import { accountedFor, buildCatalog, literals, looksLikeCopy } from "./lib/removed-literals.mjs"; const ROOT = path.resolve(import.meta.dirname, ".."); const LOCALES = path.join(ROOT, "src", "locales", "en"); const REPORT_ALL = process.argv.includes("--all"); function catalogValues() { const out = new Set(); for (const file of fs.readdirSync(LOCALES).filter((f) => f.endsWith(".json"))) { for (const value of Object.values( JSON.parse(fs.readFileSync(path.join(LOCALES, file), "utf8")), )) if (typeof value === "string") out.add(value); } return out; } /** The committed content of a path at `ref`, or "" if absent there. */ function committedSide(ref, repoPath) { try { return git(["show", `${ref}:${repoPath}`], { quiet: true }); } catch { return ""; // Absent on that side (added or deleted). } } /** * The CURRENT content of a path — working tree, not `HEAD`. * * This side must not be `git show HEAD:…`. `changedFiles` diffs the base against * the working tree, so it lists files you have edited but not committed; reading * the "after" side from HEAD compared those files against themselves and found * nothing. The result was a no-op that printed a tick WITH THE CORRECT FILE * COUNT, which is what made it convincing — and the natural workflow (finish, * run checks, commit) walks straight into it. * * A missing file is a deletion, so its strings all count as removed. */ function workingTreeSide(repoPath) { try { return fs.readFileSync(path.join(REPO_ROOT, repoPath), "utf8"); } catch { return ""; } } const resolved = resolveBase(); if (resolved.skip) { console.log(`↷ skipped removed-literal check — ${resolved.skip}`); process.exit(0); } const { base } = resolved; const values = catalogValues(); const catalog = buildCatalog(values); const files = [ ...new Set([...changedFiles(base, "M", REPO_ROOT), ...changedFiles(base, "D", REPO_ROOT)]), ]; const findings = []; let unparseable = 0; for (const repoPath of files) { const before = literals(committedSide(base, repoPath), repoPath); const after = literals(workingTreeSide(repoPath), repoPath) ?? new Set(); if (before === null) { unparseable += 1; continue; } for (const value of before) { if (after.has(value)) continue; if (!REPORT_ALL && !looksLikeCopy(value)) continue; if (accountedFor(value, catalog)) continue; findings.push({ file: repoPath.slice(WEB_PREFIX.length), value }); } } if (unparseable) console.log(`ℹ ${unparseable} file(s) could not be parsed on the base side.`); // A tick over nothing is the shape of every silent no-op this check has had. // Say plainly that there was nothing to compare rather than reporting a verdict. if (files.length === 0) { console.log( `↷ no changed .ts/.tsx under ${WEB_PREFIX} between ${base.slice(0, 9)} and the working tree — nothing to compare.`, ); process.exit(0); } if (findings.length === 0) { console.log( `✓ removed literals OK — every string ${files.length} changed file(s) dropped is still a catalog value.`, ); process.exit(0); } console.log( `\nStrings removed from source that do NOT reappear verbatim in a catalog (${findings.length}):\n`, ); for (const { file, value } of findings.sort( (a, b) => a.file.localeCompare(b.file) || a.value.localeCompare(b.value), )) console.log(` ${file}\n ${JSON.stringify(value)}\n`); console.log( "Each is one of:\n" + " - a VALUE extracted into an interpolation (reconstruct it and compare — it should be byte-identical)\n" + " - a literal hoisted to a constant, or one that was never copy\n" + " - COPY THAT CHANGED, because a reused key's English differs from what this surface rendered\n" + "\nThe last one is the bug this check exists for. Classify every entry before merging.\n", ); process.exit(1);