@babelize/engine 0.0.0-stage → 0.1.2

package/dist/qa/locale-files.js

@@ -0,0 +1,159 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LOCALE_IGNORE_DIRS = void 0;
+exports.isLocaleCode = isLocaleCode;
+exports.isIgnoredLocalePath = isIgnoredLocalePath;
+exports.groupLocaleFiles = groupLocaleFiles;
+exports.findLocaleFileSets = findLocaleFileSets;
+exports.loadLocale = loadLocale;
+/**
+ * Find a project's JSON locale files without running the pipeline (read-only).
+ *
+ * Recognised layouts, under any directory named locales/messages/lang(s)/
+ * i18n/translations (the engine itself writes `<publicDir>/locales/<locale>.json`):
+ *
+ *   locales/en.json, locales/fr.json            flat: one file per locale
+ *   locales/en/common.json, locales/fr/common.json   namespaced (i18next): keys become `common:key`
+ */
+const path = __importStar(require("path"));
+const fs_1 = require("fs");
+const fast_glob_1 = __importDefault(require("fast-glob"));
+const locale_qa_1 = require("./locale-qa");
+const LOCALE_DIR_NAMES = ['locales', 'locale', 'messages', 'lang', 'langs', 'i18n', 'translations'];
+/**
+ * Directories never searched for locale files: dependencies, build output,
+ * and test/fixture trees (whose locale files are test data, not the app's).
+ */
+exports.DEFAULT_LOCALE_IGNORE_DIRS = [
+    'node_modules', '.git', '.next', 'dist', 'build', 'coverage', '.babelize', 'out',
+    '__fixtures__', 'fixtures', '__tests__', '__mocks__', 'test', 'tests', 'testing', 'e2e',
+];
+/** en, fr, pt-BR, zh_Hant, sr-Latn-RS — a locale code, not a namespace like "common". */
+const LOCALE_CODE = /^[a-z]{2,3}(?:[-_](?:[A-Z][a-z]{3}|[A-Za-z]{2}|\d{3}))*$/;
+function isLocaleCode(name) {
+    return LOCALE_CODE.test(name);
+}
+function toPosix(p) {
+    return p.split(path.sep).join('/');
+}
+/** True when a relative path runs through an ignored directory. */
+function isIgnoredLocalePath(rel, ignoreDirs = exports.DEFAULT_LOCALE_IGNORE_DIRS) {
+    const dirs = rel.split('/').slice(0, -1);
+    return dirs.some((d) => ignoreDirs.includes(d));
+}
+/**
+ * Group relative `.json` paths into locale file sets. Paths that aren't
+ * `<dir>/<locale>.json` or `<dir>/<locale>/<ns>.json` under a locale folder
+ * are ignored.
+ */
+function groupLocaleFiles(paths, options = {}) {
+    var _a;
+    const ignoreDirs = options.ignoreDirs ?? exports.DEFAULT_LOCALE_IGNORE_DIRS;
+    const sets = new Map();
+    for (const rel of [...new Set(paths.map(toPosix))].sort()) {
+        if (!rel.endsWith('.json') || isIgnoredLocalePath(rel, ignoreDirs))
+            continue;
+        const parts = rel.split('/');
+        const file = parts[parts.length - 1];
+        const parent = parts[parts.length - 2];
+        let dir;
+        let locale;
+        let layout;
+        if (parent !== undefined && LOCALE_DIR_NAMES.includes(parent) && isLocaleCode(file.slice(0, -5))) {
+            dir = parts.slice(0, -1).join('/');
+            locale = file.slice(0, -5);
+            layout = 'flat';
+        }
+        else if (parts.length >= 3 && LOCALE_DIR_NAMES.includes(parts[parts.length - 3]) && isLocaleCode(parent)) {
+            dir = parts.slice(0, -2).join('/');
+            locale = parent;
+            layout = 'namespaced';
+        }
+        else {
+            continue;
+        }
+        const id = `${dir}\u0000${layout}`;
+        const set = sets.get(id) ?? { dir, layout, files: {} };
+        ((_a = set.files)[locale] ?? (_a[locale] = [])).push(rel);
+        sets.set(id, set);
+    }
+    return [...sets.values()];
+}
+async function findLocaleFileSets(projectDir, options = {}) {
+    const names = `{${LOCALE_DIR_NAMES.join(',')}}`;
+    const ignoreDirs = options.ignoreDirs ?? exports.DEFAULT_LOCALE_IGNORE_DIRS;
+    const found = await (0, fast_glob_1.default)([`**/${names}/*.json`, `**/${names}/*/*.json`], {
+        cwd: projectDir,
+        ignore: ignoreDirs.map((d) => `**/${d}/**`),
+        onlyFiles: true,
+        deep: 8,
+        followSymbolicLinks: false,
+    });
+    return groupLocaleFiles(found, options);
+}
+/**
+ * Read and flatten one locale of a set. Namespaced files are keyed `ns:key`.
+ * `read` reads another version of the files (e.g. from git); by default the
+ * working tree is read.
+ */
+async function loadLocale(projectDir, set, locale, read = (rel) => fs_1.promises.readFile(path.join(projectDir, rel), 'utf8').catch((err) => {
+    if (err.code === 'ENOENT')
+        return null;
+    throw err;
+})) {
+    const files = set.files[locale] ?? [];
+    const messages = {};
+    const errors = [];
+    for (const rel of files) {
+        try {
+            const content = await read(rel);
+            if (content === null)
+                continue;
+            const data = JSON.parse(content);
+            const flat = (0, locale_qa_1.flattenLocaleMessages)(data);
+            const ns = set.layout === 'namespaced' ? path.basename(rel, '.json') : null;
+            for (const [k, v] of Object.entries(flat))
+                messages[ns ? `${ns}:${k}` : k] = v;
+        }
+        catch (err) {
+            errors.push({ file: toPosix(rel), message: err instanceof SyntaxError ? `invalid JSON: ${err.message}` : err.message });
+        }
+    }
+    return { locale, files, messages, errors };
+}

package/dist/qa/locale-qa.d.ts

@@ -0,0 +1,61 @@
+export type LocaleIssueCode = 'missing_key' | 'extra_key' | 'empty_value' | 'untranslated' | 'placeholder_mismatch' | 'icu_invalid' | 'icu_mismatch' | 'plural_category_invalid' | 'plural_category_missing' | 'glossary_violation'
+/** The source text changed but the translation didn't (review of a diff). */
+ | 'stale_translation'
+/** A translation present at the base of a diff was deleted while the source still has it. */
+ | 'translation_removed'
+/** Pseudo-localized test output (`--provider pseudo`, ⟦…⟧), not a translation. */
+ | 'pseudo_translation';
+export type LocaleIssueSeverity = 'error' | 'warning' | 'info';
+export interface LocaleIssue {
+    locale: string;
+    key: string;
+    code: LocaleIssueCode;
+    severity: LocaleIssueSeverity;
+    /** What is wrong, in plain words. */
+    message: string;
+}
+export interface LocaleGlossary {
+    /** Terms that must appear unchanged in every translation (brand names, …). */
+    neverTranslate?: string[];
+    /** Terms with a fixed translation per locale. */
+    alwaysTranslateAs?: Array<{
+        term: string;
+        translations: Record<string, string>;
+    }>;
+}
+export interface LocalePairOptions {
+    /** Source locale code; values identical to the source aren't flagged for a locale of the same language. */
+    sourceLocale?: string;
+    glossary?: LocaleGlossary;
+    /**
+     * Only check these keys (e.g. the keys changed in a diff). Missing/extra
+     * detection is limited to them too.
+     */
+    keys?: string[];
+}
+export interface LocalePairReport {
+    locale: string;
+    /** Keys in the source locale (plural groups count once). */
+    total: number;
+    /** Source keys (or plural groups) with a non-empty value in the target. */
+    translated: number;
+    /** Issue count by code. */
+    counts: Partial<Record<LocaleIssueCode, number>>;
+    errors: number;
+    warnings: number;
+    issues: LocaleIssue[];
+}
+/**
+ * Flatten nested locale JSON into dotted keys with string values. The
+ * engine's `_meta` block is dropped; non-string leaves (numbers, arrays) are
+ * not messages and are skipped.
+ */
+export declare function flattenLocaleMessages(data: unknown, prefix?: string, out?: Record<string, string>): Record<string, string>;
+/**
+ * Check one target locale against the source locale. Both maps are flat
+ * (see {@link flattenLocaleMessages}). Issues come in key order, errors and
+ * warnings mixed; callers cap and sort as they need.
+ */
+export declare function checkLocalePair(source: Record<string, string>, target: Record<string, string>, locale: string, options?: LocalePairOptions): LocalePairReport;
+/** Recompute `counts`/`errors`/`warnings` from `issues` (after adding issues to a report). */
+export declare function tallyLocaleIssues(report: LocalePairReport): LocalePairReport;

package/dist/qa/locale-qa.js

@@ -0,0 +1,342 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenLocaleMessages = flattenLocaleMessages;
+exports.checkLocalePair = checkLocalePair;
+exports.tallyLocaleIssues = tallyLocaleIssues;
+/**
+ * QA of an existing target locale against its source locale, without
+ * translating anything: missing/extra keys, empty and untranslated values,
+ * lost or invented placeholders, broken ICU messages and wrong plural forms
+ * (ICU and i18next `_one`/`_other` suffix keys), and glossary violations.
+ *
+ * Pure: takes flat key → text maps, returns issues in plain words. Used by the
+ * MCP `babelize_check` / `babelize_review` tools; the checks are the same ones
+ * the translate phase applies to fresh translations (placeholder protection,
+ * ICU comparison).
+ */
+const icu_message_1 = require("../utils/icu-message");
+const glossary_match_1 = require("../utils/glossary-match");
+const rules_1 = require("../modules/glossary/rules");
+const placeholder_protection_1 = require("../utils/placeholder-protection");
+const pseudo_markers_1 = require("../utils/pseudo-markers");
+const icu_spans_1 = require("../utils/icu-spans");
+const PLURAL_CATEGORIES = ['zero', 'one', 'two', 'few', 'many', 'other'];
+const PLURAL_SUFFIX = /^(.+)_(zero|one|two|few|many|other)$/;
+/**
+ * Flatten nested locale JSON into dotted keys with string values. The
+ * engine's `_meta` block is dropped; non-string leaves (numbers, arrays) are
+ * not messages and are skipped.
+ */
+function flattenLocaleMessages(data, prefix = '', out = {}) {
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return out;
+    for (const [k, v] of Object.entries(data)) {
+        if (!prefix && k === '_meta')
+            continue;
+        const key = prefix ? `${prefix}.${k}` : k;
+        if (typeof v === 'string')
+            out[key] = v;
+        else if (v && typeof v === 'object' && !Array.isArray(v))
+            flattenLocaleMessages(v, key, out);
+    }
+    return out;
+}
+function hasLetters(text) {
+    return /\p{L}/u.test(text);
+}
+function language(locale) {
+    return locale.toLowerCase().split(/[-_]/)[0];
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** The glossary as the translate phase applies it for `locale`. */
+function resolveGlossary(glossary, locale) {
+    const rules = (0, rules_1.normalizeGlossary)([
+        ...(glossary.neverTranslate ?? []).map((term) => ({ term, type: 'never_translate' })),
+        ...(glossary.alwaysTranslateAs ?? []).map((e) => ({ term: e.term, type: 'always_translate_as', translations: e.translations })),
+    ]);
+    return {
+        neverTranslate: rules.neverTranslate,
+        alwaysTranslateAs: (0, rules_1.fixedTermsFor)(rules, locale).map((g) => ({ term: g.term, translations: { [locale]: g.translation } })),
+    };
+}
+function containsTerm(text, term, ignoreCase) {
+    return new RegExp(`(?<![\\p{L}\\p{N}_])${escapeRegex(term)}(?![\\p{L}\\p{N}_])`, ignoreCase ? 'iu' : 'u').test(text);
+}
+/** Protected spans (variables, tags, URLs, …) with how often each occurs. */
+function spanCounts(text, icu) {
+    const counts = new Map();
+    for (const span of (0, placeholder_protection_1.protectText)(text, [], { icu }).tokens) {
+        // Whitespace inside a variable is not meaningful ({ name } == {name}).
+        const norm = /^[{%$]/.test(span) ? span.replace(/\s+/g, '') : span;
+        counts.set(norm, (counts.get(norm) ?? 0) + 1);
+    }
+    return counts;
+}
+/** Variables and tags break the UI when lost; a changed URL or email may be deliberate. */
+function isStructural(span) {
+    return /^[{%$<]/.test(span);
+}
+function quoteList(spans) {
+    return spans.map((s) => (s.length > 40 ? `${s.slice(0, 37)}…` : s)).join(', ');
+}
+function icuIssueCode(issue) {
+    switch (issue.code) {
+        case 'icu_invalid':
+            return 'icu_invalid';
+        case 'icu_plural_category_invalid':
+            return 'plural_category_invalid';
+        case 'icu_plural_category_missing':
+            return 'plural_category_missing';
+        default:
+            return 'icu_mismatch';
+    }
+}
+const COUNT_SPAN = /^\{\{?-?\s*count\s*\}?\}$/;
+function pluralSpans(forms) {
+    const counts = forms.map((f) => spanCounts(f, false));
+    const required = new Map();
+    const allowed = new Set();
+    for (const c of counts)
+        for (const span of c.keys())
+            allowed.add(span);
+    for (const span of allowed) {
+        if (COUNT_SPAN.test(span))
+            continue;
+        const min = Math.min(...counts.map((c) => c.get(span) ?? 0));
+        if (min > 0)
+            required.set(span, min);
+    }
+    return { required, allowed };
+}
+function checkValue(key, source, target, locale, options, push, plural) {
+    if (target.trim() === '') {
+        if (source.trim() !== '')
+            push({ key, code: 'empty_value', severity: 'error', message: 'Value is empty; the app shows a blank string.' });
+        return;
+    }
+    if ((0, pseudo_markers_1.isPseudoLocalized)(target) && !(0, pseudo_markers_1.isPseudoLocalized)(source)) {
+        push({
+            key,
+            code: 'pseudo_translation',
+            severity: 'error',
+            message: 'Pseudo-localized test text (⟦…⟧ from --provider pseudo), not a translation. Run babelize translate with a real provider to replace it.',
+        });
+    }
+    const icu = (0, icu_message_1.isIcuMessage)(source) || (0, icu_message_1.isIcuMessage)(target);
+    if (icu) {
+        // The translate phase lets a translation add a plural over a count-like
+        // argument of a plain source ("{unreadCount} notes" → German one/other);
+        // QA accepts the same, or a correct run would fail `babelize check`.
+        const pluralizable = (0, icu_message_1.isIcuMessage)(source) ? [] : (0, icu_message_1.countArguments)(source);
+        for (const issue of (0, icu_message_1.compareIcuMessages)(source, target, locale, { pluralizable })) {
+            push({ key, code: icuIssueCode(issue), severity: issue.severity, message: `${issue.message.charAt(0).toUpperCase()}${issue.message.slice(1)}.` });
+        }
+    }
+    // Placeholders, tags, URLs: every span in the source must be in the
+    // translation exactly as often (in ICU messages braces are structure and
+    // were compared above, so only tags/URLs/code are counted).
+    const tgt = spanCounts(target, icu);
+    const lost = [];
+    const added = [];
+    if (plural && !icu) {
+        // A plural form is checked against all of the key's source forms.
+        for (const [span, n] of plural.required)
+            if ((tgt.get(span) ?? 0) < n)
+                lost.push(span);
+        for (const span of tgt.keys())
+            if (!plural.allowed.has(span) && !COUNT_SPAN.test(span))
+                added.push(span);
+    }
+    else if (icu) {
+        // An ICU message repeats a tag once per branch, and a plural added over a
+        // plain source does too: compare which spans appear, not how often (as
+        // the translate phase does).
+        const src = spanCounts(source, icu);
+        for (const span of src.keys())
+            if (!tgt.has(span))
+                lost.push(span);
+        for (const span of tgt.keys())
+            if (!src.has(span))
+                added.push(span);
+    }
+    else {
+        const src = spanCounts(source, icu);
+        for (const [span, n] of src)
+            if ((tgt.get(span) ?? 0) < n)
+                lost.push(span);
+        for (const [span, n] of tgt)
+            if ((src.get(span) ?? 0) < n)
+                added.push(span);
+    }
+    if (lost.length || added.length) {
+        const structural = [...lost, ...added].some(isStructural);
+        const parts = [
+            lost.length ? `lost ${quoteList(lost)}` : '',
+            added.length ? `added ${quoteList(added)}` : '',
+        ].filter(Boolean);
+        push({
+            key,
+            code: 'placeholder_mismatch',
+            severity: structural ? 'error' : 'warning',
+            message: `Placeholders differ from the source: ${parts.join('; ')}.`,
+        });
+    }
+    else if (icu) {
+        // Present somewhere is not enough: each branch must carry its source
+        // branch's spans (or the whole plain source, for an added plural).
+        const branch = (0, icu_spans_1.branchSpanProblems)(source, target);
+        if (branch.length) {
+            const all = branch.flatMap((p) => [...p.lost, ...p.added]);
+            push({
+                key,
+                code: 'placeholder_mismatch',
+                severity: all.some(isStructural) ? 'error' : 'warning',
+                message: `Placeholders differ from the source in ${branch.map(icu_spans_1.describeBranchSpanProblem).join('; ')}.`,
+            });
+        }
+    }
+    const neverTranslate = options.glossary?.neverTranslate ?? [];
+    if (target === source &&
+        hasLetters(source) &&
+        !(options.sourceLocale && language(options.sourceLocale) === language(locale)) &&
+        hasLetters((0, placeholder_protection_1.protectText)(source, neverTranslate, { icu }).text.replace(/\[#VAR_\d+#\]/g, ''))) {
+        const words = source.trim().split(/\s+/).filter(hasLetters).length;
+        push({
+            key,
+            code: 'untranslated',
+            severity: words >= 2 ? 'warning' : 'info',
+            message: words >= 2
+                ? 'Same text as the source; looks untranslated.'
+                : 'Same text as the source (fine for names or codes, otherwise untranslated).',
+        });
+    }
+    for (const term of neverTranslate) {
+        if (term.trim() && (0, rules_1.sourceHasTerm)(source, term) && !containsTerm(target, term, true)) {
+            push({ key, code: 'glossary_violation', severity: 'warning', message: `"${term}" must stay untranslated but is missing from the translation.` });
+        }
+    }
+    for (const entry of options.glossary?.alwaysTranslateAs ?? []) {
+        // resolveGlossary left only this locale's translation (exact, else base language).
+        const expected = (0, rules_1.localeValue)(entry.translations, locale);
+        if (!expected || !entry.term.trim())
+            continue;
+        // Same matcher as the translate phase: inflected forms count (Polish "obszaru roboczego").
+        if ((0, rules_1.sourceHasTerm)(source, entry.term, neverTranslate) && !(0, glossary_match_1.containsGlossaryTranslation)(target, expected)) {
+            push({ key, code: 'glossary_violation', severity: 'warning', message: `"${entry.term}" should be translated as "${expected}".` });
+        }
+    }
+}
+/** Plural groups (i18next `key_one` / `key_other`) in a flat map: base → category → key. */
+function pluralGroups(flat) {
+    const groups = new Map();
+    for (const key of Object.keys(flat)) {
+        const m = PLURAL_SUFFIX.exec(key);
+        if (!m)
+            continue;
+        const group = groups.get(m[1]) ?? new Map();
+        group.set(m[2], key);
+        groups.set(m[1], group);
+    }
+    return groups;
+}
+/**
+ * Check one target locale against the source locale. Both maps are flat
+ * (see {@link flattenLocaleMessages}). Issues come in key order, errors and
+ * warnings mixed; callers cap and sort as they need.
+ */
+function checkLocalePair(source, target, locale, options = {}) {
+    // Resolved the way the translate phase resolves it (case-insensitive
+    // terms, never-translate wins a conflict), so QA expects what translation does.
+    if (options.glossary)
+        options = { ...options, glossary: resolveGlossary(options.glossary, locale) };
+    const issues = [];
+    const push = (issue) => issues.push({ locale, ...issue });
+    const only = options.keys ? new Set(options.keys) : null;
+    const inScope = (key) => !only || only.has(key);
+    // A suffix group counts as plural only when the source has its `_other`
+    // form; `step_one` alone is just a key name.
+    const sourceGroups = new Map([...pluralGroups(source)].filter(([, g]) => g.has('other')));
+    const targetGroups = pluralGroups(target);
+    const pluralKeys = new Set();
+    for (const [base, group] of sourceGroups) {
+        for (const key of group.values())
+            pluralKeys.add(key);
+        for (const key of targetGroups.get(base)?.values() ?? [])
+            pluralKeys.add(key);
+    }
+    let total = 0;
+    let translated = 0;
+    for (const key of Object.keys(source)) {
+        if (pluralKeys.has(key) || !inScope(key))
+            continue;
+        total++;
+        const value = target[key];
+        if (value === undefined) {
+            push({ key, code: 'missing_key', severity: 'error', message: 'Missing in this locale; the app falls back to the source text.' });
+            continue;
+        }
+        if (value.trim() !== '')
+            translated++;
+        checkValue(key, source[key], value, locale, options, push);
+    }
+    const required = (0, icu_message_1.requiredPluralCategories)(locale).cardinal;
+    for (const [base, group] of sourceGroups) {
+        const groupKeys = [...group.values(), ...(targetGroups.get(base)?.values() ?? [])];
+        if (only && !groupKeys.some((k) => only.has(k)))
+            continue;
+        total++;
+        const label = `${base}_*`;
+        const present = targetGroups.get(base) ?? new Map();
+        if (present.size === 0) {
+            push({ key: label, code: 'missing_key', severity: 'error', message: 'Plural forms are missing in this locale; the app falls back to the source text.' });
+            continue;
+        }
+        translated++;
+        const missing = required.filter((c) => !present.has(c));
+        if (missing.length) {
+            push({
+                key: label,
+                code: 'plural_category_missing',
+                severity: 'error',
+                message: `Missing plural form${missing.length > 1 ? 's' : ''} ${missing.map((c) => `_${c}`).join(', ')} that ${locale} needs; those counts fall back to the source text.`,
+            });
+        }
+        // i18next resolves `_zero` for count 0 in every language: never unused.
+        const unused = [...present.keys()].filter((c) => c !== 'zero' && !required.includes(c) && PLURAL_CATEGORIES.includes(c));
+        if (unused.length) {
+            push({
+                key: label,
+                code: 'plural_category_invalid',
+                severity: 'warning',
+                message: `Has plural form${unused.length > 1 ? 's' : ''} ${unused.map((c) => `_${c}`).join(', ')}, which ${locale} doesn't use (valid: ${required.join(', ')}).`,
+            });
+        }
+        const spans = pluralSpans([...group.values()].map((k) => source[k]));
+        for (const [category, key] of present) {
+            const src = source[group.get(category) ?? group.get('other')];
+            checkValue(key, src, target[key], locale, options, push, spans);
+        }
+    }
+    for (const key of Object.keys(target)) {
+        if (key in source || pluralKeys.has(key) || !inScope(key))
+            continue;
+        push({ key, code: 'extra_key', severity: 'info', message: 'Not in the source locale (stale or renamed key).' });
+    }
+    return tallyLocaleIssues({ locale, total, translated, counts: {}, errors: 0, warnings: 0, issues });
+}
+/** Recompute `counts`/`errors`/`warnings` from `issues` (after adding issues to a report). */
+function tallyLocaleIssues(report) {
+    const counts = {};
+    let errors = 0;
+    let warnings = 0;
+    for (const issue of report.issues) {
+        counts[issue.code] = (counts[issue.code] ?? 0) + 1;
+        if (issue.severity === 'error')
+            errors++;
+        else if (issue.severity === 'warning')
+            warnings++;
+    }
+    return { ...report, counts, errors, warnings };
+}

package/dist/qa/review.d.ts

@@ -0,0 +1,43 @@
+import { type FindLocaleOptions, type LocaleFileSet } from './locale-files';
+import { type LocaleGlossary, type LocalePairReport } from './locale-qa';
+export interface ReviewOptions {
+    /** Ref to compare against (branch, tag, commit). Default HEAD (uncommitted changes). */
+    base?: string;
+    sourceLocale?: string;
+    /** Only these target locales. */
+    locales?: string[];
+    glossary?: LocaleGlossary;
+    /** Directory names skipped when looking for locale files. */
+    ignoreDirs?: FindLocaleOptions['ignoreDirs'];
+}
+export interface LocaleSetChangeReview {
+    dir: string;
+    layout: LocaleFileSet['layout'];
+    sourceLocale: string;
+    /** Source-locale keys added, changed and removed by the diff. */
+    source: {
+        added: string[];
+        changed: string[];
+        removed: string[];
+    };
+    /** Target locales touched by the diff (or affected by source changes). */
+    locales: Array<LocalePairReport & {
+        changedKeys: number;
+        removedKeys: number;
+        fileDeleted: boolean;
+    }>;
+}
+export interface LocaleChangeReview {
+    /** What the working tree was compared with. */
+    base: string;
+    /** Changed locale files, relative to the project. */
+    changedLocaleFiles: string[];
+    /** Other changed files (code), relative to the project. */
+    changedOtherFiles: number;
+    sets: LocaleSetChangeReview[];
+}
+export declare class ReviewError extends Error {
+    readonly code: 'not_a_repo' | 'git_missing' | 'bad_base';
+    constructor(message: string, code: 'not_a_repo' | 'git_missing' | 'bad_base');
+}
+export declare function reviewLocaleChanges(projectDir: string, options?: ReviewOptions): Promise<LocaleChangeReview>;