@katerynakhar/i18n-keeper 0.16.0

package/src/placeholders.ts

@@ -0,0 +1,123 @@
+/**
+ * Placeholder extraction across the interpolation syntaxes that actually collide
+ * in the wild. Patterns are applied in a fixed order and every match is masked
+ * out of the working copy, so `{{name}}` is never also counted as `{name}`.
+ */
+
+interface PatternSpec {
+  re: RegExp;
+  label: (m: RegExpExecArray) => string;
+}
+
+const PATTERNS: Record<string, PatternSpec> = {
+  // {{ name }} — mustache / i18next default
+  mustache: {
+    re: /\{\{\s*[#/^&]?\s*([\w.$-]+)\s*\}\}/g,
+    label: (m) => `{{${m[1]}}}`,
+  },
+  // %{name} — ruby i18n
+  ruby: {
+    re: /%\{\s*([\w.$-]+)\s*\}/g,
+    label: (m) => `%{${m[1]}}`,
+  },
+  // {count, plural, ...} — ICU complex argument; matched by its head so that
+  // nested braces in the sub-messages do not hide the argument name.
+  icu_complex: {
+    re: /\{\s*([\w.$-]+)\s*,\s*(plural|select|selectordinal|number|date|time)\b/g,
+    label: (m) => `{${m[1]},${m[2]}}`,
+  },
+  // {name} — ICU simple argument
+  icu: {
+    re: /\{\s*([\w.$-]+)\s*\}/g,
+    label: (m) => `{${m[1]}}`,
+  },
+  // %s, %d, %1$s — printf
+  printf: {
+    re: /%(?:(\d+)\$)?([sdifux])/g,
+    label: (m) => (m[1] ? `%${m[1]}$${m[2]}` : `%${m[2]}`),
+  },
+  // <0>...</0> — react-i18next <Trans> indices
+  tag: {
+    re: /<\/?(\d+)>/g,
+    label: (m) => m[0],
+  },
+  // :name — Laravel. Off by default: it false-positives on prose like
+  // "Warning:Important". Enabled automatically for PHP locale files.
+  // Laravel treats :name, :Name and :NAME as one placeholder rendered with
+  // different capitalisation, so they normalise to one label here.
+  laravel: {
+    re: /(?<![\w:]):([a-zA-Z][\w]*)/g,
+    label: (m) => `:${m[1]!.toLowerCase()}`,
+  },
+};
+
+/** Longest / most specific syntaxes first, so masking works. */
+const ORDER = ['mustache', 'ruby', 'icu_complex', 'icu', 'printf', 'tag', 'laravel'];
+
+export const DEFAULT_SYNTAXES = ['mustache', 'ruby', 'icu_complex', 'icu', 'printf', 'tag'];
+export const ALL_SYNTAXES = ORDER;
+
+const MASK = '\u0000';
+
+function maskSpans(text: string, spans: Array<[number, number]>): string {
+  const chars = [...text];
+  for (const [start, end] of spans) {
+    for (let i = start; i < end && i < chars.length; i++) chars[i] = MASK;
+  }
+  return chars.join('');
+}
+
+/** Returns a multiset of placeholder labels: `{name}` twice is not the same as once. */
+export function extractPlaceholders(text: string, syntaxes: string[]): Map<string, number> {
+  const counts = new Map<string, number>();
+  let masked = text;
+
+  for (const id of ORDER) {
+    if (!syntaxes.includes(id)) continue;
+    const spec = PATTERNS[id];
+    if (!spec) continue;
+
+    const re = new RegExp(spec.re.source, spec.re.flags);
+    const spans: Array<[number, number]> = [];
+    let m: RegExpExecArray | null;
+
+    while ((m = re.exec(masked)) !== null) {
+      if (m[0].length === 0) {
+        re.lastIndex++;
+        continue;
+      }
+      const label = spec.label(m);
+      counts.set(label, (counts.get(label) ?? 0) + 1);
+      spans.push([m.index, m.index + m[0].length]);
+    }
+
+    if (spans.length > 0) masked = maskSpans(masked, spans);
+  }
+
+  return counts;
+}
+
+export interface PlaceholderDiff {
+  missing: string[];
+  extra: string[];
+}
+
+/** What the target lost from the source, and what it invented. */
+export function diffPlaceholders(
+  source: Map<string, number>,
+  target: Map<string, number>,
+): PlaceholderDiff {
+  const missing: string[] = [];
+  const extra: string[] = [];
+
+  for (const [label, count] of source) {
+    const got = target.get(label) ?? 0;
+    if (got < count) missing.push(count - got > 1 ? `${label} x${count - got}` : label);
+  }
+  for (const [label, count] of target) {
+    const had = source.get(label) ?? 0;
+    if (count > had) extra.push(count - had > 1 ? `${label} x${count - had}` : label);
+  }
+
+  return { missing, extra };
+}

package/src/plurals.ts

@@ -0,0 +1,320 @@
+/**
+ * CLDR plural categories, taken from the ICU data already in the runtime rather
+ * than a hand-maintained table: the table would go stale, and this is the same
+ * data the application itself will use at runtime.
+ */
+
+export const CATEGORY_NAMES = ['zero', 'one', 'two', 'few', 'many', 'other'] as const;
+export type Category = (typeof CATEGORY_NAMES)[number];
+
+const CATEGORIES = new Set<string>(CATEGORY_NAMES);
+const cache = new Map<string, Set<string> | null>();
+
+export function isCategory(name: string): name is Category {
+  return CATEGORIES.has(name);
+}
+
+/**
+ * Categories CLDR defines for a locale, or null when we cannot tell.
+ *
+ * Intl.PluralRules silently falls back to the system locale for tags it does
+ * not know — asking for "zz" on a Russian machine reports four categories — so
+ * a resolved language subtag that does not match the request means "unknown"
+ * rather than a wrong answer.
+ */
+export function categoriesFor(locale: string): Set<string> | null {
+  const cached = cache.get(locale);
+  if (cached !== undefined) return cached;
+
+  const tag = locale.replace(/_/g, '-');
+  let result: Set<string> | null = null;
+
+  try {
+    const resolved = new Intl.PluralRules(tag, { type: 'cardinal' }).resolvedOptions();
+    const asked = tag.split('-')[0]!.toLowerCase();
+    const got = resolved.locale.split('-')[0]!.toLowerCase();
+    if (asked === got && resolved.pluralCategories.length > 0) {
+      result = new Set(resolved.pluralCategories);
+    }
+  } catch {
+    result = null;
+  }
+
+  cache.set(locale, result);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// ICU MessageFormat
+// ---------------------------------------------------------------------------
+
+export interface PluralBlock {
+  arg: string;
+  type: 'plural' | 'selectordinal';
+  /** Keyword selectors: one, few, other … */
+  categories: Set<string>;
+  /** Exact selectors: =0, =1 … which are not CLDR categories. */
+  exact: Set<string>;
+}
+
+export interface IcuScan {
+  blocks: PluralBlock[];
+  error: string | null;
+}
+
+const PLURAL_INTENT = /\{\s*[\w.$-]+\s*,\s*(?:plural|selectordinal)\b/;
+
+/** Whether the string is trying to be an ICU plural at all. */
+export function looksLikeIcuPlural(text: string): boolean {
+  return PLURAL_INTENT.test(text);
+}
+
+class IcuScanner {
+  private pos = 0;
+  readonly blocks: PluralBlock[] = [];
+
+  constructor(private readonly text: string) {}
+
+  private get done(): boolean {
+    return this.pos >= this.text.length;
+  }
+
+  private fail(message: string): never {
+    throw new Error(`${message} at offset ${this.pos}`);
+  }
+
+  private skipWs(): void {
+    while (!this.done && /\s/.test(this.text[this.pos]!)) this.pos++;
+  }
+
+  private readIdent(): string {
+    const start = this.pos;
+    while (!this.done && /[\w.$-]/.test(this.text[this.pos]!)) this.pos++;
+    return this.text.slice(start, this.pos);
+  }
+
+  /** ICU quoting: '{', '}' and '#' start a literal run; '' is one apostrophe. */
+  private skipQuote(): void {
+    const next = this.text[this.pos + 1];
+    if (next === "'") {
+      this.pos += 2;
+      return;
+    }
+    if (next === '{' || next === '}' || next === '#') {
+      const close = this.text.indexOf("'", this.pos + 1);
+      this.pos = close === -1 ? this.text.length : close + 1;
+      return;
+    }
+    this.pos++;
+  }
+
+  /** Consumes a message body; with `nested`, stops after the matching brace. */
+  private scanMessage(nested: boolean): void {
+    while (!this.done) {
+      const ch = this.text[this.pos]!;
+      if (ch === "'") {
+        this.skipQuote();
+        continue;
+      }
+      if (ch === '}') {
+        if (!nested) this.fail('Unexpected }');
+        this.pos++;
+        return;
+      }
+      if (ch === '{') {
+        this.scanArgument();
+        continue;
+      }
+      this.pos++;
+    }
+    if (nested) this.fail('Unclosed {');
+  }
+
+  /** Consumes `{...}` of any argument type, starting at the opening brace. */
+  private scanArgument(): void {
+    this.pos++; // {
+    this.skipWs();
+    const name = this.readIdent();
+    this.skipWs();
+
+    if (this.done) this.fail('Unclosed {');
+    if (this.text[this.pos] === '}') {
+      this.pos++;
+      return;
+    }
+    if (this.text[this.pos] !== ',') this.fail('Expected , or } in argument');
+    this.pos++;
+    this.skipWs();
+
+    const type = this.readIdent();
+    this.skipWs();
+
+    if (this.done) this.fail('Unclosed {');
+    if (this.text[this.pos] === '}') {
+      this.pos++;
+      return;
+    }
+    if (this.text[this.pos] !== ',') this.fail(`Expected , or } after ${type || 'argument type'}`);
+    this.pos++;
+
+    if (type === 'plural' || type === 'selectordinal') {
+      this.scanPluralBody(name, type);
+    } else {
+      this.scanOpaqueBody();
+    }
+  }
+
+  /** For select/number/date: keep the braces balanced, ignore the content. */
+  private scanOpaqueBody(): void {
+    let depth = 1;
+    while (!this.done) {
+      const ch = this.text[this.pos]!;
+      if (ch === "'") {
+        this.skipQuote();
+        continue;
+      }
+      if (ch === '{') depth++;
+      if (ch === '}') {
+        depth--;
+        this.pos++;
+        if (depth === 0) return;
+        continue;
+      }
+      this.pos++;
+    }
+    this.fail('Unclosed {');
+  }
+
+  private scanPluralBody(arg: string, type: 'plural' | 'selectordinal'): void {
+    const block: PluralBlock = { arg, type, categories: new Set(), exact: new Set() };
+
+    for (;;) {
+      this.skipWs();
+      if (this.done) this.fail('Unclosed plural');
+
+      if (this.text[this.pos] === '}') {
+        this.pos++;
+        break;
+      }
+
+      if (this.text.startsWith('offset:', this.pos)) {
+        this.pos += 'offset:'.length;
+        this.skipWs();
+        while (!this.done && /[\d.-]/.test(this.text[this.pos]!)) this.pos++;
+        continue;
+      }
+
+      if (this.text[this.pos] === '=') {
+        this.pos++;
+        const start = this.pos;
+        while (!this.done && /[\d.]/.test(this.text[this.pos]!)) this.pos++;
+        if (this.pos === start) this.fail('Expected a number after =');
+        block.exact.add(`=${this.text.slice(start, this.pos)}`);
+      } else {
+        const keyword = this.readIdent();
+        if (!keyword) this.fail('Expected a plural selector');
+        block.categories.add(keyword);
+      }
+
+      this.skipWs();
+      if (this.text[this.pos] !== '{') this.fail('Expected { after a plural selector');
+      this.pos++;
+      this.scanMessage(true);
+    }
+
+    this.blocks.push(block);
+  }
+
+  run(): void {
+    this.scanMessage(false);
+  }
+}
+
+export function scanIcu(text: string): IcuScan {
+  const scanner = new IcuScanner(text);
+  try {
+    scanner.run();
+    return { blocks: scanner.blocks, error: null };
+  } catch (err) {
+    return {
+      blocks: scanner.blocks,
+      // Only meaningful for strings that meant to be ICU; i18next's {{name}}
+      // is not ICU and must not be reported as broken ICU.
+      error: looksLikeIcuPlural(text) ? (err instanceof Error ? err.message : String(err)) : null,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// i18next suffix keys: item_one, item_few, item_other
+// ---------------------------------------------------------------------------
+
+export interface SuffixKey {
+  base: string;
+  category: Category;
+  separator: '_' | '.';
+}
+
+export interface PluralGroup {
+  categories: Set<Category>;
+  /** Kept so a finding can name the keys as the project actually writes them. */
+  separator: '_' | '.';
+}
+
+/** i18next writes item_one; Rails and Symfony nest it as item.one. */
+export function splitPluralSuffix(key: string): SuffixKey | null {
+  for (const separator of ['_', '.'] as const) {
+    const at = key.lastIndexOf(separator);
+    if (at <= 0) continue;
+    const suffix = key.slice(at + 1);
+    if (isCategory(suffix)) return { base: key.slice(0, at), category: suffix, separator };
+  }
+  return null;
+}
+
+/**
+ * Groups keys like item_one / item_other into base -> categories.
+ *
+ * A group must carry `other`, which every CLDR plural set has. Without that
+ * test, Rails' `restrict_dependent_destroy.has_one` / `has_many` — ActiveRecord
+ * association names — read as a plural group and were asked to grow the forms
+ * their language requires.
+ */
+export function pluralGroups(keys: Iterable<string>): Map<string, PluralGroup> {
+  const groups = new Map<string, PluralGroup>();
+  for (const key of keys) {
+    const split = splitPluralSuffix(key);
+    if (!split) continue;
+    let group = groups.get(split.base);
+    if (!group) {
+      group = { categories: new Set(), separator: split.separator };
+      groups.set(split.base, group);
+    }
+    group.categories.add(split.category);
+  }
+
+  for (const [base, group] of groups) {
+    if (!group.categories.has('other')) groups.delete(base);
+  }
+  return groups;
+}
+
+// ---------------------------------------------------------------------------
+// Laravel pipe selection — deliberately not CLDR
+// ---------------------------------------------------------------------------
+
+/**
+ * Laravel picks a segment by position or by explicit {0} / [1,*] ranges, which
+ * is its own mechanism and not CLDR. All we can honestly compare is the segment
+ * count, so that is all this reports.
+ */
+export function pipeSegments(text: string): number {
+  let count = 1;
+  let depth = 0;
+  for (const ch of text) {
+    if (ch === '{' || ch === '[') depth++;
+    else if (ch === '}' || ch === ']') depth = Math.max(0, depth - 1);
+    else if (ch === '|' && depth === 0) count++;
+  }
+  return count;
+}

package/src/report.ts

@@ -0,0 +1,162 @@
+import { relative } from 'node:path';
+import type { Finding, LocaleStat, Report } from './types.js';
+
+const useColor =
+  process.stdout.isTTY === true && !process.env['NO_COLOR'] && process.env['TERM'] !== 'dumb';
+
+const paint = (code: string) => (s: string) =>
+  useColor ? `\u001b[${code}m${s}\u001b[0m` : s;
+const dim = paint('2');
+const bold = paint('1');
+const red = paint('31');
+const yellow = paint('33');
+const green = paint('32');
+
+function pad(s: string, width: number, align: 'left' | 'right' = 'left'): string {
+  const gap = ' '.repeat(Math.max(0, width - s.length));
+  return align === 'right' ? gap + s : s + gap;
+}
+
+function colorCoverage(value: number, text: string): string {
+  if (value >= 0.99) return green(text);
+  if (value >= 0.9) return yellow(text);
+  return red(text);
+}
+
+interface Column {
+  header: string;
+  align: 'left' | 'right';
+  value: (s: LocaleStat) => string;
+  color?: (s: LocaleStat, text: string) => string;
+}
+
+function columns(report: Report): Column[] {
+  const cols: Column[] = [
+    { header: 'locale', align: 'left', value: (s) => s.locale },
+    {
+      header: 'coverage',
+      align: 'right',
+      value: (s) => `${(s.coverage * 100).toFixed(1)}%`,
+      color: (s, text) => colorCoverage(s.coverage, text),
+    },
+    { header: 'missing', align: 'right', value: (s) => String(s.missing) },
+    { header: 'orphan', align: 'right', value: (s) => String(s.orphan) },
+  ];
+
+  // Without a translation memory there is nothing to compare against, so the
+  // column would only ever print zeroes.
+  if (report.memoryLoaded) {
+    cols.push({
+      header: 'stale',
+      align: 'right',
+      value: (s) => String(s.stale),
+      color: (s, text) => (s.stale > 0 ? yellow(text) : text),
+    });
+  }
+
+  cols.push(
+    {
+      header: 'errors',
+      align: 'right',
+      value: (s) => String(s.errors),
+      color: (s, text) => (s.errors > 0 ? red(text) : text),
+    },
+    {
+      header: 'warnings',
+      align: 'right',
+      value: (s) => String(s.warnings),
+      color: (s, text) => (s.warnings > 0 ? yellow(text) : text),
+    },
+  );
+
+  return cols;
+}
+
+function renderTable(report: Report): string[] {
+  const cols = columns(report);
+  const cells = report.stats.map((s) => cols.map((c) => c.value(s)));
+  const widths = cols.map((c, i) =>
+    Math.max(c.header.length, ...cells.map((row) => (row[i] ?? '').length)),
+  );
+
+  const lines = [dim(cols.map((c, i) => pad(c.header, widths[i]!, c.align)).join('  '))];
+
+  for (const [rowIndex, row] of cells.entries()) {
+    const stat = report.stats[rowIndex]!;
+    lines.push(
+      cols
+        .map((c, i) => {
+          const text = pad(row[i] ?? '', widths[i]!, c.align);
+          return c.color ? c.color(stat, text) : text;
+        })
+        .join('  '),
+    );
+  }
+
+  return lines;
+}
+
+function renderFindings(findings: Finding[], limit: number): string[] {
+  if (findings.length === 0) return [];
+
+  const shown = findings.slice(0, limit);
+  const localeWidth = Math.max(...shown.map((f) => f.locale.length));
+  const keyWidth = Math.min(36, Math.max(...shown.map((f) => f.key.length)));
+  const ruleWidth = Math.max(...shown.map((f) => f.rule.length));
+
+  const lines: string[] = [];
+  let lastSeverity = '';
+
+  for (const f of shown) {
+    if (f.severity !== lastSeverity) {
+      lines.push('');
+      lines.push(f.severity === 'error' ? red(bold('errors')) : yellow(bold('warnings')));
+      lastSeverity = f.severity;
+    }
+    const key = f.key.length > keyWidth ? `…${f.key.slice(-(keyWidth - 1))}` : f.key;
+    lines.push(
+      '  ' +
+        [pad(f.locale, localeWidth), pad(key, keyWidth), dim(pad(f.rule, ruleWidth)), f.detail].join(
+          '  ',
+        ),
+    );
+  }
+
+  if (findings.length > shown.length) {
+    lines.push(dim(`  … ${findings.length - shown.length} more (use --limit)`));
+  }
+
+  return lines;
+}
+
+export function renderReport(report: Report, root: string, limit: number): string {
+  const errors = report.findings.filter((f) => f.severity === 'error').length;
+  const warnings = report.findings.length - errors;
+
+  const head = [
+    `${bold('i18n check')}`,
+    `source: ${bold(report.sourceLocale)}${report.sourceFromMsgid ? dim(' (msgid)') : ''}`,
+    `${report.sourceKeys} keys`,
+    dim(relative(root, report.localesDir) || report.localesDir),
+  ];
+  if (!report.memoryLoaded) head.push(dim('no memory'));
+
+  const lines = [
+    head.join(` ${dim('·')} `),
+    '',
+    ...renderTable(report),
+    ...renderFindings(report.findings, limit),
+    '',
+  ];
+
+  if (report.findings.length === 0) {
+    lines.push(green('✓ no issues'));
+  } else {
+    const parts = [];
+    if (errors > 0) parts.push(red(`${errors} error${errors === 1 ? '' : 's'}`));
+    if (warnings > 0) parts.push(yellow(`${warnings} warning${warnings === 1 ? '' : 's'}`));
+    lines.push(parts.join(dim(' · ')));
+  }
+
+  return lines.join('\n');
+}