@localheroai/cli 0.0.74-rc.1 → 0.0.74-rc.3

package/dist/commands/check.js

@@ -1,4 +1,5 @@
 import chalk from 'chalk';
+import { appendFileSync } from 'fs';
 import { configService } from '../utils/config.js';
 import { findTranslationFiles, parseFile, flattenTranslations, extractLocaleFromPath } from '../utils/files.js';
 import { findDuplicateYamlKeys, dedupeYaml } from '../utils/yaml-duplicates.js';
@@ -6,16 +7,24 @@ import { findMissingTranslationsByLocale, findTargetFile, processTargetContent }
 import { createIgnoreMatcher, filterKeys } from '../utils/ignore-keys.js';
 import { detectCheckConfig, defaultConfigDetectionDeps } from '../utils/check-config.js';
 import { findOrphanKeys, findPlaceholderMismatches, findStructureMismatches, findPluralShapeMismatches, findPluralizedFlatKeys, findMissingPluralCategories, usedPluralCategories, findEmptyAndIdentical, findConflictingKeys, toStringValue } from '../utils/check-utils.js';
+import { detectCiContext } from '../utils/ci-context.js';
+import { resolveChangeBase, runGit } from '../utils/check-git.js';
+import { baseFileSet, DUPLICATE_KEY_ERROR } from '../utils/check-changes.js';
+import { buildStepSummary, plural } from '../utils/check-summary.js';
+import { spellPlaceholders } from '../utils/placeholders.js';
+import { keyLineFinder } from '../utils/key-lines.js';
 const FAIL_ON_MODES = ['missing', 'placeholders', 'any', 'none'];
-const FORMATS = ['github'];
+const FORMATS = ['github', 'text'];
 const defaultDeps = {
     console,
     configUtils: configService,
     fileUtils: { findTranslationFiles },
     projectDetection: { detectProjectType: defaultConfigDetectionDeps.detectProjectType },
-    fsUtils: { listFiles: defaultConfigDetectionDeps.listFiles, readFile: defaultConfigDetectionDeps.readFile }
+    fsUtils: { listFiles: defaultConfigDetectionDeps.listFiles, readFile: defaultConfigDetectionDeps.readFile },
+    env: process.env,
+    git: runGit,
+    appendFile: (path, text) => appendFileSync(path, text)
 };
-const DUPLICATE_KEY_ERROR = 'Map keys must be unique';
 // The CLI's YAML parser rejects a repeated key that Rails accepts (last value
 // wins), so such files are reparsed here and the repeat becomes a finding.
 async function recoverDuplicateKeyFiles(failures, knownLocales, config, readFile) {
@@ -63,7 +72,7 @@ function targetKeysFor(targetFiles, targetLocale, sourceFile, sourceLocale) {
 function keysOf(targetFile, targetLocale, sourceLocale) {
     return processTargetContent(decode(targetFile, sourceLocale), targetLocale, targetFile.format);
 }
-function failedResult(sourceLocale = '') {
+function failedResult(format, sourceLocale = '') {
     return {
         aborted: true,
         exitCode: 1,
@@ -72,7 +81,10 @@ function failedResult(sourceLocale = '') {
         sourceFiles: [],
         keyCount: 0,
         parseFailures: [],
-        detected: null
+        detected: null,
+        format,
+        changes: null,
+        fileContents: {}
     };
 }
 const SOURCE_REASONS = {
@@ -106,8 +118,104 @@ function invalidOption(options) {
     if (options.format && !FORMATS.includes(options.format)) {
         return `Invalid --format "${options.format}". Use one of: ${FORMATS.join(', ')}.`;
     }
+    if (options.changedOnly && options.full) {
+        return 'Use either --changed-only or --full, not both.';
+    }
     return null;
 }
+function outputFormat(options, ci) {
+    if (options.json)
+        return 'json';
+    if (options.format)
+        return options.format;
+    return ci.githubActions ? 'github' : 'text';
+}
+const SILENT = { log: () => { } };
+/** Target files a missing key points at that no longer exist: the change may have deleted them. */
+function vanishedTargets(reports, files) {
+    const vanished = [];
+    for (const report of reports) {
+        const present = new Set((files.targetFilesByLocale[report.locale] ?? []).map((f) => f.path));
+        for (const path of new Set(report.missing.map((m) => m.targetPath))) {
+            if (!present.has(path))
+                vanished.push({ path, format: formatOf(path), locale: report.locale });
+        }
+    }
+    return vanished;
+}
+function compareWithBase(deps, ci, config, files, current, analyzeFiles) {
+    const configured = config.translationFiles.baseBranch || deps.env.GITHUB_BASE_REF;
+    const base = resolveChangeBase(deps.git, {
+        pullRequest: ci.pullRequest,
+        baseBranches: configured ? [configured] : ['main', 'master']
+    });
+    if ('error' in base)
+        return { status: base, reports: current };
+    let before;
+    try {
+        before = analyzeFiles(baseFileSet(deps.git, base.ref, files, vanishedTargets(current, files)));
+    }
+    catch (error) {
+        return { status: { error: `git could not read the base version: ${error.message.trim()}` }, reports: current };
+    }
+    return {
+        status: { base: base.label },
+        reports: current.map((report) => tagAgainstBase(report, before.find((b) => b.locale === report.locale)))
+    };
+}
+function sortedList(items) {
+    return [...items].sort().join('\0');
+}
+/**
+ * A finding is introduced when the base did not have the same problem. Each identity holds what makes the
+ * problem, so a placeholder mismatch that now misses a different placeholder counts as new.
+ */
+function tagAgainstBase(report, base) {
+    const tag = (current, before, identity) => {
+        const existing = new Set((before ?? []).map((finding) => JSON.stringify(identity(finding))));
+        return current.map((finding) => ({ ...finding, introduced: !existing.has(JSON.stringify(identity(finding))) }));
+    };
+    const placeholders = (f) => [f.key, f.path, sortedList(f.missingInTarget), sortedList(f.unexpectedInTarget)];
+    return {
+        ...report,
+        missing: tag(report.missing, base?.missing, (f) => [f.key, f.targetPath]),
+        empty: tag(report.empty, base?.empty, (f) => [f.key, f.path]),
+        identical: tag(report.identical, base?.identical, (f) => [f.key, f.path, f.value]),
+        placeholderMismatches: tag(report.placeholderMismatches, base?.placeholderMismatches, placeholders),
+        placeholderHints: tag(report.placeholderHints, base?.placeholderHints, placeholders),
+        orphans: tag(report.orphans, base?.orphans, (f) => [f.key, f.path]),
+        structureMismatches: tag(report.structureMismatches, base?.structureMismatches, (f) => [f.key, f.path, f.sourceShape, f.targetShape]),
+        pluralShapeMismatches: tag(report.pluralShapeMismatches, base?.pluralShapeMismatches, (f) => [f.key, f.path]),
+        missingPluralCategories: tag(report.missingPluralCategories, base?.missingPluralCategories, (f) => [f.key, f.path, sortedList(f.missing)]),
+        conflictingKeys: tag(report.conflictingKeys, base?.conflictingKeys, (f) => [f.key, f.files, f.values]),
+        duplicateKeys: tag(report.duplicateKeys, base?.duplicateKeys, (f) => [f.key, f.path, f.values])
+    };
+}
+function filterFindings(r, keep) {
+    return {
+        ...r,
+        missing: r.missing.filter(keep),
+        empty: r.empty.filter(keep),
+        identical: r.identical.filter(keep),
+        placeholderMismatches: r.placeholderMismatches.filter(keep),
+        placeholderHints: r.placeholderHints.filter(keep),
+        orphans: r.orphans.filter(keep),
+        structureMismatches: r.structureMismatches.filter(keep),
+        pluralShapeMismatches: r.pluralShapeMismatches.filter(keep),
+        missingPluralCategories: r.missingPluralCategories.filter(keep),
+        conflictingKeys: r.conflictingKeys.filter(keep),
+        duplicateKeys: r.duplicateKeys.filter(keep)
+    };
+}
+function isIntroduced(finding) {
+    return finding.introduced !== false;
+}
+function isExisting(finding) {
+    return finding.introduced === false;
+}
+function formatOf(path) {
+    return path.split('.').pop() ?? '';
+}
 function withPath(findings, path) {
     return findings.map((finding) => ({ ...finding, path }));
 }
@@ -128,68 +236,10 @@ function reshapedKeysBetween(sourceKeys, targetKeys) {
         ...findPluralizedFlatKeys(sourceKeys, targetKeys)
     ];
 }
-export async function runCheck(options = {}, deps = defaultDeps) {
-    const { console, configUtils, fileUtils, projectDetection, fsUtils } = deps;
-    const optionError = invalidOption(options);
-    if (optionError) {
-        console.error(chalk.red(`\n✖ ${optionError}\n`));
-        return failedResult();
-    }
-    const requestedLocales = parseLocales(options.locales);
-    let config = await configUtils.getProjectConfig();
-    let detected = null;
-    if (!config) {
-        const detection = await detectCheckConfig({ source: options.source, locales: requestedLocales, path: options.path, pattern: options.pattern }, { ...projectDetection, ...fsUtils });
-        if (!detection) {
-            console.error(chalk.red('\n✖ No translation files found. Run check from your project root, or point it at your locale folder with --path <dir>.\n'));
-            return failedResult();
-        }
-        ({ config, detected } = detection);
-    }
-    if (!config.translationFiles?.paths) {
-        console.error(chalk.red('\n✖ Invalid configuration: missing translationFiles.paths. Please run `npx @localheroai/cli init` to set up your configuration.\n'));
-        return failedResult();
-    }
-    const sourceLocale = options.source || config.sourceLocale;
-    const targetLocales = options.locales ? requestedLocales : config.outputLocales || [];
-    const result = await fileUtils.findTranslationFiles(config, {
-        returnFullResult: true,
-        sourceLocale,
-        targetLocales,
-        ...(options.json ? { logger: { log: console.error } } : {})
-    });
-    const discovered = result;
-    const recovered = await recoverDuplicateKeyFiles(discovered.parseFailures ?? [], [sourceLocale, ...targetLocales], config, fsUtils.readFile);
-    const recoveredPaths = new Set(recovered.files.map((f) => f.path));
-    const parseFailures = (discovered.parseFailures ?? []).filter((f) => !recoveredPaths.has(f.path));
-    const allFiles = [...discovered.allFiles, ...recovered.files];
-    const sourceFiles = [...discovered.sourceFiles, ...recovered.files.filter((f) => f.locale === sourceLocale)];
-    const targetFilesByLocale = { ...discovered.targetFilesByLocale };
-    for (const file of recovered.files.filter((f) => f.locale !== sourceLocale)) {
-        targetFilesByLocale[file.locale] = [...(targetFilesByLocale[file.locale] ?? []), file];
-    }
+function analyze(files, context) {
+    const { sourceLocale, targetLocales, detected, console, ignoreMatcher } = context;
+    const { sourceFiles, targetFilesByLocale } = files;
     const filesFor = (locale) => (targetFilesByLocale[locale] || []).map((f) => f.path);
-    if (!options.json && !options.format) {
-        if (detected)
-            printDetected(console, detected, targetLocales.length);
-        console.log(chalk.blue(`ℹ Source locale: ${sourceLocale} (${sourceFiles.map((f) => f.path).join(', ') || 'no source files found'})`));
-        if (targetLocales.length === 0 && !detected)
-            console.log(chalk.blue('ℹ Target locales: none configured'));
-        for (const locale of targetLocales) {
-            console.log(chalk.blue(`ℹ ${locale}: ${filesFor(locale).join(', ') || 'no files found'}`));
-        }
-    }
-    if (parseFailures.length > 0 && !options.json) {
-        console.error(chalk.red(`\n✖ ${parseFailures.length} translation file(s) could not be parsed and were skipped:`));
-        for (const failure of parseFailures) {
-            console.error(chalk.red(`  - ${failure.path}: ${failure.error}`));
-        }
-    }
-    if (!allFiles || allFiles.length === 0) {
-        console.error(chalk.red('\n✖ No translation files found in the specified paths.\n'));
-        return failedResult(sourceLocale);
-    }
-    const ignoreMatcher = createIgnoreMatcher(config.translationFiles?.ignoreKeys ?? []);
     const withoutIgnored = (keys) => filterKeys(keys, ignoreMatcher).kept;
     const localePluralCategories = {};
     for (const locale of targetLocales) {
@@ -198,7 +248,8 @@ export async function runCheck(options = {}, deps = defaultDeps) {
             localePluralCategories[locale] = categories;
     }
     const { missing } = findMissingTranslationsByLocale(sourceFiles, targetFilesByLocale, { sourceLocale, outputLocales: targetLocales, localePluralCategories }, false, console, { ignoreMatcher });
-    const sourceKeyMaps = sourceFiles.map((file) => ({ file, keys: withoutIgnored(sourceKeysFor(file, sourceLocale)) }));
+    const readSource = (file) => withoutIgnored(sourceKeysFor(file, sourceLocale));
+    const sourceKeyMaps = sourceFiles.map((file) => ({ file, keys: readSource(file) }));
     const totalSourceKeys = new Set();
     for (const { keys } of sourceKeyMaps) {
         for (const [key, value] of Object.entries(keys)) {
@@ -224,7 +275,7 @@ export async function runCheck(options = {}, deps = defaultDeps) {
             structureMismatches: [],
             pluralShapeMismatches: [],
             conflictingKeys: [],
-            duplicateKeys: recovered.duplicates
+            duplicateKeys: files.duplicates
                 .filter((d) => d.locale === locale)
                 .map(({ key, path, values }) => ({ key, path, values })),
             missingFiles: []
@@ -280,17 +331,129 @@ export async function runCheck(options = {}, deps = defaultDeps) {
         }
         return report;
     });
-    const failOn = options.failOn || 'missing';
-    const exitCode = shouldFail(reports, failOn) || (parseFailures.length > 0 && failOn !== 'none') ? 1 : 0;
+    return { reports, keyCount: totalSourceKeys.size };
+}
+export async function runCheck(options = {}, deps = defaultDeps) {
+    const { console, configUtils, fileUtils, projectDetection, fsUtils } = deps;
+    const ci = detectCiContext(deps.env);
+    const format = outputFormat(options, ci);
+    const optionError = invalidOption(options);
+    if (optionError) {
+        console.error(chalk.red(`\n✖ ${optionError}\n`));
+        return failedResult(format);
+    }
+    const requestedLocales = parseLocales(options.locales);
+    let config = await configUtils.getProjectConfig();
+    let detected = null;
+    if (!config) {
+        const detection = await detectCheckConfig({ source: options.source, locales: requestedLocales, path: options.path, pattern: options.pattern }, { ...projectDetection, ...fsUtils });
+        if (!detection) {
+            console.error(chalk.red('\n✖ No translation files found. Run check from your project root, or point it at your locale folder with --path <dir>.\n'));
+            return failedResult(format);
+        }
+        ({ config, detected } = detection);
+    }
+    if (!config.translationFiles?.paths) {
+        console.error(chalk.red('\n✖ Invalid configuration: missing translationFiles.paths. Please run `npx @localheroai/cli init` to set up your configuration.\n'));
+        return failedResult(format);
+    }
+    const sourceLocale = options.source || config.sourceLocale;
+    const targetLocales = options.locales ? requestedLocales : config.outputLocales || [];
+    const result = await fileUtils.findTranslationFiles(config, {
+        returnFullResult: true,
+        sourceLocale,
+        targetLocales,
+        ...(format === 'json' ? { logger: { log: console.error } } : {}),
+        ...(format === 'github' ? { logger: SILENT } : {})
+    });
+    const discovered = result;
+    const recovered = await recoverDuplicateKeyFiles(discovered.parseFailures ?? [], [sourceLocale, ...targetLocales], config, fsUtils.readFile);
+    const recoveredPaths = new Set(recovered.files.map((f) => f.path));
+    const parseFailures = (discovered.parseFailures ?? []).filter((f) => !recoveredPaths.has(f.path));
+    const allFiles = [...discovered.allFiles, ...recovered.files];
+    const sourceFiles = [...discovered.sourceFiles, ...recovered.files.filter((f) => f.locale === sourceLocale)];
+    const targetFilesByLocale = { ...discovered.targetFilesByLocale };
+    for (const file of recovered.files.filter((f) => f.locale !== sourceLocale)) {
+        targetFilesByLocale[file.locale] = [...(targetFilesByLocale[file.locale] ?? []), file];
+    }
+    const filesFor = (locale) => (targetFilesByLocale[locale] || []).map((f) => f.path);
+    if (format === 'text') {
+        if (detected)
+            printDetected(console, detected, targetLocales.length);
+        console.log(chalk.blue(`ℹ Source locale: ${sourceLocale} (${sourceFiles.map((f) => f.path).join(', ') || 'no source files found'})`));
+        if (targetLocales.length === 0 && !detected)
+            console.log(chalk.blue('ℹ Target locales: none configured'));
+        for (const locale of targetLocales) {
+            console.log(chalk.blue(`ℹ ${locale}: ${filesFor(locale).join(', ') || 'no files found'}`));
+        }
+    }
+    if (parseFailures.length > 0 && format !== 'json') {
+        console.error(chalk.red(`\n✖ ${parseFailures.length} translation file(s) could not be parsed and were skipped:`));
+        for (const failure of parseFailures) {
+            console.error(chalk.red(`  - ${failure.path}: ${failure.error}`));
+        }
+    }
+    if (!allFiles || allFiles.length === 0) {
+        console.error(chalk.red('\n✖ No translation files found in the specified paths.\n'));
+        return failedResult(format, sourceLocale);
+    }
+    const context = {
+        sourceLocale,
+        targetLocales,
+        detected,
+        console,
+        ignoreMatcher: createIgnoreMatcher(config.translationFiles?.ignoreKeys ?? [])
+    };
+    const files = { sourceFiles, targetFilesByLocale, duplicates: recovered.duplicates };
+    const current = analyze(files, context);
+    const changedOnly = !options.full && (options.changedOnly || ci.pullRequest !== null);
+    const quiet = { ...context, console: { log: SILENT.log, error: SILENT.log } };
+    const { status: changeStatus, reports } = changedOnly
+        ? compareWithBase(deps, ci, config, files, current.reports, (baseFiles) => analyze(baseFiles, quiet).reports)
+        : { status: null, reports: current.reports };
+    // Compared with the base, every finding left is one the pull request caused, so all of them fail by default.
+    const compared = changeStatus !== null && 'base' in changeStatus;
+    const failOn = options.failOn ?? (compared ? 'any' : 'missing');
+    // Without the diff, failing on every existing finding would block pull requests that did not cause them.
+    const findingsFail = !(changeStatus && 'error' in changeStatus) && shouldFail(reports.map((r) => filterFindings(r, isIntroduced)), failOn);
+    const exitCode = findingsFail || (parseFailures.length > 0 && failOn !== 'none') ? 1 : 0;
     return {
         aborted: false,
         exitCode,
         reports,
         sourceLocale,
         sourceFiles: sourceFiles.map((f) => f.path),
-        keyCount: totalSourceKeys.size,
+        keyCount: current.keyCount,
         parseFailures,
-        detected
+        detected,
+        format,
+        changes: changeStatus,
+        fileContents: rawContents(discovered.allFiles)
+    };
+}
+// Files rebuilt because of duplicate keys are left out: their lines no longer match the repo.
+function rawContents(files) {
+    const contents = {};
+    for (const file of files) {
+        if (file.content && !(file.path in contents)) {
+            contents[file.path] = Buffer.from(file.content, 'base64').toString('utf8');
+        }
+    }
+    return contents;
+}
+function lineLocator(contents) {
+    const finders = new Map();
+    return (file, key, locale) => {
+        const content = contents[file];
+        if (content === undefined)
+            return undefined;
+        const cacheKey = `${file}\u0000${locale}`;
+        let find = finders.get(cacheKey);
+        if (!find) {
+            find = keyLineFinder(content, formatOf(file), locale);
+            finders.set(cacheKey, find);
+        }
+        return find(key) ?? undefined;
     };
 }
 function shouldFail(reports, failOn) {
@@ -341,14 +504,23 @@ function printHumanReport(con, reports, keyCount, all) {
     const totalPossible = keyCount * reports.length;
     const overallComplete = totalPossible === 0 ? 100 : Math.round(((totalPossible - totalMissing) / totalPossible) * 100);
     con.log(chalk.bold(`\n${reports.length} locale(s), ${keyCount} keys, ${overallComplete}% complete, ${totalPlaceholders} placeholder mismatches, ${totalOrphans} orphans`));
+    printFindings(con, reports, all);
+}
+function placeholderProblem(m) {
+    return [
+        m.missingInTarget.length ? `missing ${spellPlaceholders(m.missingInTarget, m.source).join(' ')}` : '',
+        m.unexpectedInTarget.length ? `unexpected ${spellPlaceholders(m.unexpectedInTarget, m.target).join(' ')}` : ''
+    ]
+        .filter(Boolean)
+        .join(', ');
+}
+function printFindings(con, reports, all) {
     for (const r of reports) {
         con.log(chalk.bold(`\n== ${r.locale} ==`));
         printList(con, 'Missing keys', r.missing, (m) => m.key, all);
         printList(con, 'Empty values', r.empty, (m) => `${m.key}: "${truncate(m.source)}" -> ""`, all);
-        printList(con, 'Placeholder mismatches', r.placeholderMismatches, (m) => `${m.key}: "${truncate(m.source)}" -> "${truncate(m.target)}"` +
-            (m.missingInTarget.length ? ` [missing: ${m.missingInTarget.join(', ')}]` : '') +
-            (m.unexpectedInTarget.length ? ` [unexpected: ${m.unexpectedInTarget.join(', ')}]` : ''), all);
-        printList(con, 'Placeholder hints (a plural form may leave out a placeholder)', r.placeholderHints, (m) => `${m.key}: "${truncate(m.source)}" -> "${truncate(m.target)}" [omits: ${m.missingInTarget.join(', ')}]`, all);
+        printList(con, 'Placeholder mismatches', r.placeholderMismatches, (m) => `${m.key}: "${truncate(m.source)}" -> "${truncate(m.target)}" [${placeholderProblem(m)}]`, all);
+        printList(con, 'Placeholder hints (a plural form may leave out a placeholder)', r.placeholderHints, (m) => `${m.key}: "${truncate(m.source)}" -> "${truncate(m.target)}" [omits: ${spellPlaceholders(m.missingInTarget, m.source).join(', ')}]`, all);
         printList(con, 'Orphan keys', r.orphans, (m) => `${m.key}: "${truncate(m.target ?? '')}"`, all);
         printList(con, 'Structure mismatches', r.structureMismatches, (m) => `${m.key}: source is ${m.sourceShape}, target is ${m.targetShape}`, all);
         printList(con, 'Plural shape mismatches', r.pluralShapeMismatches, (m) => m.key, all);
@@ -367,85 +539,185 @@ function escapeAnnotationProperty(text) {
 }
 // GitHub shows only a handful of annotations per run; thousands just bury the log.
 const MAX_ANNOTATIONS = 50;
-function printGithubAnnotations(con, reports) {
-    const lines = [];
-    const annotate = (level, file, message) => lines.push(`::${level} file=${escapeAnnotationProperty(file)}::${escapeAnnotationData(message)}`);
-    // Parsed locale files carry no line numbers, so annotations are file-level.
+// A missing translation points at the source key's line: in a pull request that
+// added the key, that line is in the diff, so GitHub shows the annotation inline.
+function annotationsFor(reports, sourceLocale, lineOf = () => undefined) {
+    const annotations = [];
     for (const r of reports) {
+        const annotate = (level, file, message, key) => annotations.push({
+            level,
+            locale: r.locale,
+            file,
+            line: key === undefined ? undefined : lineOf(file, key, r.locale),
+            message
+        });
         for (const m of r.missing) {
-            annotate('error', m.targetPath, `Missing translation for "${m.key}" (locale ${r.locale})`);
+            annotations.push({
+                level: 'error',
+                locale: r.locale,
+                file: m.path,
+                line: lineOf(m.path, m.key, sourceLocale),
+                message: `Missing translation for "${m.key}" (locale ${r.locale})`,
+                targetFile: m.targetPath
+            });
         }
         for (const m of r.empty) {
-            annotate('error', m.path, `Empty translation for "${m.key}" (locale ${r.locale})`);
+            annotate('error', m.path, `Empty translation for "${m.key}" (locale ${r.locale})`, m.key);
         }
         for (const m of r.placeholderMismatches) {
-            annotate('error', m.path, `Placeholder mismatch for "${m.key}" (locale ${r.locale})`);
+            annotate('error', m.path, `Placeholder mismatch for "${m.key}" (locale ${r.locale}): ${placeholderProblem(m)}`, m.key);
         }
         for (const m of r.missingPluralCategories) {
-            annotate('error', m.path, `"${m.key}" lacks plural forms ${m.missing.join(', ')} (locale ${r.locale})`);
+            annotate('error', m.path, `"${m.key}" lacks plural forms ${m.missing.join(', ')} (locale ${r.locale})`, m.key);
         }
         for (const m of r.placeholderHints) {
-            annotate('notice', m.path, `Plural form omits ${m.missingInTarget.join(', ')} for "${m.key}" (locale ${r.locale})`);
+            const omitted = spellPlaceholders(m.missingInTarget, m.source).join(', ');
+            annotate('notice', m.path, `Plural form omits ${omitted} for "${m.key}" (locale ${r.locale})`, m.key);
         }
         for (const m of r.orphans) {
-            annotate('warning', m.path, `Orphan key "${m.key}" (locale ${r.locale}) no longer in source`);
+            annotate('warning', m.path, `Orphan key "${m.key}" (locale ${r.locale}) no longer in source`, m.key);
         }
         for (const m of r.structureMismatches) {
-            annotate('error', m.path, `Structure mismatch for "${m.key}" (locale ${r.locale})`);
+            annotate('error', m.path, `Structure mismatch for "${m.key}" (locale ${r.locale})`, m.key);
         }
         for (const m of r.pluralShapeMismatches) {
-            annotate('error', m.path, `Plural shape mismatch for "${m.key}" (locale ${r.locale})`);
+            annotate('error', m.path, `Plural shape mismatch for "${m.key}" (locale ${r.locale})`, m.key);
         }
         for (const m of r.conflictingKeys) {
-            annotate('error', m.files[0], `"${m.key}" has different values in ${m.files.join(', ')} (locale ${r.locale})`);
+            annotate('error', m.files[0], `"${m.key}" has different values in ${m.files.join(', ')} (locale ${r.locale})`, m.key);
         }
         for (const m of r.duplicateKeys) {
-            annotate('warning', m.path, `"${m.key}" is defined ${m.values.length} times; the last value wins (locale ${r.locale})`);
+            annotate('warning', m.path, `"${m.key}" is defined ${m.values.length} times; the last value wins (locale ${r.locale})`, m.key);
         }
     }
+    return annotations;
+}
+function problemsIn(reports, sourceLocale) {
+    return annotationsFor(reports, sourceLocale).filter((a) => a.level !== 'notice');
+}
+function printGithubAnnotations(con, annotations) {
+    const lines = annotations.map(({ level, file, line, message }) => {
+        const where = line === undefined ? '' : `,line=${line}`;
+        return `::${level} file=${escapeAnnotationProperty(file)}${where}::${escapeAnnotationData(message)}`;
+    });
     for (const line of lines.slice(0, MAX_ANNOTATIONS))
         con.log(line);
     if (lines.length > MAX_ANNOTATIONS) {
         con.log(`::warning::${lines.length - MAX_ANNOTATIONS} more findings not shown. Run check --json for the full report.`);
     }
 }
+function problemCounts(r) {
+    return {
+        missing: missingCount(r),
+        placeholders: r.placeholderMismatches.length,
+        plurals: r.missingPluralCategories.length + r.pluralShapeMismatches.length,
+        structure: r.structureMismatches.length,
+        conflicts: r.conflictingKeys.length + r.duplicateKeys.length,
+        orphans: r.orphans.length
+    };
+}
+function unavailableMessage(error) {
+    return `Could not compare with the base branch: ${error}. Checked every key instead; its findings do not fail the run. In GitHub Actions, check out with fetch-depth: 0 if this keeps happening.`;
+}
+function existingProblemsLine(count) {
+    return `${plural(count, 'problem')} already on the base branch ${count === 1 ? 'is' : 'are'}`;
+}
+function changedOnlyJson(changes) {
+    if (changes === null)
+        return null;
+    if ('error' in changes)
+        return { base: null, diffAvailable: false, reason: changes.error };
+    return { base: changes.base, diffAvailable: true };
+}
+function printJsonReport(con, result) {
+    con.log(JSON.stringify({
+        sourceLocale: result.sourceLocale,
+        sourceFiles: result.sourceFiles,
+        keyCount: result.keyCount,
+        parseFailures: result.parseFailures,
+        detected: result.detected,
+        changedOnly: changedOnlyJson(result.changes),
+        locales: result.reports.map((r) => ({
+            locale: r.locale,
+            files: r.files,
+            keyCount: r.keyCount,
+            missing: r.missing,
+            empty: r.empty,
+            identical: r.identical,
+            placeholderMismatches: r.placeholderMismatches,
+            placeholderHints: r.placeholderHints,
+            missingPluralCategories: r.missingPluralCategories,
+            orphans: r.orphans,
+            structureMismatches: r.structureMismatches,
+            pluralShapeMismatches: r.pluralShapeMismatches,
+            conflictingKeys: r.conflictingKeys,
+            duplicateKeys: r.duplicateKeys,
+            missingFiles: r.missingFiles
+        }))
+    }));
+}
+function countedInSummary(changes, reports) {
+    if (changes === null)
+        return [];
+    if ('error' in changes)
+        return reports;
+    return reports.map((r) => filterFindings(r, isExisting));
+}
+function writeStepSummary(deps, path, changes, reports, sourceLocale) {
+    const listed = changes !== null && 'error' in changes ? [] : reports.map((r) => filterFindings(r, isIntroduced));
+    const markdown = buildStepSummary({
+        changes,
+        problems: problemsIn(listed, sourceLocale).map((a) => ({ ...a, file: a.targetFile ?? a.file })),
+        counts: countedInSummary(changes, reports).map((r) => ({ locale: r.locale, counts: problemCounts(r) })),
+        missingTranslations: reports.some((r) => missingCount(r) > 0)
+    });
+    try {
+        deps.appendFile(path, `${markdown}\n`);
+    }
+    catch (error) {
+        deps.console.error(chalk.yellow(`⚠ Could not write the job summary: ${error.message}`));
+    }
+}
 export async function check(options = {}, deps = defaultDeps) {
     const con = deps.console;
-    const { aborted, exitCode, reports, sourceLocale, sourceFiles, keyCount, parseFailures, detected } = await runCheck(options, deps);
-    process.exitCode = exitCode;
-    if (aborted)
+    const result = await runCheck(options, deps);
+    const { reports, sourceLocale, keyCount, format, changes, fileContents } = result;
+    process.exitCode = result.exitCode;
+    if (result.aborted)
         return;
-    if (options.json) {
-        con.log(JSON.stringify({
-            sourceLocale,
-            sourceFiles,
-            keyCount,
-            parseFailures,
-            detected,
-            locales: reports.map((r) => ({
-                locale: r.locale,
-                files: r.files,
-                keyCount: r.keyCount,
-                missing: r.missing,
-                empty: r.empty,
-                identical: r.identical,
-                placeholderMismatches: r.placeholderMismatches,
-                placeholderHints: r.placeholderHints,
-                missingPluralCategories: r.missingPluralCategories,
-                orphans: r.orphans,
-                structureMismatches: r.structureMismatches,
-                pluralShapeMismatches: r.pluralShapeMismatches,
-                conflictingKeys: r.conflictingKeys,
-                duplicateKeys: r.duplicateKeys,
-                missingFiles: r.missingFiles
-            }))
-        }));
+    const unavailable = changes !== null && 'error' in changes ? changes.error : null;
+    const base = changes !== null && 'base' in changes ? changes.base : null;
+    const introduced = reports.map((r) => filterFindings(r, isIntroduced));
+    const existingProblems = base ? problemsIn(reports.map((r) => filterFindings(r, isExisting)), sourceLocale).length : 0;
+    const summaryPath = detectCiContext(deps.env).stepSummaryPath;
+    if (format === 'json') {
+        if (unavailable)
+            con.error(chalk.yellow(`⚠ ${unavailableMessage(unavailable)}`));
+        printJsonReport(con, result);
+    }
+    else if (format === 'github') {
+        if (unavailable) {
+            con.log(`::warning::${escapeAnnotationData(unavailableMessage(unavailable))}`);
+        }
+        else {
+            printGithubAnnotations(con, annotationsFor(introduced, sourceLocale, lineLocator(fileContents)));
+        }
+        if (base) {
+            const where = summaryPath ? 'counted in the job summary' : 'not listed; run with --full to see them';
+            con.log(`Compared with ${base}. ${existingProblemsLine(existingProblems)} ${where}.`);
+        }
     }
-    else if (options.format === 'github') {
-        printGithubAnnotations(con, reports);
+    else if (base) {
+        con.log(chalk.blue(`ℹ Compared with ${base}. Only new problems are listed.`));
+        printFindings(con, introduced, Boolean(options.all));
+        con.log(`\n${existingProblemsLine(existingProblems)} not listed. Run with --full to see them.`);
     }
     else {
+        if (unavailable)
+            con.log(chalk.yellow(`⚠ ${unavailableMessage(unavailable)}`));
         printHumanReport(con, reports, keyCount, Boolean(options.all));
     }
+    if (summaryPath)
+        writeStepSummary(deps, summaryPath, changes, reports, sourceLocale);
 }
 //# sourceMappingURL=check.js.map